Contents

Embedding Video and Clips

You can embed live streams, video on demand (VOD), and clips in a website. Embedded video windows must be at least 400x300 pixels.

There are three types of VODs:

This guide discusses three techniques for embedding video and clips

For more information, see Video on Demand and How to Use Clips .

Non-Interactive Inline Frames for Live Streams and VODs

<iframe
    src="https://player.twitch.tv/?<channel, video, or collection>&parent=streamernews.example.com"
    height="<height>"
    width="<width>"
    allowfullscreen>
</iframe>

Iframe Attributes

These attributes are defined in the IFrame element. The Twitch player can not set or modify them.

Name Type Description
allowfullscreen boolean A boolean attribute set by inclusion. In other words, including the attribute enables fullscreen viewing while excluding the attribute ensures fullscreen viewing is not allowed.
height number or string Height of the embedded window, in pixels. This can be expressed as a percentage, by passing a string like 100%. Recommended minimum: 300
parent string (required) Domain(s) that will be embedding Twitch. You must have one parent key for each domain your site uses.
src string The iframe src URL string should be https://player.twitch.tv/ with one of these required query string parameters:

channel – (string) Name of the channel, for a live stream.

video – (string) Video ID (for past broadcasts, highlights, and video uploads). In this context (the video player), the video ID must have a “v” prefix.

collection - (string) Collection ID, for a collection of videos.

If both video and collection are specified, the specified collection starts playing from the specified video. If the video is not in the collection, collection is ignored and the specified video is played.

If channel is specified along with video and/or collection, only channel is used.
width number or string Width of the embedded window, in pixels. This can be expressed as a percentage, by passing a string like 50%. 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. The exception is mobile devices, on which video cannot be played without user interaction. 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

Video information such as duration, view count, and associated Twitch channel is available via the Get Videos API endpoint.

Examples

Using a channel name:

<iframe
    src="https://player.twitch.tv/?channel=dallas&parent=streamernews.example.com&muted=true"
    height="720"
    width="1280"
    allowfullscreen>
</iframe>

Using a video ID:

<iframe
    src="https://player.twitch.tv/?video=v40464143&parent=streamernews.example.com&autoplay=false"
    height="720"
    width="1280"
    allowfullscreen>
</iframe>

Using a collection ID:

<iframe
    src="https://player.twitch.tv/?collection=abcDeF1ghIJ2kL&parent=streamernews.example.com"
    height="720"
    width="1280"
    allowfullscreen>
</iframe>

Interactive Frames for Live Streams and VODs

<script src= "https://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 ID>",
    video: "<video ID>",
    collection: "<collection ID>",
    // only needed if your site is also embedded on embed.example.com and othersite.example.com
    parent: ["embed.example.com", "othersite.example.com"]
  };
  var player = new Twitch.Player("<player div ID>", options);
  player.setVolume(0.5);
</script>

Required Parameters

Name Type Description
channel
– OR –
video
– OR –
collection
string Channel name (for a live stream), video ID, or collection ID. (To change the channel or video later, use setChannel, setVideo, or setCollection; see Synchronous Playback Controls.)

If both video and collection are specified, the specified collection starts playing from the specified video. If the video is not in the collection, collection is ignored and the specified video is played.

If channel is specified along with video and/or collection, only channel is used.
height number or string Height of the embedded window, in pixels. Can be expressed as a percentage, by passing a string like 100%. Recommended minimum: 300.
parent string[] Only required if your site is embedded on any domain(s) other than the one that instantiates the Twitch embed. Example parent parameter: ["streamernews.example.com", "embed.example.com"]
player div ID string Any value you like, as long as it is the same in both locations within the example.
width number or string Width of the embedded window, in pixels. Can be expressed as a percentage, by passing a string like 50%. Recommended minimum: 400.

Optional Parameters

Name Type Description
autoplay boolean If true, the video starts playing automatically, without the user clicking play. The exception is mobile devices, on which video cannot be played without user interaction. Default: true.
muted boolean Specifies whether the initial state of the video is muted. Default: false.
time string Only valid for Video on Demand content. Time in the video where playback starts. Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video).

Synchronous JavaScript Playback API

Call Description
disableCaptions():void Disables display of Closed Captions.
enableCaptions():void Enables display of Closed Captions. Note captions will only display if they are included in the video content being played. See the CAPTIONS JavaScript Event for more info.
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. Does not work for live streams.
setChannel(channel:String):void Sets the channel to be played.
setCollection(collection ID:String, video ID:String):void Sets the collection to be played.

Optionally also specifies the video within the collection, from which to start playback. If a video ID is not provided here or the specified video is not part of the collection, playback starts with the first video in the collection.
setQuality(quality:String):void Sets the quality of the video. quality should be a string value returned by getQualities.
setVideo(video ID:String, timestamp:Number):void Sets the video to be played to be played and starts playback at timestamp (in seconds).

Synchronous JavaScript Volume API

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 JavaScript Status API

Call Description
getPlaybackStats():PlaybackStats Returns an object with statistics on the embedded video player and the current live stream or VOD. See below for more info.
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.
getQualities():String[] Returns the available video qualities. For example, chunked (pass-through of the original source).
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.

PlaybackStats Object attributes

Name Type Description
backendVersion string The version of the Twitch video player backend.
bufferSize number The size of the video buffer in seconds.
codecs string Codecs currently in use, comma-separated (video,audio).
displayResolution string The current size of the video player element (eg. 850x480).
fps number The video playback rate in frames per second. Not available on all browsers.
hlsLatencyBroadcaster number Current latency to the broadcaster in seconds. Only available for live content.
playbackRate number The playback bitrate in Kbps.
skippedFrames number The number of dropped frames.
videoResolution string The native resolution of the current video (eg. 640x480).

JavaScript Events

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

Event Emitted when …
Twitch.Player.CAPTIONS Closed captions are found in the video content being played. This event will be emitted once for each new batch of captions, in sync with the corresponding video content. The event payload is a string containing the caption content.
Twitch.Player.ENDED Video or stream ends.
Twitch.Player.PAUSE Player is paused. Buffering and seeking is not considered paused.
Twitch.Player.PLAY Player just unpaused, will either start video playback or start buffering.
Twitch.Player.PLAYBACK_BLOCKED Player playback was blocked. Usually fired after an unmuted autoplay or unmuted programmatic call on play().
Twitch.Player.PLAYING Player started video playback.
Twitch.Player.OFFLINE Loaded channel goes offline.
Twitch.Player.ONLINE Loaded channel goes online.
Twitch.Player.READY Player is ready to accept function calls.
Twitch.Player.SEEK User has used the player controls to seek a VOD, the seek() method has been called, or live playback has seeked to sync up after being paused.

Example

<script src= "https://player.twitch.tv/js/embed/v1.js"></script>
<div id="SamplePlayerDivID"></div>
<script type="text/javascript">
  var options = {
    width: 854,
    height: 480,
    channel: "twitchdev",
    // Only needed if this page is going to be embedded on other websites
    parent: ["embed.example.com", "othersite.example.com"]
  };
  var player = new Twitch.Player("SamplePlayerDivID", options);
  player.setVolume(0.5);
</script>

Non-Interactive IFrames 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.

IFrame Prototype

<iframe
    src="https://clips.twitch.tv/embed?clip=<slug>&parent=streamernews.example.com"
    height="<height>"
    width="<width>"
    allowfullscreen>
</iframe>

Iframe Attributes

Name Type Description
allowfullscreen boolean A boolean attribute set by inclusion. In other words, including the attribute enables fullscreen viewing while excluding the attribute ensures fullscreen viewing is not allowed.
clip string A globally unique string called a slug, by which clips are referenced.
height number or string Height of the embedded window, in pixels. This can be expressed as a percentage, by passing a string like 50%. Recommended minimum: 300.
parent string (required) Domain(s) that will be embedding Twitch. You must have one parent key for each domain your site uses.
preload enum A hint to the browser about what the developer thinks will lead to the best user experience. Valid values:

none - The video should not be preloaded.

metadata - Only video metadata (e.g., length) is fetched. This is the recommended value.

auto - The whole video file could be downloaded, even if the user is not expected to use it.

"" (empty string) - Same as auto.

Default: browser-defined.

The HTML specification does not force the browser to follow the value of this attribute; it is merely a hint.
width number or string Width of the embedded window, in pixels. This can be expressed as a percentage, by passing a string like 50%. Recommended minimum: 400.

Optional IFrame Query Parameters

Name Type Description
autoplay boolean If true, the video starts playing automatically, without the user clicking play. The exception is mobile devices, on which video cannot be played without user interaction. Default: false.
muted boolean Specifies whether the initial state of the video is muted. Default: false.

Example

<iframe
   src="https://clips.twitch.tv/embed?clip=IncredulousAbstemiousFennelImGlitch&parent=streamernews.example.com&parent=embed.example.com"
   height="360"
   width="640"
   allowfullscreen>
</iframe>