---
name: "convention-mux"
type: convention
description: Conventions for Mux video in Aled's system — the per-project environment model, the setup sequence for standing up a dedicated Mux environment and least-privilege credentials, the Vercel/Sanity wiring, playback defaults, and what requires human action. Read before any operation that stands up or touches Mux video for a project, so the sequence is followed rather than re-derived each time. Sits beside convention-vercel and convention-sanity; grown as the conventions solidify.
license: CC BY-NC-SA 4.0
---

# convention-mux

How Mux is used for video in Aled's system. Stub — grown as the conventions solidify. Companion to `convention-vercel` (deployment) and `convention-sanity` (content), for the projects that carry video in a work/portfolio block. Standing up a Mux environment has been done operator-directed, step by step, for each project (meirionpritchard-com, careerOS) — this convention fixes the sequence so the next one is followed, not re-derived.

## Role

Mux is the video host and player for projects whose content model carries video (the work / portfolio block). The CMS holds the Mux asset reference; the front end renders the player from it. Mux has two products behind one dashboard — **Mux Video** (encoding, hosting, playback; this is what we use) and **Mux Data** (viewer analytics) — and the setup traps below turn on not confusing them.

## Projects in scope

| Project | Repo | Mux environment |
| -- | -- | -- |
| meirionpritchard-com | assoc-one/meirionpritchard-com | `meirionpritchard-com` |
| careerOS | (cOS.Build) | per COS-222 |

One Mux **environment per project** — this isolates assets, usage, and billing per project, the same per-project split as Vercel and Sanity.

## Setup — standing up a per-project Mux environment

New environment provisioning is **human** (the `agent`-group value) — it needs account-level Mux dashboard access and generates a secret shown once. The operator does it; agents reference the environment name and the Vercel-set credentials once they exist. The sequence:

1. **Create the environment.** Mux dashboard → environment switcher → **Create environment**, name it `<project>` (matching the repo/Vercel project), Member Access: All Members. One environment per project.
2. **Dismiss the "Get started with Data" onboarding.** Mux drops you into Mux **Data** (viewer analytics) first; its "Environment key" is **not** the Video credential. This is the common wrong turn — the Data env key does not authenticate Video API calls, so grabbing it here leads to a silent dead end. Skip past Data.
3. **Generate a Video API access token.** Settings → **API Access Tokens** → **Generate**, with the correct environment selected, scoped to **Mux Video → Read + Write only** (least-privilege — no Data, no System scopes). This yields `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET`; the secret is shown once, so capture it immediately.
4. **Wire the credentials into Vercel.** Add both `MUX_TOKEN_ID` and `MUX_TOKEN_SECRET` to the Vercel project (Production **and** Preview scopes), then redeploy. The embedded `/studio` (Sanity Studio) rides the same Vercel deploy, so no separate Sanity Studio environment variable is needed — the studio reads the same Vercel-injected values (see `convention-vercel` for env-var scopes, `convention-sanity` for the embedded-studio setup).
5. **Default to public playback** unless there is a specific reason to restrict. A signing key for signed/private playback can be added later without redoing the environment, so start public and tighten only if the content requires it.
6. **Pick the plan tier before the first upload, not after the first failure.** Mux's free tier caps stored video, and a project that will hold more than a handful of videos starts on a paid plan rather than discovering the cap in a client Studio. This is an **Owner action at setup** — it is an account and billing change, the same `human` class as creating the environment in step 1 — so it belongs in this sequence and not in an agent's build leg. Where a project is already live on the free tier and approaching the cap, the upgrade is its own ticket in the project's own team, never an unticked criterion on a build ticket. (Worked case: `meirionpritchard-com` was stood up on the free tier and hit the cap on 2026-09-23 with the environment otherwise correct; the upgrade is A1-505 and the two bugs it surfaced are A1-499 and A1-504.)

## Environment variables

- `MUX_TOKEN_ID` / `MUX_TOKEN_SECRET` — the Video API token pair, least-privilege (Read + Write on Mux Video only). Secrets live in Vercel, never in the repo (`convention-vercel`).
- Set on both **Production** and **Preview** scopes so preview deploys can also upload and play.

## Gotchas

- **Mux Data vs Mux Video.** The dashboard opens on Data; its "Environment key" is analytics, not a Video credential. Video calls need an **API Access Token** (id + secret) from Settings, scoped to Mux Video. Confusing the two is the standard setup wrong turn (step 2 above).
- **The secret is shown once.** `MUX_TOKEN_SECRET` is displayed at generation only. Capture it into Vercel immediately; if lost, generate a fresh token rather than hunting for it.
- **One environment per project.** Do not reuse one environment's token across projects — it defeats the per-project isolation of assets, usage, and billing.
- **Public by default is deliberate.** Signed playback adds a signing key and per-URL tokens; only take it on where the content genuinely needs restricting, since it can be added later without re-provisioning.
- **A bare `500` from the Sanity Mux proxy on upload is the plan cap, until the asset count says otherwise — count the assets in the Mux dashboard before debugging anything else.** `POST /addons/mux/uploads/<environment>` returns `500 Internal Server Error` with **no reason in the body** when the environment is at its stored-video cap, so the most available readings are all wrong and all expensive: a broken credential, a misconfigured proxy, a Studio defect, a Sanity outage. The cheap discriminator is one number — the count of assets in the Mux dashboard for that environment against the plan's cap — and it is a read, not a change. Only once that count is below the cap is a 500 evidence about anything else. (Worked case: every new Studio upload on `meirionpritchard-com` failed with a bare 500 on 2026-09-23; the Mux environment held 10 videos on the free tier and deleting unused videos fixed it immediately. Diagnosis took a live-versus-preview comparison and a manual dashboard count because canon pointed nowhere. A1-499, APP-1696.)
- **The cap fills from two leftovers that no Sanity-side reconciliation can see, and they fail in opposite directions.** (i) **Mux-only videos.** Resetting `sanity-plugin-mux-input`'s upload box mid-upload deletes the Sanity `mux.videoAsset` document, but the file has often already reached Mux — so the video exists in **Mux only**: it counts against the cap and a GROQ query over Sanity cannot see it, which means the two counts legitimately disagree and the Sanity one is the smaller. On 2026-09-23 Mux held 10 and Sanity 4. The plugin's **Videos tab can import Mux-only videos back into Sanity**, which is the route to reconciling rather than re-uploading. (ii) **Deleted-in-Mux documents.** Deleting a video in the Mux dashboard leaves its Sanity document behind with `status: "ready"`, and attaching it shows *"Video does not exist"* — a document that reads healthy against an asset that is gone. So **the asset count that matters is Mux's, never Sanity's**, and a discrepancy between them is the expected state after either leftover rather than a defect to chase. (A1-499, A1-504; APP-1696.)

- **Nothing in the delivery sandbox reaches Mux — not the CLI and not the browser — so any test of playback-failure behaviour is `page.route()`-mocked from the start.** The sandbox's egress proxy refuses CONNECT to Mux's hosts (`curl https://image.mux.com/...` → `CONNECT tunnel failed, response 403`), the same shape `convention-sanity` records for `*.sanity.io`, and this is not a CLI or tool-proxy artefact: a Playwright page's own in-page `fetch()` to `image.mux.com` throws `TypeError: Failed to fetch`. So no unmocked Mux request of any kind completes there, a real playback ID and a fabricated one fail identically, and there is no "let it hit the real 404" path to exercise a fallback against — the mock is the only route. **A fabricated playback ID is not a free fixture once anything reacts to playback outcome.** It 404s on real network too ("Invalid Playback ID"), so the moment a component starts reacting to a failed `error` event or a failed thumbnail probe, every fixture that used a made-up ID as a network-avoidance shortcut goes red in CI as well as in the sandbox — unlike the Sanity-CDN class of sandbox-only red, and it surfaces as ordinary-looking spec failures with no visible link to the error handling that caused them. Check for those fixtures before adding error-reactive behaviour to a shared player component. **The mock for "must not complete, must not fail"** is a `page.route()` handler that returns a never-resolving promise: the request stays permanently pending, so the player never receives either a success or a failure and never errors. A permanently-pending request is definitionally not idle, so a spec using it waits on an element rather than `page.waitForLoadState("networkidle")`, which can otherwise never resolve. (Instance: A1-521, `meirionpritchard-com` PR #186, 2026-09-24, the deleted-Mux-video colour fallback — five specs in one file broke on the fabricated ID and needed a real fix, not a waiver — APP-1750.) **Unverified premise — the sandbox egress readings:** the 403 and the in-page `fetch()` failure were probed on the delivery sandbox during that leg; they are not re-probed here, because the ops surface is a different machine. Confirm CONNECT to `image.mux.com` against the delivery sandbox before restating them for a new sandbox image (expected: 403). Adding Mux's hosts to the sandbox allowlist would be an Owner config action, not canon — the same standing as the Sanity hosts.

## Source

meirionpritchard-com Mux setup (A1-106, 2026-07-01); reference careerOS COS-222 step 1 (polymorphic media field on the slide schema). Captured via APP-405.
