Upload Implementation
Code examples and best practices for implementing video uploads
Implement video uploads with comprehensive code examples and best practices for reliable, efficient video processing.
Upload Implementation
Implementation Overview
Video uploads on RIXL use a secure two-step direct upload model:
- Initialize Upload: Request upload credentials and presigned URLs for your video (and optional poster).
- Direct Upload: Stream your media file directly to the presigned storage URL using HTTP
PUT. Once bytes are written, transcoding begins automatically.
Upload Optimization Guidelines
Format: MP4 + H.264
Fastest processing with universal compatibility across all target devices
Resolution: Upload Highest Available
Up to 4K for Pro tier, platform automatically generates lower renditions
Audio: Opus / AAC Codec
Best compression, fidelity, and cross-browser streaming performance
SDK Quick Start (@rixl/media-react)
If you are building a TypeScript or JavaScript application, use @rixl/media-react for a pre-built uploader with progress events and cancellation (the core ships bundled inside — no separate install needed):
npm install @rixl/media-reactimport {uploadVideo} from "@rixl/media-react";
const videoId = await uploadVideo({
projectId: "YOUR_PROJECT_ID",
apiKey: "YOUR_PROJECT_API_KEY",
file: selectedFile,
videoQuality: "VIDEO_QUALITY_PRO",
onProgress: (percent) => {
console.log(`Upload progress: ${percent}%`);
},
});
console.log(`Video uploaded and processing! Video ID: ${videoId}`);REST API Code Examples
interface CreateVideoUploadResponse {
video_id: string;
video_upload_url: string;
poster_id?: string;
poster_upload_url?: string;
expires_at?: string;
}
async function uploadVideo(
projectId: string,
apiKey: string,
videoFile: File,
videoQuality: 'VIDEO_QUALITY_BASIC' | 'VIDEO_QUALITY_SHORTS' | 'VIDEO_QUALITY_PRO' = 'VIDEO_QUALITY_PRO',
onProgress?: (percentage: number) => void
): Promise<string> {
// Step 1: Initialize upload to get presigned upload URL
const initResponse = await fetch(
`https://api.rixl.com/media/v1/projects/${projectId}/videos/upload`,
{
method: 'POST',
headers: {
'X-API-Key': apiKey,
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: videoFile.name,
video_quality: videoQuality
})
}
);
if (!initResponse.ok) {
const error = await initResponse.json().catch(() => ({}));
throw new Error(`Upload initialization failed: ${error.message || initResponse.statusText}`);
}
const { video_id, video_upload_url }: CreateVideoUploadResponse = await initResponse.json();
// Step 2: Upload file bytes directly to signed URL with progress tracking
await new Promise<void>((resolve, reject) => {
const xhr = new XMLHttpRequest();
if (onProgress) {
xhr.upload.addEventListener('progress', (e) => {
if (e.lengthComputable) {
onProgress(Math.round((e.loaded / e.total) * 100));
}
});
}
xhr.addEventListener('load', () => {
if (xhr.status >= 200 && xhr.status < 300) {
resolve();
} else {
reject(new Error(`Storage upload failed with status ${xhr.status}`));
}
});
xhr.addEventListener('error', () => reject(new Error('Network error during file upload')));
xhr.addEventListener('abort', () => reject(new Error('Upload aborted')));
xhr.open('PUT', video_upload_url);
xhr.setRequestHeader('Content-Type', videoFile.type || 'video/mp4');
xhr.send(videoFile);
});
return video_id;
}Resilient Upload Pattern
When uploading large video files, wrap the upload step with exponential backoff to handle intermittent network dropouts:
async function uploadVideoWithRetry(projectId: string, apiKey: string, file: File, maxRetries = 3): Promise<string> {
// Initialize once to obtain signed URL
const initResponse = await fetch(`https://api.rixl.com/media/v1/projects/${projectId}/videos/upload`, {
method: "POST",
headers: {
"X-API-Key": apiKey,
"Content-Type": "application/json",
},
body: JSON.stringify({
name: file.name,
video_quality: "VIDEO_QUALITY_PRO",
}),
});
if (!initResponse.ok) {
throw new Error(`Failed to initialize upload: ${initResponse.statusText}`);
}
const {video_id, video_upload_url} = await initResponse.json();
// Retry the binary PUT upload if network drops
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
const uploadResponse = await fetch(video_upload_url, {
method: "PUT",
body: file,
headers: {
"Content-Type": file.type || "video/mp4",
},
});
if (!uploadResponse.ok) {
throw new Error(`Upload returned status ${uploadResponse.status}`);
}
return video_id;
} catch (error) {
if (attempt === maxRetries) throw error;
const backoffMs = Math.pow(2, attempt) * 1000;
await new Promise((resolve) => setTimeout(resolve, backoffMs));
}
}
return video_id;
}Batch Uploads
To upload multiple assets without saturating the client browser's network pipe, run uploads with a controlled concurrency limit:
async function batchUploadVideos(
projectId: string,
apiKey: string,
files: File[],
concurrency = 2
): Promise<Array<{fileName: string; videoId?: string; error?: string}>> {
const results: Array<{fileName: string; videoId?: string; error?: string}> = [];
for (let i = 0; i < files.length; i += concurrency) {
const chunk = files.slice(i, i + concurrency);
const chunkResults = await Promise.all(
chunk.map(async (file) => {
try {
const videoId = await uploadVideoWithRetry(projectId, apiKey, file);
return {fileName: file.name, videoId};
} catch (err) {
return {fileName: file.name, error: (err as Error).message};
}
})
);
results.push(...chunkResults);
}
return results;
}Next Steps
- Set up processing status monitoring to track transcoding progress
- Learn about quality tiers to optimize resolution ladders
- Play videos using the React component in Video Player Reference
- Review supported formats for optimal compatibility