Skip to content
Merged
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
4 changes: 2 additions & 2 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ prebuilt CLI artifacts for 32-bit boards are not yet available.
| `import` | `archive <url>` | Replay a recording from an object store. |
| `export` | `fmp4`, `mkv`, `ts`, `flv`, `h264`, `h265` | Write a container to stdout. |
| `export` | `mp4 --output <file>` | Record a regular MP4 that stays playable if the recording is cut short. |
| `export` | `hls --listen`, `hls --output <dir>` | Serve the broadcast as HLS over HTTP, record it to a directory, or both. |
| `export` | `hls --hls-listen`, `hls --output <dir>` | Serve the broadcast as HLS over HTTP, record it to a directory, or both. |
| `export` | `rtmp`, `srt`, `rtc` | Serve plays (`--listen`) or push to a remote (`--connect`). |
| `export` | `archive <url>` | Record every broadcast under the prefix into an object store. |
| `play` | | Decode and play in a native window with sound. |
Expand Down Expand Up @@ -365,7 +365,7 @@ over one connection:
```bash
moq --connect https://relay.example.com/anon \
import --broadcast event.hang srt --listen 0.0.0.0:9000 \
-- export --broadcast event.hang hls --listen 0.0.0.0:8080 \
-- export --broadcast event.hang hls --hls-listen 0.0.0.0:8080 \
-- export --broadcast event.hang archive file:///recordings
```

Expand Down
8 changes: 4 additions & 4 deletions doc/bin/hls.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ a remote HLS master or media playlist into a broadcast.
# Publish, then serve. Players open
# http://localhost:8089/my-stream.hang/master.m3u8 (or manifest.mpd for DASH)
ffmpeg -re -i input.mp4 -c copy -f mp4 -movflags cmaf+separate_moof+delay_moov+skip_trailer -frag_duration 1000 - | moq --connect https://relay.example.com/anon --broadcast my-stream.hang import fmp4
moq --connect https://relay.example.com/anon --broadcast my-stream.hang export hls --listen '[::]:8089'
moq --connect https://relay.example.com/anon --broadcast my-stream.hang export hls --hls-listen '[::]:8089'
Comment thread
kixelated marked this conversation as resolved.
Resolved

# Record into ./recording, ending once the broadcast finishes
moq --connect https://relay.example.com/anon --broadcast my-stream.hang export hls --output ./recording
Expand Down Expand Up @@ -83,7 +83,7 @@ recording needs moq-lite 07 on every network hop for track discovery; see
```bash
moq --connect https://relay.example.com/anon --connect-version moq-lite-07-wip --broadcast event export archive s3://recordings
moq --connect https://relay.example.com/anon --broadcast event-replay.hang import archive s3://recordings/event/@<instance>
moq --connect https://relay.example.com/anon --broadcast event-replay.hang export hls --listen '[::]:8089'
moq --connect https://relay.example.com/anon --broadcast event-replay.hang export hls --hls-listen '[::]:8089'
```

The archived catalog and media replay as recorded, so the export lists the same
Expand All @@ -94,7 +94,7 @@ window as a live broadcast.
`--output <dir>` writes `master.m3u8` and each rendition's
`{video,audio}/{name}/media.m3u8`, init, and `.m4s` segments into an empty or
absent directory as each segment completes. Recording alone binds no HTTP port;
add `--listen` to serve and record from one stage, in which case serving goes on
add `--hls-listen` to serve and record from one stage, in which case serving goes on
after the recording completes.

The recording starts at the oldest segment in the `--window` and gets
Expand All @@ -111,7 +111,7 @@ removed and re-added with another target, which logs a warning. A GOP longer
than the target is still recorded, with a warning, so keep keyframe intervals
within the declared interval.

`--listen-tls-cert`/`--listen-tls-key` or `--listen-tls-generate` serve HTTPS,
`--hls-tls-cert`/`--hls-tls-key` or `--hls-tls-generate` serve HTTPS,
and `--cors-origin` opens it to browsers. HLS TLS reads `MOQ_HLS_TLS_*`;
`MOQ_LISTEN_TLS_*` configures only the MoQ listener. See `moq export hls --help`.

Expand Down
14 changes: 7 additions & 7 deletions doc/bin/relay/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -110,13 +110,13 @@ relay.with_web(web).run().await?;
ICE, DTLS, and RTP arrive on it, and its `send` answers from the same
port. On a wildcard bind with several local addresses, set the reply's
`Transmit.src_ip` to the `Datagram.local` it answers; left `None`, the kernel
picks the source address, which the peer may not accept. It fails unless the
tokio runtime serves QUIC: on a stream-only relay, and with `runtime.io_uring`,
whose workers do not split the port yet.
- To serve RTMP on the web ports, take `relay.rtmp()` and pass each accepted
stream to `moq_rtmp::accept_stream`. The HTTP and HTTPS listeners hand it
plaintext RTMP, and RTMPS (TLS with no ALPN) already decrypted; untaken, the
relay closes them.
picks the source address, which the peer may not accept. It is `None` once
taken, and unless the tokio runtime serves QUIC: on a stream-only relay, and
with `runtime.io_uring`, whose workers do not split the port yet.
- To serve RTMP on the web ports, take `relay.rtmp()` (`None` once taken) and
pass each accepted stream to `moq_rtmp::accept_stream`. The HTTP and HTTPS
listeners hand it plaintext RTMP, and RTMPS (TLS with no ALPN) already
decrypted; untaken, the relay closes them.

See [docs.rs/moq-relay](https://docs.rs/moq-relay) and
[`rs/moq-relay/examples/embed.rs`](https://github.com/moq-dev/moq/blob/main/rs/moq-relay/examples/embed.rs).
Expand Down
1 change: 0 additions & 1 deletion quest/m2/api-shape/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,6 +58,5 @@ Rejected in planning:
- [Transports take shared types](/quest/m2/api-shape/transport.md) - moq-uring takes a congestion factory and rustls configs, and the tokio server request stops exposing its QUIC internals
- [Crates re-export no whole crate](/quest/m2/api-shape/reexports.md) - no moq crate re-exports a whole crate, moq's own included, so a dependency bump is no moq break, and moq-mux's container `Guard` gets a name
- [Media crates' small surface fixes](/quest/m2/api-shape/media.md) - exporters, the container consumer, catalog color range, rate grant, moq-stats, JSON, and MSF each have one path and one name
- [Apps' small surface fixes](/quest/m2/api-shape/apps.md) - the relay, gateways, moq-hls, moq-cli, and moq-boy drop dead or unreachable surface and gain role names
- [JS packages' small surface fixes](/quest/m2/api-shape/js.md) - track info, connection, qmux, watch, publish, ui, video, boy, and auth exports each have one path and one name
- [Bindings' small surface fixes](/quest/m2/api-shape/bindings.md) - Go's read cancel, JSON producer construction, and the Python wheel's test module
41 changes: 0 additions & 41 deletions quest/m2/api-shape/apps.md

This file was deleted.

45 changes: 39 additions & 6 deletions rs/moq-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1079,7 +1079,7 @@ impl Export {
ExportSink::Flv(args) => found.extend(args.deprecated()),
ExportSink::H264(args) | ExportSink::H265(args) => found.extend(args.deprecated()),
ExportSink::Rtmp(rtmp) => found.extend(rtmp.deprecated()),
ExportSink::Hls(hls) => found.extend(hls.tls.deprecated()),
ExportSink::Hls(hls) => found.extend(hls.deprecated()),
_ => {}
}
found
Expand Down Expand Up @@ -1792,7 +1792,7 @@ mod tests {
fn sinks_without_selection_refuse_it() {
let sinks = [
["ts"].as_slice(),
&["hls", "--listen", "127.0.0.1:8080"],
&["hls", "--hls-listen", "127.0.0.1:8080"],
&["rtmp", "--listen", "127.0.0.1:1935"],
&["srt", "--listen", "127.0.0.1:9000"],
&["rtc", "--listen", "127.0.0.1:8443"],
Expand Down Expand Up @@ -1899,7 +1899,11 @@ mod tests {
for sink in ["ts", "fmp4", "mkv", "flv", "h264", "h265"] {
export(&["--echo", "alice", sink]).unwrap().validate().unwrap();
}
for sink in [["hls", "--listen", "127.0.0.1:8080"].as_slice(), &["report"], &["echo"]] {
for sink in [
["hls", "--hls-listen", "127.0.0.1:8080"].as_slice(),
&["report"],
&["echo"],
] {
let err = export(&[["--echo", "alice"].as_slice(), sink].concat())
.unwrap()
.validate()
Expand Down Expand Up @@ -2119,8 +2123,37 @@ mod tests {

let reported = err.to_string();
assert!(reported.contains("--tls-cert"), "{reported}");
assert!(reported.contains("--listen-tls-cert"), "{reported}");
assert!(reported.contains("--listen-tls-root"), "{reported}");
assert!(reported.contains("--hls-tls-cert"), "{reported}");
assert!(reported.contains("--hls-tls-root"), "{reported}");
}

/// The released `export hls --listen*` spellings name their `--hls-*` replacements
/// rather than reach the MoQ listener's flags of the same name.
#[test]
fn released_hls_listener_flags_are_refused() {
for (old, value, new) in [
("--listen", "127.0.0.1:8080", "--hls-listen"),
("--listen-tls-cert", "cert.pem", "--hls-tls-cert"),
("--listen-tls-key", "key.pem", "--hls-tls-key"),
("--listen-tls-generate", "localhost", "--hls-tls-generate"),
("--listen-tls-root", "ca.pem", "--hls-tls-root"),
] {
let Err(err) = Invocation::try_parse_from([
"moq",
"--connect",
"http://relay/anon",
"--broadcast",
"room",
"export",
"hls",
old,
value,
]) else {
panic!("{old} on export hls must not start a run");
};
let reported = err.to_string();
assert!(reported.contains(old) && reported.contains(new), "{reported}");
}
}

/// One released spelling stops the run even when the rest of the command line is
Expand Down Expand Up @@ -2309,7 +2342,7 @@ mod tests {
"--broadcast",
"cam1.hang",
"hls",
"--listen",
"--hls-listen",
"0.0.0.0:8080",
])
.unwrap();
Expand Down
73 changes: 42 additions & 31 deletions rs/moq-cli/src/hls.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ use crate::moq::{ImportTarget, notify_ready};

mod record;

/// Where `export hls` serves when neither `--listen` nor `--output` is given.
/// Where `export hls` serves when neither `--hls-listen` nor `--output` is given.
const LISTEN: SocketAddr = SocketAddr::new(std::net::IpAddr::V6(std::net::Ipv6Addr::UNSPECIFIED), 8089);

/// HLS import (pull a remote playlist) args.
Expand All @@ -37,9 +37,13 @@ pub struct ImportArgs {
pub struct ExportArgs {
/// HTTP listener for the HLS endpoints. Defaults to `[::]:8089` unless `--output` records
/// without serving.
#[usage(long, value_name = "ADDR")]
#[usage(long = "hls-listen", value_name = "ADDR")]
pub listen: Option<SocketAddr>,

/// The released `--listen`, refused by name: the MoQ side's `--listen` is another listener.
#[usage(name = "hls-legacy-listen", long = "listen", hide = true)]
legacy_listen: Option<String>,

/// Record the broadcast's playlists and segments into this directory, which must be empty
/// or absent. Fails if the recording ends abruptly or misses a segment.
#[usage(long, value_name = "DIR", value_hint = usage_rs::ValueHint::DirPath)]
Expand All @@ -61,25 +65,28 @@ pub struct ExportArgs {
}

/// TLS for the HLS HTTP listener, independent of the MoQ listener's environment.
#[derive(usage_rs::Args, Clone)]
#[derive(usage_rs::Args, Clone, Default)]
#[usage(unknown_flags = "error", args_override_self = false)]
pub struct Tls {
/// Load the HLS listener's PEM certificate.
#[usage(long = "listen-tls-cert", env = "MOQ_HLS_TLS_CERT", value_hint = usage_rs::ValueHint::FilePath)]
#[usage(long = "hls-tls-cert", env = "MOQ_HLS_TLS_CERT", value_hint = usage_rs::ValueHint::FilePath)]
pub cert: Vec<PathBuf>,
/// Load the HLS listener's PEM private key.
#[usage(long = "listen-tls-key", env = "MOQ_HLS_TLS_KEY", value_hint = usage_rs::ValueHint::FilePath)]
#[usage(long = "hls-tls-key", env = "MOQ_HLS_TLS_KEY", value_hint = usage_rs::ValueHint::FilePath)]
pub key: Vec<PathBuf>,
/// Generate the HLS listener's self-signed certificate for these hostnames.
#[usage(long = "listen-tls-generate", env = "MOQ_HLS_TLS_GENERATE", delimiter = ',')]
#[usage(long = "hls-tls-generate", env = "MOQ_HLS_TLS_GENERATE", delimiter = ',')]
pub generate: Vec<String>,
/// Trust these PEM roots for optional HLS client certificates.
#[usage(long = "listen-tls-root", env = "MOQ_HLS_TLS_ROOT", delimiter = ',', value_hint = usage_rs::ValueHint::FilePath)]
#[usage(long = "hls-tls-root", env = "MOQ_HLS_TLS_ROOT", delimiter = ',', value_hint = usage_rs::ValueHint::FilePath)]
pub root: Vec<PathBuf>,

// Every released spelling of each listener TLS setting. `MOQ_LISTEN_TLS_*` stay
// out: they configure the MoQ listener now.
#[usage(
name = "hls-legacy-cert",
long = "tls-cert",
alias = "server-tls-cert",
aliases("server-tls-cert", "listen-tls-cert"),
env = "MOQ_SERVER_TLS_CERT",
hide = true
)]
Expand All @@ -88,7 +95,7 @@ pub struct Tls {
#[usage(
name = "hls-legacy-key",
long = "tls-key",
alias = "server-tls-key",
aliases("server-tls-key", "listen-tls-key"),
env = "MOQ_SERVER_TLS_KEY",
hide = true
)]
Expand All @@ -97,7 +104,7 @@ pub struct Tls {
#[usage(
name = "hls-legacy-generate",
long = "tls-generate",
alias = "server-tls-generate",
aliases("server-tls-generate", "listen-tls-generate"),
env = "MOQ_SERVER_TLS_GENERATE",
delimiter = ',',
hide = true
Expand All @@ -107,42 +114,54 @@ pub struct Tls {
#[usage(
name = "hls-legacy-root",
long = "server-tls-root",
alias = "listen-tls-root",
env = "MOQ_SERVER_TLS_ROOT",
delimiter = ',',
hide = true
)]
legacy_root: Vec<PathBuf>,
}

impl Tls {
impl ExportArgs {
/// The released spellings in use, each paired with what replaced it.
pub(super) fn deprecated(&self) -> moq_tokio::cli::Deprecated {
let mut found = self.tls.deprecated();
if self.legacy_listen.is_some() {
found.flag("--listen", None, "--hls-listen");
}
found
}
}

impl Tls {
fn deprecated(&self) -> moq_tokio::cli::Deprecated {
let mut found = moq_tokio::cli::Deprecated::default();
if !self.legacy_cert.is_empty() {
found.flag(
"--tls-cert",
"--listen-tls-cert, --tls-cert, --server-tls-cert",
Some("MOQ_SERVER_TLS_CERT"),
"--listen-tls-cert / MOQ_HLS_TLS_CERT",
"--hls-tls-cert / MOQ_HLS_TLS_CERT",
);
}
if !self.legacy_key.is_empty() {
found.flag(
"--tls-key",
"--listen-tls-key, --tls-key, --server-tls-key",
Some("MOQ_SERVER_TLS_KEY"),
"--listen-tls-key / MOQ_HLS_TLS_KEY",
"--hls-tls-key / MOQ_HLS_TLS_KEY",
);
}
if !self.legacy_generate.is_empty() {
found.flag(
"--tls-generate",
"--listen-tls-generate, --tls-generate, --server-tls-generate",
Some("MOQ_SERVER_TLS_GENERATE"),
"--listen-tls-generate / MOQ_HLS_TLS_GENERATE",
"--hls-tls-generate / MOQ_HLS_TLS_GENERATE",
);
}
if !self.legacy_root.is_empty() {
found.flag(
"--server-tls-root",
"--listen-tls-root, --server-tls-root",
Some("MOQ_SERVER_TLS_ROOT"),
"--listen-tls-root / MOQ_HLS_TLS_ROOT",
"--hls-tls-root / MOQ_HLS_TLS_ROOT",
);
}
found
Expand Down Expand Up @@ -287,11 +306,11 @@ pub async fn export(origin: moq_net::origin::Consumer, args: ExportArgs, name: S
None => {
anyhow::ensure!(
tls.cert.is_empty() && tls.key.is_empty() && tls.generate.is_empty() && tls.root.is_empty(),
"the HLS listener's TLS flags only apply with `export hls --listen`"
"the HLS listener's TLS flags only apply with `export hls --hls-listen`"
);
anyhow::ensure!(
args.cors.origin.is_empty(),
"`--cors-origin` only applies to `export hls --listen`"
"`--cors-origin` only applies to `export hls --hls-listen`"
);
None
}
Expand Down Expand Up @@ -454,16 +473,8 @@ mod test {
let args = ExportArgs {
listen: None,
output: Some(dir.path().join("recording")),
tls: Tls {
cert: Vec::new(),
key: Vec::new(),
generate: Vec::new(),
root: Vec::new(),
legacy_cert: Vec::new(),
legacy_key: Vec::new(),
legacy_generate: Vec::new(),
legacy_root: Vec::new(),
},
legacy_listen: None,
tls: Tls::default(),
window: std::time::Duration::from_secs(16).into(),
cors: Default::default(),
};
Expand Down
Loading
Loading