The @mux/convex package is a reusable Convex component that bridges Mux video services with the Convex backend. It provides database tables for Mux resources, webhook handling, and query helpers for building video applications.

What you'll get

After setup, your Convex database will have tables for:

• assets - Mux video assets and their metadata
• uploads - Direct upload records
• liveStreams - Live stream configurations and status
• events - Webhook event history
• videoMetadata - App-level metadata (user ID, title, description, visibility, tags, custom fields)

Prerequisites

Before you begin, make sure you have:

• A Mux account with API credentials
• A Convex project with a convex/ directory already initialized
• The Convex CLI installed (npm install -g convex)
• A TypeScript web application (e.g., Next.js, React, or any Convex-supported framework)

1. Install packages

Install the required packages in your project:

npm install convex @mux/convex @mux/mux-node

2. Generate project files

Run the initialization script to generate the required Convex files:

npx @mux/convex init --component-name mux

This creates four files in your convex directory:

• convex.config.ts - Mounts the Mux component into your Convex app
• migrations.ts - Backfill function for syncing existing Mux assets
• muxWebhook.ts - Webhook handler for receiving Mux events
• http.ts - HTTP route that exposes the webhook endpoint

If any of these files already exist, the CLI will skip them. Use --force to overwrite existing files.

3. Set environment variables

Configure your Mux API credentials in Convex:

npx convex env set MUX_TOKEN_ID your-mux-token-id
npx convex env set MUX_TOKEN_SECRET your-mux-token-secret

You can find your API credentials in the Mux Dashboard.

4. Start development and backfill

Start the Convex development server:

npx convex dev

In another terminal, run the backfill migration to sync your existing Mux assets:

npx convex run migrations:backfillMux '{}'

This will import your existing Mux assets into the Convex assets and videoMetadata tables. You can customize the backfill with options:

npx convex run migrations:backfillMux '{"maxAssets": 500, "defaultUserId": "my-user-id", "includeVideoMetadata": true}'

5. Configure the Mux webhook

In the Mux Dashboard, create a new webhook with your Convex HTTP endpoint as the URL:

https://your-deployment.convex.site/mux/webhook

Mux will send all events to this endpoint. The component automatically handles routing asset, live stream, and upload events to the appropriate tables and ignores unsupported event types.

After creating the webhook, copy the signing secret and add it to your Convex environment:

npx convex env set MUX_WEBHOOK_SECRET your-webhook-signing-secret

Verify the setup

Check your Convex dashboard to verify the tables are populated:

1. Navigate to your project's Data tab
2. You should see the Mux tables: assets, uploads, liveStreams, events, and videoMetadata
3. Upload a test video in Mux and verify it appears in your Convex database

Querying your data

The component syncs Mux data into your Convex database via webhooks. To access that data, you wrap the component's built-in queries with your own Convex functions, then call those functions from your frontend.

Define your queries

Create a new file in your convex directory (e.g., convex/videoQueries.ts) to wrap the component queries:

import { query } from './_generated/server';
import { components } from './_generated/api';
import { v } from 'convex/values';

// Returns an array of asset objects, each containing:
// muxAssetId, status, playbackIds, durationSeconds, aspectRatio, tracks, etc.
export const listAssets = query({
  handler: async (ctx) => {
    return await ctx.runQuery(components.mux.catalog.listAssets, {});
  },
});

// Returns a single asset object or null
export const getAsset = query({
  args: { muxAssetId: v.string() },
  handler: async (ctx, args) => {
    return await ctx.runQuery(components.mux.catalog.getAssetByMuxId, {
      muxAssetId: args.muxAssetId,
    });
  },
});

// Returns an array of { metadata, asset } pairs for a given user
export const getUserVideos = query({
  args: { userId: v.string() },
  handler: async (ctx, args) => {
    return await ctx.runQuery(components.mux.videos.listVideosForUser, {
      userId: args.userId,
    });
  },
});

Use queries in your frontend

Call these queries from your React components using Convex's useQuery hook:

import { useQuery } from 'convex/react';
import { api } from '../convex/_generated/api';

function VideoList() {
  const assets = useQuery(api.videoQueries.listAssets);

  if (!assets) return <div>Loading...</div>;

  return (
    <ul>
      {assets.map((asset) => (
        <li key={asset.muxAssetId}>
          {asset.muxAssetId} — {asset.status}
        </li>
      ))}
    </ul>
  );
}

These queries are reactive — your UI will update automatically when the underlying data changes in Convex, such as when a webhook updates an asset's status.

Available queries

The component exposes the following queries through components.mux:

All list queries accept an optional limit parameter (default: 50).

Adding video metadata

The catalog queries above return Mux-level data synced via webhooks. The video metadata system lets you layer your own app-level data — like titles, descriptions, user ownership, and visibility — on top of those synced assets.

import { mutation } from './_generated/server';
import { components } from './_generated/api';
import { v } from 'convex/values';

export const setVideoMetadata = mutation({
  args: {
    muxAssetId: v.string(),
    userId: v.string(),
    title: v.optional(v.string()),
    description: v.optional(v.string()),
    visibility: v.optional(
      v.union(v.literal('public'), v.literal('private'), v.literal('unlisted'))
    ),
    tags: v.optional(v.array(v.string())),
  },
  handler: async (ctx, args) => {
    await ctx.runMutation(components.mux.videos.upsertVideoMetadata, {
      muxAssetId: args.muxAssetId,
      userId: args.userId,
      title: args.title,
      description: args.description,
      visibility: args.visibility,
      tags: args.tags,
    });
  },
});

Once metadata is set, queries like videos.listVideosForUser and videos.getVideoByMuxAssetId will return both the Mux asset data and your app-level metadata together.

Important notes

Resources

• GitHub repository
• Convex documentation
• Mux API reference