What needed solving.
A single media library must work across browsers with different codecs, range-request behavior, remotes, and network bandwidth. Playback also needs resumable sessions, source selection, subtitles, and resilient recovery without relying on a single browser capability profile.
- 01Catalog + browser capabilities
- 02Source selection + range streaming
- 03Resumable player
Simplified from the implementation and project notes.
How it fits together.
Source selection combines browser, audio and network constraints
The catalog/provider layer supplies candidate sources; the client reports browser codec capabilities and the picker ranks only playable, non-blocked sources with English audio. It estimates bitrate from file size and runtime, then weighs connection fit, resolution, cache availability, audio channels and conversion cost. Automatic playback is limited to fitting versions at 720p or better, with a small retry set before asking the user. Tests cover codec parsing, language hints, resolution and bandwidth ranking, unknown size, blocked/uncached availability and smaller-version choice.
Range reads are coalesced and cached across the browser and FFmpeg
A local server mediates byte-range reads. It stores 256 KiB blocks under a 512 MiB LRU budget, joins nearby readers to an in-flight upstream fetch, reads ahead for playback, limits concurrent upstream requests and retries transient failures. A changed source URL clears old blocks because a provider may return different bytes. Tests exercise range parsing and cache behavior; the important failure cases are upstream refusal/expired links, ignored or malformed ranges, short reads, silent connections and a new URL replacing cached content.
Playback falls back through remux and HLS while preserving progress
When the browser cannot decode a source directly, FFmpeg copies video and converts the selected audio track to AAC; HEVC is tagged hvc1 for MP4 compatibility. Safari can use HLS fragments, while sessions retain playback position for resume and expose source alternatives after repeated stalls. Seeking restarts conversion near the target and relies on the range cache for indexed reads. Server tests cover route/session behavior and FFmpeg-dependent response paths; device codec support remains runtime-specific, so a passing unit test does not prove playback on every TV.
Inside the software.
A media client spanning video playback, ebooks, music libraries, and discovery. Its experimental Story DNA pipeline adds structured story profiles to the catalog. Screenshots use a fresh local library; the book and audio samples were created for this walkthrough.
Video discovery and resumable playback
Browse and search movie and TV catalogs, open title and episode pages, pick a source, and resume playback from saved progress.
React client and TypeScript/Bun API; profile-scoped progress and My List in SQLite; episode ordering, player sessions, source picker and recovery paths.
Implemented; actual stream requires configured provider/account and compatible media source.
Implementation references
debrid-flix/README.mddebrid-flix/src/pages/Home.tsxdebrid-flix/src/pages/Title.tsxdebrid-flix/src/pages/VideoPlayer.tsxdebrid-flix/src/pages/SourcePicker.tsxdebrid-flix/server.tsdebrid-flix/src/playback.ts
Capability-aware streaming and recovery
Select among available versions using codec support, audio, bitrate, cache state and device fit; provide alternatives when playback stalls.
Client codec and bandwidth detection feeds a ranking picker. Server range cache coalesces nearby 256 KiB reads under a 512 MiB LRU; FFmpeg remux/HLS paths cover browser limitations, with source changes invalidating cached bytes.
Source includes unit/server tests; per-device codec success remains environment-dependent.
Implementation references
debrid-flix/src/pick.tsdebrid-flix/src/codecs.tsdebrid-flix/src/bandwidth.tsdebrid-flix/server/rangecache.tsdebrid-flix/server/remux.tsdebrid-flix/test/server.test.tsdebrid-flix/src/pick.test.ts
Profiles and kids mode
Separate watch progress, lists, reading progress and YouTube preferences by profile, with optional service sections and a rating-limited kids profile.
Profile selection is persisted locally and passed on API requests; kids mode applies rating allowlists and alternate home rows. Profiles are identity/preferences partitions, not password accounts.
Present in the reviewed source.
Implementation references
debrid-flix/README.mddebrid-flix/server/profiles.tsdebrid-flix/src/pages/Profiles.tsxdebrid-flix/src/profile.tsdebrid-flix/src/store.ts
Catalog and story-led discovery
Filter IMDb catalog by genre, decade, ratings and story attributes; accept typed descriptions as structured filters and show related story rows on title pages.
URL-backed filter state; IMDb advanced search and a SQLite story index. Story filter choices are drawn from profiled titles; semantic matching uses locally stored vectors when available.
Implemented discovery flows; underlying story profiles have partial coverage and background enrichment.
Implementation references
debrid-flix/README.mddebrid-flix/server/discover.tsdebrid-flix/src/pages/Discover.tsxdebrid-flix/server/story.tsdebrid-flix/server/storydna.tsdebrid-flix/server/db.ts
Taste-based home rows
Build profile-specific recommendations from watched titles and My List, including continue watching, new episodes, similar titles and taste-based rows.
Taste weights title completion, recency and list saves across genre, people and story features; scores candidate rows and diversifies results. IMDb/catalog data is cached locally.
Implemented; recommendation quality depends on available history and profile coverage.
Implementation references
debrid-flix/README.mddebrid-flix/server/taste.tsdebrid-flix/server/morelike.tsdebrid-flix/server/imdb.tsdebrid-flix/src/pages/Home.tsx
Story DNA analysis
Generate structured story profiles covering story type, plot, arc, stakes, devices, themes, motifs and tone, with source citations and uncertainty readings.
Pilot pipeline combines Wikipedia, IMDb plot/keywords/reviews and model judgments; stores source text and candidate readings, validates claims against quotes, and exposes profiles on title pages.
Implemented pilot/research feature. README reports evaluation on a small curated set; its model-generated profiles remain experimental.
Implementation references
debrid-flix/README.mddebrid-flix/server/storydna.tsdebrid-flix/server/story.tsdebrid-flix/src/pages/Story.tsx
Books library and reader
Browse a book library and read supported ebook and comic formats with saved reading position.
Dedicated Books and Reader routes use vendored Foliate.js readers, PDF.js and format modules; profile-scoped reading progress is persisted separately from video progress.
Implemented; local library/provider ingestion depends on configuration.
Implementation references
debrid-flix/src/pages/Books.tsxdebrid-flix/src/pages/Reader.tsxdebrid-flix/vendor/foliate-js/view.jsdebrid-flix/vendor/foliate-js/epub.jsdebrid-flix/vendor/foliate-js/comic-book.jsdebrid-flix/server.ts
Music library and player
Browse and play music with a dedicated music surface and profile-specific activity.
Separate music page/player logic and server API integrate configured catalog/source add-ons; music state is available to discovery and profile preferences.
Implemented; source availability depends on configured integrations.
Implementation references
debrid-flix/src/pages/Music.tsxdebrid-flix/src/music.tsdebrid-flix/src/pages/Player.tsxdebrid-flix/src/pages/SongSearch.tsxdebrid-flix/src/addons.ts
Music discovery and analysis tools
Explore song search, recommendations and analysis views including Song DNA, trends, taste and X-ray pages.
Dedicated pages expose discovery and analysis surfaces backed by server modules and configured music sources; related analysis routes are distinct from basic playback.
Implemented UI and supporting routes; third-party data/source coverage varies. Analysis accuracy has not been independently evaluated.
Implementation references
debrid-flix/src/pages/SongDna.tsxdebrid-flix/src/pages/SongTrends.tsxdebrid-flix/src/pages/MusicTaste.tsxdebrid-flix/src/pages/SongXray.tsxdebrid-flix/src/pages/Discover.tsxdebrid-flix/src/pages/Lineage.tsx
YouTube channels, captions and inspiration
Manage channel subscriptions and categories, save videos, browse recommendations and inspect captions or inspiration collections.
Per-profile channel manager, topic/history state and caption/search pages are exposed through the React app and server integrations.
Implemented; recommendation and caption content depends on configured external services/data.
Implementation references
debrid-flix/src/pages/ChannelManager.tsxdebrid-flix/src/pages/YouTubeCaptions.tsxdebrid-flix/src/pages/Inspiration.tsxdebrid-flix/src/pages/Harmony.tsxdebrid-flix/README.md
Building and checking it.
A user selects a profile, browses a catalog, chooses a title, and the server selects a browser-compatible source and streams it through the local service. The player resumes from saved progress and can switch to a smaller or more compatible source after repeated stalls. Keyboard and TV remote navigation share app-level focus and playback actions.
Books and music use separate ingestion and playback flows but share profiles, home discovery, and persistent progress. Media-provider credentials and host topology are deployment configuration, not part of the public case study.
A personal-use integration dependent on external catalog and media services. Codec support and TV behavior vary by device; some playback paths require FFmpeg. The code does not establish rights to third-party media.
Source notes
Based on repository code and project records reviewed on October 30, 2026. Historical checks are described as recorded, not rerun for this article. Screenshots, renders, and mockups are labeled individually.
debrid-flix/README.mddebrid-flix/package.jsondebrid-flix/src/pick.tsdebrid-flix/server/rangecache.tsdebrid-flix/server/remux.tsdebrid-flix/test/server.test.tsdebrid-flix/src/pick.test.tsdebrid-flix/server/rangecache.test.ts