Class: SourceResolverController

Defined in: packages/player/src/source-resolver.ts:167

Owns one player's source resolver: the function itself, the in-flight de-duplication, the ahead-of-time resolution, and the answers to mpv.

Why there is a TypeScript-side cache as well as a native one

The native cache is what mpv's hook reads; this one is what stops the resolver being called again. Resolve-ahead runs on every queue movement, so without it a five-entry queue would re-sign the same two URLs on every track change. The two share a TTL and are cleared together, so they cannot disagree about which answers are live.

Why answers are generation-stamped

Replacing or removing a resolver must not let an in-flight call from the old one land afterwards: a stale answer written into the cache is exactly the non-determinism the whole design exists to avoid. Every resolution captures the generation it started in, and a settled promise whose generation has moved on is dropped.

Constructors

Constructor

new SourceResolverController(client: MpvClient, options: SourceResolverOptions): SourceResolverController;

Defined in: packages/player/src/source-resolver.ts:183

Parameters

Parameter	Type	Description
client	MpvClient	The player's mpv binding.
options	SourceResolverOptions	See SourceResolverOptions.

Returns

SourceResolverController

Accessors

hasResolver

Get Signature

get hasResolver(): boolean;

Defined in: packages/player/src/source-resolver.ts:197

Whether the app has installed a resolver of its own.

Returns

boolean

---

installed

Get Signature

get installed(): boolean;

Defined in: packages/player/src/source-resolver.ts:192

Whether anything is resolving — the app's resolver, the built-in stage, or both. This is what decides whether mpv's hooks answer from JavaScript.

Returns

boolean

Methods

armBuiltIn()

armBuiltIn(): void;

Defined in: packages/player/src/source-resolver.ts:213

Switch the built-in rewrite on for this player. Idempotent.

Called the first time a URI that needs it is loaded — never at creation — so a player that only ever plays https:// and file:// sources keeps mpv's load hooks answering natively, with no JavaScript on the load path at all. Once armed it stays armed: the queue can still hold URIs that need it, and disarming would be a second state to get wrong for no measurable gain.

Returns

void

Throws

Whatever installSourceResolver throws — this is called from load(), which has a caller to reject.

---

destroy()

destroy(): void;

Defined in: packages/player/src/source-resolver.ts:345

Drop everything. Called by Player.destroy(); idempotent.

Returns

void

---

handleRequest()

handleRequest(request: SourceResolutionRequest): void;

Defined in: packages/player/src/source-resolver.ts:312

Answer one native SourceResolutionRequest.

Always answers, on every path — a play-time request is holding mpv's core open, and the only thing worse than a slow answer is none at all.

Parameters

Parameter	Type	Description
request	SourceResolutionRequest	The request as the native binding delivered it.

Returns

void

---

resolveAhead()

resolveAhead(uris: readonly string[]): void;

Defined in: packages/player/src/source-resolver.ts:291

Resolve uris ahead of mpv asking, and push the answers into the native cache.

This is the path that keeps mpv's core out of the JavaScript thread's way: an answer that is already cached when a hook fires costs a map lookup and a property write, and nothing else. URIs that are already resolved (and still fresh) or already being resolved are skipped.

Parameters

Parameter	Type	Description
uris	readonly string[]	Logical URIs, in priority order. Anything falsy is ignored.

Returns

void

---

set()

set(resolver: SourceResolver | null): void;

Defined in: packages/player/src/source-resolver.ts:239

Install, replace or remove the resolver.

Every cached answer is dropped: a different resolver may legitimately answer differently, and keeping the old answers would mean the change silently did not take effect for the entries already in flight.

Parameters

Parameter	Type	Description
resolver	SourceResolver | null	The resolver, or null to remove it.

Returns

void

Remarks

Native failures propagate: this is a direct call from the app, so it is the one place in this class with a caller to throw to.