moqtail 0.12.1 → 0.14.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 CHANGED
@@ -71,7 +71,7 @@ All content is packaged as `MoqtObject` instances, which represent the atomic un
71
71
 
72
72
  - **Location**: Identified by `groupId` and `objectId` (e.g., video frames within GOPs)
73
73
  - **Payload**: The actual media data or content
74
- - **Metadata**: Publisher priority, forwarding preferences, and extension headers
74
+ - **Metadata**: Publisher priority, forwarding preferences, and properties
75
75
  - **Status**: Normal data, end-of-group markers, or error conditions
76
76
 
77
77
  ### Object Caching
@@ -375,9 +375,9 @@ if (result instanceof PublishNamespaceError) {
375
375
  console.log('Namespace published successfully')
376
376
  }
377
377
 
378
- // Stop announcing a namespace
379
- const publish_namespace_done = new publishNamespaceDone(Tuple.tryNew(['live', 'conference']))
380
- await client.publishNamespaceDone(publish_namespace_done)
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']))
381
381
  ```
382
382
 
383
383
  #### Subscribe to Announcements
@@ -394,9 +394,9 @@ await client.subscribeNamespace(subscribeNamespace)
394
394
  // The client will now receive announce messages for tracks
395
395
  // matching the 'live' prefix through its announcement handling
396
396
 
397
- // Stop subscribing to announcements
398
- const unsubscribeNamespace = new UnsubscribeNamespace(Tuple.tryNew(['live']))
399
- await client.unsubscribeNamespace(unsubscribeNamespace)
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
400
  ```
401
401
 
402
402
  #### Track Status Requests
@@ -417,6 +417,49 @@ if (result instanceof RequestError) {
417
417
  }
418
418
  ```
419
419
 
420
+ #### Observing Control Messages
421
+
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.
423
+
424
+ Pass them when connecting so the SETUP exchange is reported as well:
425
+
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
+ ```
435
+
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.
437
+
438
+ A message is reported once it has been written to its stream, or once it has been fully decoded on arrival.
439
+
440
+ #### Observing Data Streams
441
+
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
+ ```
460
+
461
+ The callback runs for every object, so keep it cheap: update counters there and render them on a timer.
462
+
420
463
  ## Utilities
421
464
 
422
465
  The MOQtail library provides several utility classes to help with common streaming scenarios: