every.channel: sanitized baseline

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

@@ -0,0 +1,60 @@
+# 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.