Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/moqtail/moqtail/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Fetch class represents a MOQT Fetch control message. It allows clients to request a specific range of objects from a track without establishing a long-lived subscription. Fetch supports three modes: standalone, relative (to an existing subscription), and absolute (to an existing subscription).

​
Class Definition

class Fetch {
  constructor(
    public readonly requestId: bigint,
    public readonly subscriberPriority: number,
    public readonly groupOrder: GroupOrder,
    public readonly typeAndProps:
      | {
          readonly type: FetchType.StandAlone
          readonly props: { 
            fullTrackName: FullTrackName
            startLocation: Location
            endLocation: Location 
          }
        }
      | {
          readonly type: FetchType.Relative
          readonly props: { 
            joiningRequestId: bigint
            joiningStart: bigint 
          }
        }
      | {
          readonly type: FetchType.Absolute
          readonly props: { 
            joiningRequestId: bigint
            joiningStart: bigint 
          }
        },
    public readonly parameters: KeyValuePair[],
  )
}

​
Properties

​
requestId
bigint
required
Unique identifier for this fetch request.
​
subscriberPriority
number
required
Priority value (0-255) for this fetch request. Higher priority requests are processed 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
​
typeAndProps
object
required
Discriminated union defining the fetch type and its associated properties.
​
parameters
KeyValuePair[]
required
Additional protocol parameters for the fetch request.

​
Fetch Types

​
StandAlone Fetch

Fetches objects from a track independently of any subscription.

​
Relative Fetch

Fetches objects relative to the current position of an existing subscription.

​
Absolute Fetch

Fetches objects starting at an absolute location relative to an existing subscription.

​
Methods

​
getType

Returns the control message type identifier. 
getType(): ControlMessageType
Returns: ControlMessageType.Fetch

​
serialize

Serializes the Fetch message to a frozen byte buffer for transmission. 
serialize(): FrozenByteBuffer
Returns: FrozenByteBuffer containing the serialized message Throws: LengthExceedsMaxError if the payload exceeds 65535 bytes

​
parsePayload

Deserializes a Fetch message from a byte buffer. 
static parsePayload(buf: BaseByteBuffer): Fetch
​
buf
BaseByteBuffer
required
Buffer containing the serialized Fetch message payload
Returns: Deserialized Fetch instance Throws:
  • NotEnoughBytesError if the buffer doesn’t contain enough data
  • CastingError if invalid fetch type or group order values are encountered
  • Error if the fetch type is unknown

​
Usage Examples

​
Standalone Fetch

Fetch a specific range of objects from a track. 
import { Fetch, FetchType, FullTrackName, Location, GroupOrder } from 'moqtail'

const fetch = new Fetch(
  161803n,
  15,
  GroupOrder.Descending,
  {
    type: FetchType.StandAlone,
    props: {
      fullTrackName: FullTrackName.tryNew('video/vod', 'episode1'),
      startLocation: new Location(0n, 0n),
      endLocation: new Location(10n, 99n),
    }
  },
  []
)

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

​
Relative Fetch

Fetch objects relative to an existing subscription’s position. 
import { Fetch, FetchType, GroupOrder, KeyValuePair } from 'moqtail'

const fetch = new Fetch(
  99999n,
  10,
  GroupOrder.Original,
  {
    type: FetchType.Relative,
    props: {
      joiningRequestId: 12345n,  // Existing subscription
      joiningStart: 5n,           // Fetch 5 groups ahead
    }
  },
  [KeyValuePair.tryNewVarInt(0, 1)]
)

​
Absolute Fetch

Fetch objects from an absolute position, joining an existing subscription. 
import { Fetch, FetchType } from 'moqtail'

const fetch = new Fetch(
  77777n,
  20,
  GroupOrder.Ascending,
  {
    type: FetchType.Absolute,
    props: {
      joiningRequestId: 12345n,  // Existing subscription
      joiningStart: 100n,         // Start at group 100
    }
  },
  []
)

​
Parse Incoming Fetch

import { Fetch, ByteBuffer, FetchType } 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 fetch = Fetch.parsePayload(buf.freeze())

if (fetch.typeAndProps.type === FetchType.StandAlone) {
  console.log(`Fetch from: ${fetch.typeAndProps.props.fullTrackName.toString()}`)
  console.log(`Range: ${fetch.typeAndProps.props.startLocation.group} to ${fetch.typeAndProps.props.endLocation.group}`)
} else {
  console.log(`Joining request: ${fetch.typeAndProps.props.joiningRequestId}`)
}

​
Fetch vs Subscribe

FeatureFetchSubscribe
DurationOne-time requestLong-lived stream
Use CaseHistorical data, specific segmentsLive streaming, ongoing updates
RangeFixed start and endOpen-ended or filtered
Server ResourcesTemporaryPersistent
Use Fetch for on-demand content retrieval and Subscribe for continuous streaming scenarios.

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us