ClientSetup

Setup parameters and configuration for MOQT client connections

ClientSetup

The ClientSetup message is sent by the client during the MOQT handshake to negotiate protocol version and capabilities with the server.

Overview

ClientSetup is the first control message sent over the bidirectional control stream after establishing a WebTransport connection. It contains:

1. A list of supported protocol versions (in preference order)
2. Optional setup parameters for capability negotiation

The server responds with a ServerSetup message selecting one of the offered versions and providing its own parameters.

ClientSetup Class

Constructor

const clientSetup = new ClientSetup(
  supportedVersions: number[],
  setupParameters: KeyValuePair[]
)

supportedVersions · number[] · required

Ordered list of MOQT protocol version numbers the client supports. The server will select one from this list.

Common versions:

• 0xff00000e (4278190094) - MOQT Draft-14 (current)
• 0xff00000b (4278190091) - MOQT Draft-11

setupParameters · KeyValuePair[] · required

Array of key-value pairs containing setup parameters. Use SetupParameters builder for convenience.

Methods

serialize()

Serializes the ClientSetup message to a wire format.

serialize(): FrozenByteBuffer

return · FrozenByteBuffer

Serialized message ready for transmission

Throws:

• LengthExceedsMaxError - If payload length exceeds 65535 bytes

parsePayload()

Parses a ClientSetup message from a buffer.

static parsePayload(buf: BaseByteBuffer): ClientSetup

buf · BaseByteBuffer · required

Buffer containing the serialized ClientSetup payload

return · ClientSetup

Parsed ClientSetup instance

---

SetupParameters Builder

The SetupParameters class provides a fluent API for building setup parameter lists.

Constructor

const params = new SetupParameters()

Creates an empty SetupParameters builder.

Methods

addMaxRequestId()

Sets the maximum request ID the client will use.

addMaxRequestId(maxRequestId: bigint | number): SetupParameters

maxRequestId · bigint | number · required

Maximum request ID value (must be >= 0)

return · SetupParameters

The builder instance for chaining

Parameter Key: 0x00

addMaxAuthTokenCacheSize()

Sets the maximum number of authorization tokens to cache.

addMaxAuthTokenCacheSize(size: bigint | number): SetupParameters

size · bigint | number · required

Maximum cache size (must be >= 0)

return · SetupParameters

The builder instance for chaining

Parameter Key: 0x01

addRole()

Sets the client’s role in the MOQT session.

addRole(role: Role): SetupParameters

role · Role · required

Client role:

• Role.Publisher (0x01) - Can publish tracks
• Role.Subscriber (0x02) - Can subscribe to tracks
• Role.PubSub (0x03) - Can both publish and subscribe

return · SetupParameters

The builder instance for chaining

Parameter Key: 0x00 (in version-specific parameters)

build()

Builds the final parameter array.

build(): KeyValuePair[]

return · KeyValuePair[]

Array of key-value pairs ready for use in ClientSetup

---

Usage Examples

Basic Setup

const params = new SetupParameters().build();
const clientSetup = new ClientSetup(
  [0xff00000e], // Draft-14
  params
);

---

ServerSetup Response

After sending ClientSetup, the client receives a ServerSetup message containing:

interface ServerSetup {
  selectedVersion: number;        // Version chosen from client's list
  setupParameters: KeyValuePair[]; // Server's parameters
}

Access the negotiated setup via:

const client = await MOQtailClient.new({ /* ... */ });
const serverSetup = client.serverSetup;

console.log('Negotiated version:', serverSetup.selectedVersion.toString(16));
console.log('Server parameters:', serverSetup.setupParameters);

---

Setup Parameter Keys

Common Setup Parameters

Key	Name	Type	Description
0x00	MAX_REQUEST_ID	VarInt	Maximum request ID client will use
0x01	MAX_AUTH_TOKEN_CACHE_SIZE	VarInt	Maximum authorization tokens to cache

Version-Specific Parameters

These parameters are nested within setup parameters:

Key	Name	Type	Description
0x00	ROLE	VarInt	Client role (Publisher=1, Subscriber=2, PubSub=3)

---

Protocol Flow

---

Best Practices

Version Negotiation: List versions in order of preference. The server will select the first version it supports from your list.

Max Request ID: Setting a low maxRequestId can limit the number of concurrent operations. Choose a value appropriate for your use case (default: unlimited).

Role Parameter: Setting the role parameter helps relays optimize resource allocation. Use Role.Publisher if you only publish, Role.Subscriber if you only subscribe, or Role.PubSub if you do both.

---

See Also

• MOQtailClient - Main client class
• VersionSpecificParameters - Request-level parameters
• MOQT Protocol Draft-14 - Official specification