# Mux Background Video A super lightweight component and HLS engine for creating background videos using Mux HLS streams. ## Features - **Background Video**: Perfect for hero sections, landing pages, and immersive experiences - **HLS Video Support**: Built-in HLS video engine for smooth streaming - **React**: React component for easy integration - **Web Components**: Custom element for easy integration - **TypeScript Support**: Full TypeScript definitions included - **Lightweight**: Minimal bundle size with no dependencies - **Preload Control**: Control video preloading behavior - **Audio Control**: Optionally enable audio tracks for background videos - **Resolution Control**: Set maximum resolution for optimal performance ## Installation ```bash npm install mux-embed # Enable Mux Data integration npm install @mux/mux-background-video ``` ## Usage > [!IMPORTANT] > Requires Mux [Basic](https://www.mux.com/docs/guides/use-video-quality-levels#basic) or [Premium](https://www.mux.com/docs/guides/use-video-quality-levels#premium) video quality. The [Plus](https://www.mux.com/docs/guides/use-video-quality-levels#plus) tier (and other classic HLS sources) is **not** supported because it serves MPEG-TS (`.ts`) segments, which this engine does not transmux. ### HTMLCustom Element The easiest way to use Mux Background Video is with the custom element: ```html Background Video Mux Background Video ``` ### JavaScript Import You can also import the custom element directly: ```ts import 'mux-embed'; // (optional) Enable Mux Data integration import '@mux/mux-background-video/html'; // The custom element is automatically registered // You can now use in your HTML ``` ### React Component For React applications, use the React component: ```tsx import 'mux-embed'; // (optional) Enable Mux Data integration import { MuxBackgroundVideo } from '@mux/mux-background-video/react'; function HeroSection() { return ( Mux Background Video ); } ``` ## Mux Data Integration [Mux data](https://www.mux.com/data) integrates with video players to provide detailed analytics and insights about video performance, which can be found in the Mux dashboard. Mux can also use this performance data to help improve the player and streaming. All that's required to use Mux data is including or importing the script. Once the script is included, Mux data will automatically be enabled for all background videos on the page. ```html ``` ## API Reference ### HTML Custom Element: `` The `` element automatically handles HLS streaming. #### Attributes - **`src`**: The Mux HLS stream URL (required) - **`max-resolution`**: Maximum resolution for the video (e.g., "720p", "1080p") - **`audio`**: Enable audio track (default: false) - **`preload`**: Controls video preloading behavior (default: auto) - `"none"`: No preloading - `"metadata"`: Preload only metadata - `"auto"`: Preload video data #### HTML Structure ```html Mux Background Video ``` #### JavaScript Attributes You can also set attributes programmatically: ```typescript const element = document.querySelector('mux-background-video'); // Set maximum resolution element.setAttribute('max-resolution', '1080p'); // Enable audio track element.toggleAttribute('audio', true); // Set preload behavior element.setAttribute('preload', 'metadata'); // Set the stream URL element.setAttribute('src', 'https://stream.mux.com/NEW_PLAYBACK_ID.m3u8'); // Get current values console.log(element.getAttribute('src')); console.log(element.getAttribute('max-resolution')); console.log(element.hasAttribute('audio')); console.log(element.getAttribute('preload')); ``` ### React Component: `MuxBackgroundVideo` #### Props - **`src`**: The Mux HLS stream URL (required) - **`maxResolution`**: Maximum resolution for the video (e.g., "720p", "1080p") - **`audio`**: Enable audio track (default: false) - **`preload`**: Controls video preloading behavior (default: auto) - `"none"`: No preloading - `"metadata"`: Preload only metadata - `"auto"`: Preload video data #### Example ```tsx Mux Background Video ``` ## Development ### Prerequisites - Node.js 18+ - npm or yarn ### Setup 1. Clone the repository: ```bash git clone cd mux-background-video ``` 2. Install dependencies: ```bash npm install ``` 3. Start the development server: ```bash npm start ``` ### Development Commands - **`npm start`**: Start development server with watch mode - **`npm run build`**: Build the project - **`npm run watch`**: Watch for changes and rebuild - **`npm test`**: Run tests locally - **`npm run test:browserstack`**: Run integration tests on BrowserStack - **`npm run setup:browserstack`**: Interactive setup for BrowserStack credentials ### Testing #### Local Testing Run tests locally: ```bash npm test ``` ### Development Server When running the dev server, you can use the following URL parameters: - **`PLAYBACK_ID`**: Set a custom Mux playback ID (defaults to demo video) - **`max-resolution`**: Set maximum resolution for the background video - **`audio`**: Enable or disable audio track (default: false) - **`preload`**: Set preload behavior ("none", "metadata", or "auto") - **`debug`**: Enable debug mode - **`nomuted`**: Disable muted attribute - **`noloop`**: Disable loop attribute - **`noautoplay`**: Disable autoplay attribute Example: ``` http://localhost:3000/PLAYBACK_ID?max-resolution=720p&audio=1&preload=metadata ``` ## License MIT License - see LICENSE file for details. ## Contributing Contributions are welcome! Please feel free to submit a Pull Request. ## Support For issues and questions, please [open an issue](https://github.com/muxinc/mux-background-video/issues/new) on GitHub.