Twitch Embed Guide: Requirements and Troubleshooting
Twitch players embed differently from YouTube players: they need a declared parent domain, a minimum size and an unobscured frame. Here is what that means, and what to check when a Twitch stream will not play.
A Twitch stream can be shown on another website through Twitch's embedded player, but only if the page that embeds it follows Twitch's rules: it must name its own domain as the player's parent, it must be served over HTTPS, it must not cover the player, and the player must be at least a minimum size. When a Twitch embed will not play, the cause is usually one of those rules, an offline channel, or something in the browser blocking the player.
This guide explains the rules in plain terms and what they mean for people who watch embedded Twitch streams, including in StreamTiles, and for people who add Twitch players to their own pages. It is not a replacement for Twitch's own documentation, which is the authority and can change; the Twitch embedding documentation (opens in a new tab) is linked here for that reason.
What a Twitch embed is
Like YouTube, Twitch supplies a player that other sites can place in a page. The page includes either an iframe pointing at Twitch's player address or Twitch's JavaScript, which builds the same player. The video comes from Twitch, so the page that embeds it does not host or own the stream, as StreamTiles explains about third-party content. StreamTiles uses the second approach: it loads Twitch's script, only when a Twitch stream is in your grid and only after you allow third-party content, and then asks Twitch for a player.
https://player.twitch.tv/?channel=CHANNEL&parent=example.com&muted=trueThe parent domain rule
Twitch requires every embed to declare the domain of the page it appears on, using a parameter called parent. Twitch uses this to verify where its player is being shown. According to Twitch's documentation, an embed that does not declare a parent triggers a playback error that sends viewers to Twitch to watch instead.
For a viewer this is invisible: the site declares its own domain, and you do nothing. For a site builder it is the most common source of a blank Twitch player. The usual mistakes are declaring the wrong hostname, forgetting a second domain that the page is also served on, including a port or a path in the value, and testing on a local or staging address that was never declared. StreamTiles reads the real hostname of the page it is running on and passes that, without a port.
Size and visibility
Twitch states that embedded video must be at least 400 by 300 pixels, and that the minimum size and visibility are necessary for autoplay to start. Its terms also say the player should not be obscured by other page elements, and that some features may be switched off when it is hidden or covered.
This has visible consequences in a multi-stream grid. A tile in StreamTiles can be smaller than 400 by 300, so the viewer lays the Twitch player out at that minimum and scales it down to fit. Twitch's own text and buttons therefore look smaller than a YouTube tile's. And because Twitch asks not to be covered, StreamTiles places a Twitch tile's controls in a strip beneath the player instead of over the video, and leaves the player itself clickable.
Channels, videos and clips are different things
Twitch's player can show a live channel, a past broadcast or a clip, and each has a different kind of address. StreamTiles supports live channels only. A link to a channel, such as twitch.tv/channelname, works. Links to videos, clips and other Twitch pages, such as the directory or settings pages, are recognised and refused with a message saying so. It is easy to mistake a clip address for a channel address, so if a link is refused, check what kind of page it is.
A channel that is offline
A Twitch channel is only playable while it is live. When it is not, Twitch's player shows its own offline screen. In StreamTiles that is shown as an OFFLINE marker on the tile, and it is not treated as an error, because the embed itself works. When the channel goes live, Twitch's player is the one that starts, and the tile follows what it reports. A channel can be offline for long stretches, so a tile that stays offline is not a sign that something is broken.
When the player does not load
Twitch's player does not report much about why it failed. StreamTiles therefore keeps the wording careful: if no ready signal arrives in about twenty seconds, or the script cannot load, the tile says Unable to load stream and offers Try again, Open on Twitch and Remove stream. It does not claim that the channel is offline or removed, because it cannot know that from a load failure.
The usual causes of a player that never appears:
- A content blocker or privacy extension stopping Twitch's script or frame.
- A network filter on a school, work or public connection.
- Third-party content not yet allowed. In StreamTiles, a tile shows an Allow YouTube and Twitch content button until you choose to allow it.
- A browser that is out of date or has strict privacy settings.
- A page problem, such as a wrong parent value, on a site that embeds Twitch.
Autoplay, sound and mature-content prompts
Browsers generally block autoplay with sound, so StreamTiles starts every Twitch tile muted, as it does with YouTube. If you unmute and the browser refuses, the tile returns to muted rather than showing a volume that is not audible. Twitch's own player also has its own controls and may show prompts, such as a confirmation for content marked mature, which need a click inside the player. That is why a Twitch tile's frame stays interactive.
StreamTiles' mute button and volume slider control Twitch's player, but the controls inside Twitch's player are not synchronised with them, and changing the volume there does not move the StreamTiles slider. Use one set for a given tile.
A short troubleshooting order
- Open the channel on Twitch. If it is offline, that is the explanation.
- Check the link. It should be a channel address, not a video, a clip or another page.
- Allow third-party content if the tile asks, then press Try again.
- Try a private window with extensions off, then another browser.
- Try another network in case a filter is blocking Twitch.
- Leave it to Twitch. If it still fails, Twitch may not be allowing the player in your browser or region. StreamTiles does not work around that.
If you embed Twitch on your own site
Read the current rules in Twitch's documentation before you build anything, because they apply to your domain and Twitch can revoke embed access for domains that do not comply. In practice: serve the page over HTTPS, declare every domain that serves the page as a parent, keep the player unobscured and at least 400 by 300, and expect it to stay muted until the visitor chooses otherwise. Twitch's pages for embedding videos and clips (opens in a new tab) cover the size attributes and the player's options.
Frequently asked questions
What is the Twitch parent parameter?
It is the domain of the page that shows the player. Twitch requires every embed to declare it, and an embed without it shows a playback error that points viewers to Twitch.
Why does a Twitch tile say OFFLINE?
The channel is not live. Twitch's offline screen stays visible and the tile starts playing when the channel goes live.
Can I add a Twitch clip or a past broadcast to StreamTiles?
No. Only live channels are supported. A link to a clip or video is refused with a message saying so.
Why is a Twitch tile's text small?
Twitch asks for a player of at least 400 by 300 pixels. In a smaller tile, the player is laid out at that size and scaled down to fit.
Does StreamTiles show Twitch chat?
No. A Twitch tile shows the video player only.
Conclusion
Twitch embeds fail for a small set of reasons: a missing or wrong parent domain, a player that is too small or covered, a channel that is offline, and blockers or filters between the viewer and Twitch. Check the channel on Twitch first, then the link, then your browser. For the wider picture of combining Twitch with other streams, read how to watch Twitch and YouTube streams together, or compare it with YouTube embed errors.