Mux & Astro
Ta treść nie jest jeszcze dostępna w Twoim języku.
Mux is a hosted media service that provides video streaming infrastructure and performance analytics for businesses of all scales.
When you use Mux to store and host your video content, you’ll have access to Astro-native video components for Mux Player, a drop-in component for adding Mux videos in your Astro project, and Mux Uploader for uploading videos to Mux from your website. These components integrate seamlessly with Mux Data to track your video engagement and performance.
You can also interact with your content through the Mux Node SDK.
Learn more about features such as embedding, storing, streaming, and customizing video at Mux’s dedicated page for video in Astro!
Using Mux in Astro
Section titled “Using Mux in Astro”Mux’s APIs and web components work in Astro to compress and optimize your videos and streams for the web, adapt the quality of your video to network conditions, and integrate additional features like captions, thumbnails, and analytics. The Mux Node SDK supports both Mux Data and the Mux Video API.
Prerequisites
Section titled “Prerequisites”- An existing Astro project. Some features may additionally require an adapter installed for on-demand server rendering.
- A Mux account. If you don’t have an account, you can sign up with Mux using the code
ASTRO
to receive a $50 credit.
Mux Player
Section titled “Mux Player”In Astro, you can use the full-featured Mux Player as a native Astro component for optimized, responsive video playback and live streams.
Mux Player provides a responsive UI based on video player dimensions and stream type, automatic thumbnail previews and poster images, and modern video player capabilities (e.g. fullscreen, picture-in-picture, Chromecast, AirPlay).
---import { MuxPlayer } from "@mux/mux-player-astro";---<MuxPlayer playbackId="DS00Spx1CV902MCtPj5WknGlR102V5HFkDe" metadata={{ video_title: 'My Astro Video' }}/>
Mux Player has built-in support for Mux Data analytics, and will automatically show visitor engagement and video quality metrics in your dashboard once your video has views on your deployed site.
Installation
Section titled “Installation”Install the Astro version of Mux Player using your preferred package manager:
npm install @mux/mux-player-astro
pnpm add @mux/mux-player-astro
yarn add @mux/mux-player-astro
Mux Player can also be used in your Astro project as:
- a web component (
<mux-player>
from@mux/mux-player
) - a React component (
<MuxPlayer />
from@mux/mux-player-react
) - an HTML web embed (
<iframe>
)
Play a video from Mux
Section titled “Play a video from Mux”Import and use the native <MuxPlayer />
Astro component directly in your .astro
files like any other Astro component.
You will need the playbackId
for your asset, which can be found in your Mux dashboard or retrieved from its ASSET_ID
.
All other options to control the Mux web player (e.g. hide or display controls, style elements, disable cookies) are optional:
<MuxPlayer playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00" metadata={{ video_title: 'Starlight by Astro', }} style={{ display: 'block', aspectRatio: '16/9', backgroundColor: '#000', margin: '1rem 0 2rem', }} primaryColor="#f2ec3a" secondaryColor="#0caa09" accentColor="#6e1e99" defaultShowRemainingTime={true}/>
If your playbackId
belongs to a live stream instead of a prerecorded video on demand, then the Mux Player will allow you to further customize the player with options such as whether or not to enable DVR mode.
<MuxPlayer playbackId="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00" metadata={{ video_title: 'Starlight stream with Astro', }} streamType="live:dvr"/>
Every live stream is recorded and saved on Mux as a video asset for future on-demand playback.
Mux video Element
Section titled “Mux video Element”The Mux video element is a drop-in replacement for the HTML5 <video>
element that provides browser support for HLS playback, and has Mux Data automatically configured to show visitor and performance metrics. Use this when you do not need or want all the features of Mux Player.
To use the <mux-video>
web component, first install mux-video
using your preferred package manager:
npm install @mux/mux-video
pnpm add @mux/mux-video
yarn add @mux/mux-video
Then, you can import and render the web component in a <script>
tag in your .astro
file.
You will need the playback-id
for your video asset, which can be found in your Mux dashboard or retrieved from its ASSET_ID
.
All attributes for the HTML 5 <video>
element (e.g. poster
, controls
, muted
) are available, as well as additional Mux video player controls (e.g. to provide metadata, control the resolution, disable cookies):
<script>import '@mux/mux-video'</script>
<mux-video playback-id="FOTbeIxKeMPzyhrob722wytaTGI02Y3zbV00NeFQbTbK00" metadata-video-title="Starlight by Astro" controls disable-tracking></mux-video>
Mux Node SDK
Section titled “Mux Node SDK”The Mux Node SDK provides authenticated access to the Mux REST API from server-side TypeScript or JavaScript. This allows you to interact with your Mux assets and data in the component script of your .astro
files.
While the Mux Player and Mux Video components do not require authentication and can play any publicly accessible video given its playbackId
, connecting to your hosted Mux data via the Node SDK requires a Mux API access token.
Installation
Section titled “Installation”Install the Mux Node SDK using your preferred package manager:
npm install @mux/mux-node
pnpm add @mux/mux-node
yarn add @mux/mux-node
Mux Environment API access
Section titled “Mux Environment API access”API tokens are tied to a specific Mux Environment, which is essentially a container for your videos and related data. When you sign up for Mux, an Environment is created for you automatically. If you’ve created additional Environments, make sure you select the correct one before generating your tokens. From there, you can get your ID and SECRET tokens and provide them to the Node SDK. These tokens can be passed into your Astro components as environment variables stored in a .env
file.
This will allow you to create an instance of the Mux Node SDK for retrieving information about your videos, creating new assets, accessing metrics and real-time performance, and more:
---import Mux from "@mux/mux-node";
const mux = new Mux ({ tokenId: import.meta.env.MUX_TOKEN_ID, tokenSecret: import.meta.env.MUX_TOKEN_SECRET,})---
Retrieve asset data
Section titled “Retrieve asset data”To fetch information about your video to use in your Astro project, provide the video’s ASSET_ID
(available in the Mux dashboard) to the retrieve()
helper function. This will allow you to pass values to both your Mux components and your HTML template, such as the video’s title or duration:
---import Mux from "@mux/mux-node";import { MuxPlayer } from "@mux/mux-player-astro";
const mux = new Mux({ tokenId: import.meta.env.MUX_TOKEN_ID, tokenSecret: import.meta.env.MUX_TOKEN_SECRET,})
const ASSET_ID = "E01irAaN8c6dk1010153uC2mzst7RVbAdJJWtHECAHFvDo";const asset = await mux.video.assets.retrieve(ASSET_ID);
const playbackId = asset.playback_ids?.find((id)=> id.policy=== "public")?.id;const videoTitle = asset?.meta?.title;const createdAt = Number(asset?.created_at);const duration = Number(asset?.duration)
const date = new Date(createdAt * 1000).toDateString()const time = new Date(Math.round(duration) * 1000).toISOString().substring(14, 19)---<h1>My Video Page</h1><p>Title: {videoTitle}</p><p>Upload Date: {date}</p><p>Length: {time}</p>
<MuxPlayer playbackId={playbackId} metadata={{video_title: videoTitle}}/>
See all asset properties in the Mux Asset API documentation.
Mux Uploader
Section titled “Mux Uploader”Mux Uploader is a fully-functional, customizable video upload UI for your Astro website. The native Astro <MuxUpload />
component allows you to build video upload functionality into your web app.
Mux Uploader supports both manual file selection and drag and drop for file uploads, optional pausing and resuming of uploads, and more.
Installation
Section titled “Installation”Install the Astro version of Mux Uploader using your preferred package manager:
npm install @mux/mux-uploader-astro
pnpm add @mux/mux-uploader-astro
yarn add @mux/mux-uploader-astro
Upload a video to Mux
Section titled “Upload a video to Mux”Before uploading a video, make sure you have your Mux API access tokens configured. With those in place, you can use the create()
function from the Mux Node SDK to start a new video upload:
---import Layout from '../../layouts/Layout.astro';import Mux from "@mux/mux-node";import { MuxUploader } from "@mux/mux-uploader-astro";
const mux = new Mux({ tokenId: import.meta.env.MUX_TOKEN_ID, tokenSecret: import.meta.env.MUX_TOKEN_SECRET});
const upload = await mux.video.uploads.create({ new_asset_settings: { playback_policy: ['public'], video_quality: 'basic' }, cors_origin: '*',});---<Layout title="Upload a video to Mux"> <MuxUploader endpoint={upload.url} /></Layout>
Customize the uploader
Section titled “Customize the uploader”You can customize the functionality and appearance of the <MuxUploader />
with additional component attributes. In addition to styling your element, this allows you to control options such as the ability to pause a download or set a maximum file size.
---import { MuxUploader } from '@mux/mux-uploader-astro';---
<MuxUploader endpoint="https://my-authenticated-url/storage?your-url-params" pausable maxFileSize={1000000000} chunkSize={8192} style={{ '--progress-bar-fill-color': '#7e22ce', '--button-background-color': '#f0f0f0', }}/>
See the Mux Uploader customization guide for more options.
Event handling for uploads
Section titled “Event handling for uploads”Mux Uploader provides a feature-rich, dynamic UI that changes based on the current state of your media upload. The uploader’s behavior responds to both user-driven events (e.g. selecting a file, retrying after an error) and state-driven events (e.g. upload in-progress, upload successfully completed).
You can listen for these events and handle them in your Astro component with client-side scripts. A MuxUploaderElement
type is also available.
---import { MuxUploader } from '@mux/mux-uploader-astro';---
<MuxUploader id="my-uploader" endpoint="https://my-authenticated-url/storage?your-url-params" pausable/>
<script> import type { MuxUploaderElement } from '@mux/mux-uploader-astro';
const uploader = document.getElementById('my-uploader') as MuxUploaderElement;
uploader.addEventListener('uploadstart', (event) => { console.log('Upload started!', event.detail); });
uploader.addEventListener('success', (event) => { console.log('Upload successful!', event.detail); });
uploader.addEventListener('uploaderror', (event) => { console.error('Upload error!', event.detail); });
uploader.addEventListener('progress', (event) => { console.log('Upload progress: ', event.detail); });</script>
Official Resources
Section titled “Official Resources”For the full API and webhook reference, usage guides, and information about additional topics, such as integrating with a CMS, building custom video workflows, and more, please see:
- The official Mux documentation for Astro
@mux/mux-player-astro
API reference@mux/mux-uploader-astro
API reference- Building a video uploader with Mux and Astro (YouTube)
- Astro uploader and player code example (GitHub)