Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
24 commits
Select commit Hold shift + click to select a range
a5fb61c
build(mux): build against mp4-atom's Common Encryption boxes
michaelstuurman Nov 4, 2026
a73e823
feat(hang): a root drm section for protected CMAF renditions
michaelstuurman Nov 4, 2026
ce4cc86
feat(msf): read and write CMSF content protection
michaelstuurman Nov 4, 2026
4ff8916
feat(mux): import Common Encryption fMP4 in passthrough
michaelstuurman Nov 4, 2026
6250f7b
feat(cli): license and certificate servers for import fmp4
michaelstuurman Nov 4, 2026
7046865
feat(msf): CMSF content protection in JavaScript
michaelstuurman Nov 4, 2026
d09f284
feat(watch): hide protected renditions as unplayable
michaelstuurman Nov 4, 2026
0f17c1f
docs(hang): the drm catalog section and protected CMAF import
michaelstuurman Nov 4, 2026
56914d0
fix(mux): refuse an encrypted fragment without senc
michaelstuurman Nov 4, 2026
18fb32b
fix(mux): share a drm entry only when it is identical, and release it…
michaelstuurman Nov 4, 2026
04c44da
fix: treat a protected rendition as undecodable in every Rust consumer
michaelstuurman Nov 4, 2026
bbcc107
style(mux): rustfmt the protected rendition changes
michaelstuurman Nov 4, 2026
ed39b95
fix(msf): drop only a bad content protection, and match its split IDs…
michaelstuurman Nov 4, 2026
bbec20e
fix(cli): refuse a repeated --drm-license or --drm-certificate system…
michaelstuurman Nov 4, 2026
109905b
docs(hang): protected renditions in the Rust tools, and soften the CM…
michaelstuurman Nov 4, 2026
889404a
fix(mux): add a rendition's drm entries in the same catalog edit
michaelstuurman Nov 4, 2026
b32d344
fix(mux): drop the unreachable ProtectionLacksSample
michaelstuurman Nov 4, 2026
7bd8510
fix(mux): never read an encrypted CMAF init as clear
michaelstuurman Nov 4, 2026
f4414cb
fix(mux): drop protected renditions before selecting, and fail when n…
michaelstuurman Nov 4, 2026
ff665d9
fix(c,ffi): hide protected renditions from the bindings
michaelstuurman Nov 4, 2026
279ef2d
fix(cli): take urn:uuid DRM system IDs in --drm-license and --drm-cer…
michaelstuurman Nov 4, 2026
6683c49
build: take mp4-atom#268 from its pushed commit instead of a local path
michaelstuurman Nov 4, 2026
41720c7
Merge origin/main into feat/drm-import
michaelstuurman Nov 5, 2026
de60830
build: take mp4-atom#268 on 0.17.1 and restore the 0.17.1 requirement
michaelstuurman Nov 5, 2026
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 Cargo.lock

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

2 changes: 2 additions & 0 deletions Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,8 @@ zeroize = { version = "1", features = ["derive"] }
# the member, and the next publish that reaches both fails to resolve a single
# version (#3551).
kio = { path = "rs/kio" }
# Common Encryption boxes (kixelated/mp4-atom#268), until a release ships them.
mp4-atom = { git = "https://github.com/michaelstuurman/mp4-atom", rev = "10490e39383294ea11e3d5827517ef1eb9d950a8" }

[profile.dev]
# Full DWARF is what makes a debug build enormous: the debug `libmoq_ffi.a`
Expand Down
18 changes: 18 additions & 0 deletions doc/bin/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,24 @@ MP4 parser. `import fmp4 --cmaf` publishes each fragment whole as
[`cmaf`](/concept/hang#container) instead, keeping the source's exact sample
timing.

`import fmp4 --cmaf` also publishes Common Encryption (`cenc` and `cbcs`) media,
such as Shaka Packager's output, unchanged, and signals it in the catalog's
[`drm`](/concept/hang#content-protection) section. Name each DRM system's
license server with `--drm-license SYSTEM=URL`, and FairPlay's certificate with
`--drm-certificate SYSTEM=URL`, once per system; SYSTEM is `widevine`,
`playready`, `fairplay`, `clearkey`, or a system ID, and one the media carries
no `pssh` for is refused. A system ID may also be written as a
`urn:uuid:` URN. `SYSTEM:TYPE=URL` also gives the server's type, such as
`widevine:EME-1.0=…` or `fairplay:application/pkcs7-mime=…`. Encrypted media
without `--cmaf`, key rotation, and a clear lead are refused too. An export
leaves the protected renditions out, since nothing in `moq` decrypts them, and
fails when every rendition is protected.

```bash
moq --connect https://relay.example.com/anon --broadcast movie.hang \
import fmp4 --cmaf --drm-license clearkey=https://license.example.com/clearkey < cbcs.mp4
```

`import rtsp` pulls an IP camera's H.264 or H.265 video and AAC audio without
re-encoding. RTP rides the RTSP connection, so run it on the camera's network
and the camera needs no inbound port. Credentials go in the URL
Expand Down
36 changes: 36 additions & 0 deletions doc/concept/hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -64,6 +64,7 @@ A few things the catalog can express beyond decoder config:
- **Labels.** Any rendition may carry a human-readable `label` for a track picker. The map key stays the rendition's ID, so labels need not be unique and renaming one doesn't rename the track.
- **Renditions in another broadcast.** A rendition may point at a relative broadcast path, so a transcoder can publish a ladder that adds low rungs and references the source's original rendition without re-publishing its bytes. The path resolves against where the consumer found the catalog, so a reference that escapes above the root names nothing and the catalog is rejected. `@moq/watch` and `moqsrc` follow a referenced path's announcements like their own, restarting the rendition on each instance that serves it; every other reader, such as `moq play`, the exporters, and the bindings, waits for the first one announced and keeps it, and an exporter ends the rendition with it. An optional `instance` beside the path names the [stream](/concept/moq-lite#publisher-instances) it expects: a route of another instance ends the rendition instead of falling back to it, while a route whose instance a session minted (one that crossed an older version) cannot prove one, so there it is best effort. Omit `instance` for a broadcast produced on demand, which has none until a worker answers; see [identity and recovery](/concept/identity).
- **Whole contributions.** A root `contributions` map names whole broadcasts, such as each guest feed in a composed room, by the same relative path and optional `instance` as a rendition's reference. Listing one opens nothing, so a contribution produced on demand starts only once a viewer selects it, which `@moq/watch` does with `broadcast.contribution(effect, id)`. Its rendition IDs stay its own.
- **DRM.** A root `drm` map describes the DRM systems protecting Common Encryption (`cenc` or `cbcs`) CMAF renditions, one entry per system, scheme, and key: its `system` and `kid` UUIDs, the `pssh` box, and the `license` and `certificate` servers. A protected rendition lists its entries' IDs in its own `drm` field, keeps the encrypted sample entry in its `init`, and names the codec that entry wraps; a rendition listing an ID the root lacks refuses the catalog. Renditions under one key, with the same servers, share an entry. The MSF catalog carries the same entries as CMSF `contentProtections`. See [Content protection](#content-protection).
- **Track names.** The map key is a rendition's ID and, by default, its track name. A rendition sets `track` only when the two must differ, such as two renditions of same-named tracks in different broadcasts, or a rendition whose media changed and so needs a new name; readers subscribe to `track` when present. An ID can't name both a video and an audio rendition.
- **Jitter.** A rendition can say how much media it writes behind a frame's timestamp, in whole milliseconds rounded up: the reorder delay of B-frames and the span of a fragment or batch written together. It is measured from media timestamps alone, never the time a frame was written, so neither a constant encoder delay nor a capture clock counts. It describes the publisher, never the network, only grows over the life of a stream, and a player sizes its buffer to at least this much. A `0` is read as absent.
- **Delay.** A rendition can also say how far its frames' timestamps trail those another rendition already wrote, so a video encoder running 200 ms behind audio advertises `delay: 200` on video. A rendition alone measures none. It follows the same rules as jitter. A player holds the largest `delay + jitter` among the renditions it subscribes to, and never subtracts one rendition's `delay` from another's.
Expand Down Expand Up @@ -240,6 +241,41 @@ derived from the credential and a semantic name such as `foo.hang`; it carries
no format marker. `moq-crypto` is the Rust implementation. Relays need no
configuration to carry it.

## Content protection

DRM is separate from moq-e2ee: the media itself is Common Encryption CMAF,
encrypted before it reaches MoQ by a packager such as Shaka Packager, and a
relay carries it like any other CMAF. `moq import fmp4 --cmaf` publishes such a
file unchanged and fills the catalog's `drm` section from each track's `schm`,
`tenc`, and `pssh` boxes. The license and certificate servers are not in the
media, so the publisher supplies them per DRM system, with `--drm-license` and
`--drm-certificate` or `fmp4::Import::with_drm`.

```json
{
"drm": {
"1": {
"system": "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b",
"scheme": "cbcs",
"kid": "a1b2c3d4-e5f6-0718-293a-4b5c6d7e8f90",
"pssh": "AAAANHBzc2gB...",
"license": { "url": "https://license.example.com/clearkey" }
}
},
"video": { "renditions": { "video": { "codec": "avc1.64000c", "drm": ["1"], "container": { "kind": "cmaf", "init": "..." } } } }
}
```

WebCodecs cannot decrypt, so `@moq/watch` treats a protected rendition as
unplayable and never selects it. Playback through MSE and EME is not built yet.
Nothing in the Rust tools decrypts either: `moq play`, `moq export`, the HLS
gateway, recordings, transcoding, and the C and UniFFI bindings leave a
protected rendition out, as they would a codec they cannot decode, and `moq
export` fails when nothing else is left. They also count a CMAF rendition whose
`init` holds an encrypted sample entry as protected when it lists no `drm`.
Key rotation and a clear lead are refused on import, as is anything else the
republished media could not decrypt.

## Your own format

hang is a convention, not a requirement. If you control both ends, publish
Expand Down
42 changes: 40 additions & 2 deletions drafts/draft-lcurley-moq-hang.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,14 @@ author:

normative:
moqmsf: I-D.ietf-moq-msf
moqcmsf: I-D.ietf-moq-cmsf
cenc:
title: "Information technology - MPEG systems technologies - Part 7: Common encryption in ISO base media file format files"
author:
- org: ISO/IEC
seriesinfo:
ISO/IEC: 23001-7
date: false
moql: I-D.lcurley-moq-lite
moqflate:
title: "DEFLATE Compressed Tracks for MoQ"
Expand Down Expand Up @@ -160,6 +168,7 @@ type Catalog = {
"broadcast": string,
"instance": string | undefined,
}> | undefined,
"drm": Record<string, DrmSchema> | undefined,
// ... any custom fields ...
}
~~~
Expand All @@ -172,7 +181,7 @@ For example, a chat entry should name a chat track, not carry individual chat me
This way catalog updates are rare and a client MAY choose to not subscribe.
The `json` and `binary` sections ({{data}}) are how a track like that is listed.

This specification defines audio, video, and text media tracks, an optional `media` section ({{media}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), and whole broadcasts listed as `contributions` ({{contributions}}).
This specification defines audio, video, and text media tracks, an optional `media` section ({{media}}) holding the clock that maps content time to wall time and the interval a viewer can join on, the root `version` ({{catalog-version}}), the application data tracks in {{data}}, optional publisher statistics and solicited viewer feedback ({{media-stats}}), whole broadcasts listed as `contributions` ({{contributions}}), and the DRM systems protecting encrypted renditions ({{drm}}).

## Version {#catalog-version}
The root `version` field is the oldest draft of this specification that reads the catalog correctly, by draft number: `4` needs a consumer of moq-hang-04 or later.
Expand All @@ -188,7 +197,7 @@ This draft needs `version` 4 for:
- a `track` ({{field-track}}) other than the entry's ID, which an older consumer subscribes to instead;
- a video `warmup` ({{field-warmup}}) above zero, since an older consumer starts decoding a group at a picture that is not a keyframe.

Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `contributions` ({{contributions}}) only offer broadcasts to open on selection; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints.
Every other catalog change in this draft is safe to ignore: `enabled` ({{field-enabled}}) leaves an older consumer selecting a disabled rendition, which plays nothing; `media` ({{media}}) only offers the clock and join interval, which an older consumer goes without; `stats` and `echo` ({{media-stats}}) only offer optional tracks; `contributions` ({{contributions}}) only offer broadcasts to open on selection; `drm` ({{drm}}) leaves an older consumer reading a rendition its init segment already marks as encrypted; video `reorder` leaves an older consumer inferring decode times from timestamps; `jitter`, `delay`, audio `warmup`, and the data track estimates are hints.

## Media {#media}
The catalog's root `media` field holds what applies to every audio and video track:
Expand Down Expand Up @@ -255,6 +264,34 @@ A contribution's rendition IDs belong to its own catalog and MUST NOT replace ID
An unavailable contribution does not invalidate the listing catalog.
A consumer does not expand a contribution's own `contributions`: each needs a selection of its own.

## DRM {#drm}
The optional root `drm` map describes the DRM systems protecting encrypted renditions.
Each key is an entry ID, and each entry is one DRM system for one Common Encryption scheme and one key:

~~~
type DrmSchema = {
"system": string,
"scheme": "cenc" | "cbcs",
"kid": string,
"pssh": string | undefined,
"license": { "url": string, "type": string | undefined } | undefined,
"certificate": { "url": string, "type": string | undefined } | undefined,
}
~~~

The `system` field is the DRM system ID and `kid` the default key ID, each a hyphenated UUID string, and `scheme` is the Common Encryption scheme {{cenc}}.
The `pssh` field is the system's whole `pssh` box, base64-encoded ({{!RFC4648, Section 4}}).
The `license` field names the server a consumer requests a license from, and `certificate` the server certificate a system such as FairPlay needs first; each `type` is the license protocol or the certificate's MIME type.
Renditions encrypted under the same system, scheme, and key MAY share an entry.

A protected audio or video rendition lists the IDs of the entries that can decrypt it in its `drm` field, an array of strings; absent or empty means the rendition is clear.
Common Encryption is defined for CMAF, so a protected rendition is in practice a `cmaf` one ({{cmaf}}): its `init` keeps the encrypted sample entry with its `sinf`, and the `pssh` boxes, while its `codec` names the codec the encrypted entry wraps.
A consumer MUST reject a catalog with a malformed entry, or with a rendition listing an ID the root `drm` lacks.
A consumer that cannot decrypt a rendition MUST treat it as one it cannot decode.

Each entry maps onto a CMSF `contentProtections` entry {{moqcmsf}}: the ID is its `refID`, `kid` its single `defaultKID`, `system`, `license`, `certificate`, and `pssh` its `drmSystem`'s `systemID`, `laURL`, `certURL`, and `pssh`, and a rendition's `drm` its `contentProtectionRefIDs`.
A CMSF entry naming several `defaultKID`s has no single hang entry, so a consumer converting it splits it into one entry per key.

## Track Identity {#identity}
A track name always means the same content, so a catalog update never redefines an audio or video track.
A track's identity is the fields a consumer cannot change without reinitializing its decoder or demuxer: `codec`, `description`, and `container`, plus `displayAspectWidth`, `displayAspectHeight`, and `interlaced` for video and `sampleRate` and `numberOfChannels` for audio.
Expand Down Expand Up @@ -1127,6 +1164,7 @@ This document has no IANA actions.
- Added the optional video `preference` field: a consumer selects automatically among the highest preference it can decode.
- Added the optional video `reorder` field: the most frames that can precede one in decode order and follow it in presentation, fixed for the track once declared. A consumer that authors decode times derives them from it and the current group alone, refusing deeper reordering; without it, a consumer infers them from timestamps.
- Added an optional `instance` beside every rendition and data track `broadcast` reference ({{field-instance}}). A consumer reads each referenced path from the first broadcast it resolves for a catalog instance; a present `instance` fails a rendition that resolves another stream, and is best effort against an Instance a receiver minted.
- Added the optional root `drm` map ({{drm}}) and the audio and video `drm` field: the DRM systems, scheme, and key protecting a Common Encryption `cmaf` rendition, mapping onto CMSF `contentProtections`. A dangling entry ID refuses the catalog.
- Added the optional root `contributions` map ({{contributions}}): whole broadcasts named by a relative `broadcast` and an optional `instance`, opened only on selection, whose rendition IDs stay their own.
- An HLS master selects the contributions it lists by reading their catalogs, without demanding media, and segments them on the listing catalog's `media`; an on-demand publisher answers its catalog without starting media production.
- Added optional `stats` and `echo` catalog sections, publisher/viewer snapshots keyed by rendition ID, and the `.echo` feedback broadcast convention.
Expand Down
6 changes: 6 additions & 0 deletions js/hang/src/catalog/audio.ts
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ const AudioConfigFields = z.object({
// The container format, used to decode the timestamp and more.
container: ContainerSchema,

// The IDs of the root `drm` entries protecting this rendition, one per DRM system that can
// decrypt it. Absent or empty means clear. Common Encryption is defined for CMAF, so in practice
// it is a CMAF rendition, and `codec` names the codec its encrypted sample entry wraps. A consumer
// that can't decrypt skips it.
drm: z.optional(z.array(z.string())),

// The description is used for some codecs.
// If provided, we can initialize the decoder based on the catalog alone.
// Otherwise, the initialization information is in-band.
Expand Down
70 changes: 70 additions & 0 deletions js/hang/src/catalog/drm.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,70 @@
import * as z from "zod/mini";

/**
* Well-known DRM system IDs, as draft-ietf-moq-cmsf lists them.
*/
export const SYSTEM = {
widevine: "edef8ba9-79d6-4ace-a3c8-27dcd51d21ed",
playready: "9a04f079-9840-4286-ab92-e65be0885f95",
fairplay: "94ce86fb-07ff-4f43-adb8-93d2fa968ca2",
// The W3C Common System ID: for testing, since the key travels in the clear.
clearkey: "1077efec-c0b2-4d02-ace3-3c1e52e2fb4b",
} as const;

/** A license or certificate server. */
export const DrmServerSchema = z.object({
url: z.url(),
// The protocol a license server speaks (e.g. `EME-1.0`), or the MIME type of a certificate.
type: z.optional(z.string()),
});

/** A license or certificate server. */
export type DrmServer = z.infer<typeof DrmServerSchema>;

/**
* One DRM system protecting renditions under one Common Encryption scheme and one default key.
*
* Each protected video or audio rendition lists the IDs of its entries in its own `drm` field;
* each entry maps onto one of draft-ietf-moq-cmsf's `contentProtections`, and a CMSF entry naming
* several default keys splits into one entry per key on parse.
*/
export const DrmSchema = z.object({
// The DRM system ID, as a UUID string (see `SYSTEM`).
system: z.guid(),
// How the samples are encrypted; draft-ietf-moq-cmsf allows only these two.
scheme: z.enum(["cenc", "cbcs"]),
// The default key ID (`tenc`'s `default_KID`), as a UUID string.
kid: z.guid(),
// The system's whole `pssh` box from the init segment, base64.
pssh: z.optional(z.base64()),
// Where to request a license.
license: z.optional(DrmServerSchema),
// Where to fetch the server certificate, which systems such as FairPlay need first.
certificate: z.optional(DrmServerSchema),
});

/** One DRM system protecting renditions. */
export type Drm = z.infer<typeof DrmSchema>;

/** A protected rendition lists a `drm` entry the root `drm` section lacks. */
export class MissingDrm extends Error {
/** The rendition listing the entry. */
readonly rendition: string;
/** The entry ID the root lacks. */
readonly id: string;

constructor(rendition: string, id: string) {
super(`rendition ${rendition} references missing drm entry ${id}`);
this.name = "MissingDrm";
this.rendition = rendition;
this.id = id;
}
}

/**
* Whether a rendition is protected: it lists `drm` entries, so its samples are encrypted and only a
* consumer that can decrypt them may select it.
*/
export function isProtected(config: { drm?: string[] }): boolean {
return (config.drm?.length ?? 0) > 0;
}
5 changes: 3 additions & 2 deletions js/hang/src/catalog/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@
* JSON catalog schema and types describing a broadcast's tracks: audio/video decoder configs for
* WebCodecs, container format, rendition layout, the `media` section (the broadcast's `clock` and
* `join` interval),
* plus the `json` and `binary` data sections, optional `stats` and `echo` discovery, and whole
* `contributions` listed without opening them.
* plus the `json` and `binary` data sections, optional `stats` and `echo` discovery, whole
* `contributions` listed without opening them, and the `drm` systems protecting CMAF renditions.
*
* @module
*/
Expand All @@ -26,6 +26,7 @@ export * from "./binary";
export * from "./clock";
export * from "./container";
export * from "./contribution";
export * from "./drm";
export * from "./echo";
export * from "./format";
export * from "./hex";
Expand Down
Loading