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 PublishNamespace class represents a MOQT PublishNamespace control message (formerly known as “Announce”). It allows publishers to declare their intent to publish tracks within a specific namespace, along with any associated parameters.

​
Class Definition

class PublishNamespace {
  constructor(
    public readonly requestId: bigint,
    public readonly trackNamespace: Tuple,
    public readonly parameters: KeyValuePair[],
  )
}

​
Properties

​
requestId
bigint
required
Unique identifier for this publish namespace request. Used to correlate with PublishNamespaceOk or PublishNamespaceError responses.
​
trackNamespace
Tuple
required
The namespace tuple that identifies the collection of tracks. Typically a hierarchical path like video/conference/room1.
​
parameters
KeyValuePair[]
required
Additional protocol parameters for the namespace announcement. Can include authorization tokens, capabilities, or custom metadata.

​
Methods

​
getType

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

​
serialize

Serializes the PublishNamespace 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 PublishNamespace message from a byte buffer. 
static parsePayload(buf: BaseByteBuffer): PublishNamespace
​
buf
BaseByteBuffer
required
Buffer containing the serialized PublishNamespace message payload
Returns: Deserialized PublishNamespace instance Throws: NotEnoughBytesError if the buffer doesn’t contain enough data

​
Usage Examples

​
Announce a Namespace

import { PublishNamespace, Tuple, KeyValuePair } from 'moqtail'

// Announce a video streaming namespace
const publishNs = new PublishNamespace(
  12345n,
  Tuple.fromUtf8Path('video/livestream/channel42'),
  [
    KeyValuePair.tryNewVarInt(0, 10),  // Parameter type 0, value 10
    KeyValuePair.tryNewBytes(1, new TextEncoder().encode('auth-token-here'))
  ]
)

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

​
Announce Without Parameters

import { PublishNamespace, Tuple } from 'moqtail'

const publishNs = new PublishNamespace(
  67890n,
  Tuple.fromUtf8Path('audio/podcast/episode123'),
  []  // No additional parameters
)

​
Parse Incoming PublishNamespace

import { PublishNamespace, 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 publishNs = PublishNamespace.parsePayload(buf.freeze())

console.log(`Namespace: ${publishNs.trackNamespace.toUtf8Path()}`)
console.log(`Request ID: ${publishNs.requestId}`)
console.log(`Parameters: ${publishNs.parameters.length}`)

​
Handle Server Response

import { PublishNamespace, PublishNamespaceOk } from 'moqtail'

// Send announcement
const publishNs = new PublishNamespace(
  12345n,
  Tuple.fromUtf8Path('video/stream'),
  []
)

await sendMessage(publishNs.serialize())

// Wait for response
const response = await receiveMessage()
if (response.type === ControlMessageType.PublishNamespaceOk) {
  console.log('Namespace announced successfully')
  // Can now publish tracks in this namespace
} else if (response.type === ControlMessageType.PublishNamespaceError) {
  console.error(`Announcement failed: ${response.errorCode}`)
}

​
Namespace Hierarchy

Namespaces are hierarchical and typically organized by content type and specificity: 
// Organization level
Tuple.fromUtf8Path('mycompany')

// Service level
Tuple.fromUtf8Path('mycompany/videoconf')

// Session level
Tuple.fromUtf8Path('mycompany/videoconf/meeting-uuid')

// Participant level
Tuple.fromUtf8Path('mycompany/videoconf/meeting-uuid/user123')
Within each namespace, you can publish multiple tracks (video, audio, metadata, etc.).

​
Error Codes

The server may respond with a PublishNamespaceError message containing one of these error codes:
​
InternalError
0x0
Server encountered an internal error
​
Unauthorized
0x1
Client is not authorized to publish to this namespace
​
Timeout
0x2
Request timed out
​
NotSupported
0x3
Server does not support publishing to this namespace
​
Uninterested
0x4
Server has no subscribers interested in this namespace
​
MalformedAuthToken
0x10
Authorization token is malformed
​
UnknownAuthTokenAlias
0x11
Referenced auth token alias is unknown
​
ExpiredAuthToken
0x12
Authorization token has expired

​
Best Practices

Always wait for a PublishNamespaceOk response before attempting to publish tracks within the namespace.
Use meaningful, hierarchical namespace structures to enable efficient routing and authorization.
The namespace does not include the individual track names. Use FullTrackName to combine the namespace with a track name when publishing.

​
See Also