@muhkoo/theater-transcoder

A tiny native-ffmpeg worker for Muhkoo Theater. Sign in as yourself and it drains your library's transcode queue using all your cores — so uploads finish far faster than in-browser WebAssembly (which is ~20–40× slower and capped at a few threads).

Run it on a spare machine (a many-core server, say) alongside or instead of the browser. It coordinates with your browser tabs as a peer over your private Muhkoo Space: any device can claim a job, progress streams live everywhere, and pause/cancel from any device stops it here too.

Install & run

# one-off (no install)
npx @muhkoo/theater-transcoder --username you

# or install globally
npm i -g @muhkoo/theater-transcoder
MUHKOO_USERNAME=you MUHKOO_PASSWORD=… theater-transcoder

You'll be prompted for your password if it isn't in $MUHKOO_PASSWORD. Credentials never leave the machine — it runs the same zero-knowledge login the browser uses. Requires Node ≥ 20 (≥ 22 recommended).

ffmpeg (hardware acceleration)

The transcoder prefers a system-installed ffmpeg and offloads work to the GPU when one is available — Apple VideoToolbox, NVIDIA NVENC, Intel QuickSync, or VAAPI. It runs the whole pipeline on-GPU where it can (hardware decode → scale → encode, frames never leaving the GPU), which on NVENC/QuickSync boxes hits many times realtime; on Apple Silicon the encoder is the ceiling but GPU decode still roughly halves CPU use. It automatically steps down — full-GPU → GPU-encode-only → software libx264 — to whatever actually runs on the machine.

• Best: install ffmpeg so hardware encoding kicks in automatically:
  • macOS: brew install ffmpeg
  • Debian/Ubuntu: sudo apt install ffmpeg
  • (or point at a specific build with FFMPEG_PATH=/path/to/ffmpeg)
• Fallback: if no system ffmpeg is found, the bundled ffmpeg-static binary is used (software libx264 — works everywhere, just slower). You'll see a one-time warning nudging you to install ffmpeg.

On startup the worker logs exactly which binary and encoder it picked, e.g. ✓ hardware encoder: Apple VideoToolbox (h264_videotoolbox). If a GPU path is present but fails on a given file, it logs the fallback and keeps going — down to software libx264 if needed.

Leave it running. Upload videos in the app and this box starts chewing through the queue. Ctrl-C to stop.

How it works

1. ZK login as you → obtains the group key for your per-user library Space via the always-online keeper (no other device need be online).
2. Claims queued jobs from the shared jobs table (best-effort claim + heartbeat lease, identical to the browser worker).
3. Fetches the raw upload by manifest (client.storage.readByManifest — over origin; the browser peers it over WebRTC on a LAN).
4. Transcodes with native ffmpeg to HLS (720p, 6s segments, MSE-safe: yuv420p / main / stereo / keyframe-per-segment) — byte-compatible with what the browser writes.
5. Stores each segment as an encrypted shard and writes the media row + marks the job done, then nudges the @scanner agent to fetch poster/metadata.

Offline + P2P are auto-disabled in Node (no IndexedDB / WebRTC), so its shard and DB writes are identical to the browser's.

Options

| flag | env | default | |---|---|---| | --username | MUHKOO_USERNAME | — (required) | | --password | MUHKOO_PASSWORD | prompt | | --base | MUHKOO_BASE_URL | https://api.muhkoo.dev | | --app-key | MUHKOO_THEATER_KEY | public prod key | | — | FFMPEG_PATH | system ffmpeg → bundled static | | — | VAAPI_DEVICE | /dev/dri/renderD128 |