Skip to content

Publish a track ​

A publisher announces a namespace, registers each track with the client, and writes the track's objects into a stream. The client sends them to whoever asks. This page follows the publisher in apps/client-js, which publishes a camera as video tracks and a catalog.

You need a connected client: see Connect to a relay. The examples publish to a local relay at moqt://localhost:4433.

Announce the namespace ​

ts
import { RequestError, Tuple } from 'moqtail'

const namespace = Tuple.fromUtf8Path('my-app/camera')
const announced = await client.publishNamespace(namespace)
if (announced instanceof RequestError) {
  throw new Error(`Namespace refused: ${announced.reasonPhrase.phrase}`)
}

publishNamespace() returns the relay's RequestOk or its RequestError. The namespace stays announced until you call unpublishNamespace() or the session ends. While it is announced, the relay passes on SUBSCRIBE and FETCH requests for tracks in it to you.

Register the track ​

A track's live objects come from a ReadableStream of MoqtObjects, wrapped in a LiveTrackSource. Keep the stream's controller: you write objects with it.

ts
import { FullTrackName, LiveTrackSource, type MoqtObject, type Track } from 'moqtail'

const fullTrackName = FullTrackName.tryNew(namespace, 'video')

let controller!: ReadableStreamDefaultController<MoqtObject>
const objects = new ReadableStream<MoqtObject>({
  start: (c) => {
    controller = c
  },
})

const track: Track = {
  fullTrackName,
  trackSource: { live: new LiveTrackSource(objects) },
  publisherPriority: 1,
}
client.addOrUpdateTrack(track)

addOrUpdateTrack() gives the track a random track alias when it has none. publisherPriority goes from 0, the highest, to 255, the lowest.

From now on the client answers a SUBSCRIBE for this track and sends it the objects you write. It refuses tracks you haven't registered with DOES_NOT_EXIST. If that is all you need, skip to Write objects: the relay asks for the track when a subscriber does.

Push it to the relay ​

To have the relay take the track before anyone asks for it, publish it:

ts
const published = await client.publish(fullTrackName, true, track.trackAlias!)
if (published instanceof RequestError) {
  throw new Error(`Track refused: ${published.reasonPhrase.phrase}`)
}

The arguments are the track, the forward state, and the alias addOrUpdateTrack() gave it. Once the relay accepts, the client sends it every object you write. A track you push also reaches subscribers that ask for every track under a prefix.

With false as the forward state, the client holds back objects until the relay asks for them. forwardstatechange tells you when that changes:

ts
client.on('forwardstatechange', (requestId, forward) => {
  if (requestId === published.requestId) console.log(forward ? 'Sending' : 'Paused')
})

The relay can also ask you for things. The client answers these requests itself, and the events let you see them: peersubscribenamespace when the relay subscribes to a namespace prefix you publish under, and peersubscribetracks when it asks for every track under a prefix, which the client then pushes to it.

Write objects ​

Each object needs a location: a group ID and an object ID within the group. A group is where a subscriber can start, so a video track starts a new group at each key frame:

ts
import { LOCProperties, Location, MoqtObject, ObjectForwardingPreference } from 'moqtail'

let group = 0n
let object = 0n

function send(payload: Uint8Array, isKey: boolean): void {
  if (isKey) {
    group++
    object = 0n
  }
  const location = new Location(group, object)
  object++

  const properties = new LOCProperties()
    .addTimestamp(Date.now() * 1000)
    .addVideoFrameMarking(isKey)
    .build()

  controller.enqueue(
    MoqtObject.newWithPayload(fullTrackName, location, 1, ObjectForwardingPreference.Subgroup, 0n, properties, payload),
  )
}

The arguments of MoqtObject.newWithPayload() are the track, the location, the publisher priority, the forwarding preference, the subgroup ID, the object properties (or null) and the payload. LOCProperties builds the LOC properties: here the capture time in microseconds since the Unix epoch, and whether the frame is a key frame.

Call send() with each encoded frame, for example from a VideoEncoder:

ts
const encoder = new VideoEncoder({
  output: (chunk) => {
    const payload = new Uint8Array(chunk.byteLength)
    chunk.copyTo(payload)
    send(payload, chunk.type === 'key')
  },
  error: (error) => console.error('Encoder failed:', error),
})

The client opens a data stream for each group and closes it when the next group starts. It sends only objects you write after a subscription starts or the relay accepts the push. Objects with ObjectForwardingPreference.Datagram are not sent: to send datagrams, connect with enableDatagrams: true and write them with client.createDatagramSender(trackAlias).

A player also needs a catalog that describes your tracks. Catalogs and packaging explains what goes in it.

Serve past objects ​

A FETCH asks for objects already published. The client answers it from the track's past source, and refuses it with NOT_SUPPORTED for a track without one. To serve both, register the track with a HybridTrackSource instead, and add each object to its cache as you write it:

ts
import { HybridTrackSource, RingBufferObjectCache } from 'moqtail'

const cache = new RingBufferObjectCache(300)
const track: Track = {
  fullTrackName,
  trackSource: new HybridTrackSource(cache, objects),
  publisherPriority: 1,
}

function write(obj: MoqtObject): void {
  cache.add(obj)
  controller.enqueue(obj)
}

RingBufferObjectCache keeps the latest objects, 100 unless you give another number. MemoryObjectCache keeps all of them. For a recording with no live part, use { past: new StaticTrackSource(cache) } as the track source.

Stop publishing ​

Stop the encoder and close the stream, end the push, then withdraw the track and the namespace:

ts
encoder.close()
controller.close()
await client.publishDone(published.requestId)
client.removeTrack(track)
await client.unpublishNamespace(namespace)
await client.disconnect()

Closing the stream ends every subscription the client answered for the track, with PUBLISH_DONE and TRACK_ENDED. A push needs publishDone() too. It reports TRACK_ENDED unless you give another status code. removeTrack() only stops the client from answering new requests for the track.

More information ​