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.
- package/README.md +153 -473
- package/dist/{client-BviQ20Lc.cjs → client-DQ5aGbLR.cjs} +1089 -1074
- package/dist/client-DUzLw_Y8.d.cts +1932 -0
- package/dist/{client-zi0lmuIL.mjs → client-DVi4Nh1J.mjs} +930 -921
- package/dist/client-epHqMdHm.d.mts +1932 -0
- package/dist/client.cjs +121 -4
- package/dist/client.d.cts +23 -1944
- package/dist/client.d.mts +23 -1944
- package/dist/client.mjs +117 -2
- package/dist/emitter-UbeRcbuf.mjs +109 -0
- package/dist/{logger-c2NoQqtx.cjs → emitter-qNJYD3yQ.cjs} +61 -2
- package/dist/index-B-BMK-b6.d.mts +2090 -0
- package/dist/index-BtemTtwe.d.cts +2090 -0
- package/dist/{index-BY6e1obL.d.cts → index-CNn9BgO6.d.mts} +119 -324
- package/dist/index.cjs +38 -34
- package/dist/index.d.cts +20 -4
- package/dist/index.d.mts +20 -4
- package/dist/index.mjs +5 -4
- package/dist/logger-B8IYkljn.d.cts +64 -0
- package/dist/logger-B8IYkljn.d.mts +64 -0
- package/dist/model.cjs +122 -340
- package/dist/model.d.cts +2896 -2
- package/dist/model.d.mts +17 -2
- package/dist/model.mjs +122 -340
- package/dist/player/component.cjs +317 -0
- package/dist/player/component.d.cts +50 -0
- package/dist/player/component.d.mts +50 -0
- package/dist/player/component.mjs +315 -0
- package/dist/player-CJayEzwt.cjs +6750 -0
- package/dist/player-DcctWhyM.mjs +6599 -0
- package/dist/player.cjs +27 -0
- package/dist/player.d.cts +17 -0
- package/dist/player.d.mts +17 -0
- package/dist/player.mjs +1 -0
- package/dist/rolldown-runtime-CmQyd0Gu.cjs +27 -0
- package/dist/util.cjs +9 -10
- package/dist/util.d.cts +20 -13
- package/dist/util.d.mts +20 -13
- package/dist/util.mjs +4 -6
- package/package.json +45 -5
- package/dist/index-BY6e1obL.d.mts +0 -3087
- package/dist/logger-ByDB8lYF.mjs +0 -56
- package/dist/logger-dEoueCj7.d.cts +0 -35
- package/dist/logger-dEoueCj7.d.mts +0 -35
package/README.md
CHANGED
|
@@ -1,552 +1,232 @@
|
|
|
1
|
-
#
|
|
1
|
+
# moqtail
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A TypeScript MOQT client and an MSF/CMSF player for the browser.
|
|
4
4
|
|
|
5
|
-
|
|
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
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
-
|
|
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
|
-
|
|
20
|
+
## How It Fits Together
|
|
69
21
|
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
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
|
|
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
|
-
|
|
34
|
+
## MOQT In Short
|
|
135
35
|
|
|
136
|
-
|
|
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
|
-
|
|
38
|
+
## Client
|
|
143
39
|
|
|
144
|
-
|
|
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
|
-
|
|
42
|
+
```ts
|
|
43
|
+
import { MOQtailClient, FullTrackName, GroupOrder, LocationFilter, LocationFilterType, RequestError } from 'moqtail'
|
|
158
44
|
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
190
|
-
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
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
|
-
|
|
239
|
-
|
|
240
|
-
|
|
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
|
-
|
|
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
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
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
|
-
|
|
81
|
+
Publishing goes through `client.publishNamespace` and `client.publish`. [`apps/client-js`](../../apps/client-js) is a complete publisher.
|
|
285
82
|
|
|
286
|
-
|
|
83
|
+
The client's events, attached with `client.on()`:
|
|
287
84
|
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
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
|
-
|
|
299
|
-
```
|
|
89
|
+
## `<moqtail-video>`
|
|
300
90
|
|
|
301
|
-
|
|
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
|
-
|
|
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
|
-
|
|
350
|
-
|
|
95
|
+
```ts
|
|
96
|
+
import { defineMOQtailVideo } from 'moqtail/player/component'
|
|
351
97
|
|
|
352
|
-
|
|
353
|
-
}
|
|
98
|
+
defineMOQtailVideo()
|
|
354
99
|
```
|
|
355
100
|
|
|
356
|
-
|
|
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
|
-
|
|
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
|
-
|
|
107
|
+
## Player
|
|
386
108
|
|
|
387
|
-
|
|
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
|
-
|
|
395
|
-
|
|
111
|
+
```ts
|
|
112
|
+
import { MOQtailPlayer, PlayerError, liveBuffer } from 'moqtail/player'
|
|
396
113
|
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
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
|
-
|
|
407
|
-
|
|
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
|
-
|
|
410
|
-
|
|
411
|
-
|
|
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
|
-
|
|
127
|
+
### From `source()` To Playing
|
|
421
128
|
|
|
422
|
-
|
|
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
|
-
|
|
131
|
+
The constructor already ran each plugin's `init` and `setup`, so their SETUP parameters are known. `init()` then:
|
|
425
132
|
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
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
|
-
|
|
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
|
-
|
|
142
|
+
### Player Events
|
|
439
143
|
|
|
440
|
-
|
|
144
|
+
Attached with `player.on()`:
|
|
441
145
|
|
|
442
|
-
`
|
|
443
|
-
|
|
444
|
-
- `
|
|
445
|
-
- `
|
|
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
|
-
|
|
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
|
-
##
|
|
153
|
+
## Element Selection
|
|
464
154
|
|
|
465
|
-
The
|
|
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
|
-
|
|
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
|
-
|
|
159
|
+
A source the probe picks can be your own:
|
|
470
160
|
|
|
471
|
-
```
|
|
472
|
-
import {
|
|
161
|
+
```ts
|
|
162
|
+
import { CapabilityCode, MOQtailPlayer, SourceElement, defineElement } from 'moqtail/player'
|
|
473
163
|
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
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
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
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
|
-
|
|
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
|
-
|
|
179
|
+
Its pads still need a transform or sink whose `in` capabilities match them, or the player warns `PAD_UNLINKED`.
|
|
494
180
|
|
|
495
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
196
|
+
```ts
|
|
197
|
+
import { MOQtailPlayer, definePlugin, liveBuffer, ssts } from 'moqtail/player'
|
|
508
198
|
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
size: 1024, // Bytes transferred
|
|
199
|
+
const loc = definePlugin({
|
|
200
|
+
name: 'loc',
|
|
201
|
+
features: () => [{ type: 'element', item: locSource }],
|
|
513
202
|
})
|
|
514
203
|
|
|
515
|
-
|
|
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
|
-
|
|
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
|
-
|
|
523
|
-
|
|
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
|
-
|
|
212
|
+
class StallLogger implements BufferController {
|
|
213
|
+
#player: MOQtailPlayer | undefined
|
|
214
|
+
readonly #onStalled = () => console.log('stalled')
|
|
528
215
|
|
|
529
|
-
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
216
|
+
attach(player: MOQtailPlayer): void {
|
|
217
|
+
this.#player = player
|
|
218
|
+
player.on('stalled', this.#onStalled)
|
|
219
|
+
}
|
|
533
220
|
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
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
|
-
|
|
542
|
-
|
|
226
|
+
const stallLogger = definePlugin({
|
|
227
|
+
name: 'stall-logger',
|
|
228
|
+
features: () => [{ type: 'buffer-controller', item: new StallLogger() }],
|
|
229
|
+
})
|
|
543
230
|
```
|
|
544
231
|
|
|
545
|
-
|
|
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.
|