Skip to main content

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
}"
StepField
Who may watchplayback_policy, passwordpublic, signed or password (Access and permissions)
Protectionprotectionclear, aes or drm
Watermarkwatermarkslogo (and which, logo_id; the project's default without one), forensic
Encodingsencodings, bitrateOne to three, a codec each, with their highest quality and encoding quality
Audionormalize_audioIts sound brought to one loudness
PlayerplayerOne of the project's players, "default" or "platform"
Adsad_tagOne of the project's ad tags, or "none" for no ads
Storagestorage_idWhere its uploads and imports keep their files: one of GET /projects/{id}/storages/ (Storage and CDN)
MetadatametadataKey-value pairs added to its videos', its own value where both have a key
Mergeintro_id, outro_idVideos of the project merged in before and after
Captionscaptions, captions_languageMade from its speech, in that language or the one heard
ChapterschaptersRead 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:

  1. Merge: the intro and outro are joined on. Until it's done, the video is still importing.
  2. Encodings start, as for any upload.
  3. Captions are made at the same time.
  4. 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.