Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
54 changes: 53 additions & 1 deletion packages/spf/src/playback/actors/tests/track-subscriber.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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 },
Expand Down
30 changes: 27 additions & 3 deletions packages/spf/src/playback/actors/track-subscriber.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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<MessageParameters>;
/**
* Data-starvation watchdog: a live MSF media track delivers continuously, so a subscription this long without a
Expand Down Expand Up @@ -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<Partial<Record<MoqTrack['type'], number>>> = {
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
Expand Down Expand Up @@ -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,

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P3: The auth-refresh resubscribe drops any subscriberPriority that refreshAuth returns, because this line overwrites it after ...refreshed. refreshAuth is documented to return parameters to retry with, so a refreshed value should win and the resolved kind default should be the fallback. Use refreshed.subscriberPriority ?? parameters.subscriberPriority.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At packages/spf/src/playback/actors/track-subscriber.ts, line 617:

<comment>The auth-refresh resubscribe drops any `subscriberPriority` that `refreshAuth` returns, because this line overwrites it after `...refreshed`. `refreshAuth` is documented to return parameters to retry with, so a refreshed value should win and the resolved kind default should be the fallback. Use `refreshed.subscriberPriority ?? parameters.subscriberPriority`.</comment>

<file context>
@@ -596,7 +611,12 @@ export function createTrackSubscriberActor(options: CreateTrackSubscriberOptions
+                  subscribe({
+                    ...parameters,
+                    ...refreshed,
+                    subscriberPriority: parameters.subscriberPriority,
+                    locationFilter: parameters.locationFilter,
+                  });
</file context>
Suggested change
subscriberPriority: parameters.subscriberPriority,
subscriberPriority: refreshed.subscriberPriority ?? parameters.subscriberPriority,

locationFilter: parameters.locationFilter,
});
})
.catch((refreshError) => {
if (destroyed) return;
Expand Down Expand Up @@ -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,
});

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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';
Expand Down Expand Up @@ -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();
});
});
Loading