Connect to a relay
Every subscription, fetch and publication goes through a MOQtailClient: one WebTransport session to one relay. Open it first. If you only want to play a stream, MOQtailPlayer opens the session for you.
The examples import from the moqtail package. To add it to a project, see Install the library.
Open a session
import { MOQtailClient } from 'moqtail'
const client = new MOQtailClient({ url: 'moqt://relay.moqtail.dev' })
client.on('sessionterminated', (reason) => console.warn('Session ended:', reason))
await client.init()The constructor only stores the options. init() opens the WebTransport session, offers moqt-22 as its protocol and exchanges SETUP with the relay. Listeners you attach before init() see that exchange too. Once init() resolves, client.serverSetup holds the relay's SETUP.
init() runs once per client. A second call throws a MOQtailError. If it fails, it closes the client, fires sessionterminated and rejects, so to try again you make a new client:
async function connect(url: string, attempts = 3): Promise<MOQtailClient> {
for (let attempt = 1; ; attempt++) {
const client = new MOQtailClient({ url })
try {
await client.init()
return client
} catch (error) {
if (attempt === attempts) throw error
await new Promise((resolve) => setTimeout(resolve, 1000 * attempt))
}
}
}Choose the URL
url takes a moqt:// or an https:// URL, as a string or a URL. A moqt:// URL is opened as the matching https:// URL, because the browser only opens WebTransport over HTTPS:
| You pass | WebTransport opens |
|---|---|
moqt://relay.moqtail.dev | https://relay.moqtail.dev (port 443) |
moqt://localhost:4433 | https://localhost:4433 |
moqt://localhost:4433/app?room=1#msf:x | https://localhost:4433/app?room=1 |
https://relay.example.com:4433/app | https://relay.example.com:4433/app |
The fragment after # never leaves the browser. The scheme is not case-sensitive. Transports explains how one relay port serves both WebTransport and raw QUIC.
The browser must trust the relay's certificate, or init() fails without asking. For a relay on your own machine, see Set up TLS certificates.
Send setup options
setupOptions takes a SetupOptions builder. Its options go into the client's SETUP message. For example, to send an authorization token and name your application:
import { AuthorizationToken, MOQtailClient, SetupOptions } from 'moqtail'
const token = 'your token'
const setupOptions = new SetupOptions()
.addAuthorizationToken(AuthorizationToken.newUseValue(0, new TextEncoder().encode(token)))
.addMoqtImplementation('my-app/1.0')
const client = new MOQtailClient({ url: 'moqt://localhost:4433', setupOptions })- You don't need
addPath(): over WebTransport the path travels in the URL. - Don't add an AUTHORITY option. It is not allowed over WebTransport, and
init()rejects it. - The client tells the relay it accepts 32 filter ranges per request.
addMaxFilterRanges()sets another number.
Pass WebTransport options
transportOptions goes to the browser's WebTransport constructor as it is. The client adds moqt-22 to its protocols. For example, serverCertificateHashes makes the browser accept a self-signed certificate by its SHA-256 hash. The browser only allows this for a certificate that is valid for 14 days or less.
const certificateHash = Uint8Array.from(atob('<base64 SHA-256 of the DER certificate>'), (c) => c.charCodeAt(0))
const client = new MOQtailClient({
url: 'moqt://localhost:4433',
transportOptions: {
serverCertificateHashes: [{ algorithm: 'sha-256', value: certificateHash }],
},
})Set the other options
| Option | Default | What it does |
|---|---|---|
enableDatagrams | false | Starts reading and writing QUIC datagrams in init(). client.startDatagrams() does it later. |
ordering | none | Releases each request's objects in location order. See Subscribe and fetch. |
dataStreamTimeoutMs | none | How long a data stream may go without new bytes before the client gives up on it. |
controlStreamTimeoutMs | none | How long the client waits for the rest of a control message that arrived in part. When it runs out, the session ends. |
trackAliasResolutionTimeoutMs | 2000 | How long a data stream that arrives before its SUBSCRIBE_OK waits for it. |
switchDrainTimeoutMs | 2000 | How long the old track of a soft switch may stay quiet before the client stops waiting for it. |
fillOpenTimeoutMs | 1000 | How long after SUBSCRIBE_OK ordering waits for a fill stream to open. |
All timeouts are in milliseconds.
Handle the end of a session
Two events tell you the session is ending:
goaway: the relay is shutting down or wants you elsewhere.goAway.newSessionUriis where to reconnect, orundefinedfor the same URL. The relay closes the sessiongoAway.timeoutmilliseconds later, or without a set deadline when that is0. The client does not reconnect for you.sessionterminated: the session is over, because you calleddisconnect(), the relay closed it, or it failed. It fires once. The client can't be used after it, so make a new one.
const url = 'moqt://relay.moqtail.dev'
client.on('goaway', (goAway) => {
void moveTo(goAway.newSessionUri ?? url).catch((error) => console.error('Reconnect failed:', error))
})
async function moveTo(url: string): Promise<void> {
const next = await connect(url)
// Start your subscriptions and publications again on `next`, then close the old session
await client.disconnect('moved to a new session')
}A relay can also send GOAWAY for one request only. The client then sends that request again on the same session by itself. If that GOAWAY names a new session, the client ends the request and fires goaway instead.
Run the relay in production covers when the relay sends GOAWAY.
Turn on logging
The library logs to the console, warnings and errors only by default. The log level and the module filter are global: they apply to every client and player on the page.
import { LogLevel, MOQtailClient } from 'moqtail'
MOQtailClient.setLogLevel(LogLevel.DEBUG)
MOQtailClient.setLogEnabledModules(['MOQtailClient', 'control_stream'])Each line starts with [MOQtail][<module>]. setLogEnabledModules() keeps only the modules you list, and null shows all of them again. LogLevel.NONE silences the library.
To see every control message, listen to messagesent and messagereceived:
client.on('messagesent', (msg) => console.log('→', msg))
client.on('messagereceived', (msg) => console.log('←', msg))Disconnect
await client.disconnect()disconnect() ends every open request, closes the WebTransport session and fires sessionterminated. It takes an optional reason, which sessionterminated passes on. Calling it again does nothing. If you publish, end your tracks first, as Publish a track shows.