System Design: Video Streaming Platform

// Upload and processing pipeline

interface VideoUpload {
  id: string;
  userId: string;
  originalFileName: string;
  originalUrl: string;     // S3 location of uploaded file
  status: "uploading" | "processing" | "ready" | "failed";
  metadata: VideoMetadata;
  createdAt: Date;
}

interface VideoMetadata {
  title: string;
  description: string;
  tags: string[];
  duration: number;        // seconds
  resolution: string;      // "1920x1080"
  codec: string;
  frameRate: number;
  fileSize: number;        // bytes
}

interface ProcessedVideo {
  videoId: string;
  variants: VideoVariant[];
  thumbnails: string[];
  manifest: string;        // HLS/DASH manifest URL
}

interface VideoVariant {
  resolution: string;      // "1080p", "720p", "480p", "360p"
  bitrate: number;         // kbps
  codec: string;
  segmentUrls: string[];   // URLs of video segments
}

// Upload flow
class VideoUploadService {
  async initiateUpload(userId: string, metadata: Partial<VideoMetadata>): Promise<UploadSession> {
    // Generate a pre-signed S3 URL for direct upload
    // Client uploads directly to S3 (bypasses our servers)
    const uploadId = generateId();
    const s3Key = `uploads/${userId}/${uploadId}/original`;

    const presignedUrl = await this.s3.getSignedUrl("putObject", {
      Bucket: "video-uploads",
      Key: s3Key,
      Expires: 3600, // 1 hour
      ContentType: "video/*",
    });

    // Create upload record
    await this.db.videoUploads.insert({
      id: uploadId,
      userId,
      status: "uploading",
      originalUrl: `s3://video-uploads/${s3Key}`,
      metadata,
    });

    return {
      uploadId,
      presignedUrl,
      // For large files, use multipart upload
      multipartUrls: await this.generateMultipartUrls(s3Key),
    };
  }

  // Triggered by S3 event notification when upload completes
  async onUploadComplete(uploadId: string): Promise<void> {
    await this.db.videoUploads.update(uploadId, { status: "processing" });

    // Submit to processing pipeline
    await this.messageQueue.publish("video-processing", {
      uploadId,
      stages: ["validate", "transcode", "thumbnail", "manifest"],
    });
  }
}

// Transcoding pipeline (runs on GPU-equipped workers)
class TranscodingService {
  private profiles = [
    { name: "1080p", width: 1920, height: 1080, bitrate: 5000 },
    { name: "720p",  width: 1280, height: 720,  bitrate: 2500 },
    { name: "480p",  width: 854,  height: 480,  bitrate: 1200 },
    { name: "360p",  width: 640,  height: 360,  bitrate: 700 },
  ];

  async transcodeVideo(uploadId: string, sourceUrl: string): Promise<VideoVariant[]> {
    const variants: VideoVariant[] = [];

    // Get source video info
    const sourceInfo = await this.probe(sourceUrl);

    // Only transcode to resolutions <= source resolution
    const applicableProfiles = this.profiles.filter(
      (p) => p.height <= sourceInfo.height
    );

    // Process each profile (can be parallelized across workers)
    for (const profile of applicableProfiles) {
      const segments = await this.transcodeToProfile(sourceUrl, profile);
      variants.push({
        resolution: profile.name,
        bitrate: profile.bitrate,
        codec: "h264", // or h265/AV1 for better compression
        segmentUrls: segments,
      });
    }

    return variants;
  }

  // Each video is split into small segments (2-10 seconds)
  // This enables adaptive bitrate switching at segment boundaries
  private async transcodeToProfile(
    sourceUrl: string,
    profile: TranscodeProfile
  ): Promise<string[]> {
    // Using FFmpeg under the hood:
    // ffmpeg -i input.mp4     //   -vf scale=1280:720     //   -b:v 2500k     //   -hls_time 6     //   -hls_segment_filename "segment_%03d.ts"     //   output.m3u8

    const outputDir = `processed/${profile.name}/`;
    const segmentDuration = 6; // seconds

    // Simplified - actual implementation uses FFmpeg
    return this.ffmpeg.transcode({
      input: sourceUrl,
      output: outputDir,
      width: profile.width,
      height: profile.height,
      bitrate: profile.bitrate,
      segmentDuration,
      format: "hls", // HTTP Live Streaming
    });
  }
}

// HLS manifest structure (simplified)
// Master playlist (video.m3u8) - points to variant playlists
const masterPlaylist = `
#EXTM3U
#EXT-X-STREAM-INF:BANDWIDTH=5000000,RESOLUTION=1920x1080
1080p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=2500000,RESOLUTION=1280x720
720p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=1200000,RESOLUTION=854x480
480p/playlist.m3u8
#EXT-X-STREAM-INF:BANDWIDTH=700000,RESOLUTION=640x360
360p/playlist.m3u8
`;

// Variant playlist (720p/playlist.m3u8) - lists segments
const variantPlaylist = `
#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXTINF:6.0,
segment_001.ts
#EXTINF:6.0,
segment_002.ts
#EXTINF:6.0,
segment_003.ts
#EXTINF:4.5,
segment_004.ts
#EXT-X-ENDLIST
`;

// The player:
// 1. Downloads the master playlist
// 2. Selects a variant based on current bandwidth
// 3. Downloads segments from that variant
// 4. If bandwidth changes, switches to a different variant at the next segment boundary

class ThumbnailService {
  async generateThumbnails(
    videoUrl: string,
    videoId: string,
    duration: number
  ): Promise<string[]> {
    const thumbnails: string[] = [];

    // Generate thumbnails at regular intervals
    const intervals = this.calculateIntervals(duration);
    // e.g., for a 60s video: [0, 10, 20, 30, 40, 50]

    for (const timestamp of intervals) {
      // Extract frame using FFmpeg
      // ffmpeg -i input.mp4 -ss 10 -frames:v 1 -vf scale=320:180 thumb.jpg
      const thumbnailUrl = await this.extractFrame(videoUrl, timestamp, {
        width: 320,
        height: 180,
        format: "webp", // Smaller than JPEG
      });
      thumbnails.push(thumbnailUrl);
    }

    // Generate video preview (animated thumbnail / sprite sheet)
    const spriteSheet = await this.generateSpriteSheet(videoUrl, intervals);

    // Store thumbnail URLs in video metadata
    await this.db.videos.update(videoId, {
      thumbnails,
      defaultThumbnail: thumbnails[Math.floor(thumbnails.length / 3)],
      spriteSheet,
    });

    return thumbnails;
  }

  // Sprite sheets enable scrubbing preview on hover
  // A single image containing all thumbnail frames in a grid
  private async generateSpriteSheet(
    videoUrl: string,
    timestamps: number[]
  ): Promise<string> {
    // Combine all thumbnails into a grid image
    // Used for hover preview when scrubbing the progress bar
    return this.imageProcessor.createGrid(
      timestamps.map(t => this.extractFrame(videoUrl, t, { width: 160, height: 90 }))
    );
  }
}

// Storage tiering strategy
class StorageTierManager {
  // Videos are tiered based on view frequency
  async tierVideo(videoId: string): Promise<void> {
    const stats = await this.getViewStats(videoId);
    const daysSinceUpload = this.daysSince(stats.uploadedAt);
    const recentViews = stats.viewsLast30Days;

    if (recentViews > 1000) {
      // Hot: keep all variants on fast storage + CDN
      await this.moveToTier(videoId, "hot"); // S3 Standard
    } else if (recentViews > 10) {
      // Warm: keep popular variants, move others to cheaper storage
      await this.moveToTier(videoId, "warm"); // S3 Infrequent Access
      // Only keep 720p and 360p on fast storage
      await this.archiveVariants(videoId, ["1080p", "4k"]);
    } else if (daysSinceUpload > 365) {
      // Cold: archive to cheapest storage, transcode on demand
      await this.moveToTier(videoId, "cold"); // S3 Glacier
      // Keep only 360p, re-transcode higher res on demand
    }
  }
}

// Bandwidth cost optimization:
// 1. Use efficient codecs (AV1 > H.265 > H.264) for popular content
// 2. Serve WebP/AVIF thumbnails instead of JPEG (50% smaller)
// 3. Client-side bandwidth estimation to avoid over-serving quality
// 4. Limit max quality based on screen size (don't serve 4K to phones)