Embedding Twitch
Everything

Embedding Everything

This guide explains how to embed video-on-demand content or live video with Twitch Chat on your website.

Authentication

Users of embedded Twitch are authenticated in the same way as the Twitch website and logging in is a seamless, lightweight experience. Logged-in users can chat, follow a channel, or subscribe to a channel. If a user attempts to perform one of these actions while not logged in, they will be prompted to log in or create a Twitch account.

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 be displayed.
  2. Load the Twitch embed JavaScript file.
  3. Initialize a Twitch.Embed object, with the placeholder element ID and options. If your site will be embedded on other domains, you must include them as a JavaScript array of strings under the parent key.
<html>
  <body>
    <!-- Add a placeholder for the Twitch embed -->
    <div id="twitch-embed"></div>
 
    <!-- Load the Twitch embed JavaScript file -->
    <script src="https://embed.twitch.tv/embed/v1.js"></script>
 
    <!-- Create a Twitch.Embed object that will render within the "twitch-embed" element -->
    <script type="text/javascript">
      new Twitch.Embed("twitch-embed", {
        width: 854,
        height: 480,
        channel: "monstercat",
        // Only needed if this page is going to be embedded on other websites
        parent: ["embed.example.com", "othersite.example.com"]
      });
    </script>
  </body>
</html>

Embed Parameters

OptionTypeDescription
allowfullscreenbooleanIf true, the player can go full screen. Default: true.
autoplaybooleanIf 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.
channelstringName of the chat room and channel (live content only).
collectionstringThe VOD collection to play. If you use this, you may also specify an initial video in the VOD collection, otherwise playback will begin with the first video in the collection. All VODs are auto-played. Chat replay is not supported. Example parameters object: { video: "124085610", collection: "GMEgKwTQpRQwyA" }
heightnumber or stringHeight of the rendered element, in pixels. This can be expressed as a percentage, by passing a string like 50%. Minimum: 400. Default: 480.
layoutstringDetermines the screen layout.
Valid values:

video-with-chat: Default if channel is provided, and only supported for live content. 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).
mutedbooleanSpecifies whether the initial state of the video is muted. Default: false.
parentstring[]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"].
themestringThe Twitch embed color theme to use. Valid values: light or dark. Default: dark.
timestringTime in the video where playback starts. Specifies hours, minutes, and seconds. Default: 0h0m0s (the start of the video).
videostringID of a VOD to play. Chat replay is not supported.
widthnumber or stringMaximum 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.VIDEO_READY, function() {
  console.log('The video is ready');
});

Available Events

EventDescription
Twitch.Embed.VIDEO_PLAYThe video started playing. This callback receives an object with a sessionId property.
Twitch.Embed.VIDEO_READYThe video player is ready for API commands.

Programmatic Access

To provide additional functionality to our API, access specific components with getPlayer(), which retrieves the current video player instance from the embed and 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" element. -->
    <script type="text/javascript">
      var embed = new Twitch.Embed("twitch-embed", {
        width: 854,
        height: 480,
        channel: "monstercat",
        layout: "video",
        autoplay: false,
        // Only needed if this page is going to be embedded on other websites
        parent: ["embed.example.com", "othersite.example.com"]
      });
 
      embed.addEventListener(Twitch.Embed.VIDEO_READY, () => {
        var player = embed.getPlayer();
        player.play();
      });
    </script>
  </body>
</html>