Skip to main content

​
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:

​
Running the Demo

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.

​
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: 
just relay
Starts the relay server on localhost:4443.

​
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

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

Build docs developers (and LLMs) love

Get started for freeTalk to us