# 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.