Migrate from Mux to Transloadit

Mux ingests video, encodes it, and packages it for HLS playback⁠. Transloadit is a broader media processing platform: you can upload or import files, generate multiple renditions, create HLS or MPEG-DASH outputs, produce thumbnails, add subtitles, transcribe audio, and store the results in your own storage.

This guide covers an on-demand video catalog: ingest, encoding, thumbnails, export to your own storage, and the application changes around them. It identifies decisions for metadata, uploads, webhooks, and security. Player SDK implementation, playback analytics, live streaming, DRM, multilingual track packaging, and rebuilding AI workflows are outside the worked example.

Storage and DAM scope. The flow below exports to your S3 bucket and CDN. Hosted DAM migration, folder and metadata import, tlcdn.com delivery cutover, migration dry runs/manifests, Media Library roles, widgets, and CMS/editor integrations require a separate migration plan. This guide does not provide a hosted DAM importer.

Migration map

An Assembly does not recreate a Mux asset, its playback IDs, access policies, or analytics history. Decide which application owns each of those responsibilities before moving media bytes.

Choose upfront or on-demand encoding

Preset and URL migration. Mux currently names its quality levels basic, plus, and premium; plus uses per-title encoding. The fixed three-rendition ladder below does not reproduce that behavior. Compare quality, file size, aspect ratio, frame rate, and the highest required resolution on representative videos before choosing your own presets. See Mux’s quality-level guide⁠. Inventory thumbnail URL options⁠, such as frame time, dimensions, and fit mode, and generate matching outputs deliberately; carrying those query strings to an exported image does not apply transformations.

For predictable catalogs, encode variants up front with /video/encode and /video/adaptive. For large catalogs where only a fraction of videos are watched, evaluate /video/ondemand with Smart CDN so HLS assets are generated as viewers request them. This Robot needs a separate compatible Smart CDN Template whose response branch ends in /file/serve. Sign the URLs on your backend to protect your encoding budget from abuse. The upload-and-export Template below is for upfront encoding, not Smart CDN.

Example adaptive video Template

This Template receives a video, encodes three renditions, segments them, writes variant playlists and a multivariant playlist, creates a thumbnail, and stores the package on S3. Use one source video per Assembly for this example and choose renditions appropriate to its resolution; the three presets do not add missing detail to a low-resolution source:

{
  "steps": {
    ":original": {
      "robot": "/upload/handle"
    },
    "encoded_480p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/480p",
      "ffmpeg_stack": "v7"
    },
    "encoded_720p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/720p",
      "ffmpeg_stack": "v7"
    },
    "encoded_1080p": {
      "use": ":original",
      "robot": "/video/encode",
      "preset": "hls/1080p",
      "ffmpeg_stack": "v7"
    },
    "hls": {
      "use": {
        "steps": ["encoded_480p", "encoded_720p", "encoded_1080p"],
        "bundle_steps": true
      },
      "robot": "/video/adaptive",
      "technique": "hls",
      "playlist_name": "playlist.m3u8",
      "result": true
    },
    "poster": {
      "use": ":original",
      "robot": "/video/thumbs",
      "count": 1,
      "result": true
    },
    "exported_hls": {
      "use": "hls",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "videos/${assembly.id}/${file.meta.relative_path}/${file.name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    },
    "exported_poster": {
      "use": "poster",
      "robot": "/s3/store",
      "credentials": "YOUR_AWS_CREDENTIALS",
      "path": "videos/${assembly.id}/posters/${file.url_name}",
      "url_prefix": "https://cdn.example.com/",
      "acl": "bucket-default"
    }
  }
}

/video/adaptive sets relative_path on its outputs. Preserve it in the export path so the playlist references resolve. Configure Third-party Credentials and a CDN that can read the bucket root; url_prefix does not configure delivery or grant access. acl: "bucket-default" sends no object ACL; configure access through your bucket policy and CDN origin access.

Set notify_url in your signed Assembly request, verify notification signatures, and require ASSEMBLY_COMPLETED. Export updates URLs under the producing Steps: results.hls lists the segments and playlists; select the entry named playlist.m3u8 with an empty meta.relative_path. Read the thumbnail from results.poster, checking is_temp_url: false before persisting its URL. Temporary Transloadit URLs expire after 24 hours and must not be used for playback; see saving conversion results. Test the exported manifest, variant playlists, and segments through your CDN in the intended HLS player before switching traffic.

Import existing Mux source files

Export from Mux. List the assets in each environment⁠ and follow pagination. Keep each asset’s playback IDs, policy, tracks, metadata, and processing settings in a migration manifest. Prefer your retained original files when you need the original bytes. If Mux holds the only copy, enable temporary master access⁠ with master_access: "temporary", wait for master.status: "ready" or video.asset.master.ready, and use the returned master.url for the import. The URL lasts 24 hours; request access again before retrying an expired import. Mux describes the master as equivalent in quality to the input, with resolution controlled by max_resolution_tier, rather than promising the original bytes. The MP4 includes video and the primary audio track; preserve alternate audio and download text tracks separately⁠. See Mux’s master download guide⁠.

Static MP4 renditions⁠ are encoded delivery files at the asset’s quality level. Use master access for the backfill when you need Mux’s master; a static rendition is a separate choice with its own quality and resolution constraints.

If you still have source video files in S3, use 🤖/s3/import. If your application stores temporary HTTPS source URLs, use 🤖/http/import. Save a backfill variant of the Template: replace the :original upload Step with an import Step named imported, and change all four use: ":original" references (three encodes and the poster) to use: "imported". Configure that import Step with one authorized source URL or S3 key per Assembly. For /s3/import, configure its own source credentials and path; for /http/import, configure url. For example, the HTTPS import Step can read a backend-selected source URL from your signed Assembly request's fields.source_url:

{
  "steps": {
    "imported": {
      "robot": "/http/import",
      "url": "${fields.source_url}"
    }
  }
}

This is the replacement input Step, not the complete processing Template. Use only source URLs you are authorized to access. Temporary source URLs must remain valid until the import finishes; refresh expired URLs before retrying. After a successful export and playback check, write the new playback URL to your database while retaining the source asset ID for reconciliation.

Metadata, organization, and versions. Copy Mux’s meta.title, meta.creator_id, and meta.external_id⁠ into your catalog, along with passthrough⁠, if used. Preserve your application’s tags, folder paths, collection memberships, and revision history in the same manifest. An import Step transfers media, not these catalog relationships. Assign new object keys to each revision and keep the mapping from old asset and playback IDs to new manifest, poster, and text-track URLs. The sample uses the Assembly ID as an output prefix, so retries also need reconciliation before you publish a replacement revision.

Checklist

Upload widget. Mux Uploader uses Mux Direct Upload URLs⁠. Replace that UI and endpoint flow with Uppy and its Transloadit plugin using the framework integration guide⁠. Authorize the user and select the permitted Template on your server before returning short-lived signed Assembly options. Keep upload progress distinct from processing completion; publish the playback URL only after the export succeeds.

Webhooks and automation. Mux’s video.asset.ready event⁠ signals playback readiness; it does not signal that a separate master download or static rendition is ready. Mux signs webhooks in the mux-signature header⁠, and its delivery may include duplicates and retries⁠. Implement Transloadit notification verification from its own docs. Deduplicate catalog updates by source revision and Assembly ID, handle failures, and keep a retry ledger before replacing your Mux event handlers. Do not reuse the Mux signature verifier for Assembly Notifications.

Security. Mux signed playback uses JWTs generated on your server⁠. Those tokens do not authorize your replacement CDN. Rebuild viewer authorization using your destination CDN’s mechanism, protect HLS manifests, playlists, segments, posters, and captions, and test allowed and denied requests. Assembly request signatures authorize processing; they do not grant or restrict access to exported files. Keep S3 access policies and CDN origin permissions aligned with each asset’s visibility. Add 🤖/file/virusscan if your upload policy requires malware scanning; the example above has no scan or quarantine flow. Content moderation and malware scanning need separate acceptance rules.

Mux Robots and AI workflows. Mux Robots⁠ provide hosted AI workflows including captions, summaries, chapters, and moderation; Directives⁠ can order workflows and trigger them when assets become ready. Inventory the jobs, dependencies, outputs, and moderation decisions your application uses. The encoding Template above does not replace those workflows. Keep their outputs and existing automation until you have tested each replacement’s languages, schema, accuracy, thresholds, and cost. A Transloadit Template makes processing Steps inspectable; it does not make AI predictions deterministic. Track the Template revision, Assembly IDs, failures, and export paths, measure spend on a pilot, and cap backfill batches accordingly. Confirm processing and storage regions and compliance requirements with your team before the cutover.

Effort estimate. As a planning estimate, allow two to five engineering days for a public on-demand video integration when a developer has the originals, S3/CDN delivery, and a compatible HLS player already in place. That covers the Template, upload/signing flow, notification handler, and a pilot catalog cutover; it excludes bulk transfer time. Mux-only masters, private playback, CMS changes, captions, alternate audio, and AI workflows require additional work. Measure import, encoding, and export throughput on representative files to estimate the full backfill duration.

1. Decide whether videos should be encoded up front or on demand.
2. Inventory source files, asset/playback IDs, visibility, tracks, metadata, URL options, and automation.
3. Create and test a Template for your required renditions, thumbnails, and exports. Plan text-track packaging separately.
4. Configure storage credentials, CDN access, CORS for HLS playback, and private-delivery controls where needed.
5. Replace the uploader and webhook integration for a pilot, retaining the old delivery mapping for rollback.
6. Backfill in bounded batches; compare duration, resolution, playback, posters, permissions, and catalog counts before publishing each mapping.
7. Update application and CMS records to the exported manifest or Smart CDN URL. For URLs on a domain you control, configure and test redirects there; update references to Mux-hosted URLs in your application.
8. Check embedded players, bookmarks, captions, and CDN segment requests, then expand the rollout. Keep old assets available until your rollback window and cache lifetimes have passed.