Library browse + search API with artwork (for the create-channel picker) #65
Closed
opened 2026-07-01 23:01:57 +02:00 by timothy
·
6 comments
No Branch/Tag Specified
main
renovate/dotnet-monorepo
renovate/meziantou.analyzer-3.x
renovate/lucene.net
renovate/sqlitepclraw.bundle_e_sqlite3-3.x
renovate/cliwrap-3.x
913-scripted-playout-401
release/v26.15.0-notes
issue-806-guard-populations
scratch/767b-poisoned
scratch/767b-control
release/v26.14.0-notes
release/v26.14.0
docs/510-skill-logo-bug-policy
fix/510-watermark-resolution-policy
fix/629-verdict-classifier-falseopens
fix/609-decisions-edit-token-scope
issue-135-clear-to-none
release/v26.12.0-notes
fix/409b-lastscan-api-parity
fix/401-updatechannel-mirror-422
fix/327-playlist-rename-validation
fix/410-scancancel-log-level
fix/409-447-librariesscreen-neverscanned
fix/338-zap-exit-code
fix/367-plex-budget-message
fix/310-debom-legacy-cs
ci/604-lane-rebalance
feat/388-design-mirror
feat/247-test-ownership
feat/247-primary-action
feat/357-player-owned-playback
feat/357-jellyfin-plugin-poc
fix/289-mcp-hardening
issue58-mcp
feat/244-channels-extract
ci/auto-bump-prod-compose
feat/multi-rerun-collections-api
feat/collections-api
feat/quick-wins
feat/185-docs-part2
feat/140-collections-screen
feat/146-channel-edit
feat/147-classic-ui-link
issue22-renovate-dashboard
feat/91-cutover
feat/63-composite-create
feat/65-library-browse
feat/85-epg
feat/86-schedule-editor
feat/109-dashboard-data
feat/99-session-tracking
fix/dockerfile-node-tag
feat/59-spa-foundation
docs/59-ui-redesign-brief
feat/102-json-guide
feat/111-schedule-durations
feat/104-artwork-upload
feat/103-media-sources-api
feat/playouts-read-api
feat/108-health-api
feat/105-picker-list-endpoints
issue-97-channel-state-api
issue42-jellyfin-musicvideos
issue46-rest-api-error-contract
dependabot/nuget/ErsatzTV.FFmpeg.Tests/multi-d307a2e06f
qsv-improvements
hdr-vulkan-cuda-test
v26.16.0
v26.15.0
v26.14.0
v26.13.0
v26.12.0
v26.11.0
v26.10.0
v26.9.0
v26.8.0
v26.7.0
blazor-final
v26.6.0
v26.5.0
v26.4.0
v26.3.1
v26.3.0
v26.2.0
v26.1.1
v26.1.0
v25.9.0
v25.8.0
v25.7.1
v25.7.0
v25.6.0
v25.5.0
v25.4.0
v25.3.1
v25.3.0
v25.2.0
v25.1.0
v0.8.8-beta
v0.8.7-beta
v0.8.6-beta
v0.8.5-beta
v0.8.4-beta
v0.8.3-beta
v0.8.2-beta
v0.8.1-beta
v0.8.0-beta
v0.7.9-beta
v0.7.8-beta
v0.7.7-beta
v0.7.6-beta
v0.7.5-beta
v0.7.4-beta
v0.7.3-beta
v0.7.2-beta
v0.7.1-beta
v0.7.0-beta
v0.6.9-beta
v0.6.8-beta
v0.6.7-beta
v0.6.6-beta
v0.6.5-beta
v0.6.4-beta
v0.6.3-beta
v0.6.2-beta
v0.6.1-beta
v0.6.0-beta
v0.5.8-beta
v0.5.7-beta
v0.5.6-beta
v0.5.5-beta
v0.5.4-beta
v0.5.3-beta
v0.5.2-beta
v0.5.1-beta
v0.5.0-beta
v0.4.5-alpha
v0.4.4-alpha
v0.4.3-alpha
v0.4.2-alpha
v0.4.1-alpha
v0.4.0-alpha
v0.3.8-alpha
v0.3.7-alpha
develop
v0.3.6-alpha
v0.3.5-alpha
v0.3.4-alpha
v0.3.3-alpha
v0.3.2-alpha
v0.3.1-alpha
v0.3.0-alpha
v0.2.5-alpha
v0.2.4-alpha
v0.2.3-alpha
v0.2.2-alpha
v0.2.1-alpha
v0.2.0-alpha
v0.1.5-alpha
v0.1.4-alpha
v0.1.3-alpha
v0.1.2-alpha
v0.1.1-alpha
v0.1.0-alpha
v0.0.62-alpha
v0.0.61-alpha
v0.0.60-alpha
v0.0.59-alpha
v0.0.58-alpha
v0.0.57-alpha
v0.0.56-alpha
v0.0.55-alpha
v0.0.54-alpha
v0.0.53-alpha
v0.0.52-alpha
v0.0.51-alpha
v0.0.50-alpha
v0.0.49-prealpha
v0.0.48-prealpha
v0.0.47-prealpha
v0.0.46-prealpha
v0.0.45-prealpha
v0.0.44-prealpha
v0.0.43-prealpha
v0.0.42-prealpha
v0.0.41-prealpha
v0.0.40-prealpha
v0.0.39-prealpha
v0.0.38-prealpha
v0.0.37-prealpha
v0.0.36-prealpha
v0.0.35-prealpha
v0.0.34-prealpha
v0.0.33-prealpha
v0.0.32-prealpha
v0.0.31-prealpha
v0.0.30-prealpha
v0.0.29-prealpha
v0.0.28-prealpha
v0.0.27-prealpha
v0.0.26-prealpha
v0.0.25-prealpha
v0.0.24-prealpha
v0.0.23-prealpha
v0.0.22-prealpha
v0.0.21-prealpha
v0.0.20-prealpha
v0.0.19-prealpha
v0.0.18-prealpha
v0.0.17-prealpha
v0.0.16-prealpha
v0.0.15-prealpha
v0.0.14-prealpha
v0.0.13-prealpha
v0.0.12-prealpha
v0.0.11-prealpha
v0.0.10-prealpha
v0.0.9-prealpha
v0.0.8-prealpha
v0.0.7-prealpha
v0.0.6-prealpha
v0.0.5-prealpha
v0.0.4-prealpha
v0.0.3-prealpha
v0.0.2-prealpha
v0.0.1-prealpha
Labels
Clear labels
ad-hoc
api
bug
ci-cd
content
dependencies
enhancement
frontend
in-progress
jellyfin
parked
priority: high
priority: low
priority: medium
review
security
One-off / ad-hoc work not tracked by a dedicated issue
REST API / HTTP endpoints
Something isn't working
Build, test, deploy pipeline
Channel content / schedules / playlists
Dependency updates (Renovate)
New feature or improvement
ChicoryTV React SPA frontend
Claimed by an active session — do not pick up
Jellyfin tuner / IPTV integration
Excluded from automatic queue pickup; work only when explicitly selected
Adversarial review finding
Security / vulnerability fix
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
No Assignees
Notifications
Due Date
No due date set.
Blocks
#89 ChicoryTV SPA: Channel Builder (primary deliverable)
timothy/ersatztv
Reference: timothy/ersatztv#65
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
Part of #62 (Create Channel backend prerequisites).
Goal
An API to browse and search the media library with artwork, powering the left pane of the create-channel builder (grid of poster art, searchable, filterable by library).
Scope
Notes
Scope additions from the ChicoryTV plan audit (2026-07-02)
The Channel Builder (#89) and Schedule editor (#86) prototypes consume more than artwork + title search. Add to this issue's scope:
min/sub) depend on them.CollectionType(CollectionId/MultiCollectionId/SmartCollectionId/RerunCollectionId/MediaItemIdfor show/season/artist /PlaylistId). Shows/seasons/artists, playlists, multi-collections, and reruns currently have no browse/list endpoint at all.Findings / approach before coding
I inspected the existing REST foundation and search infrastructure in the issue #65 worktree.
Search-index reuse decision
ISearchIndex.Search(...)/LuceneSearchIndexfor media-item candidate selection, paging, total count, type filtering, library filtering, and title search. Existing Blazor list/search pages already use this path (QuerySearchIndexMovies/Shows/Seasons/Artists/...).(type, id), so the browse handler will use Lucene for the interactive search/page candidate set, then do bounded EF projections for only the returned ids to add artwork/count/duration metadata. This avoids a new unbounded EF search path and avoids the #102-style wide include load.Collection,SmartCollection,MultiCollection,RerunCollection, andPlaylisttables, paged with the combined result set. If this becomes too large, I’ll keep media browse/search first and call out the split rather than silently dropping collection scope.Projection shape
LibraryBrowseItemResponseModelfields planned:id,mediaType,title,libraryId,libraryName,artwork,duration,itemCount,collectionKind, and picker ids:collectionId,multiCollectionId,smartCollectionId,rerunCollectionId,mediaItemId,playlistId./artwork/posters/..., Jellyfin/Emby relative proxy mapping, Plex-relative artwork routes where already used). I will not add a new artwork URL scheme.CollectionId; smart =>SmartCollectionId; multi =>MultiCollectionId; rerun =>RerunCollectionId; playlist =>PlaylistId; movie/show/season/artist =>MediaItemIdwith the correspondingCollectionType/media type.Endpoints / DTOs
GET /api/library/browse(Name = "BrowseLibrary"): query paramsquery,libraryId,mediaType,pageNum,pageSize; returnsPagedLibraryBrowseItemsResponseModel.GET /api/media-sources(GetMediaSources). I’ll consume that model conceptually rather than duplicating a library list endpoint.Tests / verification plan
Done
What was done: Read-only inspection of existing Lucene/search infrastructure and Blazor/UI usage for issue #65, focused on
ISearchIndex/LuceneSearchIndex, result shapes, indexed fields, current query handlers, and whether title search can support movies, shows, artists, and collections.Root cause: n/a
Files changed: none
Verification: Read-only code inspection in
/Users/timothy/ersatztv/.worktrees/issue-65-library-browse; no build/tests run because no code was changed.Deferred: Implementation remains pending. Key finding: Lucene is suitable for media title search and paging for movies/shows/artists, but collections are not first-class Lucene documents today and existing collection autocomplete uses EF
LIKE.Follow-up issues: none
Docs updated: n/a
Progress
Implemented the first backend slice in the issue worktree:
GET /api/library/browse(BrowseLibrary) with clamped paging.LibraryBrowseMediaType,LibraryBrowseItemResponseModel, andPagedLibraryBrowseItemsResponseModelunderErsatzTV.Core/Api/LibraryBrowsewith#nullable enable.GetLibraryBrowseItems+ handler.ISearchIndex.Search(...)for movie/show/season/artist candidate ids, type filters, library filters, title search, total count, and paging; EF only hydrates returned ids for title/artwork/duration/count fields.CollectionId,SmartCollectionId,MultiCollectionId,RerunCollectionId,PlaylistId,MediaItemId).Current test evidence:
TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj --filter "FullyQualifiedName~LibraryBrowseControllerTests|FullyQualifiedName~GetLibraryBrowseItemsHandlerTests" -v minimal=> 6 passed.Known scope caveat while continuing: manual collections and playlists currently expose cheap item counts; smart/multi/rerun aggregate duration/artwork is still limited because those are not first-class search-index documents and exact expansion can become expensive. I’m continuing verification and will either tighten this further or explicitly list it as deferred if it should split from core browse/search.
Done
What was done: Opened PR #130 from
feat/65-library-browseimplementing the backend library browse/search API slice. AddedGET /api/library/browse(BrowseLibrary) with clamped paging, title query, library filter, media-type filter, poster-grid artwork references, duration/count fields, and typed picker id slots for media, manual/smart/multi/rerun collections, and playlists. Media candidate search reusesISearchIndex.Search(...)/ Lucene for movie/show/season/artist candidate ids, total count, type filtering, library filtering, and interactive title search; EF only hydrates the bounded page ids. Collection-like targets are projected with narrow EF queries because collections are not first-class Lucene documents today. OpenAPI and generated TS types were regenerated.Root cause: n/a
Files changed:
ErsatzTV.Application/LibraryBrowse/Queries/GetLibraryBrowseItems.cs;ErsatzTV.Application/LibraryBrowse/Queries/GetLibraryBrowseItemsHandler.cs;ErsatzTV.Core/Api/LibraryBrowse/LibraryBrowseItemResponseModel.cs;ErsatzTV.Core/Api/LibraryBrowse/LibraryBrowseMediaType.cs;ErsatzTV.Core/Api/LibraryBrowse/PagedLibraryBrowseItemsResponseModel.cs;ErsatzTV/Controllers/Api/LibraryBrowseController.cs;ErsatzTV.Tests/Application/LibraryBrowse/GetLibraryBrowseItemsHandlerTests.cs;ErsatzTV.Tests/Controllers/LibraryBrowseControllerTests.cs;ErsatzTV/wwwroot/openapi/v1.json;web/src/api/generated/v1.d.ts.Verification:
TZ=UTC dotnet build ErsatzTV/ErsatzTV.csprojpassed;./scripts/update-openapi.shwas run, with the OpenAPI target rerun successfully after a local hang;TZ=UTC dotnet build ErsatzTV.slnpassed;TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj -v minimalpassed 374 tests;TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj -v minimalpassed 493 tests with 1 skipped;cd web && npm cipassed;cd web && npm run generate:apipassed;cd web && npm run typecheckpassed. PR CI run 251 for head127a1307379f5dd9a07c7f4fb3874ab402799da3completed successfully: Build & test passed, EF migration integrity passed, PR image job skipped.Deferred: Exact aggregate total duration and representative artwork for smart/multi/rerun collections remain limited/deferred. Those targets are not first-class Lucene docs, and exact expansion risks becoming the expensive graph walk this issue explicitly wanted to avoid. Manual collection and playlist cheap counts are included; media duration/count projection is included. Library filter chips continue to come from the existing
GET /api/media-sourcesread model rather than a duplicated endpoint.Follow-up issues: none created; recommend splitting exact aggregate collection duration/artwork into a follow-up if Fable/user wants that before #65 closes.
Docs updated: OpenAPI
v1.jsonand generated web API typings updated; no prose docs/skills changes.Done
What was done: Applied Fable review fixes on PR #130 and pushed
630119f382385040d77cd68b63b1ceb6fb88464btofeat/65-library-browse. ManualCollectionbrowse rows now include bounded page-level total duration and representative poster artwork from collection member media. Added regression coverage for page transitions across media/manual/smart results, manual collection metadata, season hydration, artist hydration, and libraryId collection filtering. Also fixed the review nits: stale-index paging comment, deterministic metadata row selection, OpenAPI tagLibraries, escaped EFLIKEwildcards, deterministic max duration, and rerun schedule-addressing comment.Root cause: Review follow-up; the original slice intentionally deferred smart/multi/rerun aggregates but also left manual collection artwork/duration empty even though manual collection members are directly reachable with bounded page queries.
Files changed:
ErsatzTV.Application/LibraryBrowse/Queries/GetLibraryBrowseItemsHandler.cs;ErsatzTV.Tests/Application/LibraryBrowse/GetLibraryBrowseItemsHandlerTests.cs;ErsatzTV/Controllers/Api/LibraryBrowseController.cs;ErsatzTV/wwwroot/openapi/v1.json.Verification: Focused red/green showed
Handle_Should_Hydrate_Manual_Collection_Artwork_And_Total_Durationfailing on the previous code, then focusedFullyQualifiedName~LibraryBrowsepassed 11 tests.TZ=UTC dotnet build ErsatzTV/ErsatzTV.csprojpassed../scripts/update-openapi.shwas run after the successful build but locally returnedBuild FAILEDafter a silent 24m31s with 0 warnings/0 errors; the equivalent OpenAPI targetTZ=UTC dotnet build ErsatzTV.csproj -t:GenerateOpenApiDocuments -v normalfromErsatzTV/passed and regeneratedv1.json.cd web && npm cipassed.cd web && npm run generate:apipassed.cd web && npm run typecheckpassed.TZ=UTC dotnet build ErsatzTV.slnpassed.TZ=UTC dotnet test ErsatzTV.Tests/ErsatzTV.Tests.csproj -v minimalpassed 379 tests.TZ=UTC dotnet test ErsatzTV.Core.Tests/ErsatzTV.Core.Tests.csproj -v minimalpassed 493 tests with 1 skipped. PR CI run 255 for head630119f382385040d77cd68b63b1ceb6fb88464bcompleted successfully: Build & test passed, EF migration integrity passed, PR image job skipped.Deferred: Exact aggregate duration/artwork for smart/multi/rerun collections remains deferred because exact expansion is the expensive graph walk already called out for this slice. Playlists remain count-only as accepted.
Follow-up issues: none created.
Docs updated: OpenAPI
v1.jsonupdated for theLibrariestag; generated TS types were regenerated and unchanged.Closing #65 — merged to main via PR #130 (merge commit
c4007293).What was done
GET /api/library/browse(BrowseLibrary): unified browse/search across movies, shows, seasons, artists (via the existing LuceneISearchIndex— reuse decision documented on this issue) plus manual/smart/multi/rerun collections and playlists (narrow EF projections; they are not Lucene documents). Paging spans both sources with a hand-verified skip cascade; pageNum/pageSize clamped server-side.CollectionType(CollectionId/MultiCollectionId/SmartCollectionId/RerunCollectionId/MediaItemId/PlaylistId) for the #86/#89 pickers.Librariestag; deterministic max duration; stale-index paging comment; RerunRerun note. New tests for cross-source paging, season/artist hydration, manual-collection metadata, and libraryId filtering (ErsatzTV.Tests 374→379).Root cause: n/a (feature).
Files: ErsatzTV.Application/LibraryBrowse/, ErsatzTV.Core/Api/LibraryBrowse/, ErsatzTV/Controllers/Api/LibraryBrowseController.cs, tests, regenerated v1.json + web v1.d.ts.
Deferred (follow-up when #89 needs it): exact aggregate total duration + representative artwork for smart/multi/rerun collections (not first-class Lucene docs; exact expansion = expensive graph walk — they return kind badge + item counts today). Minor: the two manual-collection metadata helpers each fetch CollectionItems (could share one fetch); very large manual collections make the duration sum inherently heavy.
Docs: browse endpoint recorded in the ChicoryTV issue-queue handoff (docs/handoffs/chicorytv-issue-queue.md); no operational doc impact.
Library filter chips remain sourced from
GET /api/media-sourcesper the scope note.