Mux Video Upload & Asset Management

Version 1.0.75 introduces full Mux video integration across the platform. Coaches can attach videos to movement library entries and Skills School lessons, members can submit videos for review, and all content is delivered via adaptive streaming — no manual transcoding or CDN configuration required.

Overview

Mux is the video infrastructure layer used by the platform. It handles:

Upload — direct-to-Mux uploads via server-issued URLs
Transcoding — automatic processing into multiple quality tiers
Delivery — HLS adaptive bitrate streaming to all devices
Asset lifecycle — webhook events signal when assets are ready for playback

How Video Upload Works

1. Server-Side Upload URL Generation

The client never directly communicates with Mux using API credentials. Instead, the server generates a short-lived, authenticated upload URL and returns it to the client.

POST /api/video/upload-url

The response contains a one-time upload URL. The client then PUTs the video file directly to that URL.

Why server-side? This keeps Mux API keys off the client and allows the server to associate the resulting asset with the correct record (movement, lesson, or member submission) before the upload begins.

2. Direct Upload from the Browser

Once the client receives the upload URL, the video file is sent directly from the browser to Mux's ingest endpoint. This avoids routing large video files through your own servers.

PUT <mux_upload_url>
Content-Type: video/*

<binary video data>

3. Transcoding

Mux automatically transcodes the uploaded file into multiple resolutions and packages it as an HLS stream. This process is asynchronous — the asset is not immediately available for playback.

4. Webhook: Asset Ready

When transcoding completes, Mux sends a video.asset.ready webhook to the platform. The webhook handler updates the corresponding record's status from processing to ready, making it visible and playable to end users.

POST /api/webhooks/mux

The handler verifies the Mux webhook signature before processing any event.

Affected Flows

Movement Library

Coaches and admins can attach a demonstration video to any movement entry. The video is uploaded via the upload URL flow described above. Members see the Mux player inline on the movement detail page once the asset is ready.

Skills School

Lesson videos in Skills School use the same upload pipeline. Instructors upload video through the lesson editor; learners see the adaptive player embedded in the lesson view.

Member Video Submissions

Members can submit a video recording of a movement or workout for coach review. The submission flow:

Member selects or records a video on their device.
The app requests an upload URL from the server.
The video uploads directly to Mux.
The submission record is created with status processing.
On video.asset.ready, the submission status updates to ready.
The assigned coach receives the submission in their review queue with an embedded Mux player.

MuxPlayer Component

A reusable MuxPlayer UI component is available across all contexts that require video playback. It wraps the Mux player SDK with platform-consistent styling and default controls.

Props

Prop	Type	Description
`playbackId`	`string`	The Mux playback ID for the asset
`title`	`string`	Accessible title for the player (used by screen readers)
`autoPlay`	`boolean`	Whether to start playback automatically (default: `false`)
`muted`	`boolean`	Whether to start muted (default: `false`)

Example Usage

import { MuxPlayer } from '@/components/MuxPlayer';

<MuxPlayer
  playbackId="your-mux-playback-id"
  title="Barbell Back Squat — Demo"
/>

The component is used in:

Movement library detail pages
Skills School lesson views
Coach submission review screens

Asset Status Lifecycle

uploading  →  processing  →  ready
                              │
                              └─ errored  (on Mux asset error event)

Status	Description
`uploading`	Upload URL issued; file transfer in progress
`processing`	Mux has received the file; transcoding underway
`ready`	Asset transcoded and available for playback
`errored`	Transcoding failed; upload should be retried

Configuration

The following environment variables are required for Mux integration:

Variable	Description
`MUX_TOKEN_ID`	Mux API token ID — from the Mux dashboard under Settings → API Tokens
`MUX_TOKEN_SECRET`	Mux API token secret — paired with `MUX_TOKEN_ID`
`MUX_WEBHOOK_SECRET`	Signing secret used to verify incoming Mux webhook payloads

Obtain these from your Mux dashboard.

Notes

Videos are not shown to members until asset status is ready. Content flagged as processing renders a loading/pending state in the UI.
All webhook events are idempotent — duplicate delivery of a video.asset.ready event will not cause duplicate state changes.
There is no file size limit enforced at the platform level; Mux's own limits apply.