ersatztv/docs/superpowers/specs/2026-07-16-auto-tuning-design.md

Auto-Tuning: generate channels automatically from library metadata (#69)

Status: Design approved 2026-07-16. Implementation pending. Issue: ersatztv#69 Depends on (shipped): #63 composite create-channel-from-lineup, #64 Channel Templates.

Goal

"Install it and it builds a lineup for you." A creation mode that auto-generates whole channels from existing library metadata — a second, automatic-first path alongside the manual create-channel builder (epic #62). A large library becomes a full channel lineup with little manual work.

Inspired by PseudoTV Live's signature Auto-Tuning feature. We deliberately fix its two biggest weaknesses:

• PseudoTV is all-or-nothing per category with no preview/selection. We add a preview-and-select step (this is written into #69's body).
• PseudoTV wipes and rebuilds the whole lineup on every run (destructive to manual tweaks). We are additive and non-destructive — auto-tune never mutates or deletes existing channels.

Scope — first slice (3-axis MVP)

The full issue lists nine axes. This MVP ships the complete pipeline (enumerate → preview → select → bulk-create) for three axes only, the highest-value and simplest, covering both TV and movie libraries:

Axis	Enumerate (exact count, EF)	Generated channel query (SmartCollection)	Playback order	Channel name
TV Show (24/7 per-show)	distinct shows with ≥ minItems episodes	type:episode AND show_title:"X"	SeasonEpisode	X
TV Genre	distinct genres on episodes/shows with ≥ minItems episodes	type:episode AND genre:"X"	Shuffle	X
Movie Genre	distinct genres on movies with ≥ minItems movies	type:movie AND genre:"X"	Shuffle	X Movies

Deferred to follow-up PRs (not this MVP): TV Network, Movie Studio, Mixed Genre, Music Genre, Smart-Collection→channel, Mixed Content; per-axis templates; "even show distribution" balancing.

Key architectural decision — enumerate via EF, persist via SmartCollection

• Enumeration (for the preview) uses EF Core distinct + count queries over the metadata tables (ShowMetadata, GenreMetadata, MovieMetadata, …). This gives exact item counts, which we need for the min-items threshold and the preview display.
• Persistence — each generated channel references a newly-created SmartCollection (a live Lucene query), not a static Collection. So a "Comedy" channel keeps picking up new comedies as the library grows — PseudoTV's regenerative intent, but non-destructive. #63's lineup Item DTO already accepts a SmartCollectionId.
• Query authorship is server-side only. The client never sends a Lucene string. The preview returns { axis, value }; bulk-create takes { axis, value, … } and the server regenerates the query. This avoids client-authored query injection and keeps the axis semantics in one place.

Query-value escaping: show titles / genres containing quotes or Lucene special characters must be escaped when building show_title:"…" / genre:"…". Enumeration returns raw values; query generation escapes them.

Coexistence model (additive, non-destructive)

• Numbering: the user picks a starting channel number for the batch (default 500). Generated channels get sequential numbers from there, skipping any already taken.
• Dedup: on preview, a proposed channel whose generated name already matches an existing channel is flagged alreadyExists: true and is de-selected by default in the UI. Re-running auto-tune after adding library content therefore surfaces only genuinely-new channels.
• Auto-tune never edits or deletes an existing channel. Number/name collisions are resolved by skipping, never overwriting.
• Concurrency: numbers are re-validated at create time (another channel may have taken a number between preview and create); a now-taken number is skipped/reallocated, and that outcome is reported per-channel rather than failing the batch.

API surface (under the frozen /api/v1)

All three follow docs/api-conventions.md (§1 controller shape, §2 request DTO with ToCommand(), §3 error mapping, §7b post-commit side effects on CancellationToken.None, §9 auth posture). New endpoints are additive to the frozen contract.

1. POST /api/v1/channels/auto-tune/preview (no writes)

Request:

{
  "axes": ["TvShow", "TvGenre", "MovieGenre"],   // subset, ≥1
  "minItems": 5,                                    // default 5
  "startingNumber": 500                             // default 500
}

Response — a list of proposed channels:

[
  { "axis": "TvShow", "value": "The Office", "name": "The Office",
    "number": 500, "itemCount": 201, "alreadyExists": false },
  { "axis": "MovieGenre", "value": "Action", "name": "Action Movies",
    "number": 501, "itemCount": 42, "alreadyExists": false },
  ...
]

Ordering of results: grouped by axis (TvShow, TvGenre, MovieGenre), then by value. Number allocation is computed here so the UI can show final numbers; it is advisory (re-validated at create).

2. POST /api/v1/channels/auto-tune (bulk create)

Request — the selected proposals echoed back (server regenerates the query from axis+value):

{
  "templateId": <int>,
  "channels": [
    { "axis": "TvShow", "value": "The Office", "name": "The Office", "number": 500 },
    { "axis": "MovieGenre", "value": "Action", "name": "Action Movies", "number": 501 }
  ]
}

Response — partial-success list, mirroring the existing ResetAllPlayoutsResult / …ResponseModel pattern (api-conventions §3a):

{
  "results": [
    { "name": "The Office", "status": "Created", "channelId": 88 },
    { "name": "Action Movies", "status": "Skipped", "reason": "number 501 already taken" },
    { "name": "Sci-Fi", "status": "Failed", "reason": "…" }
  ],
  "createdCount": 1, "skippedCount": 1, "failedCount": 1
}

Per selected channel the handler: (a) creates a SmartCollection with the server-generated query, (b) allocates a free number, (c) calls the #63 composite create-from-lineup handler with a single-item lineup referencing that SmartCollectionId, the batch templateId, and an Advanced.PlaybackOrder override for the axis (SeasonEpisode / Shuffle). Each channel is independent — one failure does not abort the batch. Side effects (BuildPlayout, RefreshChannelList) are enqueued by the reused #63 handler on CancellationToken.None.

SPA

New wizard screen web/src/screens/AutoTuneScreen.tsx following docs/spa-conventions.md, reached from the Channels area (a "Auto-tune channels" action). Flow:

1. Configure — axis checkboxes, starting number, min items, template select.
2. Preview — calls the preview endpoint; renders a table grouped by axis with per-row checkboxes, select-all-per-axis, item counts, and alreadyExists rows shown greyed and unchecked.
3. Create — posts selected rows to the bulk endpoint; shows a per-channel result summary (created / skipped / failed counts + any errors).

No client-side query construction; the screen only passes axis+value back.

Testing / verification

• Application handler tests (NUnit + Shouldly, the in-memory Sqlite EnsureCreatedAsync harness from #28): enumeration distinct+count correctness, min-items threshold, name-dedup / alreadyExists, number allocation with gaps, and bulk-create partial-success (Created/Skipped/Failed). Enumerate lazy LanguageExt returns in tests (the #229 lesson — a lazy Map/Seq the test never enumerates hides write-path faults).
• OpenAPI: build the app project, then ./scripts/update-openapi.sh + npm run generate:api; update docs/api-conventions.md checklist, regenerate endpoint-index.md.
• Docs: docs/domain-model.md (auto-tune as a second creation mode), docs/spa-conventions.md if a new pattern is introduced, docs/decisions.md (the enumerate-via-EF / persist-via-SmartCollection + additive-coexistence decisions), docs/blazor-route-parity.md + docs/README.md for the new screen/route.
• Live-E2E (required — write-path handlers) via scripts/e2e-local.sh: seed a tiny TV + movie library (testsrc MKVs + LibraryPath rows + scan per docs/e2e-local.md), run preview → create, and verify the generated channels appear and produce valid M3U/XMLTV. Never exercise download endpoints via browser tabs — curl them.

Phasing (2 PRs)

• PR1 — backend: EF enumeration, preview endpoint, bulk-create endpoint, server-side SmartCollection query generation, handler tests, OpenAPI regen + doc updates. Write-path handlers → independent (cross-model or cold) review is mandatory.
• PR2 — SPA wizard + live-E2E verification.

Defaults chosen (recorded so they can be revisited)

• minItems default 5.
• Movie-genre channels suffixed " Movies"; TV genre and TV show names bare. (Disambiguates a genre that exists for both TV and movies, e.g. "Comedy" vs "Comedy Movies".)
• Per-axis playback order: TV Show → SeasonEpisode; TV/Movie Genre → Shuffle.
• One Channel Template for the whole batch (per-axis templates deferred).
• Server owns all query generation; the client never sends Lucene.

Non-goals (MVP)

• The remaining six axes, per-axis templates, even-show-distribution balancing, editing generated channels in-wizard, scheduling filler/bumpers between items (channels inherit whatever the chosen template configures), and any destructive "rebuild my lineup" mode.