every.channel/evolution/proposals/ECP-0035-multi-variant-streams.md

ECP-0035: Multi-Variant Streams (Quality Pools)

Status: Draft Author: Codex Reviewers: founder@every.channel Created: 2026-02-07

Decision

Support multiple quality variants per logical channel/stream (bitrate, resolution, codec profile) by:

• Encoding/publishing each variant as its own StreamId (using StreamKey.variant).
• Advertising the variant set in the stream catalog so receivers can pick one (or switch).
• Keeping the transport canonical at CMAF init + fMP4 fragments; playlists (HLS) are optional views.

Motivation

• Scaling: low-bitrate variants are cheaper to relay and friendlier to mobile.
• Interop: many origins already provide ABR ladders (HLS/DASH); we should preserve that structure.
• Determinism experiments: variants bound the encoding parameters so byte-equivalence is testable.

Scope

In scope:

• Catalog representation for variants.
• CLI/UI selection of a variant for playback/subscription.
• Optional "encode ladder" mode for local sources (HDHR/DVB) using x264 in deterministic settings.

Out of scope:

• Full ABR switching heuristics.
• Distributed, consensus-driven variant negotiation.

Proposed Data Model

Add to ec-core (names illustrative):

• StreamVariant:
  • variant_id (string, stable, e.g. v1-1080p2500k)
  • stream_id (StreamId)
  • codec (e.g. h264)
  • container (e.g. cmaf/fmp4)
  • width/height (optional)
  • bitrate (optional)
  • fps (optional)
  • audio (optional fields)

Add to StreamCatalogEntry:

• variants: Vec<StreamVariant> (optional; empty implies single-variant legacy)

Publishing Strategy

• For live sources (HDHR/DVB): spawn one encoder per variant (separate ffmpeg processes initially).
• For HLS origins with ABR: map each origin rendition to a variant and (initially) republish bytes as-is when possible.

Determinism Notes

• Determinism is only expected within the same variant_id and encoder profile.
• Single-threaded x264 settings remain the baseline deterministic profile for now.

Reversibility

• This is additive to the catalog and backwards compatible (single-variant streams remain valid).
• Variant publishing can be introduced incrementally per source type.