Integrate Mux with Strapi
Stream and manage high-quality video content in Strapi with Mux’s powerful video infrastructure.
These integration guides are not official documentation and the Strapi Support Team will not provide assistance with them.
What Is Mux?
Mux is an API platform built specifically for video, letting developers create sophisticated live and on-demand video experiences through simple API calls. Instead of managing complex infrastructure, you make API requests while Mux handles the technical processing.
The platform manages processing, storage, and delivery with automatic transcoding into multiple formats and resolutions. This adaptive approach ensures smooth playback regardless of device or connection speed—viewers always get the best quality their current setup can handle.
Mux distributes content through a global CDN, putting videos closer to viewers worldwide to cut latency and speed up loading. You also get real-time analytics showing performance, engagement, and delivery metrics.
For developers building content systems, Mux's integration capabilities provide robust video functionality without requiring you to manage complex infrastructure yourself.
Why Integrate Mux with Strapi
Combining Strapi's headless CMS with Mux's video processing creates a powerful content system that addresses the unique challenges of video-first applications. It brings together intuitive content management with reliable video infrastructure.
Your content team can upload videos directly in Strapi without switching between platforms or managing complex workflows. They can handle videos alongside text, images, and other media in one familiar interface. The Mux Video Uploader plugin transforms video management from a technical challenge into a straightforward editorial process.
This integration is particularly valuable when videos need to connect with custom collection types. Whether you're building a learning system, media library, or product showcase, you can create content models that fit your specific business requirements. Videos become first-class citizens in your content architecture, not awkward add-ons.
The streamlined workflow eliminates friction between creation and delivery. Your team can upload, organize, and publish video content without switching tools or waiting for technical teams to handle processing.
Strapi's role-based access control protects your video content by precisely controlling who can upload videos, edit metadata, and publish. Your valuable video assets remain secure throughout their lifecycle.
As your video library grows, Strapi's flexible architecture adapts while Mux handles the technical complexities of processing, storage, and global delivery.
Strapi Cloud and v5 enhance this integration with advanced features and improved performance, bringing enterprise-scale video management within reach.
To get started with this powerful combination, you can deploy Strapi, explore our demo, or join our community.
How to Integrate Mux with Strapi
Setting up Strapi and Mux requires attention to detail and good security practices. We'll walk through the process step by step, from initial setup to video playback in your frontend.
Prerequisites
Before starting, you'll need:
- Node.js version 16 or higher
- NPM or Yarn as your package manager
- Git for version control
- A free Mux account for their video API services
- A publicly accessible Strapi installation
The public accessibility requirement creates a challenge for local development. You'll need a webhook relay service like SMEE or tools like ngrok to make your local server reachable.
It's important to prioritize security throughout this process. Never commit API keys or sensitive credentials to your repository. Use environment variables to store these values securely. Use a .env file for local development (add it to your .gitignore) and proper environment management in production.
Installing the Mux Video Uploader Plugin
Different Strapi versions need different plugin versions, so install the right one for your setup.
For Strapi v4, use the latest plugin version:
npm i strapi-plugin-mux-video-uploader@latestIf you're using Yarn:
yarn add strapi-plugin-mux-video-uploader@latestFor Strapi v3 installations, use version 2.0.0 specifically:
npm i strapi-plugin-mux-video-uploader@2.0.0Or with Yarn:
yarn add strapi-plugin-mux-video-uploader@2.0.0Restart your Strapi instance after installation for the plugin to take effect. This step is crucial for Strapi to recognize and initialize the plugin properly.
Creating and Configuring Mux Access Tokens
Proper token management creates secure communication between Strapi and Mux. To get started, log into your Mux account, go to Settings, then API Access Tokens.
Click "Generate new token" with appropriate settings. Choose "Development" for your development environment. Select "Mux Video" as the service and enable both "Read" and "Write" permissions. These permissions allow your Strapi app to both retrieve video information and upload new content.
After generating the token, you'll get both an Access Token ID and a Secret Key. Copy both immediately—the Secret Key won't appear again for security reasons. Store these credentials using environment variables, not hardcoded in your application.
In your Strapi admin panel, go to the Mux Video Uploader plugin settings. Enter your Mux Access Token ID and Secret Key in the fields provided. Save to connect Strapi with your Mux account. Test by uploading a small video file to ensure everything works correctly.
Setting Up Webhooks
Webhooks provide real-time updates about video processing from Mux. When you upload a video, it goes through various processing stages, and webhooks keep Strapi informed without constant polling.
In your Mux dashboard, go to "Webhooks" and create a new webhook. The webhook URL should follow this format: https://your-strapi-domain.com/strapi-plugin-mux-video-uploader/webhooks. Replace "your-strapi-domain.com" with your actual domain. Select the events you want to track, like upload completion, encoding progress, and error notifications.
For local development, you need special handling since Mux can't reach your local server directly. Set up a webhook relay using a service like SMEE. Create a SMEE channel at smee.io and install the SMEE client:
npm install -g smee-clientRun the SMEE client to forward webhook events to your local Strapi:
smee --url https://smee.io/your-unique-channel --path /strapi-plugin-mux-video-uploader/webhooks --port 1337Use the SMEE URL as your webhook endpoint in the Mux dashboard instead of your local URL. This creates a tunnel allowing Mux to send webhook events to your local environment.
Creating Content Types for Videos
With the plugin installed and configured, create a content type for managing video content. In your Strapi admin panel, go to Content-Types Builder to create a new collection type. Name it "Video" or something appropriate for your use case.
Add fields that make sense for your video content needs. Include Title for the video name, Description for content details, and Categories or Tags for organization. The key field is the Video field, which uses the Mux Video Uploader field type from the plugin.
Consider adding Featured Image for thumbnails, Release Date for scheduling, and Duration for display. You might also want fields for SEO metadata, content ratings, or other attributes specific to your application.
Save your content type and restart Strapi if prompted. Content editors can now use this type to upload videos directly through the Strapi interface. The Video Uploader field provides an intuitive interface for selecting and uploading videos, with real-time feedback about upload progress and processing.
Implementing Video Playback in Frontend Applications
After setting up your backend, implement video playback in your frontend application. We'll use Next.js as an example, though the principles apply to other React-based frameworks too.
To get started, set up a Next.js project if you don't have one:
npx create-next-app my-video-app
cd my-video-appInstall the Mux React Player component:
npm install @mux/mux-player-reactCreate a component to fetch and display videos from your Strapi API:
import { useState, useEffect } from 'react';
import MuxPlayer from '@mux/mux-player-react';
export default function VideoGallery() {
const [videos, setVideos] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function fetchVideos() {
try {
const response = await fetch('https://your-strapi-api.com/api/videos?populate=*');
const data = await response.json();
setVideos(data.data);
} catch (error) {
console.error('Error fetching videos:', error);
} finally {
setLoading(false);
}
}
fetchVideos();
}, []);
if (loading) return <div>Loading videos...</div>;
return (
<div className="video-gallery">
<h1>Video Gallery</h1>
<div className="video-grid">
{videos.map((video) => (
<div key={video.id} className="video-card">
<h2>{video.attributes.title}</h2>
<p>{video.attributes.description}</p>
<MuxPlayer
streamType="on-demand"
playbackId={video.attributes.muxVideo.data.attributes.playbackId}
metadata={{
video_title: video.attributes.title,
video_id: video.id,
}}
style={{ aspectRatio: '16/9', width: '100%' }}
/>
</div>
))}
</div>
</div>
);
}This implementation fetches video data from your Strapi API and renders each video using the Mux Player component. The player handles adaptive streaming automatically, ensuring optimal playback quality based on the viewer's connection and device.
Replace the API URL with your actual Strapi endpoint and adjust the data structure access based on your content type configuration. The integration tutorial provides more examples and customization options for complex implementations.
Project Example: Build a Learning Management System with Strapi and Mux
Let's explore "EduStream," a learning management system that demonstrates the capabilities of integrating Mux with Strapi.
The backend uses Strapi v4 with the Video Uploader plugin handling seamless uploads. Here's how to set up your content structure:
// api/course/content-types/course/schema.json
{
"kind": "collectionType",
"collectionName": "courses",
"info": {
"singularName": "course",
"pluralName": "courses",
"displayName": "Course"
},
"options": {
"draftAndPublish": true
},
"attributes": {
"title": {
"type": "string",
"required": true
},
"description": {
"type": "richtext"
},
"videos": {
"type": "relation",
"relation": "oneToMany",
"target": "api::video.video"
}
}
}// api/video/content-types/video/schema.json
{
"kind": "collectionType",
"collectionName": "videos",
"info": {
"singularName": "video",
"pluralName": "videos",
"displayName": "Video"
},
"options": {
"draftAndPublish": true
},
"attributes": {
"title": {
"type": "string",
"required": true
},
"description": {
"type": "text"
},
"duration": {
"type": "decimal"
},
"transcript": {
"type": "richtext"
},
"categories": {
"type": "enumeration",
"enum": ["beginner", "intermediate", "advanced"]
},
"asset": {
"type": "customField",
"customField": "plugin::mux-video-uploader.asset"
},
"course": {
"type": "relation",
"relation": "manyToOne",
"target": "api::course.course",
"inversedBy": "videos"
}
}
}After setting up your content types, follow these steps to implement the integration:
- Install the plugin in your Strapi project:
cd your-strapi-project
npm i strapi-plugin-mux-video-uploader@latest- Configure environment variables:
# .env
MUX_TOKEN_ID=your_token_id
MUX_TOKEN_SECRET=your_token_secret
MUX_WEBHOOK_SECRET=your_webhook_secret- Restart Strapi and verify the plugin appears in your admin panel
The Next.js frontend uses React Player components for intuitive browsing. Here's a sample component for displaying a course video:
// components/VideoPlayer.js
import React, { useState } from 'react';
import ReactPlayer from 'react-player';
const VideoPlayer = ({ video }) => {
const [playing, setPlaying] = useState(false);
const [playbackRate, setPlaybackRate] = useState(1);
// Extract playback ID from Mux asset
const playbackId = video?.asset?.data?.attributes?.playbackId;
if (!playbackId) return <div>Video not available</div>;
const videoUrl = `https://stream.mux.com/${playbackId}.m3u8`;
return (
<div className="video-container">
<h2>{video.title}</h2>
<div className="player-wrapper">
<ReactPlayer
url={videoUrl}
controls
playing={playing}
playbackRate={playbackRate}
width="100%"
height="100%"
onPlay={() => setPlaying(true)}
onPause={() => setPlaying(false)}
/>
</div>
<div className="playback-controls">
<button onClick={() => setPlaybackRate(0.75)}>0.75x</button>
<button onClick={() => setPlaybackRate(1)}>1x</button>
<button onClick={() => setPlaybackRate(1.5)}>1.5x</button>
<button onClick={() => setPlaybackRate(2)}>2x</button>
</div>
{video.transcript && (
<div className="transcript">
<h3>Transcript</h3>
<div dangerouslySetInnerHTML={{ __html: video.transcript }} />
</div>
)}
</div>
);
};
export default VideoPlayer;To fetch course data from Strapi, implement an API service:
// services/api.js
const API_URL = process.env.NEXT_PUBLIC_API_URL || 'http://localhost:1337';
export async function getCourses() {
const res = await fetch(`${API_URL}/api/courses?populate=*`);
const data = await res.json();
return data.data;
}
export async function getCourse(id) {
const res = await fetch(
`${API_URL}/api/courses/${id}?populate[videos][populate]=*`
);
const data = await res.json();
return data.data;
}
export async function getVideo(id) {
const res = await fetch(`${API_URL}/api/videos/${id}?populate=*`);
const data = await res.json();
return data.data;
}For the course listing page:
// pages/courses/index.js
import { useEffect, useState } from 'react';
import Link from 'next/link';
import { getCourses } from '../../services/api';
export default function Courses() {
const [courses, setCourses] = useState([]);
const [loading, setLoading] = useState(true);
useEffect(() => {
async function loadCourses() {
try {
const data = await getCourses();
setCourses(data);
} catch (error) {
console.error('Error loading courses:', error);
} finally {
setLoading(false);
}
}
loadCourses();
}, []);
if (loading) return <div>Loading courses...</div>;
return (
<div className="courses-grid">
{courses.map(course => (
<Link href={`/courses/${course.id}`} key={course.id}>
<div className="course-card">
<h2>{course.attributes.title}</h2>
<p>{course.attributes.description}</p>
<span>{course.attributes.videos?.data?.length || 0} videos</span>
</div>
</Link>
))}
</div>
);
}Security follows best practices with environment-stored API tokens and role-based access limiting premium content to enrolled students. Here's how to implement role-based access:
// api/course/controllers/course.js
'use strict';
module.exports = {
async find(ctx) {
// Check if user is logged in
if (!ctx.state.user) {
return ctx.unauthorized('You must be logged in');
}
// Get user roles
const { id } = ctx.state.user;
const user = await strapi.entityService.findOne('plugin::users-permissions.user', id, {
populate: ['role', 'enrollments']
});
// Define query based on user role
let query = {};
// If not admin, only show enrolled courses
if (user.role.name !== 'Administrator') {
const enrolledCourseIds = user.enrollments.map(enrollment => enrollment.course.id);
query = {
id: { $in: enrolledCourseIds }
};
}
// Execute the query with populated videos
const courses = await strapi.entityService.findMany('api::course.course', {
filters: query,
populate: ['videos']
});
return courses;
}
};Webhooks provide real-time processing updates, informing users when new content becomes available. To handle this on the frontend:
// utils/notifications.js
import { toast } from 'react-toastify';
export function setupVideoProcessingListener(userId) {
const eventSource = new EventSource(`/api/notifications/sse?userId=${userId}`);
eventSource.onmessage = (event) => {
const data = JSON.parse(event.data);
if (data.type === 'video_ready') {
toast.success(`New video available: ${data.videoTitle}`);
}
};
eventSource.onerror = () => {
eventSource.close();
setTimeout(() => setupVideoProcessingListener(userId), 5000);
};
return () => eventSource.close();
}The interface features a responsive grid with auto-generated thumbnails, embedded players supporting speed controls and quality selection, plus a progress-tracking dashboard. The design focuses on clean navigation and smooth playback across devices.
This implementation demonstrates how Strapi's content flexibility combines with Mux's processing power to build scalable applications with excellent user experience and security.
You can explore the full EduStream codebase in our GitHub repository, including backend configuration, frontend components, deployment scripts, and production documentation.
Strapi Open Office Hours
If you have any questions about Strapi 5 or just would like to stop by and say hi, you can join us at Strapi's Discord Open Office Hours Monday through Friday at 12:30 pm – 1:30 pm CST.
For more details, visit the Strapi documentation and Mux.