Commercial product

Media Library Platform

A subscription media library for saving audio and video, organizing account content and keeping selected audio available offline on desktop and mobile. It costs about half as much as YouTube Music.

Role: Product Design & Full-stack Engineering
Period: 2023
Categories: FrontendBackendInfrastructure
Stack: ReactTypeScriptViteFastifyZodOIDCKeycloakPWAyt-dlpFFmpegDockerCaddy

Key metrics

Tracks in the library: 53,973; Current track records in the private production library.; Current snapshot; this is a catalogue count, not plays or downloads.
Albums: 5K+; Album and collection records in the private production library.; Current snapshot; threshold rounded down to 5,000.
Registered accounts: 537; Account records in the private production aggregate.; Current snapshot; this is not an active-user count.
Stored audio: 364 GB; Audio payload within the production media-storage boundary.; Current snapshot; decimal gigabytes rounded to the nearest GB; video and metadata are excluded.

Overview

Media Library Platform is a commercial subscription product for people who want to keep audio and video in one account library instead of managing separate download jobs. The subscription costs about half as much as YouTube Music.

Media Library Platform turns that lifecycle into an authenticated product workflow: inspect an item or playlist, choose exactly what belongs in an account library, save audio or video, organize it into albums and categories, and keep selected audio available offline in the installable PWA.

Challenge

Single items, playlists and time-bounded fragments need different selection controls, but they must produce one predictable library model rather than a collection of unrelated download jobs.

History, categories, stored files and playback access contain account-owned state. Every read and mutation has to remain scoped to the authenticated identity, including media elements that cannot attach a normal authorization header.

Offline playback introduces a second copy of selected audio on the device. Cache state, partial failures, removal and reconnection must stay understandable without implying that the entire remote library is mirrored.

Solution

The React PWA inspects a supplied source before processing. A user can save a single item, all playlist entries, a selected subset or an index range, choose audio or video, and trim a single item to a specific fragment before assigning the result to history or an album.

A separate Fastify API validates requests and coordinates source inspection, media processing, status updates and account-scoped persistence. The library presents history, albums, categories, playback and file actions as one product workflow rather than exposing worker mechanics.

OIDC protects the application and API. Normal requests use bearer headers; protected playback URLs accept a query token only for GET or HEAD when a browser media element cannot set that header. Silent renewal and a single authenticated retry handle an expired session, while typed errors keep processing failures bounded.

Responsibilities

Define the product model around account libraries, album organization and continuous playback rather than a one-off downloader.
Set the subscription price at roughly half the cost of YouTube Music.
Build the React and Vite PWA for desktop, mobile and installable offline use.
Implement single-item, playlist, selected-entry, index-range and fragment workflows for audio and video.
Design the Fastify API, validation, processing lifecycle, protected range streaming and account-scoped storage boundaries.
Integrate OIDC authentication, silent session renewal and restricted token handling for browser media routes.
Implement selected-album audio caching with a service worker and the Cache API, including progress, removal and partial-failure feedback.

Architecture

Interface

React installable PWA

Services

OIDC identity provider
Fastify API
Media processing worker
Protected playback routes

Data

User-scoped library
Device offline audio cache

Automation

Media item or playlist

Infrastructure

Caddy + container runtime

Item or playlist inspected before processing
Media item or playlist -> React installable PWA
OIDC sign-in and silent renewal
React installable PWA -> OIDC identity provider
Validated identity and claims
OIDC identity provider -> Fastify API
Authenticated library and processing requests
React installable PWA -> Fastify API
Validated item, playlist or fragment job
Fastify API -> Media processing worker
Prepared media and terminal status
Media processing worker -> User-scoped library
Account-owned file resolution
User-scoped library -> Protected playback routes
Protected byte-range stream
Protected playback routes -> React installable PWA
Selected audio albums
React installable PWA -> Device offline audio cache
Device-local playback state
Device offline audio cache -> React installable PWA
Controlled service runtime
Fastify API -> Caddy + container runtime
Isolated processing tools
Media processing worker -> Caddy + container runtime

Technical decisions

Model a library, not a queue of jobs

Problem: A processing result becomes difficult to reuse when it is visible only as a completed task.
Decision: Persist results into history and user-managed albums, then make organization, playback, movement and removal first-class library actions.
Reason: The product remains useful after processing finishes and supports a long-lived account library.
Trade-off: Library state and file lifecycle must remain consistent when items move between albums or are deleted.

Keep the price comparison approximate

Problem: A fixed amount would become misleading across currencies and after price changes.
Decision: State the subscription as costing about half as much as YouTube Music.
Reason: The comparison communicates the intended price level without publishing a currency-specific amount.
Trade-off: YouTube Music pricing varies by market and can change, so the comparison must remain approximate.

Keep every durable object account-scoped

Problem: Shared queries or file paths could expose another account's history, categories or media.
Decision: Derive the account boundary from the validated identity and apply it to history, categories, files, offline metadata and UI state.
Reason: Authorization is part of the data model instead of a filter added only at the interface.
Trade-off: Background processing and storage helpers must carry identity context through every operation.

Restrict query tokens to playback constraints

Problem: Audio and video elements cannot reliably attach an Authorization header to their source URL.
Decision: Use bearer headers by default and accept a query access token only on GET or HEAD media requests.
Reason: Protected range playback works without widening query-token support to mutations or ordinary API traffic.
Trade-off: Playback URLs remain sensitive and must be short-lived and excluded from logs or copied diagnostics.

Cache only selected audio albums

Problem: Mirroring every stored file would consume device space without reflecting what a user actually needs offline.
Decision: Let the user select audio albums for device-local caching and expose cached counts, size, refresh and removal controls.
Reason: Offline availability is deliberate, visible and reversible.
Trade-off: Video and unselected audio still require the authenticated online service.

Bound renewal and processing retries

Problem: Expired sessions and source-side authentication failures can otherwise produce loops or unclear terminal states.
Decision: Renew an expired access token and retry an API request once; processing retries only recognized recoverable source failures before returning a typed error.
Reason: Transient failures can recover while persistent failures remain observable and finite.
Trade-off: Some recoverable-looking failures still require a deliberate user retry after the bounded attempt is exhausted.

Media

Gallery

Outcomes

The platform is offered as a paid subscription at about half the price of YouTube Music and supports collection, organization, protected playback and offline audio on desktop and mobile.
Playlist selection, index ranges and fragment controls let users save only the part of a source that belongs in their library.
Identity-scoped storage and restricted media authorization separate each account's library data while the source code and deployment remain closed.

Verified highlights

The current implementation separates a React and Vite PWA from a Fastify API and media-processing runtime.
Single items support audio or video output and explicit start and end fragment controls.
Playlist workflows support all entries, selected entries and an index range, with an album destination.
History, categories, stored files and interface state are resolved within an authenticated account boundary.
API requests use bearer headers; query-token authentication is restricted to GET and HEAD requests needed by protected media playback.
Selected audio albums can be cached and removed through the service worker and browser Cache API.

Learnings

A media utility becomes a product when the post-processing workflow—organization, playback, retrieval and offline intent—is designed as carefully as source handling.
Offline and authenticated playback meet at awkward browser boundaries, so token scope, range requests, renewal and cache ownership need to be designed together.