Statamic Mux Laravel Package

Getting Started

Install the addon and give it Mux credentials. The package is small; reading src/ end-to-end takes under an hour and is the fastest way to understand exactly what it does and does not handle.

composer require daun/statamic-mux
php artisan vendor:publish --tag=statamic-mux-config   # confirm tag name in README

Add the Mux token pair to .env (create an Access Token in the Mux dashboard, scoped to the environment you want):

MUX_TOKEN_ID=...
MUX_TOKEN_SECRET=...

Then add the addon's fieldtype to a blueprint — typically a video or mux field on a pages or posts collection. In the control panel the field gives you an upload control that pushes the file directly to Mux and stores the resulting playback ID (and usually the asset ID) on the entry.

Render it in Antlers with the addon's tag, or drop to the raw playback ID:

{{ if video }}
  {{ mux }} {{# addon-provided player tag — verify name in README #}}
{{ /if }}

{{# or roll your own #}}
<video controls playsinline poster="https://image.mux.com/{{ video:playback_id }}/thumbnail.jpg">
  <source src="https://stream.mux.com/{{ video:playback_id }}.m3u8" type="application/x-mpegURL">
</video>

First use case: a hero background loop or a "watch the demo" block on a marketing page. Upload once in the CP, reference the entry's playback ID in the template, done. Mux handles transcoding and adaptive bitrate, so you skip the ffmpeg/HLS plumbing entirely.

Implementation Patterns

Field-per-video, not a media library. The fieldtype stores one asset per field. For a page with a hero video plus a testimonial video, add two fields. For a reusable library, point multiple entries at a shared global or a "videos" collection and reference by relationship — playback IDs are portable strings, so cross-entry reuse is trivial.

Treat the playback ID as the contract. Everything downstream — <video>, Mux Player, thumbnails, captions — keys off playback_id. If you later swap the addon's player tag for <mux-player> or Video.js, the field data doesn't change. Wrap rendering in a partial so there's one place to change:

{{# partials/video.antlers.html #}}
{{ if video }}
  <mux-player
    playback-id="{{ video:playback_id }}"
    metadata-video-title="{{ title }}"
    accent-color="#1a1a1a"
  ></mux-player>
{{ /if }}

Bard and Replicator sets. The field works inside sets, which is usually what you want for article bodies: one set type video, one field, and a {{ if type == 'video' }} branch in the set loop. Keep the player markup in that branch.

Draft/preview safety. An entry saved before the Mux asset finishes processing can have a null or half-written playback ID. Always guard:

{{ if video:playback_id }}
  ...
{{ /if }}

Static caching. Playback IDs are immutable per asset, so fully cached HTML works well. The player script loads client-side and doesn't need a server round-trip. This is the main reason the addon pairs nicely with Statamic's static cache — no per-request API call to Mux.

Pair it with the Mux PHP SDK for anything advanced. The addon covers upload + embed; signing, direct uploads from your own forms, asset deletion, and webhook handling are SDK territory:

use MuxPhp\Api\AssetsApi;

$api = new AssetsApi(app(\MuxPhp\Configuration::class));
$asset = $api->getAsset($assetId);

Keep a small service class for this rather than scattering SDK calls in controllers.

Video metadata for SEO. Mux exposes duration and thumbnails. Store title/description on the Statamic entry (not on Mux) and use the playback ID for the thumbnailUrl/contentUrl in a VideoObject JSON-LD block. You can also emit a <track> for captions if you upload them to Mux:

<track kind="captions" src="https://stream.mux.com/{{ video:playback_id }}/text/en.vtt" srclang="en">

Webhooks. Mux emits video.asset.ready when processing completes. If the addon doesn't poll asset state automatically (check its service provider/jobs), add a webhook route that updates the entry's field when ready — otherwise editors see an empty player for a few minutes and file bugs.

Gotchas and Tips

• Asset ID vs playback ID. These are different strings and both may be stored. Confusing them yields 404s on stream.mux.com. Dump the field's raw value once with {{ video | dump }} before writing templates.
• Uploads are asynchronous. A successful CP save does not mean the video plays. Editors will save, click preview, and see nothing. Surface processing state — either the addon's field UI or a small "processing" notice in the template — or you'll field the same question weekly.
• Signed playback isn't free. Public playback policies work out of the box; signed requires minting a JWT server-side with the Mux signing key. Don't cache signed tokens in the static cache — they expire. Use public playback for marketing video and signed only where DRM-ish behavior is required.
• Orphaned assets cost money. Deleting a Statamic entry does not delete the Mux asset. Add a queued job on entry delete that calls deleteAsset, or you'll accumulate storage charges silently.
• Use separate Mux environments for staging and production. Tokens are environment-scoped. A single token means staging uploads pollute production analytics and billing, and test videos get delivered to real users.
• Config cache bites. MUX_TOKEN_ID/MUX_TOKEN_SECRET must be present when php artisan config:cache runs on deploy. On Forge/Cloud, set them as environment variables before the deploy script, not just in the local .env.
• PHP upload limits are irrelevant — uploads go browser → Mux directly. But Mux CORS/cors origin settings and your CSP (media-src, connect-src for stream.mux.com and image.mux.com) can still break playback. Check the browser console first when "the video won't load."
• Cost model surprise. Encoding is per-minute and delivery is per-GB. A hero background video that autoplays on every pageview is the most expensive thing you can do with this package. Prefer click-to-play, or a poster image + lazy player.
• Low adoption, small surface. 13 stars means few battle-tested edge cases and no Stack Overflow corpus. Pin the version in composer.json, read the source when something is odd, and be prepared to fork — it's a thin wrapper, so forking is cheap.
• Publish the views. The player markup is almost certainly a publishable view. Publish it before customizing so upgrades don't silently overwrite your changes; if it isn't publishable, override via your own partial and stop using the addon's tag.
• Debugging checklist: 401 → bad/rotated token; 404 → wrong environment or asset/playback ID mismatch; stalled "processing" → check the Mux dashboard for the asset and your queue worker for failed webhook jobs; video loads in Safari but not Chrome → usually CSP or an .m3u8 MIME/CORS issue, not the addon.
• Extension point to preserve: the stored field value. Whatever you build on top of it (custom player, JSON-LD, sitemap entries), read from the field rather than the addon's tag so you can replace the rendering layer without a data migration.