Lifecycle

Every file in the upload queue moves through a defined set of statuses from the moment it’s added until it’s ready for playback. Understanding the lifecycle helps you know when to read specific fields, how retry works, and what state is safe to act on.

State machine

selected ──► validating ──► uploading ──► processing ──► ready
                │                │              │
                ▼                ▼              ▼
              failed          failed         failed

retry (from failed) ──► selected (re-enters the flow)

Status	Description
selected	File added, queued for an upload slot
validating	Running client-side validation (size, type, duration)
uploading	Upload in progress, progress updates via adapter callback
processing	Upload complete, backend is processing (transcoding, etc.)
ready	Playback URL available
failed	Validation, upload, or processing failed. error contains the reason

FileState

type FileState = {
  id: string;
  ref: FileRef;
  status: FileStatus;
  progress: number;            // 0–100 during upload
  thumbnailUri: string | null; // see Previews
  playbackUrl: string | null;  // available when ready; see Previews
  videoId: string | null;      // backend video ID
  error: string | null;        // error message when failed
  statusDetail: string | null; // sub-status from StatusChecker during processing
};

statusDetail is populated during processing when the StatusChecker provides sub-status updates (e.g. "Transcoding 480p"). Render it in your UI when file.status === "processing" && file.statusDetail.

Immutability rules

• Files in processing or ready cannot be removed; they’re committed to the server. removeFile on these statuses is a no-op.
• The file list is an append-only record of uploads in the current session.
• retry resets a failed file back to selected, re-entering the flow.