MoQT explained

SUBSCRIBE_NAMESPACE & track namespace prefix matching

SUBSCRIBE_NAMESPACE is how a MoQT client discovers what a relay offers. It carries a Track Namespace prefix — an ordered tuple such as ["sports"] — and the relay replies with REQUEST_OK, then announces every namespace that begins with that prefix using NAMESPACE messages (ending with NAMESPACE_DONE).

It is not SUBSCRIBE: it finds tracks rather than receiving them. And the announcements are NAMESPACE messages, not PUBLISH_NAMESPACE — that is a different message, sent by a publisher to advertise a namespace (see below). Matching is on whole tuple components, not characters — which is exactly why a namespace is a tuple and not a flat string.

Applies to draft-ietf-moq-transport drafts 07–19 (draft-07 uses SUBSCRIBE_ANNOUNCES).

How prefix matching works

A Track Namespace is an ordered tuple of byte-string components. A prefix matches a namespace when the namespace’s leading components equal the prefix, component-for-component:

SUBSCRIBE_NAMESPACE prefix Namespace Match?
["sports"] ["sports","live","game42"] ✓
["sports"] ["sports","vod","game17"] ✓
["sports","live"] ["sports","vod","game17"] ✗
["sports"] ["news","live"] ✗
[] (empty) any namespace ✓

Matching is component-wise: prefix ["sports"] does not match a namespace ["sportsball"] — the first component must be equal, not merely a string prefix.

The discovery flow

TX  SUBSCRIBE_NAMESPACE   prefix = ["sports"]
RX  REQUEST_OK            (subscription accepted)

RX  NAMESPACE             ["live","game42"]   ← suffix; prefix ["sports"] stripped
RX  NAMESPACE             ["vod","game17"]
RX  NAMESPACE_DONE        (initial matching set delivered)
    …further NAMESPACE messages continue as new namespaces appear…

The announcements arrive as NAMESPACE messages on the SUBSCRIBE_NAMESPACE response stream, closed off by NAMESPACE_DONE once the initial matching set has been delivered. Each NAMESPACE carries only the suffix — the tuple components after your prefix — since the prefix is already known from the request.

Don't confuse this with PUBLISH_NAMESPACE: that is a distinct message a publisher sends on its own stream to advertise that it has tracks in a namespace. A relay turns an authorized upstream PUBLISH_NAMESPACE into downstream NAMESPACE messages for each subscriber whose prefix matches. (This is the draft-17+ model; draft-16 and earlier could also forward PUBLISH_NAMESPACE downstream directly.)

Each announced namespace can then be explored for its individual tracks. Once you know a namespace and a track name, you issue a SUBSCRIBE to actually receive its objects.

SUBSCRIBE_NAMESPACE vs SUBSCRIBE_TRACKS (draft-18+)

draft-ietf-moq-transport-18 split namespace subscription into two messages:

SUBSCRIBE_NAMESPACE

"Which namespaces exist under this prefix?" You receive NAMESPACE / NAMESPACE_DONE announcements. Pure discovery — no track data.

SUBSCRIBE_TRACKS

"For namespaces under this prefix, forward the tracks’ PUBLISH messages." In draft-19 a publisher may answer with PUBLISH_SKIPPED to say a track will not be published.

Across draft versions

draft-07

Uses SUBSCRIBE_ANNOUNCES — same concept, different message name.

draft-14

SUBSCRIBE_NAMESPACE / PUBLISH_NAMESPACE, with separate SUBSCRIBE_NAMESPACE_OK (0x12), SUBSCRIBE_NAMESPACE_ERROR (0x13), and UNSUBSCRIBE_NAMESPACE (0x14) messages.

draft-17

Consolidates the OK/ERROR responses into the REQUEST_OK / REQUEST_ERROR pattern and adds NAMESPACE (0x08) and NAMESPACE_DONE (0x0E) for richer discovery.

draft-18

Splits the old single message into two: SUBSCRIBE_NAMESPACE (receive NAMESPACE / NAMESPACE_DONE announcements of matching namespaces) and SUBSCRIBE_TRACKS (actually receive the PUBLISH messages for tracks in matching namespaces).

draft-19

Renames PUBLISH_BLOCKED → PUBLISH_SKIPPED (a publisher signalling a SUBSCRIBE_TRACKS subscriber that it will not publish a given track), and adds TRACK_PROPERTY_FILTER to filter which PUBLISH messages a SUBSCRIBE_TRACKS forwards.

Frequently asked questions

What is SUBSCRIBE_NAMESPACE in MoQT?
SUBSCRIBE_NAMESPACE is the MoQT control message a subscriber sends to discover what is available on a relay. It carries a Track Namespace prefix (a tuple); the relay replies with REQUEST_OK and then announces every namespace that begins with that prefix using NAMESPACE messages, ending with NAMESPACE_DONE once the initial matching set has been delivered. Do not confuse NAMESPACE with PUBLISH_NAMESPACE: the latter is the separate message a publisher sends to advertise that it has tracks in a namespace. SUBSCRIBE_NAMESPACE is discovery — it tells you which namespaces exist, without subscribing to any track yet.
How does track namespace prefix matching work?
A Track Namespace is an ordered tuple of components, e.g. ["sports","live","game42"]. SUBSCRIBE_NAMESPACE takes a prefix tuple and matches any namespace whose leading components equal that prefix. So prefix ["sports"] matches ["sports","live","game42"] and ["sports","vod","game17"], but not ["news","live"]. An empty prefix [] matches every namespace. Matching is on whole tuple components, not on characters within a component.
What is the difference between SUBSCRIBE_NAMESPACE and SUBSCRIBE?
SUBSCRIBE_NAMESPACE operates on a namespace prefix and is about discovery — learning which namespaces (and, with SUBSCRIBE_TRACKS, which tracks) exist. SUBSCRIBE operates on one specific track (a Track Namespace plus a Track Name) and requests that track’s objects. In short: SUBSCRIBE_NAMESPACE finds tracks; SUBSCRIBE receives them.
What is SUBSCRIBE_TRACKS and how does it relate to SUBSCRIBE_NAMESPACE?
draft-18 split the single namespace-subscription message into two. SUBSCRIBE_NAMESPACE receives NAMESPACE / NAMESPACE_DONE announcements about which namespaces match a prefix. SUBSCRIBE_TRACKS goes one step further: for namespaces matching the prefix, the relay forwards the PUBLISH messages for their tracks — so the subscriber learns about individual tracks as they are published. In draft-19, a publisher can answer SUBSCRIBE_TRACKS with PUBLISH_SKIPPED to say a particular track will not be published.
How do I stop a namespace subscription?
In draft-14 you send UNSUBSCRIBE_NAMESPACE. From draft-17 onward the consolidated request pattern handles teardown by resetting the request stream rather than sending a distinct unsubscribe message. moqtap’s peek and desktop tools handle the draft-appropriate mechanism automatically.

Related

Discover namespaces on any relay

moqtap peek auto-detects the draft and runs the right discovery mechanism, listing every namespace and track a relay publishes.

Download moqtap Namespace discovery guide