MOQZR

A desktop media player for the MOQ (Media over QUIC) protocol, targeting draft-16 of the IETF MOQ Transport specification.

Architecture

MOQZR is a two-layer application:

• Native layer (Zig) -- Handles QUIC transport and MOQ protocol logic. Built as a shared library (.dll / .dylib / .so) and accessed from the app via FFI.
• App layer (TypeScript) -- Electrobun desktop app with Bun runtime. Manages the UI, WebCodecs decoding, and audio/video rendering.

Data flow

1. Renderer sends IPC messages (connect, subscribe) to the main process
2. Main process calls native FFI functions
3. Native Zig library manages QUIC connection and MOQ sessions
4. Main process polls frames from native layer at 60fps and forwards them to the renderer
5. Renderer decodes frames with WebCodecs and renders video to canvas / audio via Web Audio API

Prerequisites

• Bun >= 1.0.0
• Zig 0.16.0-dev (development version required)
• Electrobun (installed via npm)

Installing Zig 0.16.0-dev

The native library requires Zig 0.16.0-dev (not the stable release). Download the latest development build from the Zig downloads page:

macOS (Apple Silicon):

curl -L -o /tmp/zig.tar.xz "https://ziglang.org/builds/zig-aarch64-macos-0.16.0-dev.2694+74f361a5c.tar.xz"
tar -xf /tmp/zig.tar.xz -C /tmp
mkdir -p ~/bin && mv /tmp/zig-aarch64-macos-* ~/bin/zig-dev
export PATH="$HOME/bin/zig-dev:$PATH"

macOS (Intel):

curl -L -o /tmp/zig.tar.xz "https://ziglang.org/builds/zig-x86_64-macos-0.16.0-dev.2694+74f361a5c.tar.xz"
tar -xf /tmp/zig.tar.xz -C /tmp
mkdir -p ~/bin && mv /tmp/zig-x86_64-macos-* ~/bin/zig-dev
export PATH="$HOME/bin/zig-dev:$PATH"

Linux (x86_64):

curl -L -o /tmp/zig.tar.xz "https://ziglang.org/builds/zig-x86_64-linux-0.16.0-dev.2694+74f361a5c.tar.xz"
tar -xf /tmp/zig.tar.xz -C /tmp
mkdir -p ~/bin && mv /tmp/zig-x86_64-linux-* ~/bin/zig-dev
export PATH="$HOME/bin/zig-dev:$PATH"

Windows: Download from https://ziglang.org/builds/zig-x86_64-windows-0.16.0-dev.2694+74f361a5c.zip and extract to a folder in your PATH.

Note: The build script automatically uses ~/bin/zig-dev/zig if present, falling back to system zig.

Verify installation:

zig version  # Should show 0.16.0-dev.xxxx

Getting Started

Install dependencies:

bun install

Run in development mode:

bun run dev

Build for production:

bun run build

Build output is placed in build/<target>/ (e.g., build/dev-macos-arm64/MOQZR Player-dev.app).

Platform-specific builds

bun run build:windows
bun run build:macos
bun run build:linux

Native library only

cd native
~/bin/zig-dev/zig build                    # build library
~/bin/zig-dev/zig build test               # run tests
~/bin/zig-dev/zig build run -- [args]      # CLI tool

Or if zig-dev is in your PATH:

cd native && zig build

Project Structure

src/
  main/           Main process (Bun runtime)
    native/       FFI bindings to Zig library
    ipc.ts        IPC handler registry
    index.ts      App entry point
  renderer/       Renderer process (browser)
    player.ts     Player orchestration
    decoder.ts    WebCodecs video/audio decoders
    renderer.ts   Canvas and Web Audio rendering
    controls.ts   UI controls and keyboard shortcuts
  shared/
    types.ts      Shared type definitions

native/
  src/
    root.zig      FFI exports (C-compatible API)
    cli.zig       Standalone CLI for testing
    moq/          MOQ protocol implementation
    transport/    QUIC transport client
    loc/          LOC demuxer for media frames

License

See LICENSE for details.