@ziplayer/net 0.0.0-stage → 0.0.1

package/dist/ZiNet.d.ts

@@ -0,0 +1,165 @@
+import { PassThrough } from "node:stream";
+import { NetNode, type NetNodeOptions } from "./NetNode";
+import { NetExtension } from "./ext/NetExtension";
+import { StreamImporter, type StreamImporterOptions } from "./stream/StreamImporter";
+import { StreamProvider } from "./stream/StreamProvider";
+import { RemoteVoiceHub } from "./voice/RemoteVoice";
+import { type RoutePlan } from "./router";
+import { type NetSearchOptions, type NetSearchResult, type ServeSearchOptions } from "./search";
+import type { GatewayLike } from "./voice/Gateway";
+export interface ZiNetOptions extends NetNodeOptions {
+    /** The local PlayerManager (needed to provide streams and to accept voice). */
+    manager?: any;
+    /** Required on a node that hands voice off (it owns the Discord gateway). */
+    gateway?: GatewayLike;
+    importer?: StreamImporterOptions;
+    /** Source (plugin) names this node can resolve. Defaults to the manager's registered plugin names. */
+    sources?: string[];
+    /** Extra / overriding query prefixes for `search()`: `{ ytm: "youtube" }` makes `ytm:lofi` search the youtube plugin. */
+    searchAliases?: Record<string, string>;
+}
+export interface DelegateVoiceOptions {
+    /** Channel object to reconnect locally if the hand-off fails or is reclaimed. Defaults to `gateway.resolveChannel`. */
+    channel?: any;
+    /**
+     * Where the executor gets audio: `"executor"` (default) resolves with its own plugins; `"owner"` pulls
+     * from this node, which must call `provideStreams()`. Tracks already marked with `markTrack` keep their owner.
+     */
+    streamFrom?: "executor" | "owner";
+}
+interface Delegation {
+    executor: string;
+    channelId: string;
+    channel: any;
+    streamFrom: "executor" | "owner";
+    stopRelay: () => void;
+}
+export declare function markTrack<T extends {
+    metadata?: Record<string, any>;
+}>(track: T, ownerNodeId: string): T;
+/**
+ * High level entry point: wires a {@link NetNode} to a PlayerManager.
+ *
+ * - Owner streamInfo: `provideStreams()`; consumers just play tracks marked with `markTrack(track, nodeId)`.
+ * - Owner connection: `player.connect()` as usual; `delegateVoice()` hands the voice session to another node.
+ */
+export declare class ZiNet {
+    private readonly options;
+    readonly node: NetNode;
+    readonly importer: StreamImporter;
+    readonly hub: RemoteVoiceHub;
+    private provider?;
+    private readonly delegations;
+    private readonly executions;
+    private readonly manager;
+    private readonly gateway?;
+    private voiceAccepting;
+    private searchProvider?;
+    private readonly aliases;
+    private allowVoice?;
+    constructor(options: ZiNetOptions);
+    private readonly capsCache;
+    localSources(): string[];
+    peerCapabilities(peerId: string, maxAgeMs?: number): Promise<{
+        at: number;
+        sources: string[];
+        players: number;
+        search?: boolean;
+    }>;
+    /**
+     * Plans where each track should be resolved and, with `apply` (default), marks tracks with their owner node
+     * and moves or reclaims the voice when the plan calls for it.
+     *
+     * - `relay`: voice stays here; foreign tracks are pulled from the node that can resolve them.
+     * - `handoff`: voice moves to the node that can play most tracks; others are pulled from their owners.
+     */
+    routeTracks(player: any, tracks: any[], options?: {
+        handoffThreshold?: number;
+        apply?: boolean;
+        peers?: string[];
+        delegate?: DelegateVoiceOptions;
+    }): Promise<RoutePlan & {
+        applied: boolean;
+        error?: Error;
+    }>;
+    get nodeId(): string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /** Extension class to pass in `manager.create(guild, { extensions: [net.extensionClass()] })`. */
+    extensionClass(): new (player?: any) => NetExtension;
+    /**
+     * Serve search results from this node's plugins to trusted peers that hold the `provide-search` role
+     * (the default `*` role includes it). Opt-in, like `provideStreams()`.
+     */
+    provideSearch(options?: ServeSearchOptions): void;
+    /**
+     * Searches across the cluster. Tracks found by another node come back already marked with that node as owner
+     * (`track.metadata.net.owner`), so `player.play(track)` pulls the audio from it.
+     *
+     * `yt:lofi`, `sc:…`, `sp:…`, `tts:…` target the node that has that plugin; anything else (a plain query or a URL)
+     * is tried on this node first and, if nothing is found, on every node that serves search.
+     */
+    search(text: string, options?: NetSearchOptions): Promise<NetSearchResult>;
+    /** Searches on one specific node (it must run `provideSearch()` and trust this node). */
+    searchOn(peerId: string, text: string, options?: NetSearchOptions): Promise<NetSearchResult>;
+    private searchCandidates;
+    /** Runs the query on this node's plugins. With a `plugins` filter it goes straight to the shared plugin manager. */
+    private searchLocal;
+    private onSearch;
+    /** Serve streams resolved by this node's plugins to trusted peers that hold the `provide-stream` role. */
+    provideStreams(options?: {
+        allow?: (track: any, peerId: string) => boolean | Promise<boolean>;
+        chunkBytes?: number;
+    }): StreamProvider;
+    /** Open a remote stream as a ziplayer `StreamInfo`. */
+    openRemoteStream(ownerId: string, track: any, position?: number, signal?: AbortSignal): Promise<{
+        stream: import("stream").Readable;
+        track: any;
+        streamType: string;
+        type: string;
+        recreate: (positionMs: number) => Promise<import("stream").Readable>;
+        cacheable: boolean;
+        metadata: {
+            net: {
+                owner: string;
+            };
+        };
+    }>;
+    delegationFor(guildId: string): Delegation | undefined;
+    /**
+     * Hands the player's Discord voice session to `executorId`. This node keeps the gateway and the queue; the
+     * executor joins voice (through a relay adapter) and plays. Call it while nothing is playing.
+     */
+    delegateVoice(player: any, executorId: string, options?: DelegateVoiceOptions): Promise<void>;
+    /** Takes the voice session back and reconnects locally. */
+    reclaimVoice(player: any, options?: {
+        channel?: any;
+    }): Promise<void>;
+    private dropDelegation;
+    /** Remote playback handle for a delegated player (same contract Lavalink uses). */
+    buildRemoteStream(player: any, track: any): {
+        stream: PassThrough;
+        track: any;
+        streamType: string;
+        type: string;
+        remote: boolean;
+        handle: {
+            play: () => Promise<undefined>;
+            pause: () => Promise<undefined>;
+            resume: () => Promise<undefined>;
+            stop: () => Promise<void>;
+            seek: (position: number) => Promise<undefined>;
+            setVolume: (volume: number) => Promise<undefined>;
+            destroy: () => Promise<undefined>;
+        };
+    } | null;
+    private onExecutorEvent;
+    private onPeerGone;
+    /** Accept voice hand-offs from trusted owners that hold the `delegate-voice` role. */
+    acceptVoice(options?: {
+        allow?: (guildId: string, from: string) => boolean | Promise<boolean>;
+    }): void;
+    private onDelegate;
+    private endExecution;
+}
+export {};