feat(spf): send SUBSCRIBER_PRIORITY by track kind on MoQ media subscribes
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_PRIORITYintrack-subscriber.tsholds{ audio: 16, video: 96 }. The actor picks the value from the track's catalog kind (track.type), not its name.track-subscriberis 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
subscriberPriorityinCreateTrackSubscriberOptions.parametersreplaces 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-trackswith 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_streampublisher and thespf-moq-playersandbox 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-publisherssets 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.