Embedding Video and Clips

Introduction

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

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 techniques for embedding video and clips

Embedding live streams and VODs in a non-interactive frame.
Embedding live streams and VODs in an interactive iframe.
Embedding clips in a non-interactive frame.

For more information, see VOD, Clips, and Clips Discovery.

Non-Interactive Inline Frames for Live Streams and VODs

Iframe Attributes

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

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 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`	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. 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

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

Examples

Using a channel name:

Using a video ID:

Using a collection ID:

Interactive Frames for Live Streams and VODs

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`	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: `true`.

Synchronous JavaScript Playback API

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 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
`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`	(Deprecated) Returns an object with statistics on the embedded video player and the current live stream or VOD. The format of the returned object is undefined.
`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.

JavaScript Events

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 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.

Example

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 Attributes

Name	Type	Description
`allowfullscreen`	boolean	If `true`, the player can go full screen.
`clip`	string	A globally unique string called a slug, by which clips are referenced.
`height`	integer	Height of the embedded window, in pixels. Recommended minimum: 300.
`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.
`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 IFrame Query String 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`.

Embedding Video and Clips

Introduction

Non-Interactive Inline Frames for Live Streams and VODs

Iframe Attributes

Optional Query String Parameters on Iframe src

Video Metadata

Examples

Interactive Frames for Live Streams and VODs

Required Parameters

Optional Parameter

Synchronous JavaScript Playback API

Synchronous JavaScript Volume API

Synchronous JavaScript Status API

JavaScript Events

Example

Non-Interactive IFrames for Clips

Iframe Attributes

Optional IFrame Query String Parameters

Example

Optional Query String Parameters on Iframe `src`