Contents

Embedding Everything

Introduction

This guide explains how to embed Chat, Live Video, Video on Demand, and Clips in a non-Twitch website.

Logging In

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, or subscribe to a channel. When users try to perform one of these actions, they are prompted to create a Twitch account or sign in to an existing one.

Authentication

Users of embedded Twitch are authenticated in the same way as users of the Twitch website - that is, with the same authentication flow.

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

OptionTypeDescription
allowfullscreenbooleanIf true, the player can go full screen. Default: true.
channelstringOptional for VOD embeds; otherwise, required. Name of the chat room and channel to stream.
collectionstringThe 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-sizestringSize of font to use for chat. Valid values: small, medium, large. Default: small.
heightstringHeight 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. 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).
themestringThe Twitch embed color theme to use. Valid values: light or dark. Default: light.
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

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

Programmatic Access

Advanced usage: 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" 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>