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.

Role
Solo developer · product, architecture, backend, frontend, media pipeline, and deployment
Timeline
2026
Status
Functional v1

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

  1. Vue Library

    A browser and TV-oriented interface provides discovery, playback, preferences, and local resume state.

  2. Fastify API

    The TypeScript API manages catalog data, playback authorization, signed access, and requested quality.

  3. Redis & BullMQ

    Bounded queues coordinate media work, deduplicate requests, and keep expensive jobs away from web processes.

  4. FFmpeg Workers

    Workers probe inputs, stream-copy compatible media, transcode when necessary, and validate generated HLS.

  5. 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.

  1. Checkpoint 01

    Mount the archive read-only and treat generated media as replaceable artifacts with explicit ownership and retention rules.

  2. Checkpoint 02

    Prefer stream copying when codecs are compatible, then use controlled transcoding only when playback requires it.

  3. Checkpoint 03

    Publish immutable, validated output generations so viewers never receive partially written playlists or segments.

  4. Checkpoint 04

    Keep disposable cache separate from durable derived media and make quality selection an explicit client decision.

  5. Checkpoint 05

    Store personal playback preferences and resume points locally rather than requiring an account for the showcase experience.

Critical Encounter

Boss Fight

Boss HP Resolved

  • 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

View Source on GitHub

Capabilities describe the public functional v1 repository. Performance objectives in the project documentation are design targets, not claimed production results.