@discord-player/plugin-host 0.0.0-stage → 8.0.0-dev.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Androz2091
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,348 @@
-# Temporary Holding Version
+# @discord-player/plugin-host
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Standalone source execution for Discord Player v8, built on the published
+`@remedia/plugin-host`. Requires Node.js 22.18 or newer.
+
+```text
+discord-player → @discord-player/plugin-host → @remedia/plugin-host
+```
+
+`discord-player` installs this package as a regular dependency and re-exports its
+canonical `BaseExtractor`, `Track`, `Playlist`, `SearchResult`, plugin declarations,
+registry, and serialization classes. Constructor identity and `instanceof` work
+across package imports. No Player, queue manager, Discord client, native audio
+binding, or Remedia audio engine is initialized by importing or creating a host.
+The `@remedia/client` dependency supplies source descriptor types only.
+
+The official `@discord-player/extractor` collection is an optional, separate package.
+It is neither bundled nor automatically registered.
+
+## Using a host from a bot
+
+Normal applications do not need to create an HTTP host. Register sources locally
+as before, or configure standalone deployments once in Player options:
+
+```ts
+const player = new Player({
+  // Existing Remedia nodes and gateway send callback:
+  ...audioOptions,
+  sourceHosts: [
+    {
+      hostId: 'sources-1',
+      url: 'https://plugins.example.com',
+      token: process.env.SOURCE_TOKEN,
+      timeoutMs: 15000,
+    },
+  ],
+});
+
+const result = await player.search('some song', { hostId: 'sources-1' });
+await player.play(channel, result);
+```
+
+This requires `@remedia/client@0.1.0-dev.5` and a matching remote server configured
+with the same `pluginHosts` ID and the `discord-player.source` / `source.stream`
+operation. The bot searches over HTTP and sends an operation descriptor for play
+and automatic crossfade staging. Encoded bytes flow directly from host to audio
+node. Local sources run locally. Embedded nodes cannot play hosted Tracks.
+
+See the [complete deployment example](https://discord-player.js.org/docs/plugins/remote-hosts).
+The direct HTTP examples below describe protocol consumers; a bot should use
+`player.search()` and queue playback, without fetching media grants itself.
+
+## Registration and direct execution
+
+```ts
+import { createSourcePluginHost, SOURCE_PLUGIN_ID } from '@discord-player/plugin-host';
+import { MyExtractor } from './my-extractor.js';
+import { mySourcePlugin } from './my-source-plugin.js';
+
+// Local-only handle() usage may omit hostId.
+const host = createSourcePluginHost({ name: 'My Source Host' });
+await host.extractors.register(MyExtractor);
+await host.plugins.register(mySourcePlugin());
+
+const response = await host.handle({
+  pluginId: SOURCE_PLUGIN_ID,
+  operation: 'source.search',
+  input: { query: 'example' },
+});
+if (response.handled) console.log(response.result);
+// Or use typed source APIs directly:
+const result = await host.runtime.search('example');
+const track = result.first();
+if (track) {
+  const source = await host.plugins.resolveStream(track);
+  // Caller owns consumption and destruction of returned Readables.
+  console.log(source);
+}
+await host.close();
+```
+
+Direct execution preserves model and stream references. It needs no public URL,
+listener, or serialization. `host.remedia` exposes the actual generic Remedia host
+for discovery and lifecycle inspection; use `host.handle` and `host.fetch` as the
+application entrypoints, so the boundary conversion remains active.
+
+Both Player and standalone execution use `SourcePluginRuntime`. There is one
+registry with the existing `first`, `collect`, `pipe`, and `broadcast` policies,
+provider priorities, protocol matching, bridging, registration cancellation,
+post-stream transforms, and cleanup ownership. Player retains all queue, voice,
+Gateway, crossfade, and playback orchestration.
+
+## Hono
+
+```ts
+import { Hono } from 'hono';
+import { serve } from '@hono/node-server';
+import { createSourcePluginHost } from '@discord-player/plugin-host';
+import { MyExtractor } from './my-extractor.js';
+
+const host = createSourcePluginHost({ name: 'Sources', hostId: 'sources-eu-1', publicUrl: 'http://localhost:3000' });
+await host.extractors.register(MyExtractor);
+const app = new Hono();
+app.all('*', (c) => host.fetch(c.req.raw));
+const server = serve({ fetch: app.fetch, port: 3000 });
+process.once('SIGTERM', () => {
+  server.close();
+  void host.close();
+});
+```
+
+## Express
+
+Mount Remedia's existing middleware at the origin root before body parsers.
+
+```ts
+import express from 'express';
+import { createNodeMiddleware } from '@remedia/plugin-host/node';
+import { createSourcePluginHost } from '@discord-player/plugin-host';
+import { MyExtractor } from './my-extractor.js';
+
+const host = createSourcePluginHost({ name: 'Sources', hostId: 'sources-eu-1', publicUrl: 'http://localhost:3000' });
+await host.extractors.register(MyExtractor);
+const app = express();
+app.use(createNodeMiddleware(host));
+app.use(express.json());
+const server = app.listen(3000);
+process.once('SIGTERM', () => {
+  server.close();
+  void host.close();
+});
+```
+
+No listener starts automatically. Remedia owns HTTP routing, authorization,
+request limits, media tokens, backpressure, stream cancellation, and disposal.
+Configure `token`, `mediaTtlMs`, and `maxMediaTokens` through the host options.
+`publicUrl` is a trusted HTTP(S) origin and is needed only for HTTP media results.
+
+## HTTP source contract
+
+One aggregate registration, `discord-player.source`, advertises:
+
+| Operation        | Input                           | Result                                     |
+| ---------------- | ------------------------------- | ------------------------------------------ |
+| `source.search`  | `{ query, options? }`           | Metadata through normal provider matching  |
+| `source.resolve` | `{ query, pluginId, options? }` | Metadata from an explicit provider         |
+| `source.related` | `{ track }`                     | Related metadata from the track's provider |
+| `source.stream`  | `{ track }`                     | Deferred Remedia media descriptor          |
+
+`source.stream` includes normal bridge fallback and post-stream transformations;
+internal operation handlers are not separate Remedia registrations. HTTP options
+accept portable plugin/source/searchEngine hints, limit, requester ID, and blocked
+provider IDs. Local HTTP request options, functions and Discord objects do not
+cross the boundary. The transport validates input before source execution.
+
+```ts
+import { SOURCE_PLUGIN_ID, deserializeSourceResult, type PortableSourceResult } from '@discord-player/plugin-host';
+
+const response = await fetch('http://localhost:3000/remedia/v1/execute', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({ pluginId: SOURCE_PLUGIN_ID, operation: 'source.search', input: { query: 'example' } }),
+});
+if (!response.ok) throw new Error(`Source search failed: ${response.status}`);
+const search = (await response.json()) as { handled: boolean; result: PortableSourceResult };
+if (!search.handled) throw new Error('Unhandled search');
+const localModels = deserializeSourceResult(search.result);
+console.log(localModels.first());
+
+// Send the original portable representation back, including its optional state hint.
+const mediaResponse = await fetch('http://localhost:3000/remedia/v1/execute', {
+  method: 'POST',
+  headers: { 'content-type': 'application/json' },
+  body: JSON.stringify({
+    pluginId: SOURCE_PLUGIN_ID,
+    operation: 'source.stream',
+    input: { track: search.result.tracks[0] },
+  }),
+});
+if (!mediaResponse.ok) throw new Error(`Source stream failed: ${mediaResponse.status}`);
+const media = (await mediaResponse.json()) as { handled: boolean; result: { url: string; expiresAtMs: number } };
+if (!media.handled) throw new Error('Unhandled media');
+// Redeem media.result.url before expiresAtMs; this is a short-lived, single-use grant.
+const bytes = await fetch(media.result.url);
+console.log(bytes.body);
+```
+
+Media resolution starts when the grant is redeemed, using that request's
+cancellation signal rather than the completed JSON request's signal. Readables,
+files, buffers, and upstream HTTP(S) URLs become encoded byte streams before
+post-stream transforms. URLs are proxied inside the host so provider resolution
+and transforms remain there. The adapter never buffers complete media files.
+Direct calls retain native descriptors; HTTP never returns nested Readables.
+
+## Portable metadata and process-local state
+
+HTTP results contain version 1 Track and Playlist data. `deserializeSourceResult()`
+retains the opaque `sourceState` token on the normal Track and links Playlist
+instances. Pass `serializeSourceTrack(track)` to source operations; no second HTTP
+payload needs to be retained. `serialize()` and `toJSON()` deliberately omit the
+temporary token. Persistence and clones made through persistence reconstruct from
+provider metadata. Ordinary queue/history insertion retains the same Track and its
+token. Host identity persists in `sourceReference.hostId`, separate from
+`sourceReference.pluginId` and the provider's source name/data.
+
+HTTP hosts must configure a stable non-secret `hostId`, including deployments
+that do not configure `publicUrl`. Construction with `publicUrl` requires it, and
+`fetch()` rejects HTTP use without it. Local-only `handle()` hosts may omit it and
+receive a generated process identifier that intentionally does not survive restarts. Two hosts
+can use the same provider IDs, but cannot redeem one another's Tracks. The embedded
+registry rejects hosted Tracks when used as local sources. DiscordPlayer routes them
+through configured remote hosts and compatible Remedia nodes instead.
+Do not put endpoints, bearer tokens or credentials in sourceReference.
+
+The per-host FIFO cache defaults to 1000 Track states for ten minutes. Previous
+10000/one-hour defaults could retain substantial provider payloads and playlists.
+Periodic cleanup runs even while idle (at most every 30 seconds), with additional
+checks on use, provider lifetime changes and shutdown. Cached snapshots omit
+Playlist links and metadata callbacks so one entry cannot retain the whole result
+through those links. This is a count limit, not a byte memory guarantee: trusted
+providers can still attach large engines. Tune limits for the deployment.
+
+Concurrent remote playback receives copied engine/public metadata, never the
+cached Track itself. Non-cloneable engines are reconstructed instead. Copies use
+snapshot metadata rather than callbacks closing over the original Track. Direct
+execution retains original object identity and the caller's ownership contract.
+
+After eviction, expiration, or restart, modern plugins receive reconstructed
+Track metadata and their portable sourceReference. Legacy extractors re-run
+`handle()` through their original provider using the public Track URL, select the
+matching URL, and then receive the newly constructed Track in `stream()`. If the
+provider is unavailable or cannot reconstruct the track, execution fails with an
+explicit diagnostic. This means queued tracks can survive cache loss when their
+provider supports URL reconstruction; ephemeral-only sources must be searched
+again. A serialized Track is never a promise of permanent source availability.
+
+Raw engines, credentials, functions, live streams, circular objects and legacy
+metadata callbacks are never serialized. Modern metadata and sourceReference
+must follow the existing JSON-safe contract; plugins must put only public source
+identifiers there, never secrets. Invalid metadata fails serialization rather
+than being silently removed. Credentials belong to host-local plugin options.
+
+## Legacy compatibility
+
+The audited v7 extractors use `this.context.player` for Track/Playlist construction,
+source lookup/bridging, diagnostics and `probeTimeout`. `LegacyPlayerContext` is a
+structural source API, backed by the runtime when standalone and by the actual
+Player when embedded. It supports plugins, extractors, search, debug/error events,
+source options, and legacy constructors. Optional `getRemedia(false)` returns
+null standalone; required audio access and queue/voice operations fail explicitly.
+It never instantiates a dummy Player, queue or voice connection.
+
+Legacy raw PCM/Opus override streams remain unsupported: return encoded media.
+Queue history, Discord clients and other process-local playback objects are not
+part of HTTP requests. An extractor that needs arbitrary Player/voice APIs or
+cannot reconstruct private state after expiration requires migration; the source
+compatibility surface does not emulate the whole Player API.
+
+## Remedia server integration boundary
+
+Remedia dev.5 supports generic host discovery, authenticated operation execution,
+native decoding of single-use grants, and cancellation. Configure the deployment
+in the server's `pluginHosts` list and in the bot's `sourceHosts` list. Installing
+`@remedia/plugin-host@0.1.0-dev.5` alone does not register a host with an audio node.
+
+DiscordPlayer sends operation descriptors for playback and staged-next preparation;
+the audio node invokes `source.stream` and consumes encoded bytes directly. The
+bot uses HTTP only for metadata and never redeems a playback grant. Host affinity
+is checked during session selection and before playback/staging. Embedded playback
+continues to execute local registrations and rejects remote-host Tracks.
+
+## Validation
+
+`pnpm build`, `pnpm typecheck`, `pnpm test`, `pnpm lint`, and `pnpm format:check`
+cover the workspace. Tests include the published optional extractor collection (SDK calls stubbed),
+real HTTP disconnect/shutdown, and real FFmpeg decoding of generated MP3, Ogg/Opus
+and faststart M4A. FFmpeg must be installed; CI installs it explicitly. No personal
+media files or third-party service access are needed. CI builds the host before discord-player,
+includes its dist artifacts, and publishes it before dependent packages using the
+shared release inventory.
+
+## Remote media policy
+
+`mediaPolicy` denies private, loopback, link-local, reserved and transition IP
+ranges by default. DNS results are checked and the selected address is pinned to
+the connection, preserving TLS hostname verification. Every redirect is checked;
+TLS downgrades and URL user/password credentials are rejected. Optional
+`allowedHosts` restricts exact hostnames. No inbound authorization or provider
+request headers are copied to upstreams. Providers needing custom authorization
+must return an encoded Readable opened by their trusted SDK. Plugins execute
+trusted code and can open their own network/file resources; this policy does not
+sandbox extractor `handle()` or provider-created streams.
+
+File descriptors require explicit `allowedFileRoots`. Canonical paths are checked,
+then regular files are opened through owned handles. Authorized roots and parent
+directories must be administrator-owned; concurrent hostile filesystem mutation is
+outside this policy's trust boundary. Default limits are 32 active streams, 512 MiB
+per stream, 30 minutes total, five redirects and 30 seconds upstream socket idle.
+Tune `maxConcurrent`, `maxBytes`, `timeoutMs`, and `allowPrivateNetworks` for trusted
+private deployments. Buffers are already allocated by providers; the host bounds
+output bytes but cannot undo that allocation. Streaming uses backpressure; abort,
+consumer disconnect, byte/deadline errors and host shutdown release resources.
+After headers, errors terminate the body/socket, never masquerade as successful
+JSON responses. Use Remedia's Node middleware to connect network disconnects to
+Fetch cancellation. Configure `token` and HTTPS for remote authorization.
+
+Default proxy delivery resolves media on grant redemption. Expired provider
+sources are rejected rather than fetching expired credentials; request a fresh
+`source.stream` grant. Provider expiration survives materialization and stream
+transforms. Grant expiration is a separate deadline managed by Remedia.
+`mediaDelivery: 'direct-url'` enables direct delivery for explicitly declared
+`directUrlProviders` only. Invoking an arbitrary `track.stream` handler may already
+open a Readable, so unknown or mixed-source providers must stay deferred. Declare
+only trusted providers whose handlers return URL metadata without opening media:
+
+```ts
+const host = createSourcePluginHost({
+  name: 'Sources',
+  hostId: 'sources-eu-1',
+  publicUrl: 'https://sources.example.com',
+  mediaDelivery: 'direct-url',
+  directUrlProviders: ['example.url-provider'],
+});
+```
+
+These providers resolve URL metadata at `source.stream` invocation, never search.
+The dispatcher checks active, unblocked transformations for the actual stream
+owner. Applicable byte transforms force the existing secure proxy path, and run
+once on redemption. Unrelated providers' transforms do not prevent direct delivery.
+The check repeats after asynchronous URL preparation so newly registered transforms
+cannot be skipped. A declining URL-only handler defers bridge resolution; a handler
+that returns bytes despite its declaration fails explicitly and its stream is
+destroyed, without a retry. Do not list legacy or mixed-result providers.
+
+All other providers, including Readables, files and buffers, resolve and materialize
+only when their grant is redeemed. There is no eager byte-source fallback or retained
+live stream in an unredeemed grant. Cancellation, expiration, provider removal and
+shutdown release transport resources; an old grant cannot bind a replacement
+registration. Provider URL expiration remains intact. The consuming node must still
+independently enforce its DNS/redirect policy for direct URLs. Authentication or
+byte transformations requiring the host must use proxy delivery.
+
+Single-use media grants reject Range requests. Remedia dev.5 opens these operation
+results as sequential, non-seekable FFmpeg inputs, avoiding default Range probing.
+This does not add random access or turn grant URLs into durable source references.
+See [the Remedia integration contract](docs/remedia-contract.md) for the current
+protocol and validation limits. Native Remedia playback and Discord voice delivery
+remain outside this repository's HTTP/client integration tests.

package/dist/compat/base-extractor.d.ts

@@ -0,0 +1,88 @@
+import type { Readable } from 'node:stream';
+import type { SourceRuntimeEvents } from '../legacy-player.js';
+import type { Track } from '../structures/track.js';
+import type { Playlist } from '../structures/playlist.js';
+import type { ExtractorExecutionContext } from './extractor-execution-context.js';
+import type { SearchQueryType } from './query-types.js';
+import type { ExtractorInfo, ExtractorSearchContext, ExtractorStreamable, NextFunction } from './extractor-types.js';
+/** Minimal v7 lifecycle and source API, adapted to the source operation registry. */
+export declare class BaseExtractor<Options extends object = object> {
+    /** Owning legacy registration context. */
+    context: ExtractorExecutionContext;
+    /** Original local extractor configuration. */
+    options: Options;
+    /** Default identifier; subclasses should override. */
+    static identifier: string;
+    /** Higher priority wins before match confidence. */
+    priority: number;
+    /** Supported explicit query protocols. */
+    protocols: string[];
+    /** Create a compatibility instance; use player.extractors.register to own it.
+     * @param context Owning compatibility context.
+     * @param options Original extractor options.
+     */
+    constructor(
+    /** Owning legacy registration context. */
+    context: ExtractorExecutionContext, 
+    /** Original local extractor configuration. */
+    options?: Options);
+    /** Subclass static identifier. */
+    get identifier(): string;
+    /** Obsolete demux support is unavailable. */
+    get supportsDemux(): boolean;
+    /** Acquire extractor resources. */
+    activate(): Promise<void>;
+    /** Release extractor resources. */
+    deactivate(): Promise<void>;
+    /** Recreate the owned registration with new options.
+     * @param options Replacement options.
+     */
+    reconfigure(options: Options): Promise<void>;
+    /** Test whether this extractor accepts a query.
+     * @param query Search text.
+     * @param type Query hint.
+     */
+    validate(query: string, type?: SearchQueryType | null): Promise<boolean>;
+    /** Resolve metadata.
+     * @param query Search text.
+     * @param context Search hints.
+     */
+    handle(query: string, context: ExtractorSearchContext): Promise<ExtractorInfo>;
+    /** Resolve media, or decline to enable bridging.
+     * @param track Track to stream.
+     */
+    stream(track: Track): Promise<ExtractorStreamable | undefined>;
+    /** Resolve related metadata.
+     * @param track Seed track.
+     * @param history Optional queue history; local execution only.
+     */
+    getRelatedTracks(track: Track, history?: unknown): Promise<ExtractorInfo>;
+    /** Explicit fallback for another source.
+     * @param track Track needing a stream.
+     * @param sourceExtractor Original extractor, if legacy.
+     */
+    bridge(track: Track, sourceExtractor: BaseExtractor<any> | null): Promise<ExtractorStreamable | null>;
+    /** Transform an encoded local Readable. Raw codec overrides are unsupported.
+     * @param stream Encoded input.
+     * @param next Completion callback.
+     */
+    handlePostStream(stream: Readable, next: NextFunction): void;
+    /** Build an anonymous bridge query.
+     * @param track Track metadata.
+     */
+    createBridgeQuery(track: Track): string;
+    /** Construct a metadata response.
+     * @param playlist Optional playlist.
+     * @param tracks Ordered tracks, defaulting to playlist entries.
+     */
+    createResponse(playlist?: Playlist | null, tracks?: Track[]): ExtractorInfo;
+    /** Publish a diagnostic.
+     * @param message Diagnostic text.
+     */
+    debug(message: string): void;
+    /** Forward supported Player events.
+     * @param event Player event.
+     * @param args Event arguments.
+     */
+    emit<K extends keyof SourceRuntimeEvents>(event: K, ...args: SourceRuntimeEvents[K]): boolean;
+}

package/dist/compat/base-extractor.js

@@ -0,0 +1,118 @@
+/** Minimal v7 lifecycle and source API, adapted to the source operation registry. */
+export class BaseExtractor {
+    context;
+    options;
+    /** Default identifier; subclasses should override. */
+    static identifier = 'org.example.extractor';
+    /** Higher priority wins before match confidence. */
+    priority = 1;
+    /** Supported explicit query protocols. */
+    protocols = [];
+    /** Create a compatibility instance; use player.extractors.register to own it.
+     * @param context Owning compatibility context.
+     * @param options Original extractor options.
+     */
+    constructor(
+    /** Owning legacy registration context. */
+    context, 
+    /** Original local extractor configuration. */
+    options = {}) {
+        this.context = context;
+        this.options = options;
+    }
+    /** Subclass static identifier. */
+    get identifier() {
+        return this.constructor.identifier;
+    }
+    /** Obsolete demux support is unavailable. */
+    get supportsDemux() {
+        return false;
+    }
+    /** Acquire extractor resources. */
+    async activate() { }
+    /** Release extractor resources. */
+    async deactivate() { }
+    /** Recreate the owned registration with new options.
+     * @param options Replacement options.
+     */
+    async reconfigure(options) {
+        await this.context.reconfigure(this.identifier, options);
+    }
+    /** Test whether this extractor accepts a query.
+     * @param query Search text.
+     * @param type Query hint.
+     */
+    async validate(query, type) {
+        void query;
+        void type;
+        return false;
+    }
+    /** Resolve metadata.
+     * @param query Search text.
+     * @param context Search hints.
+     */
+    async handle(query, context) {
+        void query;
+        void context;
+        return this.createResponse();
+    }
+    /** Resolve media, or decline to enable bridging.
+     * @param track Track to stream.
+     */
+    async stream(track) {
+        void track;
+        return undefined;
+    }
+    /** Resolve related metadata.
+     * @param track Seed track.
+     * @param history Optional queue history; local execution only.
+     */
+    async getRelatedTracks(track, history) {
+        void track;
+        void history;
+        return this.createResponse();
+    }
+    /** Explicit fallback for another source.
+     * @param track Track needing a stream.
+     * @param sourceExtractor Original extractor, if legacy.
+     */
+    async bridge(track, sourceExtractor) {
+        void track;
+        void sourceExtractor;
+        return null;
+    }
+    /** Transform an encoded local Readable. Raw codec overrides are unsupported.
+     * @param stream Encoded input.
+     * @param next Completion callback.
+     */
+    handlePostStream(stream, next) {
+        next(null, stream);
+    }
+    /** Build an anonymous bridge query.
+     * @param track Track metadata.
+     */
+    createBridgeQuery(track) {
+        return `${track.title} by ${track.author}`;
+    }
+    /** Construct a metadata response.
+     * @param playlist Optional playlist.
+     * @param tracks Ordered tracks, defaulting to playlist entries.
+     */
+    createResponse(playlist = null, tracks = playlist?.tracks ?? []) {
+        return { playlist, tracks };
+    }
+    /** Publish a diagnostic.
+     * @param message Diagnostic text.
+     */
+    debug(message) {
+        this.context.player.debug(message);
+    }
+    /** Forward supported Player events.
+     * @param event Player event.
+     * @param args Event arguments.
+     */
+    emit(event, ...args) {
+        return this.context.player.emit(event, ...args);
+    }
+}
+//# sourceMappingURL=base-extractor.js.map

package/dist/compat/base-extractor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base-extractor.js","sourceRoot":"","sources":["../../src/compat/base-extractor.ts"],"names":[],"mappings":"AAQA,qFAAqF;AACrF,MAAM,OAAO,aAAa;IAgBf,OAAO;IAEP,OAAO;IAjBhB,sDAAsD;IAC/C,MAAM,CAAC,UAAU,GAAG,uBAAuB,CAAC;IAEnD,oDAAoD;IAC7C,QAAQ,GAAG,CAAC,CAAC;IAEpB,0CAA0C;IACnC,SAAS,GAAa,EAAE,CAAC;IAEhC;;;OAGG;IACH;IACE,0CAA0C;IACnC,OAAkC;IACzC,8CAA8C;IACvC,OAAO,GAAY,EAAa;uBAFhC,OAAO;uBAEP,OAAO;IACb,CAAC;IAEJ,kCAAkC;IAClC,IAAW,UAAU;QACnB,OAAQ,IAAI,CAAC,WAAoC,CAAC,UAAU,CAAC;IAC/D,CAAC;IAED,6CAA6C;IAC7C,IAAW,aAAa;QACtB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,mCAAmC;IAC5B,KAAK,CAAC,QAAQ,KAAmB,CAAC;IAEzC,mCAAmC;IAC5B,KAAK,CAAC,UAAU,KAAmB,CAAC;IAE3C;;OAEG;IACI,KAAK,CAAC,WAAW,CAAC,OAAgB;QACvC,MAAM,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IAC3D,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,QAAQ,CAAC,KAAa,EAAE,IAA6B;QAChE,KAAK,KAAK,CAAC;QACX,KAAK,IAAI,CAAC;QAEV,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM,CAAC,KAAa,EAAE,OAA+B;QAChE,KAAK,KAAK,CAAC;QACX,KAAK,OAAO,CAAC;QAEb,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,MAAM,CAAC,KAAY;QAC9B,KAAK,KAAK,CAAC;QAEX,OAAO,SAAS,CAAC;IACnB,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,gBAAgB,CAAC,KAAY,EAAE,OAAiB;QAC3D,KAAK,KAAK,CAAC;QACX,KAAK,OAAO,CAAC;QAEb,OAAO,IAAI,CAAC,cAAc,EAAE,CAAC;IAC/B,CAAC;IAED;;;OAGG;IACI,KAAK,CAAC,MAAM,CAAC,KAAY,EAAE,eAA0C;QAC1E,KAAK,KAAK,CAAC;QACX,KAAK,eAAe,CAAC;QAErB,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACI,gBAAgB,CAAC,MAAgB,EAAE,IAAkB;QAC1D,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACrB,CAAC;IAED;;OAEG;IACI,iBAAiB,CAAC,KAAY;QACnC,OAAO,GAAG,KAAK,CAAC,KAAK,OAAO,KAAK,CAAC,MAAM,EAAE,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACI,cAAc,CAAC,QAAQ,GAAoB,IAAI,EAAE,MAAM,GAAY,QAAQ,EAAE,MAAM,IAAI,EAAE;QAC9F,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,CAAC;IAC9B,CAAC;IAED;;OAEG;IACI,KAAK,CAAC,OAAe;QAC1B,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IACrC,CAAC;IAED;;;OAGG;IACI,IAAI,CAAsC,KAAQ,EAAE,GAAG,IAA4B;QACxF,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,GAAI,IAAc,CAAC,CAAC;IAC7D,CAAC;CACF"}

package/dist/compat/extractor-execution-context.d.ts

@@ -0,0 +1,69 @@
+import type { LegacyPlayerContext } from '../legacy-player.js';
+import type { Track } from '../structures/track.js';
+import type { SourceStream } from '../plugins/types.js';
+import { BaseExtractor } from './base-extractor.js';
+import type { ExtractorConstructor } from './extractor-types.js';
+/** Small legacy ownership adapter; all execution goes through player.plugins. */
+export declare class ExtractorExecutionContext {
+    /** Player owning legacy registrations. */
+    readonly player: LegacyPlayerContext;
+    private bridgeAttempts;
+    private instances;
+    /** Read-only view of registered legacy instances. */
+    get store(): ReadonlyMap<string, BaseExtractor<any>>;
+    /** Number of legacy registrations. */
+    get size(): number;
+    /** Create an adapter owned by one Player.
+     * @param player Owning Player.
+     */
+    constructor(
+    /** Player owning legacy registrations. */
+    player: LegacyPlayerContext);
+    /** Look up a legacy registration.
+     * @param id Extractor identifier.
+     */
+    get(id: string): BaseExtractor<any> | undefined;
+    /** Test legacy registration membership.
+     * @param id Extractor identifier.
+     */
+    isRegistered(id: string): boolean;
+    /** Check the Player block list.
+     * @param id Extractor identifier.
+     */
+    isDisabled(id: string): boolean;
+    /** Check whether a source is allowed.
+     * @param id Extractor identifier.
+     */
+    isEnabled(id: string): boolean;
+    /** Register a legacy class through a source plugin.
+     * @param Extractor Legacy BaseExtractor subclass constructor.
+     * @param options Original options passed to the instance.
+     * @returns The owned compatibility instance.
+     */
+    register<C extends ExtractorConstructor>(Extractor: C, ...args: {} extends ConstructorParameters<C>[1] ? [options?: ConstructorParameters<C>[1]] : [options: ConstructorParameters<C>[1]]): Promise<InstanceType<C>>;
+    /** Remove an extractor and its source subscriptions.
+     * @param extractor ID or owned instance.
+     */
+    unregister(extractor: string | BaseExtractor<any>): Promise<boolean>;
+    /** Remove all legacy registrations. */
+    unregisterAll(): Promise<void>;
+    /** Replace an instance through the same registration path.
+     * @param id Legacy ID.
+     * @param options Replacement options.
+     */
+    reconfigure(id: string, options: object): Promise<BaseExtractor<any>>;
+    /** Register a bundle sequentially with deterministic precedence.
+     * @param bundle Legacy constructors.
+     * @param options Options keyed by identifier.
+     */
+    loadMulti(bundle: readonly ExtractorConstructor[], options?: Record<string, object>): Promise<void>;
+    /** Request explicit bridge fallback using the shared registry.
+     * @param track Track needing a bridge.
+     * @param sourceExtractor Original provider.
+     */
+    requestBridge(track: Track, sourceExtractor?: BaseExtractor<any> | null): Promise<{
+        result: SourceStream;
+        error: null;
+        extractor: BaseExtractor<any> | null;
+    }>;
+}