Monitoring Status
Track video processing progress and handle errors effectively.
Monitor video processing status, track progress through the pipeline, and implement robust error handling for reliable video uploads.
Processing Status Monitoring
After uploading a video to RIXL, the platform inspects the source file and transcodes it into multi-quality HLS streams. You can query the video's status programmatically to know when it is ready for streaming.
Status Enum (FileStatus)
FILE_STATUS_UPLOADING– Upload credentials generated; waiting for binary video uploadFILE_STATUS_UPLOADED– File bytes received in storage; awaiting transcodingFILE_STATUS_PROCESSING– Generating multi-resolution renditions and HLS streaming packageFILE_STATUS_READY– Video is fully packaged and ready to streamFILE_STATUS_ERROR– An error occurred during ingest or transcoding
When video transcoding completes, file.format changes to "hls". Modern players (such as @rixl/media-react's <Video>) automatically use adaptive HLS streaming when format is "hls".
Status Monitoring Implementation
Polling Helper (TypeScript)
Here is a lightweight, promise-based status polling helper with timeout protection:
export type FileStatus =
| "FILE_STATUS_UNSPECIFIED"
| "FILE_STATUS_UPLOADING"
| "FILE_STATUS_UPLOADED"
| "FILE_STATUS_PROCESSING"
| "FILE_STATUS_READY"
| "FILE_STATUS_ERROR";
export interface VideoDetails {
id: string;
project_id: string;
name: string;
video_quality: string;
file: {
status: FileStatus;
format?: string;
duration?: number;
width?: number;
height?: number;
url?: string;
};
}
export async function getVideo(apiKey: string, videoId: string): Promise<VideoDetails> {
const res = await fetch(`https://api.rixl.com/media/v1/videos/${videoId}`, {
headers: {
"X-API-Key": apiKey,
Accept: "application/json",
},
});
if (!res.ok) {
throw new Error(`Failed to fetch video: ${res.statusText}`);
}
return res.json();
}
export async function waitForVideoReady(
projectId: string,
apiKey: string,
videoId: string,
options: {
intervalMs?: number;
timeoutMs?: number;
onStatusChange?: (status: FileStatus) => void;
} = {}
): Promise<VideoDetails> {
const {intervalMs = 3000, timeoutMs = 600000, onStatusChange} = options;
const startTime = Date.now();
let lastStatus: FileStatus | undefined;
while (Date.now() - startTime < timeoutMs) {
const video = await getVideo(projectId, apiKey, videoId);
const currentStatus = video.file.status;
if (currentStatus !== lastStatus) {
lastStatus = currentStatus;
onStatusChange?.(currentStatus);
}
if (currentStatus === "FILE_STATUS_READY") {
return video;
}
if (currentStatus === "FILE_STATUS_ERROR") {
throw new Error(`Video processing failed for video ${videoId}`);
}
await new Promise((resolve) => setTimeout(resolve, intervalMs));
}
throw new Error(`Video processing timed out after ${timeoutMs / 1000}s`);
}Python Implementation
import time
import requests
def wait_for_video_ready(
api_key: str,
video_id: str,
interval_sec: int = 5,
timeout_sec: int = 600
) -> dict:
start_time = time.time()
url = f"https://api.rixl.com/media/v1/videos/{video_id}"
headers = {"X-API-Key": api_key, "Accept": "application/json"}
while time.time() - start_time < timeout_sec:
response = requests.get(url, headers=headers, timeout=15)
response.raise_for_status()
data = response.json()
status = data.get("file", {}).get("status")
if status == "FILE_STATUS_READY":
print(f"Video {video_id} is ready for streaming!")
return data
elif status == "FILE_STATUS_ERROR":
raise RuntimeError(f"Video processing failed: {data}")
print(f"Current status: {status}... checking again in {interval_sec}s")
time.sleep(interval_sec)
raise TimeoutError(f"Video {video_id} did not complete within {timeout_sec}s")Best Practices
- Poll with Reasonable Intervals: A 3 to 5 second interval is optimal for web and mobile uploads while processing is active.
- Graceful Fallbacks: Display low-resolution ThumbHash or poster image placeholders while
file.statusisFILE_STATUS_PROCESSING. - Use React SDK: If you are rendering videos with
@rixl/media-react, the<Video>component seamlessly handles poster display and streaming setup without requiring manual polling loops.
Next Steps
- Explore Quality Tiers for rendition ladders
- Review Upload Implementation for step-by-step code samples
- Learn how to play streams with Video Component