every.channel/evolution/proposals/ECP-0027-unified-add-stream-flow.md

ECP-0027: unified add-stream flow (live-only, ytdlp options, persistence)

Status: Draft

Problem / context

We currently have separate add flows for HDHomeRun and yt-dlp. Users want a single “Add stream” entry point that accepts an IP/host or URL and handles detection automatically. The flow must reject non-live content, provide yt-dlp options when relevant, and persist manual entries across restarts.

Decision

Introduce a unified add-stream flow with:

• A single URL/host input in the UI.
• A probe step that detects HDHomeRun, HLS, or yt-dlp sources.
• Live-only enforcement for HLS and yt-dlp.
• Optional yt-dlp format selection + live-from-start toggle before starting.
• Unified persistence for all manual sources.
• Stream list tags showing the source kind.

Details

Probe + add flow

• New commands:
  • probe_stream returns detection results and yt-dlp options (if needed).
  • add_stream executes the resolved ingest path.
• HDHomeRun detection is attempted for local/.local hosts or private IPs.
• HLS detection is triggered for .m3u8 URLs.
• yt-dlp is used for remaining HTTP(S) URLs.

Live-only enforcement

• HLS playlists with #EXT-X-ENDLIST or #EXT-X-PLAYLIST-TYPE:VOD are rejected.
• yt-dlp sources require is_live == true or live_status == "is_live".

Persistence

• Replace manual_hdhomerun.json with manual_sources.json.
• Each entry stores kind, input, and optional options (e.g. ytdlp format).
• Legacy HDHomeRun hosts are migrated on load.

UI

• One “Add stream” button + input.
• If yt-dlp is detected, show format choices and “live from start” toggle before proceeding.
• Channel list shows a source badge (e.g. hdhr, ytdlp, hls, moq).

Alternatives considered

• Keep separate add buttons: rejected (clutters flow).
• Allow VOD: rejected (violates live-only requirement).

Rollout / teardown plan

1. Add unified probe/add commands + detection logic in the backend.
2. Update UI flow + add yt-dlp options panel.
3. Persist manual sources and migrate legacy entries.
4. Add source tags to stream list.

Teardown: keep legacy add commands if needed; disable unified flow in UI.