Media Quest
Easy Stream
Easy Stream turns an existing read-only MKV archive into a browser-first streaming library. It generates validated CMAF and fragmented-MP4 HLS only when requested, while keeping source media isolated from disposable cache and durable derived outputs.
- MKV → HLSMedia pathArchived source files become browser-compatible CMAF and fragmented-MP4 HLS on demand.
- Read-onlySource archiveThe transcoding pipeline never mutates the original media library.
- SoloOwnershipDesigned and implemented independently across the application and streaming stack.
Mission Brief
Large MKV archives are durable and convenient for storage, but they are not a reliable delivery format for browsers, televisions, or mobile clients.
The system needed to expose a polished library without pre-transcoding everything, modifying source files, or allowing expensive FFmpeg work to grow without limits.
System Map
Architecture
Vue Library
A browser and TV-oriented interface provides discovery, playback, preferences, and local resume state.
Fastify API
The TypeScript API manages catalog data, playback authorization, signed access, and requested quality.
Redis & BullMQ
Bounded queues coordinate media work, deduplicate requests, and keep expensive jobs away from web processes.
FFmpeg Workers
Workers probe inputs, stream-copy compatible media, transcode when necessary, and validate generated HLS.
Nginx Gateway
Signed cookies protect media delivery while separate mounts isolate source, cache, and durable outputs.
Strategy Route
Battle Plan
The implementation path, checkpoint by checkpoint.
- Checkpoint 01
Mount the archive read-only and treat generated media as replaceable artifacts with explicit ownership and retention rules.
- Checkpoint 02
Prefer stream copying when codecs are compatible, then use controlled transcoding only when playback requires it.
- Checkpoint 03
Publish immutable, validated output generations so viewers never receive partially written playlists or segments.
- Checkpoint 04
Keep disposable cache separate from durable derived media and make quality selection an explicit client decision.
- Checkpoint 05
Store personal playback preferences and resume points locally rather than requiring an account for the showcase experience.
Critical Encounter
Boss Fight
Media jobs are heavy, long-running, and failure-prone. The design had to prevent one popular title or malformed source from exhausting workers, corrupting shared output, or changing the archival copy.
Achievements Unlocked
Quest Rewards
What the quest delivered.
- Reward 01 unlocked
Existing MKV libraries can be browsed and streamed without an up-front full-library conversion.
- Reward 02 unlocked
The source archive remains protected while generated output can be validated, versioned, expired, and rebuilt.
- Reward 03 unlocked
Web serving, orchestration, transcoding, and storage have clear boundaries that can scale independently.
Special Items
Technical Loadout
- TypeScript
- Vue
- Vite
- Fastify
- PostgreSQL
- Redis
- BullMQ
- FFmpeg
- Nginx
- Docker
- CMAF HLS
Proof of Work
Explore the Quest
Capabilities describe the public functional v1 repository. Performance objectives in the project documentation are design targets, not claimed production results.