feat(spf): send SUBSCRIBER_PRIORITY by track kind on MoQ media subscribes

Merged
MM
25d ago
+159-5

Closes #68.

The MoQ player's media SUBSCRIBEs now carry SUBSCRIBER_PRIORITY: 16 for audio and 96 for video, so a congested relay-to-viewer downlink sends audio first. moq-relay 0.17 orders a viewer's downlink by subscriber priority alone and ignores the publisher's 0x0E (muxinc/relay-sdks#154). On that relay any REQUEST_UPDATE ends the subscription, so the priority has to go on the SUBSCRIBE. The values match the relay SDKs' mediaSubscribeParameters (muxinc/relay-sdks#337, #343), which measured audio p99 at 74-76 ms with these priorities and 253-259 ms without, on ord behind an 800 kbit/s cap.

What changed

  • MEDIA_SUBSCRIBER_PRIORITY in track-subscriber.ts holds { audio: 16, video: 96 }. The actor picks the value from the track's catalog kind (track.type), not its name.
  • track-subscriber is the only place that builds a media SUBSCRIBE, so the initial join, ABR/layer-switch handoffs, dead-subscription rejoins and suspend/resume rejoins all get the priority. The auth-refresh resubscribe keeps it too.
  • Override: a subscriberPriority in CreateTrackSubscriberOptions.parameters replaces the default. That option is already documented as "auth tokens, priority". No new public player API.
  • The catalog subscription and text tracks still send no priority, so the relay uses its default. The catalog is fetched before any media subscription exists and later updates are rare and small, so I found no concrete reason to change it.

Verification

  • New tests check the SUBSCRIBE parameters for audio and video by catalog kind (including a track named against its kind), the override, the auth-refresh resubscribe, and, through subscribe-selected-tracks with real subscribers, an ABR switch HD→SD plus a rejoin of the handoff target, and an audio rejoin after PUBLISH_DONE.
  • pnpm -F @videojs/spf test (2429 passed), pnpm lint, pnpm typecheck.
  • Live on ord.relay.mux.global, with the relay-sdks Python videojs_stream publisher and the spf-moq-player sandbox in headless Chromium. Decoding the page's WebTransport writes with the player's own parameter decoder gave:
{"requestId":0,"track":"catalog","locationFilter":{"type":"relative-group","groupsBeforeNext":1}}
{"requestId":2,"track":"video","subscriberPriority":96,"locationFilter":{"type":"relative-group","groupsBeforeNext":0}}
{"requestId":4,"track":"audio","subscriberPriority":16,"locationFilter":{"type":"next-object"}}

The relay accepted both subscriptions and playback started.

Notes

  • Publisher side, not changed here: this branch has no publisher. On mmcc/moq-publisher, setup-track-publishers sets a per-subgroup-header publisher priority (catalog 0, audio 64, camera 128, screen 192) and does not send the 0x0E Default Publisher Priority track property with the SDK values (audio 16 / video 96). moq-relay 0.17 ignores both for viewer ordering anyway.

🤖 Generated with Claude Code


Summary by cubic

Media SUBSCRIBEs now carry SUBSCRIBER_PRIORITY chosen by track kind — 16 for audio, 96 for video — so audio stays ahead of video on a congested relay-to-viewer downlink. moq-relay 0.17 orders by subscriber priority alone, so this value rides every media SUBSCRIBE: initial join, ABR/layer-switch handoffs, dead-subscription and suspend/resume rejoins, and the auth-refresh resubscribe. The values match the relay SDKs' mediaSubscribeParameters.

The priority comes from MEDIA_SUBSCRIBER_PRIORITY in track-subscriber.ts, selected by track.type, and can be overridden with subscriberPriority in CreateTrackSubscriberOptions.parameters. refreshAuth only supplies fresh auth: the resubscribe keeps the original subscriberPriority and location whatever it returns. Catalog and text track subscribes send no priority and leave the peer's default.