Skip to main content
Live. This area is documented as current, user-reliable behavior.

​
Goal

Make readiness and safety visible before an asset reaches a player, download, transform, or public URL.

​
Prerequisites

  • A video upload or replace operation
  • FFmpeg/FFprobe available to the configured worker
  • A content policy when MIME or size restrictions need to differ from defaults

​
Workflow

1
Upload or replace a video asset.
2
Wait for the asset scan and replica gates; infected or policy-quarantined assets are not deliverable.
3
Process clean video asynchronously for metadata, a poster, 25/50/75 thumbnails, normalized MP4, and HLS renditions.
4
Choose public delivery or mint a private token before handing HLS, poster, thumbnail, or MP4 URLs to a client.
5
Use policy controls for allowed MIME types, maximum image/video/other bytes, and whether scanning is required.

​
Video outputs

The processor probes duration, dimensions, codec, bitrate, frame rate, audio presence, and rotation. It emits a first-frame poster, thumbnails at 25%, 50%, and 75% of the duration, a fast-start normalized MP4, and HLS profiles. The default profiles are 240p, 360p, 480p, 720p, and 1080p; a profile is generated only when the source height supports it, and an adaptive master points at the generated ladder.
  • Poster: videoUrl(assetId, "poster", "default").
  • Thumbnail: videoUrl(assetId, "thumbnail", "25" | "50" | "75").
  • Normalized MP4: videoUrl(assetId, "mp4", "normalized").
  • HLS media and adaptive master: videoUrl(assetId, "hls", profile) where profile is a generated rendition or adaptive.

​
States and delivery gates

Asset state is processing, ready, quarantined, failed, deleting, or deleted. Scan state is pending, clean, infected, failed, or skipped; replication is pending, replicated, degraded, or failed; video state is none, pending, processing, ready, failed, or skipped. A video output is served only when its output replica is available and the asset is not being revoked or quarantined.
  • Infected scans set quarantine_status: infected; policy failures use quarantine_status: policy.
  • Quarantined assets are blocked from original, transform, version, branch, and video delivery.
  • Policy checks run during direct upload, upload-session creation, chunk completion, replace, and signed/token upload flows.
  • After a clean scan, the worker automatically queues moderation; the same moderation route can be requested explicitly when a workflow needs a fresh result.
  • Use the asset’s video_progress_percent while processing; poll the asset or the returned async job rather than assuming the upload response is playable.

​
Configure content policy

​
Public and private playback

For public, ready assets the SDK builds CDN URLs under /assets/{assetId}/video/{kind}/{profile}. For private assets, mint a normal current-version signed URL, extract its token, and pass that token to videoUrl; the SDK switches to /private/assets/... and appends it. Do not use a maxDownloads token for HLS playback because a player makes multiple segment requests, and do not cache private URLs as public content.

​
Expected result

Video assets expose independent asset, scan, replication, and video states so a player is only pointed at an available output.

Private assets and signed URLs

Keep files private, mint version-bound download tokens, and avoid accidentally caching or logging protected media.

AI DAM and versioning

Use configured asset AI jobs, moderation, transcripts, derived images, collections, saved searches, and branching versions with explicit readiness and spend controls.