Rethink channel/playout/schedule creation: PseudoTV-style channel-first flow with a Kodi-smart-playlist-like query builder #176

Closed
opened 2026-07-07 20:42:47 +02:00 by timothy · 2 comments
Owner

Vision (from Timothy): channel/playout/schedule creation should fundamentally work more like PseudoTV (Kodi add-on) — channel-first and straightforward — with a Kodi smart-playlist-style WYSIWYG rule builder (visual SQL-ish query builder over the media collection) for defining what plays.

How the inspirations work

Kodi smart playlists (XSP): rules of field + operator + value(s) (type-scoped fields; operators like is/contains/greaterthan/inthelast), AND/OR via <match> + nested <group>s, playlists referencing playlists, <order> (incl. random) + <limit>. Docs: Smart playlists, Rules and groupings.

PseudoTV Live (repo): Autotune one-click generates channels per TV network / genre / studio / music genre; the Channel Manager builds a custom channel from any source with an inline dynamic smart-playlist builder; per-channel advanced rules (Even Show Distribution, Force Episode Ordering, sort) supersede the query's own order; broadcast day fills automatically (auto-filler pads to 15-min marks). Net: channel = one query + a few toggles; no separate schedule authoring for the common case.

Mapping to what we already have

PseudoTV/Kodi concept ErsatzTV today Gap
XSP rules + groups Lucene-ish search grammar (SearchQueryParser, SearchTargets) No visual builder (text only)
Nested playlist refs smart_collection:"Name" recursive resolution w/ cycle detection Already equivalent
order/limit on the query Ordering lives in schedules/blocks, not on the query Split model
Autotune Nothing — every channel needs collection+schedule+playout by hand Biggest gap
Channel Manager w/ inline query builder SmartCollection editor and Channel creation are separate flows Gap
Advanced rules (distribution/ordering) Blocks/Templates/Playout engine — more powerful, but manual assembly UX/discoverability, not capability
Auto-filler FillerKind/filler collections + decos Present, buried

Design directions (progressive disclosure — wizard output stays inspectable/editable as real SmartCollection+Template+Playout)

  1. One-shot "Create Channel" wizard: rule builder (compiles to the existing Lucene grammar) → order/limit → playout mode → done; composes SmartCollection + minimal template + playout behind the scenes, "Advanced" reveals them.
  2. Autotune: bulk-create one channel per library facet value (genres/studios/networks already Lucene-indexed) with auto-named smart collections (genre:"Horror"). Near-zero new backend.
  3. Visual AND/OR rule-group builder shared between SmartCollection editing and inline channel creation.
  4. Distribution/ordering toggles first-class on the wizard (Even Show Distribution, Force Episode Order → existing scheduler primitives).
  5. Graduation path: a "one query" channel can later become a hand-tuned block schedule with no migration.

Notes

  • Depends on nothing in #144 (parity) but should land AFTER phase (b)/#91 so it builds on the SPA only.
  • Existing related: composite create-channel endpoint (#63) is a partial step in this direction; smart collections + search grammar are the foundation.
  • Full research brief with XSP examples archived in this issue's first comment context (session 2026-07-07).

Done-when

  • adversarial review passed (final whole-branch review MERGEABLE at head)
  • all tests green (backend build + web suite + tsc/lint/check:api)
  • docs updated (api-conventions, decisions, spa-conventions)
  • CI green on PR head
  • deferred follow-ups filed as tracked issues

Scope note: this closes the remaining leg of #176 — the visual rule builder in the SmartCollection editor. Autotune (#69) and the composite Create-Channel wizard (#63) already shipped. Enhancements (facet typeahead, relative dates, deeper nesting, ChannelBuilder/Auto-Tune adoption, builder validation polish) are filed as separate follow-ups.

**Vision (from Timothy)**: channel/playout/schedule creation should fundamentally work more like **PseudoTV** (Kodi add-on) — channel-first and straightforward — with a **Kodi smart-playlist-style WYSIWYG rule builder** (visual SQL-ish query builder over the media collection) for defining what plays. ## How the inspirations work **Kodi smart playlists** (XSP): rules of `field + operator + value(s)` (type-scoped fields; operators like is/contains/greaterthan/inthelast), AND/OR via `<match>` + nested `<group>`s, playlists referencing playlists, `<order>` (incl. random) + `<limit>`. Docs: [Smart playlists](https://kodi.wiki/view/Smart_playlists), [Rules and groupings](https://kodi.wiki/view/Smart_playlists/Rules_and_groupings). **PseudoTV Live** ([repo](https://github.com/PseudoTV/PseudoTV_Live)): **Autotune** one-click generates channels per TV network / genre / studio / music genre; the **Channel Manager** builds a custom channel from any source with an *inline dynamic smart-playlist builder*; per-channel **advanced rules** (Even Show Distribution, Force Episode Ordering, sort) supersede the query's own order; broadcast day fills automatically (auto-filler pads to 15-min marks). Net: channel = one query + a few toggles; no separate schedule authoring for the common case. ## Mapping to what we already have | PseudoTV/Kodi concept | ErsatzTV today | Gap | |---|---|---| | XSP rules + groups | Lucene-ish search grammar (`SearchQueryParser`, `SearchTargets`) | No visual builder (text only) | | Nested playlist refs | `smart_collection:"Name"` recursive resolution w/ cycle detection | Already equivalent | | order/limit on the query | Ordering lives in schedules/blocks, not on the query | Split model | | **Autotune** | Nothing — every channel needs collection+schedule+playout by hand | **Biggest gap** | | Channel Manager w/ inline query builder | SmartCollection editor and Channel creation are separate flows | Gap | | Advanced rules (distribution/ordering) | Blocks/Templates/Playout engine — *more* powerful, but manual assembly | UX/discoverability, not capability | | Auto-filler | FillerKind/filler collections + decos | Present, buried | ## Design directions (progressive disclosure — wizard output stays inspectable/editable as real SmartCollection+Template+Playout) 1. **One-shot "Create Channel" wizard**: rule builder (compiles to the existing Lucene grammar) → order/limit → playout mode → done; composes SmartCollection + minimal template + playout behind the scenes, "Advanced" reveals them. 2. **Autotune**: bulk-create one channel per library facet value (genres/studios/networks already Lucene-indexed) with auto-named smart collections (`genre:"Horror"`). Near-zero new backend. 3. **Visual AND/OR rule-group builder** shared between SmartCollection editing and inline channel creation. 4. **Distribution/ordering toggles first-class** on the wizard (Even Show Distribution, Force Episode Order → existing scheduler primitives). 5. Graduation path: a "one query" channel can later become a hand-tuned block schedule with no migration. ## Notes - Depends on nothing in #144 (parity) but should land AFTER phase (b)/#91 so it builds on the SPA only. - Existing related: composite create-channel endpoint (#63) is a partial step in this direction; smart collections + search grammar are the foundation. - Full research brief with XSP examples archived in this issue's first comment context (session 2026-07-07). ## Done-when - [x] adversarial review passed (final whole-branch review MERGEABLE at head) - [x] all tests green (backend build + web suite + tsc/lint/check:api) - [x] docs updated (api-conventions, decisions, spa-conventions) - [x] CI green on PR head - [x] deferred follow-ups filed as tracked issues _Scope note: this closes the remaining leg of #176 — the visual rule builder in the SmartCollection editor. Autotune (#69) and the composite Create-Channel wizard (#63) already shipped. Enhancements (facet typeahead, relative dates, deeper nesting, ChannelBuilder/Auto-Tune adoption, builder validation polish) are filed as separate follow-ups._
timothy added the contentenhancementfrontendpriority: low labels 2026-07-11 19:03:44 +02:00
timothy added this to the Scheduling: refactor + distribution milestone 2026-07-17 00:25:07 +02:00
timothy added the in-progress label 2026-07-17 23:51:54 +02:00
Author
Owner

Claiming (in-progress). Scoped this vision down after recon: Autotune (#69) and the composite Create-Channel wizard (/app/new-channel, #63) already shipped, so the remaining heart of #176 is the visual WYSIWYG rule builder. Brainstormed a first sub-project with Timothy: a Kodi-style one-level-nested rule builder (compile-only to a closed Lucene subset, no schema change) landing in the SmartCollection create/edit dialog, backed by a new read-only GET /api/v1/search/fields catalog. Writing the design doc now; follow-ups (facet typeahead, relative dates, deeper nesting, ChannelBuilder/Auto-Tune inline adoption) will be filed as separate issues.

Claiming (in-progress). Scoped this vision down after recon: **Autotune** (#69) and the **composite Create-Channel wizard** (`/app/new-channel`, #63) already shipped, so the remaining heart of #176 is the **visual WYSIWYG rule builder**. Brainstormed a first sub-project with Timothy: a Kodi-style one-level-nested rule builder (compile-only to a closed Lucene subset, no schema change) landing in the SmartCollection create/edit dialog, backed by a new read-only `GET /api/v1/search/fields` catalog. Writing the design doc now; follow-ups (facet typeahead, relative dates, deeper nesting, ChannelBuilder/Auto-Tune inline adoption) will be filed as separate issues.
Author
Owner

Closed — visual rule builder shipped (PR #433, merged to main)

This completes the remaining leg of #176. Autotune (#69) and the composite Create-Channel wizard (#63) shipped earlier; this PR adds the visual WYSIWYG rule builder to the SmartCollection editor.

What was done

  • Read-only GET /api/v1/search/fields — curated, typed, labeled field catalog (single source of truth, MCP-introspectable). No DB change, no write-path change.
  • web/src/builder/rules/: Kodi one-level-nesting rule model → compiles to a closed Lucene subset and parses exactly that back (exact inverses; out-of-subset → raw-text fallback). Total escaping; round-trip proven by a 500-tree property test. useSearchFields hook + controlled RuleBuilder.
  • SmartDialog gains a Builder | Advanced toggle; the compiled Lucene string stays the single submitted value.

Design decisions (docs/decisions.md 2026-07-18): compile-only, no stored AST, no schema change — an authoritative AST would still need a Lucene→rules parser for every pre-existing/Auto-Tune query, so it buys little for a dual-provider migration cost. One-level-nesting Kodi model (arbitrary nesting = YAGNI).

Files changed: backend catalog (SearchController + GetSearchFieldCatalog + SearchFieldCatalog + DTO), web/src/builder/rules/*, web/src/screens/CollectionsScreen.tsx, docs (api-conventions, decisions, spa-conventions §12). Full test suites + property test added.

Review: 8 per-task adversarial reviews + a whole-branch Opus review. Bugs caught & fixed in-flight: fulltext operator ambiguity (split matches/notMatches), special-char escaping round-trip (made total), all-nullable generated DTO (clean RuleField), and an Important date-format bug (compiled yyyy-MM-dd vs the index's yyyyMMdd lexicographic format — would have silently excluded same-year items; fixed + re-reviewed CLEAN).

Deferred (filed as follow-ups): #434 facet-value typeahead · #435 relative dates · #436 deeper nesting · #437 ChannelBuilder/Auto-Tune inline adoption · #438 input validation/polish (bundles review minors).

Live-E2E: not gated (read-only endpoint, unchanged SmartCollection write path) — stated exemption per the skip rubric.

Docs updated: api-conventions.md (endpoint inventory), decisions.md (2026-07-18 entry), spa-conventions.md (§12 reusable rule builder), endpoint-index.md + v1.json + v1.d.ts (regenerated).

## Closed — visual rule builder shipped (PR #433, merged to main) This completes the remaining leg of #176. Autotune (#69) and the composite Create-Channel wizard (#63) shipped earlier; this PR adds the **visual WYSIWYG rule builder** to the SmartCollection editor. **What was done** - Read-only `GET /api/v1/search/fields` — curated, typed, labeled field catalog (single source of truth, MCP-introspectable). No DB change, no write-path change. - `web/src/builder/rules/`: Kodi one-level-nesting rule model → **compiles to a closed Lucene subset** and **parses exactly that back** (exact inverses; out-of-subset → raw-text fallback). Total escaping; round-trip proven by a 500-tree property test. `useSearchFields` hook + controlled `RuleBuilder`. - `SmartDialog` gains a `Builder | Advanced` toggle; the compiled Lucene string stays the single submitted value. **Design decisions** (docs/decisions.md 2026-07-18): compile-only, **no stored AST, no schema change** — an authoritative AST would still need a Lucene→rules parser for every pre-existing/Auto-Tune query, so it buys little for a dual-provider migration cost. One-level-nesting Kodi model (arbitrary nesting = YAGNI). **Files changed**: backend catalog (SearchController + GetSearchFieldCatalog + SearchFieldCatalog + DTO), `web/src/builder/rules/*`, `web/src/screens/CollectionsScreen.tsx`, docs (api-conventions, decisions, spa-conventions §12). Full test suites + property test added. **Review**: 8 per-task adversarial reviews + a whole-branch Opus review. Bugs caught & fixed in-flight: fulltext operator ambiguity (split matches/notMatches), special-char escaping round-trip (made total), all-nullable generated DTO (clean RuleField), and an **Important date-format bug** (compiled `yyyy-MM-dd` vs the index's `yyyyMMdd` lexicographic format — would have silently excluded same-year items; fixed + re-reviewed CLEAN). **Deferred** (filed as follow-ups): #434 facet-value typeahead · #435 relative dates · #436 deeper nesting · #437 ChannelBuilder/Auto-Tune inline adoption · #438 input validation/polish (bundles review minors). **Live-E2E**: not gated (read-only endpoint, unchanged SmartCollection write path) — stated exemption per the skip rubric. **Docs updated**: api-conventions.md (endpoint inventory), decisions.md (2026-07-18 entry), spa-conventions.md (§12 reusable rule builder), endpoint-index.md + v1.json + v1.d.ts (regenerated).
timothy removed the in-progress label 2026-07-18 03:30:57 +02:00
Sign in to join this conversation.
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: timothy/ersatztv#176