ryanlink 1.0.1

package/src/audio/AudioTrack.ts

@@ -0,0 +1,242 @@
+import { formatDuration, isNumber, isRecord, isString } from "../utils";
+import type { APITrack, CommonPluginInfo, CommonUserData, JsonObject } from "../types";
+
+/**
+ * Represents a music track with metadata and playback information
+ */
+export class Track<UserData extends JsonObject = CommonUserData, PluginInfo extends JsonObject = CommonPluginInfo> {
+    /**
+     * Unique identifier of the track
+     */
+    id: string;
+
+    /**
+     * Title of the track
+     */
+    title = "Unknown Track";
+
+    /**
+     * Author/artist of the track
+     */
+    author = "Unknown Author";
+
+    /**
+     * Whether the track is a live stream
+     */
+    isLive = false;
+
+    /**
+     * Whether the track is seekable
+     */
+    isSeekable = false;
+
+    /**
+     * Duration of the track in milliseconds
+     */
+    duration = 0;
+
+    /**
+     * Formatted duration string (hh:mm:ss or mm:ss)
+     */
+    formattedDuration = "00:00";
+
+    /**
+     * Uniform Resource Identifier of the track
+     */
+    uri: string | null = null;
+
+    /**
+     * International Standard Recording Code
+     */
+    isrc: string | null = null;
+
+    /**
+     * URL of the track (validated URI)
+     */
+    url: string | null = null;
+
+    /**
+     * Artwork/thumbnail URL
+     */
+    artworkUrl: string | null = null;
+
+    /**
+     * Custom user data attached to the track
+     */
+    userData = {} as UserData;
+
+    /**
+     * Additional info from plugins
+     */
+    pluginInfo = {} as PluginInfo;
+
+    /**
+     * Encoded string representation (Lavalink format)
+     */
+    encoded: string;
+
+    /**
+     * Source name (youtube, spotify, soundcloud, etc.)
+     */
+    sourceName = "unknown";
+
+    get identifier(): string {
+        return this.id;
+    }
+
+    get stream(): boolean {
+        return this.isLive;
+    }
+
+    get seekable(): boolean {
+        return this.isSeekable;
+    }
+
+    get durationFormatted(): string {
+        return this.formattedDuration;
+    }
+
+    get source(): string {
+        return this.sourceName;
+    }
+
+    get thumbnail(): string | null {
+        return this.artworkUrl;
+    }
+
+    get info() {
+        return {
+            identifier: this.id,
+            position: 0,
+            title: this.title,
+            author: this.author,
+            length: this.duration,
+            isStream: this.isLive,
+            isSeekable: this.isSeekable,
+            uri: this.uri,
+            isrc: this.isrc,
+            artworkUrl: this.artworkUrl,
+            sourceName: this.sourceName,
+        };
+    }
+
+    constructor(data: APITrack<UserData, PluginInfo>) {
+        if (!isRecord(data)) {
+            throw new Error("Track data must be an object");
+        }
+        if (!isRecord(data.info)) {
+            throw new Error("Track info is not an object");
+        }
+
+        // Validate and set identifier
+        if (isString(data.info.identifier, "non-empty")) {
+            this.id = data.info.identifier;
+        } else {
+            throw new Error("Track does not have an identifier");
+        }
+
+        // Validate and set encoded data
+        if (isString(data.encoded, "non-empty")) {
+            this.encoded = data.encoded;
+        } else {
+            throw new Error("Track does not have an encoded data string");
+        }
+
+        // Set title and author
+        if (isString(data.info.title, "non-empty")) {
+            this.title = data.info.title;
+        }
+        if (isString(data.info.author, "non-empty")) {
+            this.author = data.info.author;
+        }
+
+        // Set stream and seekable flags
+        if (data.info.isStream) {
+            this.isLive = true;
+        }
+        if (data.info.isSeekable) {
+            this.isSeekable = true;
+        }
+
+        // Set duration
+        if (this.isLive) {
+            this.duration = Number.POSITIVE_INFINITY;
+            this.formattedDuration = "Live";
+        } else if (isNumber(data.info.length, "whole")) {
+            this.duration = data.info.length;
+            this.formattedDuration = formatDuration(this.duration);
+        }
+
+        // Set URIs
+        if (isString(data.info.uri, "non-empty")) {
+            this.uri = data.info.uri;
+        }
+        if (isString(data.info.isrc, "non-empty")) {
+            this.isrc = data.info.isrc;
+        }
+
+        // Validate URL
+        if (isString(this.uri, "url")) {
+            this.url = this.uri;
+        }
+        if (isString(data.info.artworkUrl, "url")) {
+            this.artworkUrl = data.info.artworkUrl;
+        }
+
+        // Set user data and plugin info
+        if (isRecord(data.userData, "non-empty")) {
+            this.userData = data.userData;
+        }
+        if (isRecord(data.pluginInfo, "non-empty")) {
+            this.pluginInfo = data.pluginInfo;
+        }
+
+        // Set source name
+        if (isString(data.info.sourceName, "non-empty")) {
+            this.sourceName = data.info.sourceName;
+        }
+    }
+
+    /**
+     * String representation of the track
+     */
+    toString(): string {
+        return this.title;
+    }
+
+    /**
+     * JSON representation of the track
+     */
+    toJSON(): Record<string, unknown> {
+        return {
+            identifier: this.id,
+            title: this.title,
+            author: this.author,
+            duration: this.duration,
+            uri: this.uri,
+            thumbnail: this.artworkUrl,
+            source: this.sourceName,
+            isSeekable: this.isSeekable,
+            isStream: this.isLive,
+            encoded: this.encoded,
+            userData: this.userData,
+            pluginInfo: this.pluginInfo,
+        };
+    }
+
+    /**
+     * Create a clone of the track
+     */
+    clone(): Track<UserData, PluginInfo> {
+        return new Track({
+            encoded: this.encoded,
+            info: {
+                ...this.info,
+                length: this.duration,
+                isStream: this.isLive,
+            },
+            userData: this.userData,
+            pluginInfo: this.pluginInfo,
+        } as APITrack<UserData, PluginInfo>);
+    }
+}

package/src/audio/QueueController.ts

@@ -0,0 +1,252 @@
+import { EventEmitter } from "node:events";
+import { Queue } from "../audio/AudioQueue";
+import { Track } from "./AudioTrack";
+import {
+    LookupSymbol,
+    OnStateUpdateSymbol,
+    OnEventUpdateSymbol,
+    OnPingUpdateSymbol,
+    OnVoiceCloseSymbol,
+} from "../config/symbols";
+import { noop } from "../utils";
+import { EventType, TrackEndReason } from "../types/api/Websocket";
+import type { Player } from "../core/RyanlinkPlayer";
+import type {
+    CreateQueueOptions,
+    QueueContext,
+    APIPlayer,
+    PlayerState,
+    EventPayload,
+    TrackStartEventPayload,
+    TrackEndEventPayload,
+    TrackExceptionEventPayload,
+    TrackStuckEventPayload,
+    WebSocketClosedEventPayload,
+} from "../types";
+
+/**
+ * Manages all queues across guilds
+ * Handles queue creation, destruction, synchronization, and event forwarding
+ */
+export class QueueManager<Context extends Record<string, unknown> = QueueContext> extends EventEmitter {
+    #player: Player;
+    #queues = new Map<string, Queue<Context>>();
+    #players = new Map<string, APIPlayer>();
+
+    constructor(player: Player) {
+        super({ captureRejections: false });
+        this.#player = player;
+    }
+
+    get(guildId: string): Queue<Context> | undefined {
+        return this.#queues.get(guildId);
+    }
+
+    has(guildId: string): boolean {
+        return this.#queues.has(guildId);
+    }
+
+    get all(): Queue<Context>[] {
+        return Array.from(this.#queues.values());
+    }
+
+    get size(): number {
+        return this.#queues.size;
+    }
+
+    keys(): IterableIterator<string> {
+        return this.#queues.keys();
+    }
+
+    values(): IterableIterator<Queue<Context>> {
+        return this.#queues.values();
+    }
+
+    entries(): IterableIterator<[string, Queue<Context>]> {
+        return this.#queues.entries();
+    }
+
+    async create(options: CreateQueueOptions<Context>): Promise<Queue<Context>> {
+        if (this.#queues.has(options.guildId)) {
+            throw new Error(`Queue already exists for guild '${options.guildId}'`);
+        }
+
+        let voice = this.#player.voices.get(options.guildId);
+        if (!voice) {
+            voice = await this.#player.voices.connect(options.guildId, options.voiceId, {
+                node: options.node,
+                context: options.context,
+                filters: options.filters,
+                volume: options.volume,
+            });
+        }
+
+        const playerState: APIPlayer = {
+            guildId: options.guildId,
+            track: null,
+            volume: options.volume ?? 100,
+            paused: false,
+            state: {
+                time: Date.now(),
+                position: 0,
+                connected: false,
+                ping: -1,
+            },
+            voice: {
+                token: "",
+                endpoint: "",
+                sessionId: "",
+                channelId: options.voiceId,
+            },
+            filters: options.filters ?? {},
+        };
+
+        this.#players.set(options.guildId, playerState);
+
+        const queue = new Queue(this.#player, options.guildId, options.context);
+        this.#queues.set(options.guildId, queue);
+
+        this.#player.emit("queueCreate", queue);
+
+        return queue;
+    }
+
+    async destroy(guildId: string, reason = "destroyed"): Promise<void> {
+        const queue = this.#queues.get(guildId);
+        if (!queue) {
+            return;
+        }
+
+        const voice = this.#player.voices.get(guildId);
+        if (voice?.node) {
+            await voice.node.rest.destroyPlayer(guildId).catch(noop);
+        }
+
+        await this.#player.voices.destroy(guildId, reason);
+
+        this.#queues.delete(guildId);
+        this.#players.delete(guildId);
+
+        this.#player.emit("queueDestroy", queue, reason);
+    }
+
+    async relocate(guildId: string, nodeName: string): Promise<void> {
+        const queue = this.#queues.get(guildId);
+        if (!queue) {
+            throw new Error(`No queue found for guild '${guildId}'`);
+        }
+
+        const voice = this.#player.voices.get(guildId);
+        if (!voice) {
+            throw new Error(`No voice connection found for guild '${guildId}'`);
+        }
+
+        await voice.changeNode(nodeName);
+    }
+
+    async syncAll(): Promise<void> {
+        const promises: Promise<void>[] = [];
+
+        for (const queue of this.#queues.values()) {
+            promises.push(queue.sync("remote").catch(noop));
+        }
+
+        await Promise.all(promises);
+    }
+
+    [LookupSymbol](guildId: string): APIPlayer | undefined {
+        return this.#players.get(guildId);
+    }
+
+    [OnStateUpdateSymbol](guildId: string, state: PlayerState): void {
+        const player = this.#players.get(guildId);
+        if (!player) {
+            return;
+        }
+
+        player.state = state;
+
+        const queue = this.#queues.get(guildId);
+        if (queue) {
+            this.#player.emit("queueUpdate", queue, state);
+        }
+
+        const voice = this.#player.voices.get(guildId);
+        if (voice?.regionId) {
+            const region = this.#player.voices.regions.get(voice.regionId);
+            if (region) {
+                (region as unknown as { [OnPingUpdateSymbol]?(nodeName: string, state: PlayerState): void })[
+                    OnPingUpdateSymbol
+                ]?.(voice.node.name, state);
+            }
+        }
+    }
+
+    [OnEventUpdateSymbol](guildId: string, event: EventPayload): void {
+        const queue = this.#queues.get(guildId);
+        if (!queue) {
+            return;
+        }
+
+        switch (event.type) {
+            case EventType.TrackStart:
+                this.#handleTrackStart(queue, event);
+                break;
+            case EventType.TrackEnd:
+                void this.#handleTrackEnd(queue, event);
+                break;
+            case EventType.TrackException:
+                this.#handleTrackException(queue, event);
+                break;
+            case EventType.TrackStuck:
+                this.#handleTrackStuck(queue, event);
+                break;
+            case EventType.WebSocketClosed:
+                this.#handleWebSocketClosed(queue, event);
+                break;
+        }
+    }
+
+    #handleTrackStart(queue: Queue<Context>, event: TrackStartEventPayload): void {
+        const track = new Track(event.track);
+        this.#player.emit("trackStart", queue, track);
+    }
+
+    async #handleTrackEnd(queue: Queue<Context>, event: TrackEndEventPayload): Promise<void> {
+        const track = new Track(event.track);
+        const reason = event.reason;
+
+        this.#player.emit("trackFinish", queue, track, reason);
+
+        const shouldAdvance = reason === TrackEndReason.Finished || reason === TrackEndReason.LoadFailed;
+
+        if (shouldAdvance) {
+            const nextTrack = await queue.next().catch(noop);
+
+            if (!nextTrack && queue.finished) {
+                this.#player.emit("queueFinish", queue);
+            }
+        }
+    }
+
+    #handleTrackException(queue: Queue<Context>, event: TrackExceptionEventPayload): void {
+        const track = new Track(event.track);
+        this.#player.emit("trackError", queue, track, event.exception);
+    }
+
+    #handleTrackStuck(queue: Queue<Context>, event: TrackStuckEventPayload): void {
+        const track = new Track(event.track);
+        this.#player.emit("trackStuck", queue, track, event.thresholdMs);
+    }
+
+    #handleWebSocketClosed(queue: Queue<Context>, event: WebSocketClosedEventPayload): void {
+        const voice = this.#player.voices.get(queue.guildId);
+        if (voice) {
+            (
+                this.#player.voices as unknown as {
+                    [OnVoiceCloseSymbol]?(guildId: string, code: number, reason: string, byRemote: boolean): void;
+                }
+            )[OnVoiceCloseSymbol]?.(queue.guildId, event.code, event.reason, event.byRemote);
+        }
+    }
+}

package/src/audio/TrackCollection.ts

@@ -0,0 +1,138 @@
+import { formatDuration, isArray, isNumber, isRecord, isString } from "../utils";
+import { Track } from "./AudioTrack";
+import type { APIPlaylist, CommonPluginInfo, JsonObject } from "../types";
+
+/**
+ * Represents a playlist containing multiple tracks
+ */
+export class Playlist<PluginInfo extends JsonObject = CommonPluginInfo> {
+    /**
+     * Name of the playlist
+     */
+    name = "Unknown Playlist";
+
+    /**
+     * Index of the track that was selected (from URL)
+     */
+    selectedTrack = -1;
+
+    /**
+     * List of tracks in the playlist
+     */
+    tracks: Track[] = [];
+
+    /**
+     * Additional info from plugins
+     */
+    pluginInfo = {} as PluginInfo;
+
+    /**
+     * Total duration of all tracks in milliseconds
+     */
+    duration = 0;
+
+    /**
+     * Formatted total duration string
+     */
+    formattedDuration = "00:00";
+
+    constructor(data: APIPlaylist<PluginInfo>) {
+        if (!isRecord(data)) {
+            throw new Error("Playlist data must be an object");
+        }
+        if (!isRecord(data.info)) {
+            throw new Error("Playlist info is not an object");
+        }
+        if (!isArray(data.tracks)) {
+            throw new Error("Playlist tracks must be an array");
+        }
+
+        // Process tracks and calculate duration
+        for (let i = 0; i < data.tracks.length; i++) {
+            const track = new Track(data.tracks[i]);
+            if (!track.isLive) {
+                this.duration += track.duration;
+            }
+            this.tracks.push(track);
+        }
+
+        // Set playlist name
+        if (isString(data.info.name, "non-empty")) {
+            this.name = data.info.name;
+        } else if (data.info.name === "") {
+            this.name = "";
+        }
+
+        // Set selected track index
+        if (isNumber(data.info.selectedTrack, "whole")) {
+            this.selectedTrack = data.info.selectedTrack;
+        }
+
+        // Set plugin info
+        if (isRecord(data.pluginInfo, "non-empty")) {
+            this.pluginInfo = data.pluginInfo;
+        }
+
+        // Format duration
+        if (this.duration > 0) {
+            this.formattedDuration = formatDuration(this.duration);
+        }
+    }
+
+    get selected(): Track | null {
+        if (this.selectedTrack < 0 || this.selectedTrack >= this.tracks.length) {
+            return null;
+        }
+        return this.tracks[this.selectedTrack] ?? null;
+    }
+
+    /**
+     * Get the selected track (if any)
+     * @returns The selected track or undefined if none/invalid
+     */
+    getSelectedTrack(): Track | undefined {
+        return this.selected ?? undefined;
+    }
+
+    /**
+     * Get the number of tracks
+     */
+    get length(): number {
+        return this.tracks.length;
+    }
+
+    /**
+     * Get the number of tracks (alias for length)
+     */
+    get trackCount(): number {
+        return this.tracks.length;
+    }
+
+    /**
+     * Formatted total duration (alias for formattedDuration)
+     */
+    get durationFormatted(): string {
+        return this.formattedDuration;
+    }
+
+    /**
+     * String representation of the playlist
+     */
+    toString(): string {
+        return this.name;
+    }
+
+    /**
+     * JSON representation of the playlist
+     */
+    toJSON(): Record<string, unknown> {
+        return {
+            name: this.name,
+            selectedTrack: this.selectedTrack,
+            tracks: this.tracks.map((t) => t.toJSON()),
+            duration: this.duration,
+            formattedDuration: this.formattedDuration,
+            pluginInfo: this.pluginInfo,
+        };
+    }
+}

package/src/audio/index.ts

@@ -0,0 +1,9 @@
+/**
+ * Audio exports - AudioTrack, TrackCollection, AudioFilters, AudioQueue, QueueController
+ */
+
+export * from "./AudioTrack";
+export * from "./TrackCollection";
+export * from "./AudioFilters";
+export * from "./AudioQueue";
+export * from "./QueueController";