Run Robots jobs automatically with Directives
Use Directives to automatically run multiple Mux Robots workflows on your videos in the right order, with no glue code, webhook listeners, or manual dispatch.
Directives are the orchestration layer for Mux Robots. A single Robots job runs one workflow on one asset. A Directive runs several workflows in the right order, and it can kick them off the moment an asset is ready.
Reach for a Directive when you want to:
- Run a few Robots workflows on the same asset (say, generate chapters and a summary and translate the captions).
- Guarantee the prerequisites exist before a workflow runs (auto-generate captions before chapter detection, for example).
- Trigger everything automatically when an asset is created, with no glue code, no webhook listeners, and no manual dispatch.
You could already wire this up yourself: subscribe to the Mux Video and Robots webhooks, dispatch each workflow, encode the ordering between them, and babysit the retries. A Directive trades all of that for a single declaration. You say what you want once, attach it to your assets, and we handle the rest.
Configured in the Dashboard
For now, you create, configure, and run Directives entirely from the Mux Dashboard. There's no standalone Directives API yet. The one programmatic touchpoint is attaching an existing Directive to an asset when you create it — see automatically attaching to an asset. Contact support to be the first to know when API access is available.
What you can do
A Directive can run any Robots workflow, and each one takes the same parameters you'd set for a one-off Robots job. For the full list of workflows and what each one does, see What you can do in the Robots guide.
How it works
A Directive has two parts:
- Workflows — what to run.
- Resources — what those workflows depend on.
You define both once, when you create the Directive. Every run after that uses the same configuration, whether you trigger it by hand or it fires automatically. When a run starts, the engine checks that each workflow has the resources it needs, sorts out anything that's missing according to your dependency policy, and then runs the workflows in the correct order.
A Directive's workflows and dependency configuration are locked in once you create it. You can rename or delete a Directive, but to change what it runs, you create a new one and re-attach your assets. Deleting a Directive won't cancel runs that are already in progress; it just means no new ones will start.
Create your first Directive
In the Directives section of the Dashboard, click Create Directive. Give it a name, pick the workflows you want to run, set each workflow's parameters, and declare any resource dependencies.
Configure a Directive
Workflows
Pick one or more Robots workflows. Each one takes the same parameters you'd set for a one-off Robots job — for example, tone and prompt overrides for Summarize, or the target language for Translate captions.
Resources and dependencies
Some workflows need a specific resource on the asset before they can run. Generate chapters, for instance, reads from a caption text track. No captions, no chapter markers.
When you add a workflow that needs a resource you haven't declared yet, the editor adds that resource for you and picks a sensible dependency policy. If you want different behavior, you can change it.
Dependency policies
When a run starts and the engine finds a required resource missing, the dependency policy decides what happens next:
| Policy | What it does |
|---|---|
| Auto-generate | The engine calls Mux Video to create the missing resource (generating a caption track, for example), waits for it to be ready, then runs the workflows that depend on it. |
| Wait | The engine waits up to 24 hours for the resource to show up on the asset. Handy when you upload captions out of band and want chapter generation to hold until they land. |
| Fail | The engine skips the dependent workflows right away. Use this when "no captions, no chapters" is the behavior you want. |
A few workflows also have recommended inputs (captions for Summarize, for example). These sharpen the output but don't block the run if they're missing. The editor surfaces them so you can opt in, but you're never required to.
Auto-generate uses the same Mux Video APIs you'd call yourself, so the same rules apply. Generating captions, for instance, needs an audio track on the asset. If the asset can't satisfy the underlying call (a silent video, say), the dependent workflows fail and tell you why in the run output.
Run a Directive
There are two ways to trigger a run.
By hand, from the Directive detail page
Open a saved Directive and click Run on asset. Pick an asset and the run starts immediately. This is the quickest way to do a one-off run, or to test a Directive before you attach it everywhere.
Automatically, by attaching to an asset
When you create an asset, set the Directives field in the Settings step of the asset creation dialog. Any Directives you attach run automatically as soon as the asset is ready.
You can also attach a Directive through the Mux Video API by including its ID in the directives field:
curl https://api.mux.com/video/v1/assets \
-H "Content-Type: application/json" \
-X POST \
-d '{
"input": "https://example.com/my-video.mp4",
"playback_policies": ["public"],
"directives": [{ "id": "YOUR_DIRECTIVE_ID" }]
}' \
-u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}Attached Directives run once per asset. Attach the same Directive to the same asset twice and nothing doubles up; the operation is idempotent, so only one run starts. You can attach several different Directives to one asset, though. Each runs on its own, and the same workflow can run more than once if two Directives both include it.
Where to find runs and outputs
Directive runs and the workflow outputs they produce show up in two places.
On the Directive detail page
Each Directive keeps a list of its recent runs (we hold onto these for 30 days). Open a run to see the status of each workflow, the order they ran in, and anything that failed.
On the asset details page, or under Robots → Jobs
The individual workflow jobs a Directive triggers sit right alongside the ones you run by hand. Each comes with the same outputs, events, and parameters view you'd see for a one-off Robots job.
Frequently asked questions
Who can use Directives?
Directives are available to Mux Video customers on a Pay-As-You-Go plan or higher, with Mux Robots enabled. You'll need to accept the Robots terms for your environment first.
How much do Directives cost?
Directives themselves are free. You only pay for the workflow runs they trigger, at the same per-workflow rates as one-off Robots jobs — see Mux Robots pricing for the numbers.