ziplayer/dist/structures/Player.d.ts

A modular Discord voice player with plugin system

import { EventEmitter } from "events";
import { VoiceConnection, AudioPlayer as DiscordAudioPlayer } from "@discordjs/voice";
import { VoiceChannel } from "discord.js";
import { BaseExtension } from "../extensions";
import { Track, PlayerOptions, PlayerEvents, SourcePlugin, SearchResult, ProgressBarOptions, LoopMode } from "../types";
import { Queue } from "./Queue";
import { PluginManager } from "../plugins";
import type { PlayerManager } from "./PlayerManager";
export declare interface Player {
    on<K extends keyof PlayerEvents>(event: K, listener: (...args: PlayerEvents[K]) => void): this;
    emit<K extends keyof PlayerEvents>(event: K, ...args: PlayerEvents[K]): boolean;
}
/**
 * Represents a music player for a specific Discord guild.
 *
 * @example
 * // Create and configure player
 * const player = await manager.create(guildId, {
 *   tts: { interrupt: true, volume: 1 },
 *   leaveOnEnd: true,
 *   leaveTimeout: 30000
 * });
 *
 * // Connect to voice channel
 * await player.connect(voiceChannel);
 *
 * // Play different types of content
 * await player.play("Never Gonna Give You Up", userId); // Search query
 * await player.play("https://youtube.com/watch?v=dQw4w9WgXcQ", userId); // Direct URL
 * await player.play("tts: Hello everyone!", userId); // Text-to-Speech
 *
 * // Player controls
 * player.pause(); // Pause current track
 * player.resume(); // Resume paused track
 * player.skip(); // Skip to next track
 * player.stop(); // Stop and clear queue
 * player.setVolume(0.5); // Set volume to 50%
 *
 * // Event handling
 * player.on("trackStart", (player, track) => {
 *   console.log(`Now playing: ${track.title}`);
 * });
 *
 * player.on("queueEnd", (player) => {
 *   console.log("Queue finished");
 * });
 *
 */
export declare class Player extends EventEmitter {
    readonly guildId: string;
    connection: VoiceConnection | null;
    audioPlayer: DiscordAudioPlayer;
    queue: Queue;
    volume: number;
    isPlaying: boolean;
    isPaused: boolean;
    options: PlayerOptions;
    pluginManager: PluginManager;
    userdata?: Record<string, any>;
    private manager;
    private leaveTimeout;
    private currentResource;
    private volumeInterval;
    private skipLoop;
    private extensions;
    private extensionContext;
    /**
     * Attach an extension to the player
     *
     * @param {BaseExtension} extension - The extension to attach
     * @example
     * player.attachExtension(new MyExtension());
     */
    attachExtension(extension: BaseExtension): void;
    /**
     * Detach an extension from the player
     *
     * @param {BaseExtension} extension - The extension to detach
     * @example
     * player.detachExtension(new MyExtension());
     */
    detachExtension(extension: BaseExtension): void;
    /**
     * Get all extensions attached to the player
     *
     * @returns {readonly BaseExtension[]} All attached extensions
     * @example
     * const extensions = player.getExtensions();
     * console.log(`Extensions: ${extensions.length}`);
     */
    getExtensions(): readonly BaseExtension[];
    private invokeExtensionLifecycle;
    private runBeforePlayHooks;
    private runAfterPlayHooks;
    private extensionsProvideSearch;
    private extensionsProvideStream;
    /**
     * Start playing a specific track immediately, replacing the current resource.
     */
    private startTrack;
    private ttsPlayer;
    private ttsQueue;
    private ttsActive;
    private clearLeaveTimeout;
    private debug;
    constructor(guildId: string, options: PlayerOptions | undefined, manager: PlayerManager);
    private setupEventListeners;
    private ensureTTSPlayer;
    addPlugin(plugin: SourcePlugin): void;
    removePlugin(name: string): boolean;
    /**
     * Connect to a voice channel
     *
     * @param {VoiceChannel} channel - Discord voice channel
     * @returns {Promise<VoiceConnection>} The voice connection
     * @example
     * await player.connect(voiceChannel);
     */
    connect(channel: VoiceChannel): Promise<VoiceConnection>;
    /**
     * Search for tracks using the player's extensions and plugins
     *
     * @param {string} query - The query to search for
     * @param {string} requestedBy - The user ID who requested the search
     * @returns {Promise<SearchResult>} The search result
     * @example
     * const result = await player.search("Never Gonna Give You Up", userId);
     * console.log(`Search result: ${result.tracks.length} tracks`);
     */
    search(query: string, requestedBy: string): Promise<SearchResult>;
    /**
     * Play a track or search query
     *
     * @param {string | Track} query - Track URL, search query, or Track object
     * @param {string} requestedBy - User ID who requested the track
     * @returns {Promise<boolean>} True if playback started successfully
     * @example
     * await player.play("Never Gonna Give You Up", userId);
     * await player.play("https://youtube.com/watch?v=dQw4w9WgXcQ", userId);
     * await player.play("tts: Hello everyone!", userId);
     */
    play(query: string | Track, requestedBy?: string): Promise<boolean>;
    /**
     * Interrupt current music with a TTS track. Pauses music, swaps the
     * subscription to a dedicated TTS player, plays TTS, then resumes.
     *
     * @param {Track} track - The track to interrupt with
     * @returns {Promise<void>}
     * @example
     * await player.interruptWithTTSTrack(track);
     */
    interruptWithTTSTrack(track: Track): Promise<void>;
    /**
     * Play queued TTS items sequentially
     *
     * @returns {Promise<void>}
     * @example
     * await player.playNextTTS();
     */
    private playNextTTS;
    /** Build AudioResource for a given track using the plugin pipeline */
    private resourceFromTrack;
    private generateWillNext;
    private playNext;
    /**
     * Pause the current track
     *
     * @returns {boolean} True if paused successfully
     * @example
     * const paused = player.pause();
     * console.log(`Paused: ${paused}`);
     */
    pause(): boolean;
    /**
     * Resume the current track
     *
     * @returns {boolean} True if resumed successfully
     * @example
     * const resumed = player.resume();
     * console.log(`Resumed: ${resumed}`);
     */
    resume(): boolean;
    /**
     * Stop the current track
     *
     * @returns {boolean} True if stopped successfully
     * @example
     * const stopped = player.stop();
     * console.log(`Stopped: ${stopped}`);
     */
    stop(): boolean;
    /**
     * Skip to the next track
     *
     * @returns {boolean} True if skipped successfully
     * @example
     * const skipped = player.skip();
     * console.log(`Skipped: ${skipped}`);
     */
    skip(): boolean;
    /**
     * Go back to the previous track in history and play it.
     *
     * @returns {Promise<boolean>} True if previous track was played successfully
     * @example
     * const previous = await player.previous();
     * console.log(`Previous: ${previous}`);
     */
    previous(): Promise<boolean>;
    /**
     * Loop the current track
     *
     * @param {LoopMode} mode - The loop mode to set
     * @returns {LoopMode} The loop mode
     * @example
     * const loopMode = player.loop("track");
     * console.log(`Loop mode: ${loopMode}`);
     */
    loop(mode?: LoopMode): LoopMode;
    /**
     * Set the auto-play mode
     *
     * @param {boolean} mode - The auto-play mode to set
     * @returns {boolean} The auto-play mode
     * @example
     * const autoPlayMode = player.autoPlay(true);
     * console.log(`Auto-play mode: ${autoPlayMode}`);
     */
    autoPlay(mode?: boolean): boolean;
    /**
     * Set the volume of the current track
     *
     * @param {number} volume - The volume to set
     * @returns {boolean} True if volume was set successfully
     * @example
     * const volumeSet = player.setVolume(50);
     * console.log(`Volume set: ${volumeSet}`);
     */
    setVolume(volume: number): boolean;
    /**
     * Shuffle the queue
     *
     * @returns {void}
     * @example
     * player.shuffle();
     */
    shuffle(): void;
    /**
     * Clear the queue
     *
     * @returns {void}
     * @example
     * player.clearQueue();
     */
    clearQueue(): void;
    /**
     * Insert a track or list of tracks into the upcoming queue at a specific position (0 = play after current).
     * - If `query` is a string, performs a search and inserts resulting tracks (playlist supported).
     * - If a Track or Track[] is provided, inserts directly.
     * Does not auto-start playback; it only modifies the queue.
     *
     * @param {string | Track | Track[]} query - The track or tracks to insert
     * @param {number} index - The index to insert the tracks at
     * @param {string} requestedBy - The user ID who requested the insert
     * @returns {Promise<boolean>} True if the tracks were inserted successfully
     * @example
     * const inserted = await player.insert("Song Name", 0, userId);
     * console.log(`Inserted: ${inserted}`);
     */
    insert(query: string | Track | Track[], index: number, requestedBy?: string): Promise<boolean>;
    /**
     * Remove a track from the queue
     *
     * @param {number} index - The index of the track to remove
     * @returns {Track | null} The removed track or null
     * @example
     * const removed = player.remove(0);
     * console.log(`Removed: ${removed?.title}`);
     */
    remove(index: number): Track | null;
    /**
     * Get the progress bar of the current track
     *
     * @param {ProgressBarOptions} options - The options for the progress bar
     * @returns {string} The progress bar
     * @example
     * const progressBar = player.getProgressBar();
     * console.log(`Progress bar: ${progressBar}`);
     */
    getProgressBar(options?: ProgressBarOptions): string;
    /**
     * Get the time of the current track
     *
     * @returns {Object} The time of the current track
     * @example
     * const time = player.getTime();
     * console.log(`Time: ${time.current}`);
     */
    getTime(): {
        current: number;
        total: number;
        format: string;
    };
    /**
     * Format the time in the format of HH:MM:SS
     *
     * @param {number} ms - The time in milliseconds
     * @returns {string} The formatted time
     * @example
     * const formattedTime = player.formatTime(1000);
     * console.log(`Formatted time: ${formattedTime}`);
     */
    formatTime(ms: number): string;
    private scheduleLeave;
    /**
     * Destroy the player
     *
     * @returns {void}
     * @example
     * player.destroy();
     */
    destroy(): void;
    /**
     * Get the size of the queue
     *
     * @returns {number} The size of the queue
     * @example
     * const queueSize = player.queueSize;
     * console.log(`Queue size: ${queueSize}`);
     */
    get queueSize(): number;
    /**
     * Get the current track
     *
     * @returns {Track | null} The current track or null
     * @example
     * const currentTrack = player.currentTrack;
     * console.log(`Current track: ${currentTrack?.title}`);
     */
    get currentTrack(): Track | null;
    /**
     * Get the previous track
     *
     * @returns {Track | null} The previous track or null
     * @example
     * const previousTrack = player.previousTrack;
     * console.log(`Previous track: ${previousTrack?.title}`);
     */
    get previousTrack(): Track | null;
    /**
     * Get the upcoming tracks
     *
     * @returns {Track[]} The upcoming tracks
     * @example
     * const upcomingTracks = player.upcomingTracks;
     * console.log(`Upcoming tracks: ${upcomingTracks.length}`);
     */
    get upcomingTracks(): Track[];
    /**
     * Get the previous tracks
     *
     * @returns {Track[]} The previous tracks
     * @example
     * const previousTracks = player.previousTracks;
     * console.log(`Previous tracks: ${previousTracks.length}`);
     */
    get previousTracks(): Track[];
    /**
     * Get the available plugins
     *
     * @returns {string[]} The available plugins
     * @example
     * const availablePlugins = player.availablePlugins;
     * console.log(`Available plugins: ${availablePlugins.length}`);
     */
    get availablePlugins(): string[];
    /**
     * Get the related tracks
     *
     * @returns {Track[] | null} The related tracks or null
     * @example
     * const relatedTracks = player.relatedTracks;
     * console.log(`Related tracks: ${relatedTracks?.length}`);
     */
    get relatedTracks(): Track[] | null;
}
//# sourceMappingURL=Player.d.ts.map