Skip to Content

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:

  1. Initialize Upload: Request upload credentials and presigned URLs for your video (and optional poster).
  2. 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-react
import {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