Embedding Video

You can embed live streams, VODs, and Clips in your Web site. Embedded video windows must be at least 400x300 pixels.

VOD is Video on Demand. There are three types of VODs:

  • Past broadcasts are created automatically from a live stream.
  • Highlights can be created by broadcasters from past broadcasts.
  • Uploads are external videos that are added to Twitch using the Video Uploads API or the Video Manager.

This guide discusses three video embed techniques:

Also see the Clips Discovery API.

Non-Interactive Inline Frames for Live Streams and VODs

1
2
3
4
5
6
7
8
<iframe
    src="http://player.twitch.tv/?<channel or video>"
    height="<height>"
    width="<width>"
    frameborder="<frameborder>"
    scrolling="<scrolling>"
    allowfullscreen="<allowfullscreen>">
</iframe>

Iframe Attributes

These attributes are defined in https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe. The Twitch player exists in the iframe with no ability to set the attributes on the iframe.

Name Type Description
allowfullscreen boolean If true, the player can go full screen.
height integer Height of the embedded window, in pixels. Recommended minimum: 300
scrolling boolean Indicates when the browser should provide a scroll bar (or other scrolling device) for the frame. Recommended: no.
src string The iframe src URL string should be http://player.twitch.tv/ with one of these required query string parameters:
- channel – (string) Name of the channel, for a live stream
- video – (string) VOD ID
If both channel and video are specified, video is ignored.
width integer Width of the embedded window, in pixels. Recommended minimum: 400

Optional Query String Parameters on Iframe src

Name Type Description
autoplay boolean If true, the video starts playing automatically, without the user clicking play. Default: true.
muted boolean Specifies whether the initial state of the video is muted. Default: false.
time 1h2m3s Time in the video where playback starts. Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video).

Video Metadata

Information on video channels, lengths, descriptions, and viewcounts is available through the Videos API.

Examples

Using a channel name:

1
2
3
4
5
6
7
8
<iframe
    src="http://player.twitch.tv/?channel=dallas&muted=true"
    height="720"
    width="1280"
    frameborder="0"
    scrolling="no"
    allowfullscreen="true">
</iframe>

Using a video ID:

1
2
3
4
5
6
7
8
<iframe
    src="http://player.twitch.tv/?video=40464143&autoplay=false"
    height="720"
    width="1280"
    frameborder="0"
    scrolling="no"
    allowfullscreen="true">
</iframe>

Interactive Frames for Live Streams and VODs

Using a channel name:

1
2
3
4
5
6
7
8
9
10
11
<script src= "http://player.twitch.tv/js/embed/v1.js"></script>
<div id="<player div ID>"></div>
<script type="text/javascript">
	var options = {
		width: <width>,
		height: <height>,
		<channel>: "<channel>,"
	};
	var player = new Twitch.Player("<player div ID>", options);
	player.setVolume(0.5);
</script>

Using a video ID:

1
2
3
4
5
6
7
8
9
10
11
<script src= "http://player.twitch.tv/js/embed/v1.js"></script>
<div id="<player div ID>"></div>
<script type="text/javascript">
	var options = {
		width: <width>,
		height: <height>,
		<video>: "<video ID>",
	};
	var player = new Twitch.Player("<player div ID>", options);
	player.setVolume(0.5);
</script>

Required Parameters

Name Type Description
channel
– OR –
video
string Channel name (for a live stream) or video ID of the VOD to be embedded. Either channel or video must be specified. (To change the channel or video later, use setChannel or setVideo; see Synchronous Playback Controls.)
height integer Height of the embedded window, in pixels. Recommended minimum: 300.
player div ID string Any value you like, as long as it is the same in both locations within the example.
width integer Width of the embedded window, in pixels. Recommended minimum: 400.

Optional Parameter

Name Type Description
playsinline boolean If true, the embedded player plays inline for mobile iOS apps. Default: false.

Synchronous Playback Controls

Call Description
pause():void Pauses the player.
play():void Begins playing the specified video.
seek(timestamp:Float):void Seeks to the specified timestamp (in seconds) in the video and resumes playing if paused. Does not work for live streams.
setChannel(channel:String):void Sets the channel to the specified channel name.
setQuality(quality:String):void Sets the quality of the video. Valid values: chunked (pass-through of the original source), high, medium, low, mobile. Default: medium (if there are transcodes for the video). If no transcode is available, source quality is used. (Transcodes are video re-encodings of the original stream.)
setVideo(video ID:String):void Sets the video to the specified ID.

Synchronous Volume Controls

Call Description
getMuted():Boolean Returns true if the player is muted; otherwise, false.
setMuted(muted:Boolean):void If true, mutes the player; otherwise, unmutes it. This is independent of the volume setting.
getVolume():Float Returns the volume level, a value between 0.0 and 1.0.
setVolume(volumelevel:Float):void Sets the volume to the specified volume level, a value between 0.0 and 1.0.

Synchronous Player Status

Call Description
getChannel():String Returns the channel’s name. Works only for live streams, not VODs.
getCurrentTime():Float Returns the current video’s timestamp, in seconds. Works only for VODs, not live streams.
getDuration():Float Returns the duration of the video, in seconds. Works only for VODs,not live streams.
getEnded():Boolean Returns true if the live stream or VOD has ended; otherwise, false.
getPlaybackStats():Object Returns an object with statistics the embedded video player and the current live stream or VOD.
getQualities():String[] Returns the available video qualities (chunked, high, medium, low, and/or mobile).
getQuality():String Returns the current quality of video playback.
getVideo():String Returns the video ID. Works only for VODs, not live streams.
isPaused():Boolean Returns true if the video is paused; otherwise, false. Buffering or seeking is considered playing.

Events Emitted by and Defined by the Player

To listen to events, call addEventListener(event:String, callback:Function).

Event Emitted when …
Twitch.Player.ENDED Video or stream ends.
Twitch.Player.PAUSE Player is paused. Buffering and seeking is not considered paused.
Twitch.Player.PLAY Player is playing.
Twitch.Player.OFFLINE Loaded channel goes offline.
Twitch.Player.ONLINE Loaded channel goes online.
Twitch.Player.READY Player is ready to accept function calls.

Example

1
2
3
4
5
6
7
8
9
10
11
<script src= "http://player.twitch.tv/js/embed/v1.js"></script>
<div id="SamplePlayerDivID"></div>
<script type="text/javascript">
	var options = {
		width: 854,
		height: 480,
		channel: "dallas",
	};
	var player = new Twitch.Player("SamplePlayerDivID", options);
	player.setVolume(0.5);
</script>

Non-Interactive Frames for Clips

Embedding a Clip is different than embedding a live stream or VOD. The embedded Clips player uses a different set of query parameters and does not support the JavaScript interactive embed.

1
2
3
4
5
6
7
8
<iframe
    src="https://clips.twitch.tv/embed?clip=<Clip URL>"
    height="<height>"
    width="<width>"
    frameborder="<frameborder>"
    scrolling="<scrolling>"
    allowfullscreen="<allow full screen>">
</iframe>

Iframe Attributes

Name Type Description
allowfullscreen boolean If true, the player can go full screen.
clip string The Clip ID, a URL that combines the channel name and slug (randomly generated phrase).
height integer Height of the embedded window, in pixels. Recommended minimum: 300.
scrolling boolean Indicates when the browser should provide a scroll bar (or other scrolling device) for the frame. Recommended: no.
width integer Width of the embedded window, in pixels. Recommended minimum: 400.

Optional Query String Parameters

Name Type Description
autoplay boolean If true, the video starts playing automatically, without the user clicking play. Default: true.
muted boolean Specifies whether the initial state of the video is muted. Default: false.

Example

1
2
3
4
5
6
7
8
<iframe
   src="https://clips.twitch.tv/embed?clip=eleaguetv/ZealousMosquitoPeteZarollTie"
   height="360"
   width="640"
   frameborder="0"
   scrolling="no"
   allowfullscreen="true">
</iframe>