Subscribe

Subscribe to a track to receive objects over time

Overview

The Subscribe class represents a MOQT Subscribe control message. It allows clients to request streaming objects from a specific track, with configurable filtering, priority, and delivery ordering options.

Class Definition

class Subscribe {
  constructor(
    public requestId: bigint,
    public fullTrackName: FullTrackName,
    public subscriberPriority: number,
    public groupOrder: GroupOrder,
    public forward: boolean,
    public filterType: FilterType,
    public startLocation: Location | undefined,
    public endGroup: bigint | undefined,
    public parameters: KeyValuePair[],
  )
}

Properties

requestId · bigint · required

Unique identifier for this subscription request.

fullTrackName · FullTrackName · required

The fully qualified track name consisting of a namespace tuple and track name.

subscriberPriority · number · required

Priority value (0-255) for this subscription. Higher priority subscriptions receive objects first.

groupOrder · GroupOrder · required

Specifies the order in which groups should be delivered:

• GroupOrder.Original (0x0): Original order
• GroupOrder.Ascending (0x1): Ascending order
• GroupOrder.Descending (0x2): Descending order

forward · boolean · required

If true, objects are delivered forward from the start location. If false, objects are delivered in reverse.

filterType · FilterType · required

Determines which objects to receive:

• FilterType.NextGroupStart (0x1): Start from the next available group
• FilterType.LatestObject (0x2): Start from the latest object
• FilterType.AbsoluteStart (0x3): Start from an absolute location
• FilterType.AbsoluteRange (0x4): Request a specific range of groups

startLocation · Location | undefined

Starting location for AbsoluteStart and AbsoluteRange filter types. Contains group and object indices.

endGroup · bigint | undefined

Ending group for AbsoluteRange filter type. Must be greater than or equal to the start group.

parameters · KeyValuePair[] · required

Additional protocol parameters for the subscription.

Static Factory Methods

newNextGroupStart

Creates a subscription that starts from the next available group.

static newNextGroupStart(
  requestId: bigint,
  fullTrackName: FullTrackName,
  subscriberPriority: number,
  groupOrder: GroupOrder,
  forward: boolean,
  parameters: KeyValuePair[],
): Subscribe

requestId · bigint · required

Unique request identifier

fullTrackName · FullTrackName · required

Track to subscribe to

subscriberPriority · number · required

Priority level (0-255)

groupOrder · GroupOrder · required

Delivery order for groups

forward · boolean · required

Direction of delivery

parameters · KeyValuePair[] · required

Additional parameters

Returns: Subscribe instance with FilterType.NextGroupStart

newLatestObject

Creates a subscription that starts from the latest available object.

static newLatestObject(
  requestId: bigint,
  fullTrackName: FullTrackName,
  subscriberPriority: number,
  groupOrder: GroupOrder,
  forward: boolean,
  parameters: KeyValuePair[],
): Subscribe

Returns: Subscribe instance with FilterType.LatestObject

newAbsoluteStart

Creates a subscription that starts from a specific location and continues indefinitely.

static newAbsoluteStart(
  requestId: bigint,
  fullTrackName: FullTrackName,
  subscriberPriority: number,
  groupOrder: GroupOrder,
  forward: boolean,
  startLocation: Location,
  parameters: KeyValuePair[],
): Subscribe

startLocation · Location · required

The group and object location to start from

Returns: Subscribe instance with FilterType.AbsoluteStart

newAbsoluteRange

Creates a subscription for a specific range of groups.

static newAbsoluteRange(
  requestId: bigint,
  fullTrackName: FullTrackName,
  subscriberPriority: number,
  groupOrder: GroupOrder,
  forward: boolean,
  startLocation: Location,
  endGroup: bigint,
  parameters: KeyValuePair[],
): Subscribe

startLocation · Location · required

The group and object location to start from

endGroup · bigint · required

The last group to receive (inclusive)

Returns: Subscribe instance with FilterType.AbsoluteRange

Throws: Error if endGroup < startLocation.group

Methods

serialize

Serializes the Subscribe message to a frozen byte buffer for transmission.

serialize(): FrozenByteBuffer

Returns: FrozenByteBuffer containing the serialized message

Throws:

• Error if startLocation is missing for AbsoluteStart or AbsoluteRange
• Error if endGroup is missing for AbsoluteRange

parsePayload

Deserializes a Subscribe message from a byte buffer.

static parsePayload(buf: BaseByteBuffer): Subscribe

buf · BaseByteBuffer · required

Buffer containing the serialized Subscribe message payload

Returns: Deserialized Subscribe instance

Throws: Error if the buffer contains invalid or incomplete data

Usage Examples

Subscribe to Latest Content

import { Subscribe, FullTrackName, GroupOrder, KeyValuePair } from 'moqtail'

const subscribe = Subscribe.newLatestObject(
  12345n,
  FullTrackName.tryNew('video/stream', 'track1'),
  128,  // Priority
  GroupOrder.Original,
  true, // Forward
  []    // No additional parameters
)

const serialized = subscribe.serialize()
// Send serialized message to server

Subscribe to Specific Range

import { Subscribe, Location } from 'moqtail'

const subscribe = Subscribe.newAbsoluteRange(
  67890n,
  FullTrackName.tryNew('audio/stream', 'track2'),
  64,
  GroupOrder.Ascending,
  true,
  new Location(100n, 0n), // Start at group 100, object 0
  200n,                    // End at group 200
  [KeyValuePair.tryNewVarInt(0, 1)]
)

Parse Incoming Subscribe

import { Subscribe, ByteBuffer } from 'moqtail'

const buf = new ByteBuffer()
buf.putBytes(incomingData)

// Skip message type and read payload length
const msgType = buf.getVI()
const msgLength = buf.getU16()

const subscribe = Subscribe.parsePayload(buf)
console.log(`Subscribe to: ${subscribe.fullTrackName.toString()}`)
console.log(`Priority: ${subscribe.subscriberPriority}`)

Related Types

• FullTrackName - Track identifier
• Location - Group and object position
• KeyValuePair - Protocol parameters
• FilterType - Subscription filter options
• GroupOrder - Group delivery order

See Also

• Fetch - Request specific objects without subscribing
• TrackStatus - Query track availability