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