Subscribe and fetch
Subscribe to get a track's objects as they are published. Fetch to get objects that are already published. Both need a connected client: see Connect to a relay.
Name the track
A track is named by its namespace and its track name, together a FullTrackName:
import { FullTrackName } from 'moqtail'
const fullTrackName = FullTrackName.tryNew('moqtail/ch07', 'catalog')The namespace is a /-separated string or a Tuple, the name a string or bytes. tryNew throws a TrackNameError when the namespace has more than 32 fields or the whole name is longer than 4096 bytes. MOQT in brief explains namespaces, tracks, groups and objects.
Subscribe
import { GroupOrder, LocationFilter, LocationFilterType, RequestError } from 'moqtail'
const subscription = await client.subscribe({
fullTrackName,
priority: 128,
groupOrder: GroupOrder.Original,
locationFilter: new LocationFilter(LocationFilterType.NextObject),
})
if (subscription instanceof RequestError) {
throw new Error(`Subscribe refused: ${subscription.reasonPhrase.phrase}`)
}When the relay refuses, subscribe() returns its RequestError, with an errorCode and a reasonPhrase. When it accepts, you get:
requestId, which names the subscription in later calls.subscribeOk, the relay's SUBSCRIBE_OK, with the track alias and parameters.stream, aReadableStreamofMoqtObjects.done, a promise for the PUBLISH_DONE that ends the subscription.
subscribe() throws when the client is not connected or the session fails. A session failure also closes the client.
The options:
| Option | What it does |
|---|---|
fullTrackName | The track. |
priority | An integer from 0, the highest, to 255, the lowest. Other values are rounded and clamped. |
groupOrder | Original keeps the publisher's order, Ascending and Descending ask for one. |
locationFilter | Which objects to deliver: see Choose where to start. Without it, the subscription is unfiltered. |
forward | false sets up the subscription without delivering objects yet. Left out, objects are delivered. |
parameters | More message parameters, such as a fill. |
ordering | Overrides the client's ordering: see Receive objects in order. |
onEndOfRange | Called for each End of Range marker on a fill. |
earlyDiscardPolicy | { subgroupReceiveTimeout }: drops a data stream that has not finished within that many ms. |
To see where the track is now, read the Largest Object from the SUBSCRIBE_OK:
import { MessageParameter } from 'moqtail'
const largest = subscription.subscribeOk.parameters.find(MessageParameter.isLargestObject)
console.log('Track is at', largest?.location)Read the objects
const reader = subscription.stream.getReader()
for (let read = await reader.read(); !read.done; read = await reader.read()) {
const object = read.value
// End of Group and End of Track objects carry a status instead of a payload
if (!object.payload) continue
console.log(`group ${object.location.group} object ${object.location.object}: ${object.payload.byteLength} bytes`)
}Each object has its location (group and object ID), its payload, its properties and its objectStatus. Objects come in the order they arrive, which across several data streams is not always location order.
The properties are key-value pairs. findProperty reads one, such as the LOC Timestamp:
import { findProperty, Timestamp } from 'moqtail'
const sentAt = findProperty(object.properties, Timestamp)?.timestampThe stream closes when the publisher has ended the track and all its data has arrived. done resolves then, with the PUBLISH_DONE, or with undefined when the subscription ended without one. It never rejects. If the session ends first, done resolves but the stream stays open, so stop reading on sessionterminated too.
void subscription.done.then((publishDone) => {
console.log('Subscription over', publishDone?.statusCode, publishDone?.errorReason.phrase)
})Choose where to start
locationFilter takes a LocationFilter. Its type says which fields follow:
| Filter | Delivers |
|---|---|
new LocationFilter(LocationFilterType.NextObject) | From the object after the Largest Object |
new LocationFilter(LocationFilterType.RelativeStart, 0n) | From the next group. 1n is the current group, 2n the one before. |
new LocationFilter(LocationFilterType.AbsoluteStart, 100n, 0n) | From group 100, object 0 |
new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 100n, 0n, 120n) | From group 100, object 0, to the end of group 120 |
new LocationFilter(LocationFilterType.AbsoluteRange, 100n, 0n, 120n, 4n) | From group 100, object 0, to group 120, object 4, inclusive |
A start in the future waits for that object. The constructor throws a ProtocolViolationError when a field is missing or the end is before the start.
Start at the beginning of the current group
A decoder usually needs a group from its first object, but NextObject starts in the middle of one. To also get the objects of the current group that are already published, add a fill:
import { FillParameters } from 'moqtail'
const subscription = await client.subscribe({
fullTrackName,
priority: 128,
groupOrder: GroupOrder.Original,
locationFilter: new LocationFilter(LocationFilterType.NextObject),
parameters: [new FillParameters([new LocationFilter(LocationFilterType.RelativeStart, 1n)])],
})The publisher sends the fill on a stream of its own, and its objects arrive on the same stream as the live ones. With ordering on, they come in location order with them.
Change or end a subscription
subscribeUpdate() changes a running subscription. What you leave out stays as it is:
await client.subscribeUpdate({ subscriptionRequestId: subscription.requestId, priority: 200 })
await client.subscribeUpdate({ subscriptionRequestId: subscription.requestId, forward: false })forward: false pauses delivery and forward: true resumes it. locationFilter replaces the filter.
To end a subscription, stop reading and unsubscribe:
await reader.cancel()
await client.unsubscribe(subscription.requestId)You need both. Cancelling the stream does not tell the relay, and unsubscribe() does not close the stream. unsubscribe() resolves done with undefined, and calling it again does nothing.
Fetch past objects
fetch() takes the same track, priority and group order, and a filter for the objects you want. A filter without an end stops at the Largest Object, and no filter at all fetches the whole track up to it.
const fetched = await client.fetch({
fullTrackName,
priority: 128,
groupOrder: GroupOrder.Original,
locationFilter: new LocationFilter(LocationFilterType.RelativeStart, 2n),
})
if (fetched instanceof RequestError) {
throw new Error(`Fetch refused: ${fetched.reasonPhrase.phrase}`)
}
console.log('Fetch ends at', fetched.fetchOk.endLocation, 'end of track:', fetched.fetchOk.endOfTrack)
const fetchReader = fetched.stream.getReader()
for (let read = await fetchReader.read(); !read.done; read = await fetchReader.read()) {
console.log(read.value.location)
}RelativeStart with 2n fetches the current group and the one before it. The stream closes after the last object. A range the publisher has nothing for is refused with a RequestError.
Where a range of objects is missing, the publisher can say so with an End of Range marker. Pass onEndOfRange: (kind, location) => … to hear about them: every location up to location does not exist, is unknown or timed out, as kind says.
To stop a fetch early, cancel it and stop reading:
await client.fetchCancel(fetched.requestId)
await fetchReader.cancel()Receive objects in order
Without ordering, objects come as they arrive. With it, the client releases each request's objects in location order and waits a little for one that is missing. Set it for every request on the client, or per request:
const client = new MOQtailClient({
url: 'moqt://relay.moqtail.dev',
ordering: { window: { durationMs: 150 } },
})
client.on('orderinggap', (requestId, from, to) => {
console.warn(`Request ${requestId} skipped ${from.group}:${from.object} up to ${to.group}:${to.object}`)
})windowis how long an object may wait for the one before it (durationMs), and how many may wait (objects). When either runs out, the client releases what it holds and reports the skipped locations withorderinggap.onWindowExceededis what happens to an object that arrives after the client stopped waiting for it:'flush'(the default) still delivers it,'drop'drops it.sparseObjectIdsandsparseGroupIdssay IDs may skip without the publisher marking the gap.
ordering: 'none' on a subscription or fetch turns it off for that request. A request with GroupOrder.Descending is never ordered.
Ordering also decides where datagrams go. A publisher may send objects as QUIC datagrams instead of on streams, and the client reads them only with enableDatagrams: true. An ordered subscription gets them on its stream. On an unordered one, read them with client.subscribeToTrackDatagrams(subscription.subscribeOk.trackAlias, (object) => …).
Switch to another track
switch() replaces a subscription with one to another track, such as another rendition, while you keep reading the same stream. With SwitchMode.Soft, the old track keeps delivering up to the group where the new one starts, so nothing is missing between them. SwitchMode.Hard stops the old track at once. The relay must support SWITCH_FROM.
import { SwitchMode } from 'moqtail'
const switched = await client.switch({
switchFromRequestId: subscription.requestId,
switchMode: SwitchMode.Soft,
newSubscribeOptions: {
fullTrackName: FullTrackName.tryNew('my-app/live', 'video-1080p'),
priority: 128,
groupOrder: GroupOrder.Original,
locationFilter: new LocationFilter(LocationFilterType.NextObject),
},
})The result is a RequestError or a new SubscribeResult, whose stream and done are the original subscription's.