Skip to main content

Media Normalization

This guide explains the media normalization system that preprocesses videos during the publishing workflow to ensure platform compatibility.

Overview​

The publish orchestrator includes a media normalization phase that:

  • Detects video content in post submissions
  • Rehosts videos to ensure reliable access across platforms
  • Normalizes video formats for maximum platform compatibility
  • Preserves original video URLs for reference

Implementation​

Entry: apps/functions/shared/media.js

Key functions:

  • selectPrimaryMedia(content) - Identifies primary media from post content
  • normalizeVideoForPublishing(videoUrl) - Processes and rehosts video

Workflow Integration​

The normalization happens in the publish orchestrator before platform fan-out:

  1. Content Analysis: Extract primary media from post content
  2. Video Detection: Check if primary media type is "video"
  3. Normalization: Process video through normalization pipeline
  4. Request Update: Replace video URL in request with normalized URL
  5. Fan-out: Send updated request to platform-specific publishers

Data Storage​

Normalization results are stored in the post submission document:

{
  "normalization": {
    "videoUrl": "https://normalized-video-url.com/video.mp4",
    "contentType": "video/mp4"
  }
}

Original video URLs are preserved:

{
  "post": {
    "content": {
      "videoUrl": "https://normalized-video-url.com/video.mp4",
      "originalVideoUrl": "https://original-video-url.com/video.mov"
    }
  }
}

Error Handling​

  • Normalization failures are logged but don't block publishing
  • If normalization fails, original video URL is preserved
  • Platforms receive the best available video URL

Benefits​

  1. Platform Compatibility: Videos are processed to work across all platforms
  2. Reliability: Rehosted videos reduce external dependency failures
  3. Performance: Optimized videos load faster for end users
  4. Consistency: Uniform video handling across all publishing targets

Future Enhancements​

The normalization system is designed to support:

  • Format conversion (MP4, WebM, etc.)
  • Resolution optimization per platform
  • Thumbnail generation
  • Duration and size optimization