Data models

The Manager API exposes camelCase JSON. Protocol enums and execution-plan constraints are shared with Workers through @encode-flow/worker-protocol; response views add Manager-owned persistence and live data.

ExecutionPlanTemplate

The template omits version, jobId, attemptId, and fencingToken; the Manager inserts those fields after creating an attempt.

Field	Type	Description
`input.uri`required	`s3:// URI`	Source object to download.
`input.checksumSha256`	`64-char hex`	Optional source checksum; recovery-enabled execution verifies it after download.
`outputs`required	`FileOutput[] \| HlsOutput[]`	One or more output definitions.
`transforms.removedSegments`	`Segment[]`	Sorted, non-overlapping time ranges.
`transforms.watermark`	`Watermark`	Optional S3 image, anchor, margins, opacity, and timing.
`transforms.subtitles`	`SubtitleTrack[]`	Burn-in, mux, or sidecar tracks; at most one burn-in.
`transforms.audioTracks`	`AudioTrack[]`	Source selection, language, codec, gain, and default flag.
`workspace.rootDirectory`required	`string`	Worker-side workspace root.
`manifestUri`required	`s3:// URI`	Destination for the output manifest.

File output

kind is FILE; container is mp4, mkv, or webm. Video requires a codec and may include width, height, bitrate, frame rate, preset, and profile. Audio is optional and may include codec and bitrate.

HLS output

kind is HLS. It requires an S3 destination and at least one rendition. segmentDurationSeconds defaults to 6.

JobSummary

Field	Type	Description
`id`required	`UUID`	Manager-generated job ID.
`organizationId`	`UUID`	Organization derived from the project.
`projectId`required	`UUID`	Project associated with the job.
`state`required	`JobState`	Durable job lifecycle state.
`priority`required	`integer`	Scheduling priority from -1000 to 1000.
`workerPool`required	`WorkerPool`	Pool selected from required capabilities.
`requirements`required	`JobRequirements`	Required capability names.
`currentAttemptId`	`UUID \| null`	Current ownership attempt.
`currentAttempt`	`JobAttempt \| null`	Current attempt summary and live progress.
`queuedAt / startedAt / completedAt`	`timestamp \| null`	Lifecycle timestamps.
`createdAt / updatedAt`required	`timestamp`	Persistence timestamps.

JobDetail adds the complete executionPlan and an ordered attempts array.

JobAttempt

An attempt includes Worker identity, attempt number, fencing token, attempt state, processing stage, overall progress, event and progress sequences, lifecycle timestamps, failure details, output manifest URI, and optional live progress.

Live progress includes stage progress, processed and total duration, frame, FPS, speed, bitrate, ETA, and timestamp. Nullable metrics mean the Worker or FFmpeg did not report a value.

Recovery-enabled attempts also expose recovery (or null): encodedUnits, totalUnits, uploadedArtifacts, totalArtifacts, encodingComplete, and finalized. Upload counts describe artifacts rather than encoding units. Pause metadata is exposed as nullable timestamps: uploadPausedAt, uploadPauseExpiresAt, and uploadResumeRequestedAt. Local paths, multipart upload identifiers, and storage credentials are internal.

WorkerSummary

Field	Type	Description
`id / instanceId`required	`string`	Stable Worker identity and current process instance.
`hostname / version / ffmpegVersion`required	`string`	Runtime identity and versions.
`state`required	`WorkerState`	Operational Worker state.
`connectivity`required	`WorkerConnectivity`	Heartbeat freshness classification.
`capacity`required	`object`	Active and maximum concurrent jobs.
`resources`required	`object`	CPU, memory, GPU, and free-disk values.
`capabilities`required	`WorkerCapability[]`	Typed FFmpeg and GPU capability records.
`connectedAt / lastSeenAt`required	`timestamp`	Connection observation timestamps.

WorkerDetail adds liveStats, activeAttempts, completedCount, and failedCount.

ValidationError

Field	Type	Description
`statusCode`required	`400`	HTTP status.
`error`required	`"Bad Request"`	HTTP error label.
`message`required	`"Validation failed"`	Stable top-level description.
`details`required	`{ path, message }[]`	All flattened DTO validation failures.