ECP-0004: global stream identifiers and swarms

Status: Draft

Problem

We need a global, deterministic way to identify streams so that identical broadcasts from different antennas can converge in the same swarm without coordination.

Decision

Adopt a two-layer identifier scheme:

Broadcast identity: a logical identifier derived from broadcast metadata (PSIP/ATSC) such as transport stream ID and program number. This is the primary convergence key.
Source identity: a physical identifier used when broadcast identity is not yet available (e.g., early ingestion). This is a fallback.

A canonical stream ID string will be generated as:

ec/stream/v1/<scope>/<fields...>/profile-<profile>/variant-<variant>

Where <scope> is broadcast or source.

Broadcast scope fields

standard (e.g., atsc)
tsid-<transport_stream_id> (when known)
program-<program_number> (when known)
optional callsign-<callsign> and region-<region> as hints

Source scope fields

kind (e.g., hdhr or linux-dvb)
device-<device_id> when available
channel-<channel_reference> when available

Profile and variant

profile identifies the deterministic encoding profile.
variant identifies audio language, resolution, or alternate tracks.

Consequences

The network can converge on the same stream even when multiple relays ingest the same broadcast.
Early ingestion may start with source scope and migrate to broadcast scope once PSIP metadata is parsed.

Alternatives considered

Single opaque UUID per stream: rejected because it prevents convergence without coordination.
Content hash as stream ID: deferred; may be layered later as an availability primitive.

Rollout / teardown

Implement StreamKey in ec-core.
Extend ingest pipeline to parse PSIP/ATSC IDs and promote source to broadcast IDs.
Revise once PSIP parsing is in place.

1.9 KiB Raw Blame History