moqtail 0.15.0 → 0.16.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/README.md +153 -473
  2. package/dist/{client-BviQ20Lc.cjs → client-DQ5aGbLR.cjs} +1089 -1074
  3. package/dist/client-DUzLw_Y8.d.cts +1932 -0
  4. package/dist/{client-zi0lmuIL.mjs → client-DVi4Nh1J.mjs} +930 -921
  5. package/dist/client-epHqMdHm.d.mts +1932 -0
  6. package/dist/client.cjs +121 -4
  7. package/dist/client.d.cts +23 -1944
  8. package/dist/client.d.mts +23 -1944
  9. package/dist/client.mjs +117 -2
  10. package/dist/emitter-UbeRcbuf.mjs +109 -0
  11. package/dist/{logger-c2NoQqtx.cjs → emitter-qNJYD3yQ.cjs} +61 -2
  12. package/dist/index-B-BMK-b6.d.mts +2090 -0
  13. package/dist/index-BtemTtwe.d.cts +2090 -0
  14. package/dist/{index-BY6e1obL.d.cts → index-CNn9BgO6.d.mts} +119 -324
  15. package/dist/index.cjs +38 -34
  16. package/dist/index.d.cts +20 -4
  17. package/dist/index.d.mts +20 -4
  18. package/dist/index.mjs +5 -4
  19. package/dist/logger-B8IYkljn.d.cts +64 -0
  20. package/dist/logger-B8IYkljn.d.mts +64 -0
  21. package/dist/model.cjs +122 -340
  22. package/dist/model.d.cts +2896 -2
  23. package/dist/model.d.mts +17 -2
  24. package/dist/model.mjs +122 -340
  25. package/dist/player/component.cjs +317 -0
  26. package/dist/player/component.d.cts +50 -0
  27. package/dist/player/component.d.mts +50 -0
  28. package/dist/player/component.mjs +315 -0
  29. package/dist/player-CJayEzwt.cjs +6750 -0
  30. package/dist/player-DcctWhyM.mjs +6599 -0
  31. package/dist/player.cjs +27 -0
  32. package/dist/player.d.cts +17 -0
  33. package/dist/player.d.mts +17 -0
  34. package/dist/player.mjs +1 -0
  35. package/dist/rolldown-runtime-CmQyd0Gu.cjs +27 -0
  36. package/dist/util.cjs +9 -10
  37. package/dist/util.d.cts +20 -13
  38. package/dist/util.d.mts +20 -13
  39. package/dist/util.mjs +4 -6
  40. package/package.json +45 -5
  41. package/dist/index-BY6e1obL.d.mts +0 -3087
  42. package/dist/logger-ByDB8lYF.mjs +0 -56
  43. package/dist/logger-dEoueCj7.d.cts +0 -35
  44. package/dist/logger-dEoueCj7.d.mts +0 -35
package/README.md CHANGED
@@ -1,552 +1,232 @@
1
- # MOQtail TypeScript Client Library
1
+ # moqtail
2
2
 
3
- > ⚠️ **Work in Progress**: This library is under active development and the API is subject to change. Please use with caution in production environments.
3
+ A TypeScript MOQT client and an MSF/CMSF player for the browser.
4
4
 
5
- MOQT (Media over QUIC Transport) is a protocol for media delivery over QUIC connections, enabling efficient streaming of live and on-demand content. The MOQtail client library provides a TypeScript implementation that supports both publisher and subscriber roles in the MOQT ecosystem.
6
-
7
- ## Overview
8
-
9
- The `MOQtailClient` serves as the main entry point for interacting with MoQ relays and other peers. A client can act as:
10
-
11
- - **Original Publisher**: Creates and announces tracks, making content available to subscribers
12
- - **End Subscriber**: Discovers and consumes content from publishers via track subscriptions
13
-
14
- ## Publisher
15
-
16
- As a publisher, the MOQtail client allows you to create, manage, and distribute content through tracks. The library handles protocol-level details while giving you full control over content creation and packaging.
17
-
18
- ### Track Management
19
-
20
- Publishers can add or remove tracks using the `addOrUpdateTrack()` and `removeTrack()` methods:
21
-
22
- ```typescript
23
- const client = await MOQtailClient.new(clientSetup, webTransport)
24
-
25
- // Add a new track
26
- client.addOrUpdateTrack(myTrack)
27
-
28
- // Remove an existing track
29
- client.removeTrack(myTrack)
5
+ ```bash
6
+ npm install moqtail
30
7
  ```
31
8
 
32
- ### Track Structure
33
-
34
- Each track is defined by the `Track` interface, which consists of:
35
-
36
- - **`fullTrackName`**: Unique identifier for the track (namespace + track name)
37
- - **`trackAlias`**: Numeric alias used for efficient wire representation
38
- - **`forwardingPreference`**: How objects should be delivered (Datagram or Subgroup)
39
- - **`contentSource`**: The source of content for this track
40
-
41
- ### Content Sources
42
-
43
- The `ContentSource` interface is the heart of the publisher model, providing two distinct patterns for content delivery:
44
-
45
- #### Live Content (Streaming)
46
-
47
- For real-time content like live video streams, use `LiveContentSource`:
48
-
49
- - Content flows through a `ReadableStream<MoqtObject>`
50
- - Subscribers receive content via **Subscribe** operations
51
- - Suitable for continuously generated content
52
-
53
- #### Static Content (On-Demand)
54
-
55
- For archived or pre-generated content, use `StaticContentSource`:
56
-
57
- - Content is stored in an `ObjectCache` for random access
58
- - Subscribers retrieve specific ranges via **Fetch** operations
59
- - Ideal for video-on-demand, file transfers, or cached content
60
-
61
- #### Hybrid Content
62
-
63
- For tracks that support both patterns, use `HybridContentSource`:
9
+ | Entry | What's in it |
10
+ | -------------------------- | ------------------------------------------------- |
11
+ | `moqtail` | Everything below except the player |
12
+ | `moqtail/client` | `MOQtailClient`, its options, events and results |
13
+ | `moqtail/model` | Control messages, objects, parameters, properties |
14
+ | `moqtail/util` | Logger, `Emitter`, telemetry, clock helpers |
15
+ | `moqtail/player` | `MOQtailPlayer`, elements, plugins |
16
+ | `moqtail/player/component` | The `<moqtail-video>` web component |
64
17
 
65
- - Combines live streaming with historical data access
66
- - New objects are added to cache while also flowing to live subscribers
18
+ It runs in Chrome and Safari 26.4+ (WebTransport). It follows MOQT draft-22 and the MSF and CMSF editor's drafts. The player plays CMAF; LOC, captions and language switching aren't played yet. [DeepWiki](https://deepwiki.com/moqtail/moqtail) has the full list and the details this page leaves out.
67
19
 
68
- ### Object Packaging
20
+ ## How It Fits Together
69
21
 
70
- All content is packaged as `MoqtObject` instances, which represent the atomic units of data in MoQ:
71
-
72
- - **Location**: Identified by `groupId` and `objectId` (e.g., video frames within GOPs)
73
- - **Payload**: The actual media data or content
74
- - **Metadata**: Publisher priority, forwarding preferences, and properties
75
- - **Status**: Normal data, end-of-group markers, or error conditions
76
-
77
- ### Object Caching
78
-
79
- The `ObjectCache` interface provides two simple implementations for static content:
80
-
81
- - **`MemoryObjectCache`**: Unlimited in-memory storage with binary search indexing
82
- - **`RingBufferObjectCache`**: Fixed-size cache with automatic eviction of oldest objects
83
-
84
- ### Publisher Workflow
85
-
86
- 1. **Create Content**: Generate or prepare your media content
87
- 2. **Package as Objects**: Wrap content in `MoqtObject` instances with appropriate metadata
88
- 3. **Choose Content Source**: Select `LiveContentSource`, `StaticContentSource`, or `HybridContentSource`
89
- 4. **Define Track**: Create a `Track` with your content source and metadata
90
- 5. **Add to Client**: Register the track with `addOrUpdateTrack()`
91
- 6. **Publish Namespace**: Use `publishNamespace()` to make the track discoverable by subscribers
92
- 7. **Manage Lifecycle**: The library handles incoming subscribe/fetch requests and data delivery
93
-
94
- ### Example
95
-
96
- ```typescript
97
- // Create a live video track
98
- const videoTrack: Track = {
99
- fullTrackName: FullTrackName.tryNew('live/conference', 'video'),
100
- trackAlias: 1n,
101
- forwardingPreference: ObjectForwardingPreference.Subgroup,
102
- contentSource: new LiveContentSource(videoStream),
103
- }
104
-
105
- // Create a static file track
106
- const fileCache = new MemoryObjectCache()
107
- // ... populate cache with file chunks ...
108
- const fileTrack: Track = {
109
- fullTrackName: FullTrackName.tryNew('files/documents', 'presentation.pdf'),
110
- trackAlias: 2n,
111
- forwardingPreference: ObjectForwardingPreference.Datagram,
112
- contentSource: new StaticContentSource(fileCache),
113
- }
114
-
115
- // Register tracks and announce
116
- client.addOrUpdateTrack(videoTrack)
117
- client.addOrUpdateTrack(fileTrack)
118
-
119
- await client.publishNamespace(new PublishNamespace(client.nextClientRequestId, Tuple.tryNew(['live', 'conference'])))
22
+ ```
23
+ MOQtailPlayer source('moqt://relay/app#msf:ns--catalog') sink(<video>)
24
+ │ init()
25
+ ▼
26
+ MOQtailClient ── WebTransport ── relay one session per origin and setup, shared by players
27
+ │ SERVER_SETUP decides which plugins are active
28
+ ▼
29
+ catalog ──► one source per switching set ──pads──► [transforms] ──► MSE sink ──► <video>
120
30
  ```
121
31
 
122
- The library automatically manages active requests, handles protocol negotiation, and ensures efficient data delivery based on subscriber demands and network conditions.
123
-
124
- ## Subscriber
125
-
126
- As a subscriber, the MOQtail client enables you to discover, request, and consume content from publishers. The library provides two main mechanisms for content retrieval: `subscribe()` for live streaming content and `fetch()` for on-demand content access.
127
-
128
- ### Live Content Subscription
129
-
130
- For real-time streaming content, use `subscribe()` which returns either a `ReadableStream<MoqtObject>` or a `RequestError`:
131
-
132
- #### Subscribe Implementation
32
+ The client is a MOQT session and nothing more: you can use it on its own to subscribe, fetch and publish. The player sits on top of it. It turns a `moqt://` URL into a chain of elements: sources that request tracks and write media to pads, optional transforms, and sinks that play what they receive. Plugins add elements and controllers to that chain, together with the SETUP parameters they need.
133
33
 
134
- Subscribe operations are designed for live streaming and can be delivered through multiple transport mechanisms:
34
+ ## MOQT In Short
135
35
 
136
- - **Datagrams**: For low-latency delivery where occasional packet loss is acceptable
137
- - **Multiple Streams**: Each group (GOP) can be delivered in a separate stream for better prioritization
138
- - **Stream Cancellation**: The library implements intelligent stream cancellation on both publisher and subscriber sides:
139
- - **Publisher Side**: Automatically cancels streams for older groups when bandwidth is limited
140
- - **Subscriber Side**: Cancels streams for groups that are no longer needed due to latency constraints
36
+ A client opens one session to a relay and exchanges SETUP, where both sides state the parameters and extensions they support. Media is published as tracks. A track is named by a namespace (a tuple of fields, such as `live/demo`) and a track name, together the full track name. A track is a sequence of groups, each a sequence of objects; a group usually starts at a key frame, so it's where a subscriber can join. A subscriber asks for a track with SUBSCRIBE (objects as they're published) or FETCH (objects already published), and the relay answers with an OK or an error. A publisher announces a namespace with PUBLISH_NAMESPACE, or pushes a track with PUBLISH.
141
37
 
142
- This approach ensures that subscribers always receive the most recent content with minimal latency, automatically dropping outdated frames during network congestion.
38
+ ## Client
143
39
 
144
- ```typescript
145
- const subscribe = new Subscribe(
146
- client.nextClientRequestId,
147
- trackAlias, // Numeric alias for the track
148
- fullTrackName, // Full track name
149
- subscriberId, // Your subscriber ID
150
- startGroup, // Starting group ID (or null for latest)
151
- startObject, // Starting object ID (or null for latest)
152
- endGroup, // Ending group ID (or null for ongoing)
153
- endObject, // Ending object ID (or null for group end)
154
- authInfo, // Authorization information
155
- )
40
+ Each request resolves to its result or to a `RequestError`; the objects come as a `ReadableStream`. Listeners attached before `init()` see the SETUP exchange too.
156
41
 
157
- const result = await client.subscribe(subscribe)
42
+ ```ts
43
+ import { MOQtailClient, FullTrackName, GroupOrder, LocationFilter, LocationFilterType, RequestError } from 'moqtail'
158
44
 
159
- if (result instanceof RequestError) {
160
- console.error(`Subscription failed: ${result.reasonPhrase}`)
161
- // Handle error based on error code
162
- switch (result.errorCode) {
163
- case RequestErrorCode.InvalidRange:
164
- // Adjust range and retry
165
- break
166
- default:
167
- console.error(`Unknown error: ${result.reasonPhrase}`)
168
- }
169
- } else {
170
- // Success - result is ReadableStream<MoqtObject>
171
- const objectStream = result
172
- const reader = objectStream.getReader()
173
-
174
- try {
175
- while (true) {
176
- const { done, value: object } = await reader.read()
177
- if (done) break
178
-
179
- // Process each object
180
- console.log(`Received object ${object.objectId} from group ${object.groupId}`)
181
- processObject(object)
182
- }
183
- } finally {
184
- reader.releaseLock()
185
- }
186
- }
187
- ```
45
+ const client = new MOQtailClient({ url: 'moqt://relay.example.com' })
46
+ client.on('messagereceived', (msg) => console.log('←', msg))
47
+ client.on('sessionterminated', (reason) => console.log('session ended', reason))
48
+ await client.init()
188
49
 
189
- ### On-Demand Content Fetching
190
-
191
- For static or archived content, use `fetch()` which returns either a `ReadableStream<MoqtObject>` or a `RequestError`:
192
-
193
- #### Fetch Implementation
194
-
195
- Fetch operations are optimized for reliable delivery of static content:
196
-
197
- - **Single Stream**: All requested objects are delivered sequentially in a single stream
198
- - **Reliable Delivery**: Uses QUIC streams for guaranteed, ordered delivery
199
- - **No Cancellation**: All requested objects are delivered as they provide historical data
200
-
201
- ```typescript
202
- const fetch = new Fetch(
203
- client.nextClientRequestId,
204
- trackAlias,
205
- fullTrackName,
206
- subscriberId,
207
- startGroup, // Starting group ID
208
- startObject, // Starting object ID
209
- endGroup, // Ending group ID
210
- endObject, // Ending object ID
211
- authInfo,
212
- )
213
-
214
- const result = await client.fetch(fetch)
215
-
216
- if (result instanceof RequestError) {
217
- console.error(`Fetch failed: ${result.reasonPhrase}`)
218
- // Handle fetch error
219
- } else {
220
- // Success - result is ReadableStream<MoqtObject>
221
- const objectStream = result
222
- const reader = objectStream.getReader()
223
-
224
- try {
225
- while (true) {
226
- const { done, value: object } = await reader.read()
227
- if (done) break
228
-
229
- // Process fetched object
230
- processObject(object)
231
- }
232
- } finally {
233
- reader.releaseLock()
234
- }
235
- }
236
- ```
50
+ const sub = await client.subscribe({
51
+ fullTrackName: FullTrackName.tryNew('live/demo', 'video'),
52
+ priority: 128,
53
+ groupOrder: GroupOrder.Original,
54
+ locationFilter: new LocationFilter(LocationFilterType.NextObject),
55
+ })
56
+ if (sub instanceof RequestError) throw new Error(sub.reasonPhrase.phrase)
237
57
 
238
- ### Content Processing
239
-
240
- Once you have the stream, process each `MoqtObject` based on its status:
241
-
242
- ```typescript
243
- function processObject(object: MoqtObject) {
244
- // Check object status
245
- switch (object.objectStatus) {
246
- case ObjectStatus.Normal:
247
- // Regular data object with payload
248
- if (object.payload) {
249
- processData(object.payload)
250
- }
251
- break
252
- case ObjectStatus.EndOfGroup:
253
- // Marks the end of a group
254
- finalizeGroup(object.groupId)
255
- break
256
- case ObjectStatus.EndOfTrack:
257
- // Marks the end of the track
258
- finalizeTrack()
259
- break
260
- }
58
+ sub.done.then((publishDone) => console.log('subscription over', publishDone?.statusCode))
59
+ const reader = sub.stream.getReader()
60
+ for (let read = await reader.read(); !read.done; read = await reader.read()) {
61
+ console.log(read.value.location, read.value.payload?.byteLength)
261
62
  }
262
63
  ```
263
64
 
264
- ### Subscription Management
265
-
266
- #### Subscription Lifecycle
267
-
268
- ```typescript
269
- // Create and send subscription
270
- const subscribe = new Subscribe(/*...*/)
271
- const result = await client.subscribe(subscribe)
65
+ `fetch` reads objects already published. Its result carries the FETCH_OK, with the end location and the track properties:
272
66
 
273
- if (result instanceof RequestError) {
274
- console.error(`Subscription failed: ${result.reasonPhrase}`)
275
- } else {
276
- console.log('Subscription successful, processing stream...')
277
- // Process the stream as shown above
67
+ ```ts
68
+ const res = await client.fetch({
69
+ fullTrackName: FullTrackName.tryNew('live/demo', 'video'),
70
+ priority: 128,
71
+ groupOrder: GroupOrder.Original,
72
+ locationFilter: new LocationFilter(LocationFilterType.AbsoluteStartGroupEnd, 10n, 0n, 12n),
73
+ })
74
+ if (!(res instanceof RequestError)) {
75
+ console.log('ends at', res.fetchOk.endLocation)
76
+ const reader = res.stream.getReader()
77
+ for (let read = await reader.read(); !read.done; read = await reader.read()) console.log(read.value.location)
278
78
  }
279
-
280
- // Unsubscribe when done
281
- await client.unsubscribe(subscribeId)
282
79
  ```
283
80
 
284
- #### Subscription Updates
81
+ Publishing goes through `client.publishNamespace` and `client.publish`. [`apps/client-js`](../../apps/client-js) is a complete publisher.
285
82
 
286
- For live content, you can update the subscription range dynamically:
83
+ The client's events, attached with `client.on()`:
287
84
 
288
- ```typescript
289
- const subscribeUpdate = new SubscribeUpdate(
290
- subscribeId,
291
- startGroup, // New start group
292
- startObject, // New start object
293
- endGroup, // New end group (optional)
294
- endObject, // New end object (optional)
295
- subscriberPriority, // New priority (optional)
296
- )
85
+ - **Session**: `goaway` (the session is winding down, or a request moves to a new one), `sessionterminated` (once, with the reason).
86
+ - **Tracing**: `messagesent` and `messagereceived` for control messages, `datasent` and `datareceived` for stream headers and objects, `dataevent` for stream open, object and close with sizes only, `datagramsent` and `datagramreceived`, and `orderinggap` when an ordered request stops waiting for missing objects.
87
+ - **Answering the peer**: `forwardstatechange` (a track you publish may now send, or must stop), `namespacepublished`, `peerpublish` (the peer pushed a track, with its stream), `peerpublishdone`, `peerpublishskipped`, `peersubscribenamespace`, `peersubscribetracks`, `peernamespace` and `peernamespacedone`.
297
88
 
298
- await client.subscribeUpdate(subscribeUpdate)
299
- ```
89
+ ## `<moqtail-video>`
300
90
 
301
- ### Complete Subscriber Example
302
-
303
- ```typescript
304
- import { MOQtailClient } from './client/client'
305
- import { PullPlayoutBuffer } from './util/pull_playout_buffer'
306
-
307
- async function createSubscriber() {
308
- // Initialize client
309
- const client = await MOQtailClient.new(clientSetup, webTransport)
310
-
311
- // Subscribe to live video
312
- const subscribe = new Subscribe(
313
- client.nextClientRequestId,
314
- 1n, // trackAlias
315
- FullTrackName.tryNew('live/conference', 'video'),
316
- generateSubscriberId(),
317
- null,
318
- null, // Latest content
319
- null,
320
- null, // Ongoing
321
- null, // No auth
322
- )
323
-
324
- const result = await client.subscribe(subscribe)
325
-
326
- if (result instanceof RequestError) {
327
- console.error(`Failed to subscribe: ${result.reasonPhrase}`)
328
- return
329
- }
91
+ The mostly hands-off option, built on the player described below. It's a `<video>` that takes a `moqt://` URL, builds the player chain itself, and installs the default plugins: the buffer controller (`liveBuffer()`) and the ABR controller (`abr()`). Listing plugins in `config.plugins` replaces them, so leave one out of the list to play without it.
330
92
 
331
- // Set up playout buffer with the stream
332
- const playoutBuffer = new PullPlayoutBuffer(result, {
333
- bucketCapacity: 50,
334
- targetLatencyMs: 500,
335
- maxLatencyMs: 2000,
336
- })
337
-
338
- // Consumer-driven playout
339
- const playoutLoop = () => {
340
- playoutBuffer.nextObject((nextObject) => {
341
- if (nextObject) {
342
- // Decode and render the frame
343
- decodeAndRender(nextObject)
344
- }
345
- requestAnimationFrame(playoutLoop)
346
- })
347
- }
93
+ It needs two optional peer dependencies: `npm install custom-media-element media-tracks`.
348
94
 
349
- // Start playout
350
- requestAnimationFrame(playoutLoop)
95
+ ```ts
96
+ import { defineMOQtailVideo } from 'moqtail/player/component'
351
97
 
352
- return client
353
- }
98
+ defineMOQtailVideo()
354
99
  ```
355
100
 
356
- ### Other Client Operations
357
-
358
- The MOQtail client supports additional operations for track discovery and status management:
359
-
360
- #### PublishNamespace Operations
361
-
362
- Publishers use announce operations to make their tracks discoverable:
363
-
364
- ```typescript
365
- // PublishNamespace a namespace
366
- const announce = new PublishNamespace(
367
- client.nextClientRequestId,
368
- Tuple.tryNew(['live', 'conference']), // Track namespace
369
- )
370
-
371
- const result = await client.publishNamespace(announce)
372
- if (result instanceof PublishNamespaceError) {
373
- console.error(`Publishing the namespace failed: ${result.reasonPhrase}`)
374
- } else {
375
- console.log('Namespace published successfully')
376
- }
377
-
378
- // Stop announcing a namespace: draft-18 has no PUBLISH_NAMESPACE_DONE, so this closes
379
- // the stream the PUBLISH_NAMESPACE opened (§3.3.2)
380
- await client.unpublishNamespace(Tuple.tryNew(['live', 'conference']))
101
+ ```html
102
+ <moqtail-video src="moqt://relay.moqtail.dev#msf:moqtail-ch00--catalog" autoplay muted playsinline></moqtail-video>
381
103
  ```
382
104
 
383
- #### Subscribe to Announcements
105
+ `video.config = { catalogTimeoutMs: 5000 }` passes player options, read on each load. The `switch-from` attribute switches tracks with SWITCH_FROM instead of a new subscription. It fires the usual media events plus `streamtypechange`, lists renditions in `videoRenditions` and `audioRenditions` (no `selected` rendition is automatic switching, which needs a source that provides `ABR`, such as `ssts()`; otherwise the active one shows selected), and `video.player` is the `MOQtailPlayer` behind it, for the events below. [`apps/client-js`](../../apps/client-js/src/lib/videojs.ts) wraps the element in a Video.js v10 skin.
384
106
 
385
- Subscribers can discover available tracks by subscribing to announcements:
107
+ ## Player
386
108
 
387
- ```typescript
388
- // Subscribe to announcements for a namespace prefix
389
- const subscribeNamespace = new SubscribeNamespace(
390
- Tuple.tryNew(['live']), // Namespace prefix
391
- )
392
- await client.subscribeNamespace(subscribeNamespace)
109
+ For more control. `MOQtailPlayer` installs no plugins, so list the buffer controller yourself.
393
110
 
394
- // The client will now receive announce messages for tracks
395
- // matching the 'live' prefix through its announcement handling
111
+ ```ts
112
+ import { MOQtailPlayer, PlayerError, liveBuffer } from 'moqtail/player'
396
113
 
397
- // Stop subscribing to announcements: likewise no UNSUBSCRIBE_NAMESPACE, the
398
- // SUBSCRIBE_NAMESPACE stream is simply closed
399
- await client.unsubscribeNamespace(Tuple.tryNew(['live']))
400
- ```
401
-
402
- #### Track Status Requests
403
-
404
- Query the status of specific tracks:
114
+ const video = document.querySelector('video')!
115
+ const player = new MOQtailPlayer({ plugins: [liveBuffer({ targetLatency: 2 })] })
116
+ .source('moqt://relay.moqtail.dev#msf:moqtail-ch07_vod--catalog')
117
+ .sink(video)
405
118
 
406
- ```typescript
407
- const trackStatus = new TrackStatusMessage(client.nextClientRequestId, FullTrackName.tryNew('live/conference', 'video'))
119
+ player.on('statechange', (state) => console.log(state))
120
+ player.on('error', (error: PlayerError) => console.error(error.code, error.category, error.message))
408
121
 
409
- const result = await client.trackStatus(trackStatus)
410
- if (result instanceof RequestError) {
411
- console.error(`Track status request failed: ${result.reasonPhrase}`)
412
- } else {
413
- // result is TrackStatus
414
- console.log(`Track status: ${result.statusCode}`)
415
- console.log(`Last group: ${result.lastGroup}`)
416
- console.log(`Last object: ${result.lastObject}`)
417
- }
122
+ await player.init()
123
+ await player.play()
124
+ await player.seek(30)
418
125
  ```
419
126
 
420
- #### Observing Control Messages
127
+ ### From `source()` To Playing
421
128
 
422
- `onMessageSent` and `onMessageReceived` report every control message the client sends or receives, which is useful for logging, debugging, or building a message inspector. They cover both the control stream (SETUP, GOAWAY) and the bidirectional request streams that carry SUBSCRIBE, PUBLISH, FETCH, the namespace messages, and their replies.
129
+ The builder calls go `registerElement()`, `source()`, `transform()`, `sink()`, all before `init()`; anything else is a `TypeError`. `source()` takes an MSF URL, `moqt://authority/path#msf:<namespace>--<track>`, for a catalog or a single track. It throws `PlayerError` right away for a URL it can't use, such as another origin than an earlier `source()`.
423
130
 
424
- Pass them when connecting so the SETUP exchange is reported as well:
131
+ The constructor already ran each plugin's `init` and `setup`, so their SETUP parameters are known. `init()` then:
425
132
 
426
- ```typescript
427
- const client = await MOQtailClient.new({
428
- url: 'moqt://relay.example.com:4433',
429
- callbacks: {
430
- onMessageSent: (msg) => console.log('→', ControlMessageType[msg.getType()], msg),
431
- onMessageReceived: (msg) => console.log('←', ControlMessageType[msg.getType()], msg),
432
- },
433
- })
434
- ```
133
+ 1. Connects. Players with the same origin and setup share one client and its reconnects.
134
+ 2. Keeps the plugins the relay's SERVER_SETUP accepts. The others contribute nothing.
135
+ 3. Picks an element for each `source()` (see [Element selection](#element-selection)). A track no element accepts rejects `init()` with `UNSUPPORTED_SOURCE`.
136
+ 4. Starts the sources. The catalog element reads the catalog, picks an element for every switching set and timeline the same way, and loads it. A switching set goes through a plugin's switch source when one accepts it, such as SSTS.
137
+ 5. Routes each new source pad by capability: to the first transform that accepts it, otherwise to every sink that does.
138
+ 6. Once every top-level source says it has all its pads (`nomorepads`), tells the sinks, and resolves when they're ready. The state is then `ready`, or `ended` when there's nothing to play.
435
139
 
436
- The callbacks can also be assigned to `client.onMessageSent` and `client.onMessageReceived` after connecting. Request streams pick up the change straight away, but the control stream keeps the callbacks it was given at connect time.
140
+ After that, `play()`, `pause()`, `seek()` and `setPlaybackRate()` go to the media sink, and the state follows its `<video>`: `idle`, `connecting`, `ready`, then `playing`, `paused`, `stalled` or `ended`. A lost session moves to `reconnecting` and back to where it was. `error` and `destroyed` are final. `player.destroy()` tears the chain down in any state.
437
141
 
438
- A message is reported once it has been written to its stream, or once it has been fully decoded on arrival.
142
+ ### Player Events
439
143
 
440
- #### Observing Data Streams
144
+ Attached with `player.on()`:
441
145
 
442
- `onDataEvent` reports every data stream the client opens (`direction: 'out'`) or accepts (`direction: 'in'`) as small records, which is enough to count streams, groups, subgroups, objects and bytes without touching payloads:
443
-
444
- - `header`: once per stream when it opens. Subgroup streams carry the track alias and group and subgroup IDs; fetch streams carry the request ID. Both include the track name when the client knows it.
445
- - `object`: once per object, with its group, subgroup and object IDs, its payload length, its status if it has one, and its LOC Timestamp property (`locTimestamp`) if it carries one.
446
- - `end`: once per stream, with `reason` set to `'fin'`, `'reset'` (plus `resetCode`) or `'error'`.
447
-
448
- Every record carries a `streamId`, so objects can be tied back to the header of the stream they arrived on, and `at`, the local time it was written or read as `performance.now()`. Differences in `at` give interarrival times and jitter; comparing `performance.timeOrigin + at` with a sender's `locTimestamp` gives latency, provided both ends agree on the timestamp's unit and their clocks are in sync.
449
-
450
- ```typescript
451
- const client = await MOQtailClient.new({
452
- url: 'moqt://relay.example.com:4433',
453
- callbacks: {
454
- onDataEvent: (event) => {
455
- if (event.kind === 'object') bytesByDirection[event.direction] += event.payloadLength
456
- },
457
- },
458
- })
459
- ```
146
+ - **Playback**: `statechange` (new and previous state), `playing`, `pause`, `stalled`, `ended`, `autoplayblocked` (a `play()` the browser refused; the player is `paused`).
147
+ - **Session**: `client` (the connected client, again after every reconnect), `reconnecting` (with the attempt number), `reconnected`.
148
+ - **Content**: `catalog` (the catalog element, after the first catalog and each applied update), `renditionchange` (a source switched rendition), `selectionchange` (a source's selected renditions were set), `streamtypechange` (`live` or `on-demand`), `timelineevent` (records of the event timelines listed in `eventTimelines`).
149
+ - **Problems**: `error` is fatal and moves to `error`; `warning` isn't, such as a pad no element took (`PAD_UNLINKED`) or a catalog track that was skipped (`TRACK_SKIPPED`). Both carry a `PlayerError` with a `code`, a `category` (`source`, `network`, `media` or `aborted`) and the `element` it came from.
460
150
 
461
- The callback runs for every object, so keep it cheap: update counters there and render them on a timer.
151
+ `player.mediaSources` are the sources playing media: `getRenditions()` lists their renditions, `switch(id)` changes one, and `selectRenditions(ids)` sets those ABR may choose from. `player.isAbrAvailable(source)` says whether a source switches automatically, by itself (`ABR`) or through an ABR controller.
462
152
 
463
- ## Utilities
153
+ ## Element Selection
464
154
 
465
- The MOQtail library provides several utility classes to help with common streaming scenarios:
155
+ The player is a chain of elements joined by pads. Each element definition says what it is (`source`, `transform` or `sink`), the pads it creates (`out` capabilities) and the pads it accepts (`in` capabilities). A source definition also has a `probe` that says whether it handles a track.
466
156
 
467
- ### Playout Buffer
157
+ For every track, the top-level one from the URL and every one the catalog lists, the candidates are, in order: the definitions passed to `registerElement()`, then the active plugins' elements (by plugin `priority`, then list order), then the built-in ones (catalog, CMAF, media timeline, SAP timeline). Among the candidates whose probe accepts the track, the lowest `priority` wins (default 100), then the earlier one. So yours wins a tie with a plugin's, and both win a tie with a built-in one.
468
158
 
469
- The `PullPlayoutBuffer` provides consumer-driven playout with GOP-aware buffering for smooth media playback:
159
+ A source the probe picks can be your own:
470
160
 
471
- ```typescript
472
- import { PullPlayoutBuffer } from './util/pull_playout_buffer'
161
+ ```ts
162
+ import { CapabilityCode, MOQtailPlayer, SourceElement, defineElement } from 'moqtail/player'
473
163
 
474
- const playoutBuffer = new PullPlayoutBuffer(objectStream, {
475
- bucketCapacity: 50, // Max objects in buffer (default: 50)
476
- targetLatencyMs: 500, // Target latency in ms (default: 500)
477
- maxLatencyMs: 2000, // Max latency before dropping GOPs (default: 2000)
478
- })
164
+ class LocSource extends SourceElement {
165
+ // createPad('src', capabilities), write packets to it, then emit 'nomorepads'
166
+ }
479
167
 
480
- // Consumer-driven object retrieval
481
- playoutBuffer.nextObject((nextObject) => {
482
- if (nextObject) {
483
- // Process the object (decode, render, etc.)
484
- processFrame(nextObject)
485
- }
168
+ const locSource = defineElement({
169
+ type: 'source',
170
+ name: 'loc-source',
171
+ capabilities: [[{ direction: 'out', code: CapabilityCode.PACKAGING, value: 'loc' }]],
172
+ probe: (track) => track.packaging === 'loc',
173
+ init: async (context) => new LocSource(context),
486
174
  })
487
175
 
488
- // Check buffer status
489
- const status = playoutBuffer.getStatus()
490
- console.log(`Buffer size: ${status.bufferSize}, Running: ${status.isRunning}`)
176
+ new MOQtailPlayer().registerElement(locSource)
491
177
  ```
492
178
 
493
- **Key Features:**
179
+ Its pads still need a transform or sink whose `in` capabilities match them, or the player warns `PAD_UNLINKED`.
494
180
 
495
- - **GOP-Aware**: Automatically detects and manages Group of Pictures boundaries
496
- - **Smart Eviction**: Drops entire GOPs when buffer is full to maintain decodable content
497
- - **Consumer-Driven**: Pull-based API eliminates rate guessing and provides natural backpressure
498
- - **Latency Management**: Automatically manages buffer size to maintain target latency
181
+ ## Plugins
499
182
 
500
- ### Network Telemetry
183
+ A plugin bundles features with the SETUP parameters they need, so a protocol extension or a controller is one entry in `plugins`. Its hooks are optional and run in this order:
501
184
 
502
- The `NetworkTelemetry` class provides real-time network performance monitoring:
185
+ 1. `init(config)`, once per player in the constructor. Its config type is what the plugin's factory takes.
186
+ 2. `setup(ctx, clientSetup)`, also in the constructor, adds SETUP parameters; returning false drops the plugin. Two plugins setting one parameter to different values throw `UNSUPPORTED_ORIGIN`.
187
+ 3. `negotiated(ctx, serverSetup)`, after the relay's SERVER_SETUP; returning false leaves the plugin inactive, its features unused.
188
+ 4. `features(ctx)` lists what it offers:
189
+ - `element`: a candidate for [element selection](#element-selection).
190
+ - `switch-source`: wraps the source of each media switching set it accepts, ranked like elements.
191
+ - `buffer-controller`: only the first active one is used. The player attaches it while a negotiated stream is `live` and detaches it otherwise.
192
+ - `abr-controller`: only the first active one is used. The player attaches it like the buffer controller, except while a media source provides `ABR` (switches itself, as `ssts()` sources do) or a rendition is picked manually (one of several selected).
503
193
 
504
- ```typescript
505
- import { NetworkTelemetry } from './util/telemetry'
194
+ `ssts()` (sender-side track switching), `liveBuffer()` and `abr()` are built in. `liveBuffer()` and `abr()` have priority `Infinity`, so any other buffer or ABR controller wins over them. For now `abr()` keeps the current quality.
506
195
 
507
- const telemetry = new NetworkTelemetry(1000) // 1-second sliding window
196
+ ```ts
197
+ import { MOQtailPlayer, definePlugin, liveBuffer, ssts } from 'moqtail/player'
508
198
 
509
- // Report network events
510
- telemetry.push({
511
- latency: 50, // Round-trip time in ms
512
- size: 1024, // Bytes transferred
199
+ const loc = definePlugin({
200
+ name: 'loc',
201
+ features: () => [{ type: 'element', item: locSource }],
513
202
  })
514
203
 
515
- // Get current metrics
516
- console.log(`Throughput: ${telemetry.throughput} bytes/sec`)
517
- console.log(`Average latency: ${telemetry.latency} ms`)
204
+ new MOQtailPlayer({ plugins: [ssts({ algorithms: [0xff01n, 0n] }), loc(), liveBuffer()] })
518
205
  ```
519
206
 
520
- **Use Cases:**
207
+ Plugin code reaches the player through what it's handed. An element's `context.player` has the player's events and options, and `context.client` is the current client; it changes after a reconnect, so listen again on the player's `client` event. A buffer controller gets the player and the media sink in `attach()`:
521
208
 
522
- - Adaptive bitrate streaming decisions
523
- - Network condition monitoring
524
- - Performance debugging and optimization
525
- - Quality of service reporting
209
+ ```ts
210
+ import { definePlugin, type BufferController, type MOQtailPlayer } from 'moqtail/player'
526
211
 
527
- ### Clock Synchronization
212
+ class StallLogger implements BufferController {
213
+ #player: MOQtailPlayer | undefined
214
+ readonly #onStalled = () => console.log('stalled')
528
215
 
529
- The `ClockNormalizer` utility provides clock synchronization with a given time service:
530
-
531
- ```typescript
532
- import { ClockNormalizer } from './util/clock_normalizer'
216
+ attach(player: MOQtailPlayer): void {
217
+ this.#player = player
218
+ player.on('stalled', this.#onStalled)
219
+ }
533
220
 
534
- // Get clock skew relative to a given time server
535
- const numSamples = 5 // default is 5
536
- const timeServerUrl = 'https://time.akamai.com/?ms'
537
- const offset = await ClockNormalizer.calculateSkew(timeServerUrl, numSamples)
538
- const clockNormalizer = new ClockNormalizer(timeServerUrl, offset, numSamples)
539
- console.log(`Local clock is ${offset}ms ahead of network time`)
221
+ detach(): void {
222
+ this.#player?.off('stalled', this.#onStalled)
223
+ }
224
+ }
540
225
 
541
- // Adjust local timestamps for network synchronization
542
- const networkTime = Date.now() - offset
226
+ const stallLogger = definePlugin({
227
+ name: 'stall-logger',
228
+ features: () => [{ type: 'buffer-controller', item: new StallLogger() }],
229
+ })
543
230
  ```
544
231
 
545
- **Features:**
546
-
547
- - **Network Time Synchronization**: Aligns local time with network time servers
548
- - **RTT Compensation**: Accounts for round-trip time in synchronization calculations
549
- - **Cached Results**: Subsequent calls return cached offset for performance
550
- - **Media Synchronization**: Essential for multi-source media synchronization
551
-
552
- These utilities work together to provide a robust foundation for real-time media streaming applications, handling the complex aspects of buffering, network monitoring, and time synchronization.
232
+ DeepWiki explains the pad model, negotiation, the catalog, each built-in element, and the interfaces elements can provide.