diff --git a/packages/spf/src/playback/actors/tests/track-subscriber.test.ts b/packages/spf/src/playback/actors/tests/track-subscriber.test.ts index 43e9f698c9..e8c729cf2d 100644 --- a/packages/spf/src/playback/actors/tests/track-subscriber.test.ts +++ b/packages/spf/src/playback/actors/tests/track-subscriber.test.ts @@ -4,7 +4,7 @@ import type { MoqTrack } from '../../../media/moq/parse-catalog'; import { PUBLISH_DONE_STATUS, REQUEST_ERROR_CODE } from '../../../network/moqt/control-messages'; import type { MoqtObject } from '../../../network/moqt/object-stream'; import type { MoqtSession, SubscriptionHandlers } from '../../../network/moqt/session'; -import { createTrackSubscriberActor, DEFAULT_STALL_TIMEOUT_MS } from '../track-subscriber'; +import { createTrackSubscriberActor, DEFAULT_STALL_TIMEOUT_MS, MEDIA_SUBSCRIBER_PRIORITY } from '../track-subscriber'; // ============================================================================ // Fakes @@ -93,6 +93,58 @@ describe('createTrackSubscriberActor', () => { expect(subscriptions[0]!.cancelled).toBe(true); }); + it.each([ + { type: 'audio', priority: MEDIA_SUBSCRIBER_PRIORITY.audio }, + { type: 'video', priority: MEDIA_SUBSCRIBER_PRIORITY.video }, + ] as const)('sends the $type SUBSCRIBER_PRIORITY chosen by the catalog kind', ({ type, priority }) => { + const { session, subscriptions } = createFakeSession(); + // Named against its kind: the priority must follow the catalog type, not the track name. + const track = { ...TRACK, type, moq: { ...TRACK.moq, name: type === 'audio' ? 'video' : 'audio' } } as MoqTrack; + const subscriber = createTrackSubscriberActor({ session, track }); + + expect(subscriptions[0]!.options.parameters).toMatchObject({ subscriberPriority: priority }); + subscriber.destroy(); + }); + + it('puts audio ahead of video', () => { + expect(MEDIA_SUBSCRIBER_PRIORITY).toEqual({ audio: 16, video: 96 }); + }); + + it('sends no SUBSCRIBER_PRIORITY for a kind without a default', () => { + const { session, subscriptions } = createFakeSession(); + const subscriber = createTrackSubscriberActor({ session, track: { ...TRACK, type: 'text' } as MoqTrack }); + + expect(subscriptions[0]!.options.parameters).toMatchObject({ subscriberPriority: undefined }); + subscriber.destroy(); + }); + + it('lets a caller-supplied subscriberPriority replace the kind default', () => { + const { session, subscriptions } = createFakeSession(); + const subscriber = createTrackSubscriberActor({ session, track: TRACK, parameters: { subscriberPriority: 3 } }); + + expect(subscriptions[0]!.options.parameters).toMatchObject({ subscriberPriority: 3 }); + subscriber.destroy(); + }); + + it('keeps the SUBSCRIBER_PRIORITY on the auth-refresh resubscribe', async () => { + const { session, subscriptions } = createFakeSession(); + const subscriber = createTrackSubscriberActor({ + session, + track: { ...TRACK, type: 'audio' } as MoqTrack, + refreshAuth: async () => ({ subscriberPriority: undefined }), + }); + + subscriptions[0]!.handlers.onError?.({ + errorCode: REQUEST_ERROR_CODE.EXPIRED_AUTH_TOKEN, + retryInterval: 0, + reason: 'expired', + }); + await Promise.resolve(); + expect(subscriptions).toHaveLength(2); + expect(subscriptions[1]!.options.parameters).toMatchObject({ subscriberPriority: MEDIA_SUBSCRIBER_PRIORITY.audio }); + subscriber.destroy(); + }); + it.each([ { group: 41, object: 3 }, { group: 42, object: 0 }, diff --git a/packages/spf/src/playback/actors/track-subscriber.ts b/packages/spf/src/playback/actors/track-subscriber.ts index eb2bfda0ed..3c05161cf4 100644 --- a/packages/spf/src/playback/actors/track-subscriber.ts +++ b/packages/spf/src/playback/actors/track-subscriber.ts @@ -103,9 +103,15 @@ export interface CreateTrackSubscriberOptions { track: MoqTrack; /** Where to join the track. Default: `{ type: 'next-object' }` (live edge). */ locationFilter?: LocationFilter; - /** Extra request parameters (auth tokens, priority). */ + /** + * Extra request parameters (auth tokens, priority). A `subscriberPriority` here replaces the track kind's + * {@link MEDIA_SUBSCRIBER_PRIORITY}. + */ parameters?: MessageParameters; - /** Auth-expiry seam: return refreshed parameters to retry the subscribe with. */ + /** + * Auth-expiry seam: return refreshed parameters to retry the subscribe with. Only auth rides it — the retry keeps the + * original `subscriberPriority` and `locationFilter` whatever this returns. + */ refreshAuth?(): Promise; /** * Data-starvation watchdog: a live MSF media track delivers continuously, so a subscription this long without a @@ -154,6 +160,18 @@ const DEFAULT_LOCATION_FILTER: LocationFilter = { type: 'next-object' }; /** See `CreateTrackSubscriberOptions.stallTimeoutMs`. */ export const DEFAULT_STALL_TIMEOUT_MS = 10_000; +/** + * SUBSCRIBER_PRIORITY by catalog track kind, lower being more urgent: audio ahead of video on a congested downlink. + * moq-relay 0.17 orders what it sends a viewer by subscriber priority alone and ignores the publisher's, and the value + * cannot change later — any REQUEST_UPDATE ends the subscription there — so it rides every SUBSCRIBE. Same values as + * the relay SDKs' `mediaSubscribeParameters` (muxinc/relay-sdks#337). Other kinds send none, leaving the peer's + * default. + */ +export const MEDIA_SUBSCRIBER_PRIORITY: Readonly>> = { + audio: 16, + video: 96, +}; + /** * Time constant of the arrival-offset envelope's decay, in milliseconds. The bounds relax toward the current sample by * `1 − e^(−Δt/τ)` per arrival, so the envelope describes roughly the last 4 seconds: long enough to see several GOP @@ -596,7 +614,12 @@ export function createTrackSubscriberActor(options: CreateTrackSubscriberOptions if (destroyed) return; resetArrivalBaseline(); - subscribe({ ...parameters, ...refreshed, locationFilter: parameters.locationFilter }); + subscribe({ + ...parameters, + ...refreshed, + subscriberPriority: parameters.subscriberPriority, + locationFilter: parameters.locationFilter, + }); }) .catch((refreshError) => { if (destroyed) return; @@ -628,6 +651,7 @@ export function createTrackSubscriberActor(options: CreateTrackSubscriberOptions subscribe({ ...options.parameters, + subscriberPriority: options.parameters?.subscriberPriority ?? MEDIA_SUBSCRIBER_PRIORITY[track.type], locationFilter: options.locationFilter ?? DEFAULT_LOCATION_FILTER, }); diff --git a/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts b/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts index 18768bc94e..497f28ca1b 100644 --- a/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts +++ b/packages/spf/src/playback/behaviors/tests/subscribe-selected-tracks.test.ts @@ -3,12 +3,17 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vite-plus/test' import { signal } from '../../../core/signals/primitives'; import type { MoqAudioTrack, MoqVideoTrack } from '../../../media/moq/parse-catalog'; import type { MaybeResolvedPresentation } from '../../../media/types'; -import { PUBLISH_DONE_STATUS, REQUEST_ERROR_CODE } from '../../../network/moqt/control-messages'; +import { + type MessageParameters, + PUBLISH_DONE_STATUS, + REQUEST_ERROR_CODE, +} from '../../../network/moqt/control-messages'; import type { MoqtSession, SubscriptionHandlers } from '../../../network/moqt/session'; import type { MoqSessionActor, MoqSessionActorContext } from '../../actors/moq-session'; import { createTrackSubscriberActor, type CreateTrackSubscriberOptions, + MEDIA_SUBSCRIBER_PRIORITY, type TrackSubscriberActor, type TrackSubscriberContext, } from '../../actors/track-subscriber'; @@ -1234,3 +1239,76 @@ describe.each([ } }); }); + +// Real subscribers over a recording session: what reaches the wire on every +// path that builds a subscription, not just what the factory was handed. +describe('subscriber priority on the wire', () => { + beforeEach(() => { + vi.useFakeTimers(); + }); + afterEach(() => { + vi.useRealTimers(); + }); + + function recordingSession() { + const subscribes: { trackName: string; parameters?: MessageParameters; handlers: SubscriptionHandlers }[] = []; + const session: MoqtSession = { + ready: Promise.resolve(), + subscribe(options, handlers = {}) { + subscribes.push({ trackName: options.trackName, parameters: options.parameters, handlers }); + return { requestId: subscribes.length, update: vi.fn(), cancel: vi.fn() }; + }, + fetch: () => ({ requestId: 0, cancel: vi.fn() }), + trackStatus: vi.fn(), + close: vi.fn(), + destroy: vi.fn(), + }; + + return { session, subscribes }; + } + + it('sends video priority on the initial join, an ABR switch, and a rejoin', async () => { + const { session, subscribes } = recordingSession(); + const deps = makeDeps(); + + deps.context.moqSessionActor.set(makeSessionActor(session)); + const reactor = subscribeSelectedVideoTrack.setup({ ...deps, config: { subscribeRetry: { initialDelayMs: 100 } } }); + + deps.state.selectedVideoTrackId.set(HD.id); + await vi.advanceTimersByTimeAsync(0); + deps.state.selectedVideoTrackId.set(SD.id); + await vi.advanceTimersByTimeAsync(0); + expect(subscribes.map((s) => s.trackName)).toEqual(['hd', 'sd']); + + // The handoff target dies; recovery re-subscribes the same layer. + subscribes[1]!.handlers.onError?.({ errorCode: REQUEST_ERROR_CODE.INTERNAL_ERROR, retryInterval: 0, reason: 'x' }); + await vi.advanceTimersByTimeAsync(PAST_REJOIN_BACKOFF_MS); + expect(subscribes.map((s) => s.trackName)).toEqual(['hd', 'sd', 'sd']); + + for (const { parameters } of subscribes) { + expect(parameters?.subscriberPriority).toBe(MEDIA_SUBSCRIBER_PRIORITY.video); + } + + reactor.destroy(); + }); + + it('sends audio priority on the initial join and a rejoin', async () => { + const { session, subscribes } = recordingSession(); + const deps = makeAudioDeps(); + + deps.context.moqSessionActor.set(makeSessionActor(session)); + const reactor = subscribeSelectedAudioTrack.setup({ ...deps, config: { subscribeRetry: { initialDelayMs: 100 } } }); + + deps.state.selectedAudioTrackId.set(MAIN_AUDIO.id); + await vi.advanceTimersByTimeAsync(0); + subscribes[0]!.handlers.onDone?.({ statusCode: PUBLISH_DONE_STATUS.TRACK_ENDED, streamCount: 0, reason: 'ended' }); + await vi.advanceTimersByTimeAsync(PAST_REJOIN_BACKOFF_MS); + expect(subscribes.map((s) => s.trackName)).toEqual(['main', 'main']); + + for (const { parameters } of subscribes) { + expect(parameters?.subscriberPriority).toBe(MEDIA_SUBSCRIBER_PRIORITY.audio); + } + + reactor.destroy(); + }); +});