Quick Start

Get up and running with Moq in minutes using the demo application

Quick Start

This guide will help you get a Moq relay server running with a demo video stream in just a few minutes.

The demo uses an insecure self-signed certificate intended for local development only. For production, you’ll need a proper domain and TLS certificate via LetsEncrypt or similar.

Prerequisites

Choose one of the following setup options:

Nix (Recommended)

Requirements:

• Nix
• Nix Flakes enabled

Nix provides a fully reproducible development environment with all dependencies included.

Manual Setup

Requirements:

• Just - Command runner
• Rust - Latest stable version
• Bun - JavaScript runtime and package manager
• FFmpeg - Media processing

You may need additional system dependencies depending on your platform.

Running the Demo

Nix

1. Clone the repository

   git clone https://github.com/moq-dev/moq.git
   cd moq
   
2. Start the development environment

   nix develop -c just dev
   

   This single command will:

   • Start a relay server on localhost:4443
   • Publish the Big Buck Bunny demo video
   • Launch a web server with the demo UI

   If you have nix-direnv installed, you can simply run:

   just dev
   
3. Open the demo

   Visit https://localhost:8080 in your browser to see the demo.

   You’ll see the Big Buck Bunny video playing with real-time statistics.

Manual

1. Clone the repository

   git clone https://github.com/moq-dev/moq.git
   cd moq
   
2. Install dependencies

   just install
   

   This installs additional Rust tools and JavaScript dependencies.

3. Run the demo

   just dev
   

   This will:

   • Start a relay server on localhost:4443
   • Publish the Big Buck Bunny demo video
   • Launch a web server on localhost:5173
4. Open the demo

   Visit http://localhost:5173 in your browser.

   You’ll see the Big Buck Bunny video playing with real-time statistics.

What’s Happening?

The just dev command runs three services in parallel:

1. moq-relay: A relay server that receives and forwards media streams
2. Publisher: FFmpeg publishes the Big Buck Bunny video to the relay
3. Web Server: Serves the demo UI that subscribes to and plays the stream

Understanding the Demo

The demo application demonstrates:

• Real-time streaming: Sub-second latency from publisher to viewer
• Adaptive streaming: Multiple quality levels (if available)
• Statistics overlay: View bandwidth, latency, and frame metrics
• Chat: See how non-media data can be transmitted alongside video

Running Components Individually

For development or debugging, you can run each component separately:

Terminal 1: Relay

just relay

Starts the relay server on localhost:4443.

Terminal 2: Publisher

just pub bbb http://localhost:4443/anon

Publishes the “bbb” (Big Buck Bunny) video to the /anon broadcast path.

Terminal 3: Web Server

just web http://localhost:4443/anon

Starts the development web server configured to connect to the relay.

Available Test Videos

The demo includes several test videos:

• bbb - Big Buck Bunny (default)
• tos - Tears of Steel
• av1 - AV1 encoded test video
• hevc - HEVC encoded test video

To use a different video:

just pub tos http://localhost:4443/anon

Troubleshooting

Port already in use

If port 4443 is already in use, you can modify the port in dev/relay.toml or kill the process using that port:

lsof -ti:4443 | xargs kill -9

Certificate errors in browser

The demo uses a self-signed certificate. Your browser will warn you about this. You can:

• Click “Advanced” and “Proceed” (Chrome/Edge)
• Click “Advanced” and “Accept the Risk” (Firefox)
• Or visit http://localhost:4443/certificate.sha256 to see the certificate fingerprint

Video not loading

Make sure all three services are running:

1. Check that the relay is running: curl http://localhost:4443/
2. Verify the publisher is connected by checking relay logs
3. Check browser console for WebTransport connection errors

IPv6 issues

If you have IPv6 connectivity issues, try changing the listen address in dev/relay.toml from [::] to 127.0.0.1.

Next Steps

Installation

Install Moq libraries for your project

Architecture

Learn how Moq is architecturally designed

Publishing

Publish your own media streams

Watching

Subscribe to and watch Moq streams