Embedding Twitch on Your Website

This document describes several embed options:

  • Embedding Everything describes a single solution for embedding chat, live video, and VODs. This embed includes follows, subscribe, and login functionality within one inline frame (iframe).
  • Embedding Chat describes more detailed options for embedding only chat.
  • Embedding Video and Clips describes more detailed options for embedding live video, VODs, and clips.

Embedding Everything (Public Beta)

Providing Feedback

We’re constantly trying to improve the developer experience, so if you encounter any difficulty using Twitch embed, please provide feedback via http://link.twitch.tv/embed-feedbackform.

Signing In, Authentication

Logging in is a seamless, lightweight experience for users of the Twitch embed player on non-Twitch websites.

Once logged in, a user can chat, follow a channel for future notifications, or subscribe. When users try to perform one of these actions, they are prompted to create a Twitch account or sign in to an existing one.

Users are authenticated on embedded Twitch in the same way (with the same authentication flow) as on the Twitch website.

Overlays

The Twitch embed contains buttons for Sign In, Follow, and Subscribe, in an overlay above the player.

In some cases, clicking a button opens a pop-up window that allows the user to complete the desired action (for example, navigate through the payment flow or create an account). In others, it automatically goes through with the action (such as Following).

The name of the channel being watched is an overlay that appears when you hover your mouse over the player. On embeds, these titles do not link back to Twitch.

Usage

  1. Add a placeholder element with a unique ID to your page, where you want the Twitch embed to render.
  2. Load the Twitch embed JavaScript file.
  3. Initialize a Twitch.Embed object, with the placeholder element ID and options.
<html>
  <body>
    <!-- Add a placeholder for the Twitch embed -->
    <div id="twitch-embed"></div>

    <!-- Load the Twitch embed script -->
    <script src="https://embed.twitch.tv/embed/v1.js"></script>

    <!-- Create a Twitch.Embed object that will render within the "twitch-embed" root element. -->
    <script type="text/javascript">
      new Twitch.Embed("twitch-embed", {
        width: 854,
        height: 480,
        channel: "monstercat"
      });
    </script>
  </body>
</html>

Embed Parameters

Option Type Description
allowfullscreen boolean If true, the player can go full screen. Default: true.
autoplay boolean If true, the video starts playing automatically, without the user clicking play. The exception is mobile platforms, on which video cannot be played without user interaction. Default: true.
channel string Optional for VOD embeds; otherwise, required. Name of the chat room and channel to stream.
chat string Specifies the type of chat to use. Valid values:
* default: Default value, uses full-featured chat.
* mobile: Uses a read-only version of chat, optimized for mobile devices.

To omit chat, specify a value of video for the layout option.
collection string The VOD collection to play. If you use this, you also must specify an initial video in the VOD collection. All VODs are auto-played. Rechat is not supported. Example:
https://embed.twitch.tv/?video=v124085610&collection=GMEgKwTQpRQwyA
font-size string Size of font to use for chat. Valid values: small, medium, large. Default: small.
height string Height of the rendered element, in pixels. This can be expressed as a percentage, by passing a string like 50%. Minimum: 400. Default: 480.
layout string Determines the screen layout. Valid values:
* video-and-chat: Default if channel is provided. Shows both video and chat side-by-side. At narrow sizes, chat renders under the video player.
* video: Default if channel is not provided. Shows only the video player (omits chat).
muted boolean Specifies whether the initial state of the video is muted. Default: false.
playsinline boolean If true, the embedded player plays inline for mobile iOS apps. Default: false.
theme string The Twitch embed color theme to use. Valid values: light or dark. Default: light.
time 1h2m3s Time in the video where playback starts. Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video).
video string ID of a VOD to play. Chat replay is not supported.
width number or string Maximum width of the rendered element, in pixels. This can be expressed as a percentage, by passing a string like 100%. Minimum: 340. Default: 940.

Working with Events

To listen to events, create a Twitch.Embed object, then call the addEventListener method on that object:

var embed = new Twitch.Embed('twitch-embed', {
  channel: 'monstercat'
});

embed.addEventListener(Twitch.Embed.AUTHENTICATE, function(user) {
  console.log(user.login + ' just logged in');
});

Available Events

Event Description
Twitch.Embed.AUTHENTICATE The user successfully logged into Twitch. The callback receives the public representation of a user with camelCase keys.
Twitch.Embed.VIDEO_PLAY The video started playing. This callback receives an object with a sessionId property.
Twitch.Embed.VIDEO_READY The video player is ready for API commands.

Advanced Usage: Programmatic Access

To provide additional functionality to our API, access specific components with getPlayer(), which retrieves the current video player instance from the Embed. Provides full programmatic access to the video player API.

<html>
  <body>
    <!-- Add a placeholder for the Twitch embed -->
    <div id="twitch-embed"></div>

    <!-- Load the Twitch embed script -->
    <script src="https://embed.twitch.tv/embed/v1.js"></script>

    <!--
      Create a Twitch.Embed object that will render
      within the "twitch-embed" root element.
    -->
    <script type="text/javascript">
      var embed = new Twitch.Embed("twitch-embed", {
        width: 854,
        height: 480,
        channel: "monstercat",
        layout: "video",
        autoplay: false
      });

      embed.addEventListener(Twitch.Embed.VIDEO_READY, () => {
        var player = embed.getPlayer();
        player.play();
      });
    </script>
  </body>
</html>

Embedding Chat

To embed a Twitch chat window in your website, use this expression:

<iframe frameborder="<frameborder width>"
        scrolling="<scrolling>"
        id="<channel>"
        src="<src url>"
        height="<height>"
        width="<width>">
</iframe>

Parameters for Embedding Chat

Name Type Description
frameborder integer Width of the chat-window border, in pixels
height integer Height of the chat window, in pixels
id string Name of the channel to which the chat belongs. This refers to the channel broadcaster.
scrolling boolean Specifies whether scrolling in the chat window is supported (yes or no)
src string Chat window URL
width integer Width of the chat window, in pixels

Example of Embedding Chat

<iframe frameborder="0" 
        scrolling="no" 
        id="chat_embed" 
        src="http://www.twitch.tv/hebo/chat" 
        height="500" 
        width="350">
</iframe>

Embedding Video and Clips

You can embed live streams, VODs, and clips in your website. 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

<iframe
    src="http://player.twitch.tv/?<channel, video, or collection>"
    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) 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 platforms, 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:

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

<iframe
    src="http://player.twitch.tv/?video=v40464143&autoplay=false"
    height="720"
    width="1280"
    frameborder="0"
    scrolling="no"
    allowfullscreen="true">
</iframe>

Using a collection ID:

<iframe
    src="http://player.twitch.tv/?collection=abcDeF1ghIJ2kL"
    height="720"
    width="1280"
    frameborder="0"
    scrolling="no"
    allowfullscreen="true">
</iframe>

Interactive Frames for Live Streams and VODs

<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 ID>",
 		video: "<video ID>",
		collection: "<collection ID>",
	};
	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 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 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. 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 be played.

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

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

<iframe
    src="https://clips.twitch.tv/embed?clip=<slug>"
    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 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 Query String Parameters

Name Type Description
autoplay boolean If true, the video starts playing automatically, without the user clicking play. The exception is mobile platforms, 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.

Example

<iframe
   src="https://clips.twitch.tv/embed?clip=IncredulousAbstemiousFennelImGlitch"
   height="360"
   width="640"
   frameborder="0"
   scrolling="no"
   allowfullscreen="true">
</iframe>