Registry / web-framework / twitch-video-element

twitch-video-element

library0.1.6jsnpmunverified

twitch-video-element is a custom web component designed to embed Twitch player functionality into web applications, presenting an API that closely mirrors the standard HTML `<video>` element. Currently at version 0.1.6, this package is part of the larger @mux/media-elements monorepo. While the monorepo sees regular updates, this specific package is in an early pre-1.0.0 stage, indicating its API may evolve towards stability. Its primary differentiation lies in providing a familiar HTMLMediaElement interface for Twitch content, simplifying integration with other web components like Media Chrome, and abstracting the underlying complexities of the official Twitch embedded player SDK.

web-framework

npm install twitch-video-element

github ↗package ↗

INSTALL

IMPORT

SIG · TWITCH-VIDEO-ELEME

twitch-video-element

web-frameworkjavascriptv0.1.6

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

twitch-video-element

✓ import 'twitch-video-element';

✗ const TwitchVideoElement = require('twitch-video-element');

This package is designed for modern web environments (ESM) and registers the custom element as a side effect. CommonJS `require` is not supported for module import.

This quickstart demonstrates how to embed a Twitch video (VOD) and a live stream using the `<twitch-video>` custom element in an HTML page. It includes essential attributes like `controls`, `autoplay`, `muted`, and the critical `parent` attribute for security. It also shows programmatic interaction via JavaScript.

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>Twitch Video Element Quickstart</title> </head> <body> <h1>Twitch Video Demo</h1>  <twitch-video controls autoplay muted src="https://www.twitch.tv/videos/206400740" style="width: 640px; height: 360px;" parent="localhost" ></twitch-video> <p>Live stream example (replace 'channel_name' with an actual live channel):</p> <twitch-video controls autoplay muted src="https://www.twitch.tv/CHANNEL_NAME_HERE" style="width: 640px; height: 360px;" parent="localhost" ></twitch-video> <script type="module"> // Import the custom element. This registers <twitch-video> with the browser. import 'twitch-video-element'; // You can also programmatically interact with the element once registered. const twitchPlayer = document.querySelector('twitch-video'); if (twitchPlayer) { twitchPlayer.addEventListener('play', () => { console.log('Twitch video started playing!'); }); twitchPlayer.addEventListener('pause', () => { console.log('Twitch video paused!'); }); // Example of setting a new video source programmatically after a delay setTimeout(() => { console.log('Changing video source after 10 seconds...'); // Using a different VOD for demonstration twitchPlayer.src = 'https://www.twitch.tv/videos/106400740'; }, 10000); } </script> </body> </html>

Debug

Known issues

gotchaThe `parent` attribute is a critical security requirement for Twitch embeds. You must explicitly list the domain(s) where your site is embedded, e.g., `parent="localhost"` for local development or `parent="yourdomain.com"` for production. Failure to provide this will prevent the player from loading or functioning correctly.

fix

Always include the `parent` attribute on the `<twitch-video>` element, listing the hostname(s) where the element is hosted. For multiple domains, use a space-separated string: `parent="domain1.com domain2.com"`.

affects: >=0.1.0

gotchaBrowser autoplay policies often prevent media from playing automatically with sound. To ensure content starts playing, especially on initial page load, consider setting the `muted` attribute. Users can then unmute manually.

fix

Add the `muted` attribute to the `<twitch-video>` element: `<twitch-video autoplay muted src="..."></twitch-video>`.

affects: >=0.1.0

gotchaTwitch distinguishes between Video On Demand (VOD) IDs and Clip slugs. The `src` attribute is generally expecting a VOD ID (e.g., `videos/123456789`) or a channel name for a live stream, not a clip slug. Using a clip slug might result in the player failing to load content.

fix

Ensure the `src` attribute points to a valid Twitch VOD URL (containing `videos/ID`) or a Twitch channel URL (`twitch.tv/CHANNEL_NAME`). For clips, use the designated Twitch clip embed URL structure if available or integrate via the Twitch API directly if custom interaction is needed.

affects: >=0.1.0

gotchaEmbedded Twitch video players have minimum size requirements: at least 400 pixels wide and 300 pixels high. If the element's dimensions fall below these minimums, the player may not render correctly or at all.

fix

Ensure that the `<twitch-video>` element, or its containing parent, is styled to be at least 400px wide and 300px tall. For example: `<twitch-video style="width: 640px; height: 360px;" src="..."></twitch-video>`.

affects: >=0.1.0

breakingAs a pre-1.0.0 package (current version 0.1.6), the API of `twitch-video-element` is not considered stable. Future minor or patch releases could introduce breaking changes without a major version increment, aligning with common pre-1.0.0 semantic versioning practices.

fix

Pin to exact patch versions (`~0.1.6` instead of `^0.1.6`) or perform thorough testing when updating this package until it reaches a stable 1.0.0 release.

affects: >=0.1.0

Errors

Common errors & fixes

Failed to execute 'appendBuffer' on 'SourceBuffer': The HTMLMediaElement.error attribute is not null

This error often occurs in Android WebViews or specific browser environments, indicating issues with Media Source Extensions (MSE) or underlying codec support, possibly due to restrictive WebView settings or conflicts.

fix

Verify that your WebView or browser environment has JavaScript and MSE fully enabled. For WebViews, ensure proper client settings are configured. Debugging in the target environment with browser developer tools can help pinpoint the exact cause.

Twitch player not loading / displays 'Error Code 2000'

Error Code 2000 typically signifies a network problem (slow/unstable internet, router issues) or interference from browser extensions that prevent Twitch video delivery.

fix

Check your internet connection stability. Disable browser extensions (especially ad blockers or privacy tools) one by one to identify conflicts. Try loading the Twitch player in an incognito/private browser window.

Twitch player not loading / displays 'Error Code 1000'

Error Code 1000 usually points to browser or application compatibility issues, an outdated browser, or geographical restrictions on certain streaming features.

fix

Update your web browser to the latest version. Try a different browser to rule out compatibility issues. If persistent, check if the content is accessible in your region directly on Twitch.tv.

Twitch player not loading / displays 'Error Code 3000'

Error Code 3000 indicates a problem with the device's ability to decode and display the video stream, often linked to outdated browser versions, hardware acceleration problems, or conflicting browser extensions.

fix

Ensure your browser is updated. Try disabling hardware acceleration in your browser settings (often under System or Advanced settings). Temporarily disable browser extensions.

The interactive Twitch player doesn't work when I use a clip URL or ID.

The Twitch embed API distinguishes between live streams, VODs (video IDs), and clips (clip slugs). Interactive JavaScript embeds might not fully support clip slugs in the same way they do for VODs or live channels, and the expected ID format differs.

fix

For interactive embeds, ensure you are using a Twitch VOD ID (e.g., `v123456789`) or a channel name for live content. If you specifically need to embed a clip interactively, you might need to use the dedicated Twitch Clips embed iframe structure rather than the general player API, or wrap it in a non-interactive iframe.

Upgrade

Version history

0.1.6latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/muxinc/media-elements ↗

packagehttps://www.npmjs.com/package/twitch-video-element ↗