Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions .cargo/config.toml
Original file line number Diff line number Diff line change
@@ -1,2 +1,5 @@
[build]
rustflags = ["--cfg", "tokio_unstable"]

[alias]
x = "run --package x --"
2 changes: 1 addition & 1 deletion .github/workflows/check.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,4 +28,4 @@ jobs:
cache-on-failure: true

# Run checks with cached dependencies
- run: nix develop --command just check-all
- run: nix develop --command ./x check all
18 changes: 9 additions & 9 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,9 +10,9 @@ MoQ (Media over QUIC) is a next-generation live media delivery protocol providin

```bash
# Code quality and testing
just check # Run all tests and linting
just fix # Auto-fix linting issues
just build # Build all packages
./x check # Run all tests and linting
./x fix # Auto-fix linting issues
./x build # Build all packages
```

## Architecture
Expand Down Expand Up @@ -53,26 +53,26 @@ Key architectural rule: The CDN/relay does not know anything about media. Anythi

## Development Tips

1. The project uses `just` as the task runner - check `justfile` for all available commands
1. The project uses `./x` (or `cargo x`) as the task runner - check `rs/x/src/main.rs` for all available commands
2. For Rust development, the workspace is configured in the `rs/Cargo.toml`
3. For JS/TS development, bun workspaces are used with configuration in `js/package.json`

## Tooling

- **TypeScript**: Always use `bun` for all package management and script execution (not npm, yarn, or pnpm)
- **Common**: Use `just` for common development tasks
- **Common**: Use `./x` (or `cargo x`) for common development tasks
- **Rust**: Use `cargo` for Rust-specific operations

## Testing Approach

- Run `just check` to execute all tests and linting.
- Run `just fix` to automatically fix formating and easy things.
- Run `./x check` to execute all tests and linting.
- Run `./x fix` to automatically fix formating and easy things.
- Rust tests are integrated within source files

## Workflow

When making changes to the codebase:
1. Make your code changes
2. Run `just fix` to auto-format and fix linting issues
3. Run `just check` to verify everything passes
2. Run `./x fix` to auto-format and fix linting issues
3. Run `./x check` to verify everything passes
4. Commit and push changes
7 changes: 7 additions & 0 deletions Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,7 @@ members = [
"rs/moq-relay",
"rs/moq-token",
"rs/moq-token-cli",
"rs/x",
]
resolver = "2"

Expand Down
35 changes: 17 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,20 +38,19 @@ In production, you'll need a proper domain and a matching TLS certificate via [L

```sh
# Runs a relay, demo media, and the web server
nix develop -c just dev
nix develop -c ./x dev
```

Then visit [https://localhost:8080](https://localhost:8080) to see the demo.
Note that this uses an insecure HTTP fetch for local development only; in production you'll need a proper domain + TLS certificate.

*TIP:* If you've installed [nix-direnv](https://github.com/nix-community/nix-direnv), then only `just dev` is required.
*TIP:* If you've installed [nix-direnv](https://github.com/nix-community/nix-direnv), then only `./x dev` is required.


### Full Setup
If you don't like Nix, then you can install dependencies manually:

**Requirements:**
- [Just](https://github.com/casey/just)
- [Rust](https://www.rust-lang.org/tools/install)
- [Bun](https://bun.sh/)
- [FFmpeg](https://ffmpeg.org/download.html)
Expand All @@ -60,10 +59,10 @@ If you don't like Nix, then you can install dependencies manually:
**Run it:**
```sh
# Install some more dependencies
just install
./x install

# Runs a relay, demo media, and the web server
just dev
./x dev
```

Then visit [http://localhost:5173](http://localhost:5173) to see the demo.
Expand Down Expand Up @@ -147,24 +146,24 @@ Read the specifications:
## Development
```sh
# See all available commands
just
./x --help

# Build everything
just build
./x build

# Run tests and linting
just check
./x check

# Automatically fix some linting errors
just fix
./x fix

# Run the demo manually
just relay # Terminal 1: Start relay server
just pub tos # Terminal 2: Publish a demo video using ffmpeg
just web # Terminal 3: Start web server
./x relay # Terminal 1: Start relay server
./x pub fmp4 tos # Terminal 2: Publish a demo video using ffmpeg
./x web # Terminal 3: Start web server
```

There are more commands: check out the [justfile](justfile), [rs/justfile](rs/justfile), and [js/justfile](js/justfile).
The task runner is implemented in [rs/x](rs/x) and can be invoked via `./x` or `cargo x`.

## Iroh support

Expand All @@ -183,7 +182,7 @@ You can run a demo like this:

```sh
# Terminal 1: Start a relay server
just relay --iroh-enabled
./x relay --iroh-enabled
# Copy the endpoint id printed at "iroh listening"

# Terminal 2: Publish via moq-lite over raw iroh QUIC
Expand All @@ -193,18 +192,18 @@ just relay --iroh-enabled
# We set an `anon/` prefix to match the broadcast name the web ui expects
# Because moq-lite does not have headers if using raw QUIC, only the hostname
# in the URL can be used.
just pub-iroh bbb iroh://ENDPOINT_ID anon/
./x pub iroh bbb iroh://ENDPOINT_ID anon/
# Alternatively you can use WebTransport over HTTP/3 over iroh,
# which allows to set a path prefix in the URL:
just pub-iroh bbb h3+iroh://ENDPOINT_ID/anon
./x pub iroh bbb h3+iroh://ENDPOINT_ID/anon

# Terminal 3: Start web server
just web
./x web
```

Then open [localhost:5173](http://localhost:5173) and watch BBB, pushed from terminal 1 via iroh to the relay running in terminal 2, from where the browser fetches it over regular WebTransport.

`just serve` serves a video via iroh alongside regular QUIC (it enables the `iroh` feature). This repo currently does not provide a native viewer, so you can't subscribe to it directly. However, you can use the [watch example from iroh-live](https://github.com/n0-computer/iroh-live/blob/main/iroh-live/examples/watch.rs) to view a video published via `moq-native`.
`./x serve fmp4` serves a video via iroh alongside regular QUIC (it enables the `iroh` feature). This repo currently does not provide a native viewer, so you can't subscribe to it directly. However, you can use the [watch example from iroh-live](https://github.com/n0-computer/iroh-live/blob/main/iroh-live/examples/watch.rs) to view a video published via `moq-native`.

## License

Expand Down
8 changes: 4 additions & 4 deletions doc/app/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,10 +114,10 @@ The repository includes helper commands for test content:

```bash
# Publish Big Buck Bunny
just pub bbb https://relay.example.com/anon
./x pub fmp4 bbb https://relay.example.com/anon

# Publish Tears of Steel
just pub tos https://relay.example.com/anon
./x pub fmp4 tos https://relay.example.com/anon
```

## Clock Synchronization
Expand All @@ -126,10 +126,10 @@ Publish and subscribe to clock broadcasts for testing:

```bash
# Publish a clock
just clock publish https://relay.example.com/anon
./x clock publish https://relay.example.com/anon

# Subscribe to a clock
just clock subscribe https://relay.example.com/anon
./x clock subscribe https://relay.example.com/anon
```

## Debugging
Expand Down
2 changes: 1 addition & 1 deletion doc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ Get up and running in seconds with [Nix](https://nixos.org/download.html), or be

```bash
# Runs a relay, media publisher, and the web server
nix develop -c just dev
nix develop -c ./x dev
```

If everything works, a browser window will pop up demoing how to both publish and watch content via the web.
Expand Down
2 changes: 1 addition & 1 deletion doc/js/@moq/hang-demo.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Follow the [Quick Start](/setup/) guide to get started.

You can target a remote relay instead of a local one with the command:
```bash
just web https://cdn.moq.dev/anon
./x web https://cdn.moq.dev/anon
```

## Watch Demo
Expand Down
46 changes: 23 additions & 23 deletions doc/setup/dev.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,37 +8,37 @@ Still here? You must be a Big Buck Bunny fan.

This guide covers the rest of the stuff you can run locally.

## Just
We use [Just](https://github.com/casey/just) to run helper commands.
It's *just* a fancier `Makefile` so you don't have to remember all the commands.
## Task Runner
We use a Rust-based task runner ([rs/x](https://github.com/moq-dev/moq/blob/main/rs/x)) to run helper commands.
Invoke it via `./x` or `cargo x`.

### Common Commands
```bash
# List all available commands
just
./x --help

# Run the demo
just dev
./x dev

# This is equivalent to 3 terminal tabs:
# just relay
# just web
# just pub bbb
# ./x relay
# ./x web
# ./x pub fmp4 bbb

# Make sure the code compiles and passes linting
just check
./x check

# Auto-fix linting errors
just fix
./x fix

# Run the tests
just test
./x test

# Publish a HLS broadcast (CMAF) over MoQ
just pub-hls tos
./x pub hls tos
```

Want more? See the [justfile](https://github.com/moq-dev/moq/blob/main/justfile) for all commands.
Want more? Run `./x --help` or see [rs/x/src/main.rs](https://github.com/moq-dev/moq/blob/main/rs/x/src/main.rs) for all commands.

### The Internet
Most of the commands default to `http://localhost:4443/anon`.
Expand All @@ -56,19 +56,19 @@ Anything you publish is public and discoverable... so be careful and don't abuse
```bash
# Run the web server, pointing to the public relay
# NOTE: The `bbb` demo on moq.dev uses a different path so it won't show up.
just web https://cdn.moq.dev/anon
./x web https://cdn.moq.dev/anon

# Publish Tears of Steel, watch it via https://moq.dev/watch?name=tos
just pub tos https://cdn.moq.dev/anon
./x pub fmp4 tos https://cdn.moq.dev/anon

# Publish a clock broadcast
just clock publish https://cdn.moq.dev/anon
./x clock publish https://cdn.moq.dev/anon

# Subscribe to said clock broadcast (different tab)
just clock subscribe https://cdn.moq.dev/anon
./x clock subscribe https://cdn.moq.dev/anon

# Publish an authentication broadcast
just pub av1 https://cdn.moq.dev/?jwt=not_a_real_token_ask_for_one
./x pub fmp4 av1 https://cdn.moq.dev/?jwt=not_a_real_token_ask_for_one
```

## Debugging
Expand All @@ -78,14 +78,14 @@ You can set the logging level with the `RUST_LOG` environment variable.

```bash
# Print the most verbose logs
RUST_LOG=trace just dev
RUST_LOG=trace ./x dev
```

If you're getting a panic, use `RUST_BACKTRACE=1` to get a backtrace.

```bash
# Print a backtrace on panic.
RUST_BACKTRACE=1 just dev
RUST_BACKTRACE=1 ./x dev
```


Expand All @@ -103,15 +103,15 @@ Recommended extensions:

## Contributing

Run `just fix` before pushing your changes, otherwise CI will yell at you.
It runs `just check` so that's the easiest way to debug any issues.
Run `./x fix` before pushing your changes, otherwise CI will yell at you.
It runs `./x check` so that's the easiest way to debug any issues.

Please don't submit a vibe coded PR unless you understand it.
`You're absolutely right!` is not always good enough.


## Onwards
`just dev` runs three processes that normally, should run on separate hosts.
`./x dev` runs three processes that normally, should run on separate hosts.
Learn how to run them [in production](/setup/prod).

Or take a detour and:
Expand Down
13 changes: 6 additions & 7 deletions doc/setup/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,21 +29,20 @@ Install the following:
Then run the demo:
```bash
# Runs the demo using pinned dependencies
nix develop -c just dev
nix develop -c ./x dev
```

If you install `direnv`, then the Nix shell will be loaded whenever you `cd` into the repo:
```bash
# Run the demo... in 9 keystrokes
just dev
# Run the demo... in 7 keystrokes
./x dev
```


## Option 2: Manual Installation

If you don't like Nix or enjoy suffering with Windows, then you can manually install the dependencies:

- [Just](https://github.com/casey/just)
- [Rust](https://www.rust-lang.org/tools/install)
- [Bun](https://bun.sh/)
- [FFmpeg](https://ffmpeg.org/download.html)
Expand All @@ -52,16 +51,16 @@ If you don't like Nix or enjoy suffering with Windows, then you can manually ins
Then run:
```bash
# Install additional dependencies, usually linters
just install
./x install

# Run the demo
just dev
./x dev
```

When in doubt, check the [Nix Flake](https://github.com/moq-dev/moq/blob/main/flake.nix) for the full list of dependencies.

## What's Happening?
The `just dev` command starts three components:
The `./x dev` command starts three components:

- [moq-relay](/app/relay/): A server that routes live data between publishers and subscribers.
- [moq-cli](/app/cli): A CLI that publishes video content piped from `ffmpeg`.
Expand Down
1 change: 0 additions & 1 deletion flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -49,7 +49,6 @@
# Rust dependencies
rustDeps = with pkgs; [
rust-toolchain
just
pkg-config
glib
libressl
Expand Down
Loading
Loading