Workflows
A workflow is a project's saved recipe for what happens to a video once its file is in: how it's encoded, its watermark, protection, audio, player and who may watch it, an intro and outro merged around it, captions made from its speech, and chapters read from those captions. Name it when you upload or import a video, and every one comes out the same; run it again on a video that's already in.
Each step is something you could do to the video yourself (Modify videos):
a workflow decides them up front and runs them in order. Workflows take an editor
token.
1. Make one
Every step is optional; leave one out and the upload's own choice (or the video's, on a run again) stays.
curl https://your-crumbcast/api/v1/projects/$PROJECT_ID/workflows/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d "{
\"name\": \"Course lesson\",
\"intro_id\": \"$INTRO_VIDEO_ID\",
\"encodings\": [{\"codec\": \"h.264\", \"max_quality\": 1080}, {\"codec\": \"av1\"}],
\"watermarks\": {\"logo\": true},
\"playback_policy\": \"signed\",
\"normalize_audio\": true,
\"captions\": true,
\"captions_language\": \"en\",
\"chapters\": true
}"
| Step | Field | |
|---|---|---|
| Who may watch | playback_policy, password | public, signed or password (Access and permissions) |
| Protection | protection | clear, aes or drm |
| Watermark | watermarks | logo (and which, logo_id; the project's default without one), forensic |
| Encodings | encodings, bitrate | One to three, a codec each, with their highest quality and encoding quality |
| Audio | normalize_audio | Its sound brought to one loudness |
| Player | player | One of the project's players, "default" or "platform" |
| Ads | ad_tag | One of the project's ad tags, or "none" for no ads |
| Storage | storage_id | Where its uploads and imports keep their files: one of GET /projects/{id}/storages/ (Storage and CDN) |
| Metadata | metadata | Key-value pairs added to its videos', its own value where both have a key |
| Merge | intro_id, outro_id | Videos of the project merged in before and after |
| Captions | captions, captions_language | Made from its speech, in that language or the one heard |
| Chapters | chapters | Read from those captions, and saved; needs captions |
The intro and outro are merged into the video itself: it becomes intro, upload, outro, encoded once, not a second video. They're videos of the project like any other: upload them first.
Saving a workflow checks it as an upload would be checked: a step your plan doesn't have
answers 402, an intro that isn't the project's 404, one whose file isn't in yet 409.
A workflow that saves can run.
2. Use it for uploads and imports
Name it in Create Video or Import Video:
curl https://your-crumbcast/api/v1/projects/$PROJECT_ID/videos/import/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"url\": \"https://example.com/lesson-4.mp4\", \"title\": \"Lesson 4\", \"workflow_id\": \"$WORKFLOW_ID\"}"
What the workflow sets takes the place of what the request says: its encodings, watermark, protection, who may watch, audio, storage, player and ads. Its metadata is added to the video's. The rest runs once the file is in:
- Merge: the intro and outro are joined on. Until it's done, the video is still
importing. - Encodings start, as for any upload.
- Captions are made at the same time.
- Chapters are read from them once they're ready.
3. Follow its run
A video's workflow_run says how its run is going, each step waiting, running,
done, skipped or failed, with a reason for the last two:
"workflow_run": {
"workflow_id": "b71e…",
"name": "Course lesson",
"started_at": "…",
"merge": { "state": "done" },
"captions": { "state": "running" },
"chapters": { "state": "waiting" },
"steps": { "…": "…" }
}
The encodings aren't a step of their own: the video's formats are their state, and the
usual webhooks say when it plays (video.ready), is encoded
(video.encoded) and has its captions (video.captions.ready).
A step that can't run doesn't stop the others. A merge that fails leaves the upload as it
was, encoded as it is; captions your plan no longer has are skipped, and the chapters
with them. The run keeps a copy of the workflow's steps as they were when it started, so
changing or deleting the workflow meanwhile changes nothing.
Running one again
Run Workflow runs a workflow on a video that's in, to bring it in line with the others:
curl https://your-crumbcast/api/v1/videos/$VIDEO_ID/workflow/ \
-H "Authorization: Bearer $CRUMBCAST_TOKEN" \
-H "Content-Type: application/json" \
-d "{\"workflow_id\": \"$WORKFLOW_ID\"}"
Only what changes is done again: encodings it keeps in the same settings stay as they are, and formats are encoded again only for a new codec, watermark, protection or audio. A merge cuts the video as a trim does, its chapters and captions moving with it; it plays as it was meanwhile. Captions are made again, and chapters read from them, in place of the video's.
The video's changes.run_workflow says whether it may run now: not while it's encoding,
having captions made, being clipped, played live, or still in another run (409).
A video that already has the workflow's intro gets it again: runs don't look for it.
Changing and deleting
Update Workflow replaces its steps; videos already run keep what it did to them. So does Delete Workflow. A video that's a workflow's intro or outro can't be deleted while a workflow uses it.
List Workflows gives the project's workflows, with their IDs to name in uploads.