Sign in

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, and sends NAMESPACE_DONE when one of them goes away.

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.

The flow on this page is drafts 16–23 of draft-ietf-moq-transport. Drafts 07–15 use other message names; see the messages in each draft.

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 empty prefix matches every namespace in drafts 16–23; drafts 08–15 close the session if the prefix is empty.

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"]
    …later, as namespaces come and go…
RX  NAMESPACE             ["live","game43"]   ← a new matching namespace
RX  NAMESPACE_DONE        ["vod","game17"]    ← this one is withdrawn

The announcements arrive as NAMESPACE messages on the SUBSCRIBE_NAMESPACE request’s own stream: one for each matching namespace the publisher knows, then more as the set changes. NAMESPACE_DONE withdraws a namespace that was announced earlier; it never arrives before that namespace’s NAMESPACE. Both carry only the suffix — the tuple components after your prefix — since the prefix is already known from the request. The subscription stays open until you close its stream.

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.

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 (drafts 18–23)

In drafts 18–23 namespace subscription has two messages:

SUBSCRIBE_NAMESPACE

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

SUBSCRIBE_TRACKS

"Subscribe me to the tracks in namespaces under this prefix." The publisher sends a PUBLISH for each matching track, or PUBLISH_SKIPPED (drafts 19–23) for a track it will not publish to you.

In drafts 16–17 one SUBSCRIBE_NAMESPACE does both jobs, and its Subscribe Options field asks for NAMESPACE messages, PUBLISH messages, or both.

Overlapping prefixes

In draft-23 a subscriber may hold several namespace subscriptions whose prefixes overlap, say ["sports"] and ["sports","live"]. If a track matches more than one SUBSCRIBE_TRACKS, the publisher sends a PUBLISH for each, and each one carries a SUBSCRIBE_TRACKS_ID parameter naming the request it answers.

In drafts 07–22 the publisher rejects a namespace subscription whose prefix overlaps an active one in the same session (with PREFIX_OVERLAP in drafts 15–22). In drafts 18–22 the rule applies to SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS separately, so one of each may share a prefix.

The messages in each draft

Drafts Request Answer Namespace announced by Withdrawn by To stop
07–12 SUBSCRIBE_ANNOUNCES (0x11) SUBSCRIBE_ANNOUNCES_OK / _ERROR ANNOUNCE (full namespace) UNANNOUNCE UNSUBSCRIBE_ANNOUNCES
13 SUBSCRIBE_NAMESPACE (0x11) SUBSCRIBE_NAMESPACE_OK / _ERROR ANNOUNCE (full namespace) UNANNOUNCE UNSUBSCRIBE_NAMESPACE
14 SUBSCRIBE_NAMESPACE (0x11) SUBSCRIBE_NAMESPACE_OK / _ERROR PUBLISH_NAMESPACE (full namespace) PUBLISH_NAMESPACE_DONE UNSUBSCRIBE_NAMESPACE
15 SUBSCRIBE_NAMESPACE (0x11) REQUEST_OK / REQUEST_ERROR PUBLISH_NAMESPACE (full namespace) PUBLISH_NAMESPACE_DONE UNSUBSCRIBE_NAMESPACE
16–17 SUBSCRIBE_NAMESPACE (0x11), on its own stream REQUEST_OK / REQUEST_ERROR NAMESPACE (suffix) NAMESPACE_DONE Close the stream
18–23 SUBSCRIBE_NAMESPACE (0x50), on its own stream REQUEST_OK / REQUEST_ERROR NAMESPACE (suffix) NAMESPACE_DONE Close the stream

In drafts 07–15 the announcements are the messages a publisher uses to advertise a namespace, and they carry the full namespace. In drafts 13–15 the publisher also sends matching PUBLISH messages. In draft-23 a namespace whose parameters change is announced again with a new NAMESPACE.

Frequently asked questions

What is SUBSCRIBE_NAMESPACE in MoQT?
SUBSCRIBE_NAMESPACE is the MoQT control message a subscriber sends to discover what a relay or publisher offers. It carries a Track Namespace prefix (a tuple). In drafts 16–23 the publisher answers on the request’s own stream with REQUEST_OK, then sends a NAMESPACE message for every namespace that begins with the prefix, and a NAMESPACE_DONE when one of them goes away. In drafts 07–15 the matching namespaces arrive as ANNOUNCE (drafts 07–13) or PUBLISH_NAMESPACE (drafts 14–15) messages instead, and drafts 07–12 call the request SUBSCRIBE_ANNOUNCES. SUBSCRIBE_NAMESPACE is discovery: it tells you which namespaces exist, without subscribing to any track.
How does track namespace prefix matching work?
A Track Namespace is an ordered tuple of fields, e.g. ["sports","live","game42"]. A prefix matches every namespace whose leading fields equal the prefix’s fields, one for one. So prefix ["sports"] matches ["sports","live","game42"] and ["sports","vod","game17"], but not ["news","live"]. Matching compares whole fields, not characters within a field. In drafts 16–23 an empty prefix matches every namespace; drafts 08–15 close the session if the prefix is empty.
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?
In drafts 18–23 namespace subscription has two messages. SUBSCRIBE_NAMESPACE (0x50) receives NAMESPACE / NAMESPACE_DONE messages about which namespaces match a prefix. SUBSCRIBE_TRACKS (0x51) asks the publisher to send a PUBLISH for each track in the matching namespaces, so the subscriber is subscribed to tracks as they are published. A publisher can answer SUBSCRIBE_TRACKS with PUBLISH_SKIPPED (drafts 19–23) or PUBLISH_BLOCKED (draft-18) to say it will not send a PUBLISH for a track. In drafts 16–17 one SUBSCRIBE_NAMESPACE does both, and its Subscribe Options field selects NAMESPACE messages, PUBLISH messages, or both.
Can I have two namespace subscriptions whose prefixes overlap?
In draft-23, yes. A subscriber may hold several SUBSCRIBE_NAMESPACE or SUBSCRIBE_TRACKS requests whose prefixes overlap. If a track matches more than one SUBSCRIBE_TRACKS, the publisher sends a PUBLISH for each, and each PUBLISH carries a SUBSCRIBE_TRACKS_ID parameter naming the request it answers. In drafts 07–22, no: the publisher rejects a namespace subscription whose prefix overlaps an active one in the same session (with PREFIX_OVERLAP in drafts 15–22). In drafts 18–22 the rule applies to SUBSCRIBE_NAMESPACE and SUBSCRIBE_TRACKS separately, so one of each may share a prefix.
How do I stop a namespace subscription?
In drafts 16–23 SUBSCRIBE_NAMESPACE has its own stream, and closing that stream ends it. In drafts 13–15 you send UNSUBSCRIBE_NAMESPACE, and in drafts 07–12 UNSUBSCRIBE_ANNOUNCES. moqtap’s peek and intercept modes use the right mechanism for the session’s draft.

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.

About the moqtap CLI Namespace discovery guide