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/mux-background-video
`

Usage

> [!IMPORTANT]
> Requires Mux Basic or Premium video quality currently because transmuxing of .ts segments is not supported.

$3

The easiest way to use Mux Background Video is with the custom element:

`html













`

$3

You can also import the custom element directly:

`ts
import '@mux/mux-background-video/html';

// The custom element is automatically registered
// You can now use in your HTML
`

$3

For React applications, use the React component:

`tsx
import { MuxBackgroundVideo } from '@mux/mux-background-video/react';

function HeroSection() {
return (



);
}
`

Mux Data Integration

To enable Mux data collection for your background videos, include the Mux embed script in your HTML page before the Mux Background Video script:

`html

`

Once this script is included, Mux data will automatically be enabled for all background videos on the page, providing you with detailed analytics and insights about video performance.

API Reference

$3

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



`

#### 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'));
`

$3

#### 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
src="https://stream.mux.com/YOUR_PLAYBACK_ID.m3u8"
maxResolution="720p"
audio={true}
>


`

Development

$3

- Node.js 18+
- npm or yarn

$3

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
`

$3

- 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

$3

#### Local Testing

Run tests locally:
`bash
npm test
`

$3

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 on GitHub.