ziplayer 0.0.8 → 0.1.0

package/src/types/index.ts

@@ -1,7 +1,55 @@
 import { VoiceConnection } from "@discordjs/voice";
 import { Readable } from "stream";
 import { Player } from "../structures/Player";
+import type { PlayerManager } from "../structures/PlayerManager";
 
+/**
+ * Represents a music track with metadata and streaming information.
+ *
+ * @example
+ * // Basic track from YouTube
+ * const track: Track = {
+ *   id: "dQw4w9WgXcQ",
+ *   title: "Never Gonna Give You Up",
+ *   url: "https://youtube.com/watch?v=dQw4w9WgXcQ",
+ *   duration: 212000,
+ *   thumbnail: "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
+ *   requestedBy: "123456789",
+ *   source: "youtube",
+ *   metadata: {
+ *     artist: "Rick Astley",
+ *     album: "Whenever You Need Somebody"
+ *   }
+ * };
+ *
+ * // Track from SoundCloud
+ * const soundcloudTrack: Track = {
+ *   id: "soundcloud-track-123",
+ *   title: "Electronic Song",
+ *   url: "https://soundcloud.com/artist/electronic-song",
+ *   duration: 180000,
+ *   requestedBy: "user456",
+ *   source: "soundcloud",
+ *   metadata: {
+ *     artist: "Electronic Artist",
+ *     genre: "Electronic"
+ *   }
+ * };
+ *
+ * // TTS track
+ * const ttsTrack: Track = {
+ *   id: "tts-" + Date.now(),
+ *   title: "TTS: Hello everyone!",
+ *   url: "tts: Hello everyone!",
+ *   duration: 5000,
+ *   requestedBy: "user789",
+ *   source: "tts",
+ *   metadata: {
+ *     text: "Hello everyone!",
+ *     language: "en"
+ *   }
+ * };
+ */
 export interface Track {
 	id: string;
 	title: string;
@@ -13,6 +61,28 @@ export interface Track {
 	metadata?: Record<string, any>;
 }
 
+/**
+ * Contains search results from plugins, including tracks and optional playlist information.
+ *
+ * @example
+ * const result: SearchResult = {
+ *   tracks: [
+ *     {
+ *       id: "track1",
+ *       title: "Song 1",
+ *       url: "https://example.com/track1",
+ *       duration: 180000,
+ *       requestedBy: "user123",
+ *       source: "youtube"
+ *     }
+ *   ],
+ *   playlist: {
+ *     name: "My Playlist",
+ *     url: "https://example.com/playlist",
+ *     thumbnail: "https://example.com/thumb.jpg"
+ *   }
+ * };
+ */
 export interface SearchResult {
 	tracks: Track[];
 	playlist?: {
@@ -22,12 +92,46 @@ export interface SearchResult {
 	};
 }
 
+/**
+ * Contains streaming information for audio playback.
+ *
+ * @example
+ * const streamInfo: StreamInfo = {
+ *   stream: audioStream,
+ *   type: "webm/opus",
+ *   metadata: {
+ *     bitrate: 128000,
+ *     sampleRate: 48000
+ *   }
+ * };
+ */
 export interface StreamInfo {
 	stream: Readable;
 	type: "webm/opus" | "ogg/opus" | "arbitrary";
 	metadata?: Record<string, any>;
 }
 
+/**
+ * Configuration options for creating a new player instance.
+ *
+ * @example
+ * const options: PlayerOptions = {
+ *   leaveOnEnd: true,
+ *   leaveOnEmpty: true,
+ *   leaveTimeout: 30000,
+ *   volume: 0.5,
+ *   quality: "high",
+ *   selfDeaf: false,
+ *   selfMute: false,
+ *   extractorTimeout: 10000,
+ *   tts: {
+ *     createPlayer: true,
+ *     interrupt: true,
+ *     volume: 1.0,
+ *     Max_Time_TTS: 30000
+ *   }
+ * };
+ */
 export interface PlayerOptions {
 	leaveOnEnd?: boolean;
 	leaveOnEmpty?: boolean;
@@ -66,9 +170,42 @@ export interface PlayerOptions {
 	extensions?: any[] | string[];
 }
 
+/**
+ * Constructor for a SourcePlugin
+ *
+ * @example
+ * const plugin = new YouTubePlugin();
+ * console.log(`Plugin: ${plugin.name}`);
+ */
 export type SourcePluginCtor<T extends SourcePlugin = SourcePlugin> = new (...args: any[]) => T;
+
+/**
+ * SourcePlugin or SourcePluginCtor
+ *
+ * @example
+ * const plugin = new YouTubePlugin();
+ * console.log(`Plugin: ${plugin.name}`);
+ */
 export type SourcePluginLike = SourcePlugin | SourcePluginCtor;
 
+/**
+ * Configuration options for creating a PlayerManager instance.
+ *
+ * @example
+ * const managerOptions: PlayerManagerOptions = {
+ *   plugins: [
+ *     new YouTubePlugin(),
+ *     new SoundCloudPlugin(),
+ *     new SpotifyPlugin(),
+ *     new TTSPlugin({ defaultLang: "en" })
+ *   ],
+ *   extensions: [
+ *     new voiceExt(null, { lang: "en-US" }),
+ *     new lavalinkExt(null, { nodes: [...] })
+ *   ],
+ *   extractorTimeout: 10000
+ * };
+ */
 export interface PlayerManagerOptions {
 	plugins?: SourcePluginLike[];
 	extensions?: any[];
@@ -79,6 +216,16 @@ export interface PlayerManagerOptions {
 	extractorTimeout?: number;
 }
 
+/**
+ * Options for the progress bar
+ *
+ * @example
+ * const options: ProgressBarOptions = {
+ *   size: 10,
+ *   barChar: "=",
+ *   progressChar: ">"
+ * };
+ */
 export interface ProgressBarOptions {
 	size?: number;
 	barChar?: string;
@@ -87,6 +234,168 @@ export interface ProgressBarOptions {
 
 export type LoopMode = "off" | "track" | "queue";
 
+/**
+ * Context for the extension
+ *
+ * @example
+ * const context: ExtensionContext = {
+ *   player: player,
+ *   manager: manager
+ * };
+ */
+export interface ExtensionContext {
+	player: Player;
+	manager: PlayerManager;
+}
+
+/**
+ * Request for the extension to play a track
+ *
+ * @example
+ * const request: ExtensionPlayRequest = {
+ *   query: "Song Name",
+ *   requestedBy: "user123"
+ * };
+ */
+export interface ExtensionPlayRequest {
+	query: string | Track;
+	requestedBy?: string;
+}
+
+/**
+ * Response for the extension to play a track
+ *
+ * @example
+ * const response: ExtensionPlayResponse = {
+ *   handled: true,
+ *   query: "Song Name",
+ *   requestedBy: "user123"
+ * };
+ */
+export interface ExtensionPlayResponse {
+	handled?: boolean;
+	query?: string | Track;
+	requestedBy?: string;
+	tracks?: Track[];
+	isPlaylist?: boolean;
+	success?: boolean;
+	error?: Error;
+}
+
+/**
+ * Payload for the extension to play a track
+ *
+ * @example
+ * const payload: ExtensionAfterPlayPayload = {
+ *   success: true,
+ *   query: "Song Name",
+ *   requestedBy: "user123"
+ * };
+ */
+export interface ExtensionAfterPlayPayload {
+	success: boolean;
+	query: string | Track;
+	requestedBy?: string;
+	tracks?: Track[];
+	isPlaylist?: boolean;
+	error?: Error;
+}
+
+/**
+ * Request for the extension to stream a track
+ *
+ * @example
+ * const request: ExtensionStreamRequest = {
+ *   track: track
+ * };
+ */
+export interface ExtensionStreamRequest {
+	track: Track;
+}
+
+/**
+ * Request for the extension to search for a track
+ *
+ * @example
+ * const request: ExtensionSearchRequest = {
+ *   query: "Song Name",
+ *   requestedBy: "user123"
+ * };
+ */
+export interface ExtensionSearchRequest {
+	query: string;
+	requestedBy: string;
+}
+
+/**
+ * Event types emitted by Player instances.
+ *
+ * @example
+ *
+ * player.on("willPlay", (player, track) => {
+ *   console.log(`Up next: ${track.title}`);
+ * });
+ *
+ * player.on("trackEnd", (player, track) => {
+ *   console.log(`Now playing: ${track.title}`);
+ * });
+ *
+ * player.on("queueAdd", (player, track) => {
+ *   console.log(`Queue added: ${track.title}`);
+ * });
+ *
+ * player.on("queueAddList", (player, tracks) => {
+ *   console.log(`Queue added: ${tracks.length} tracks`);
+ * });
+ *
+ * player.on("queueRemove", (player, track, index) => {
+ *   console.log(`Queue removed: ${track.title} at index ${index}`);
+ * });
+ *
+ * player.on("playerPause", (player, track) => {
+ *   console.log(`Player paused: ${track.title}`);
+ * });
+ *
+ * player.on("playerResume", (player, track) => {
+ *   console.log(`Player resumed: ${track.title}`);
+ * });
+ *
+ * player.on("playerStop", (player) => {
+ *   console.log("Player stopped");
+ * });
+ *
+ * player.on("playerDestroy", (player) => {
+ *   console.log("Player destroyed");
+ * });
+ *
+ * player.on("ttsStart", (player, payload) => {
+ *   console.log(`TTS started: ${payload.text}`);
+ * });
+ *
+ * player.on("ttsEnd", (player) => {
+ *   console.log("TTS ended");
+ * });
+ *
+ * player.on("playerError", (player, error, track) => {
+ *   console.log(`Player error: ${error.message}`);
+ * });
+ *
+ * player.on("connectionError", (player, error) => {
+ *   console.log(`Connection error: ${error.message}`);
+ * });
+ * player.on("trackStart", (player, track) => {
+ *   console.log(`Track started: ${track.title}`);
+ * });
+ *
+ * player.on("volumeChange", (player, oldVolume, newVolume) => {
+ *   console.log(`Volume changed: ${oldVolume} -> ${newVolume}`);
+ * });
+ *
+ * player.on("queueEnd", (player) => {
+ *   console.log("Queue finished");
+ * });
+ *
+ */
 export interface PlayerEvents {
 	debug: [message: string, ...args: any[]];
 	willPlay: [track: Track, upcomingTracks: Track[]];
@@ -108,8 +417,15 @@ export interface PlayerEvents {
 	/** Emitted when TTS finished (interruption mode) */
 	ttsEnd: [];
 }
-
-// Plugin interfaces
+/**
+ * Plugin interface
+ *
+ * @example
+ * const plugin: SourcePlugin = {
+ *   name: "YouTube",
+ *   version: "1.0.0"
+ * };
+ */
 export interface SourcePlugin {
 	name: string;
 	version: string;
@@ -121,11 +437,34 @@ export interface SourcePlugin {
 	extractPlaylist?(url: string, requestedBy: string): Promise<Track[]>;
 }
 
-// Extension interfaces
+/**
+ * Extension interface
+ *
+ * @example
+ * const extension: SourceExtension = {
+ *   name: "YouTube",
+ *   version: "1.0.0"
+ * };
+ */
 export interface SourceExtension {
 	name: string;
 	version: string;
 	connection?: VoiceConnection;
 	player: Player | null;
-	active(alas: any): boolean;
+	active(alas: any): boolean | Promise<boolean>;
+	onRegister?(context: ExtensionContext): void | Promise<void>;
+	onDestroy?(context: ExtensionContext): void | Promise<void>;
+	beforePlay?(
+		context: ExtensionContext,
+		payload: ExtensionPlayRequest,
+	): Promise<ExtensionPlayResponse | void> | ExtensionPlayResponse | void;
+	afterPlay?(context: ExtensionContext, payload: ExtensionAfterPlayPayload): Promise<void> | void;
+	provideSearch?(
+		context: ExtensionContext,
+		payload: ExtensionSearchRequest,
+	): Promise<SearchResult | null | undefined> | SearchResult | null | undefined;
+	provideStream?(
+		context: ExtensionContext,
+		payload: ExtensionStreamRequest,
+	): Promise<StreamInfo | null | undefined> | StreamInfo | null | undefined;
 }

package/src/utils/timeout.ts

@@ -0,0 +1,10 @@
+/**
+ * Utility function to add timeout to a promise
+ * @param promise The promise to add timeout to
+ * @param timeoutMs Timeout in milliseconds
+ * @param message Error message when timeout occurs
+ * @returns Promise that rejects if timeout is reached
+ */
+export function withTimeout<T>(promise: Promise<T>, timeoutMs: number, message: string): Promise<T> {
+	return Promise.race([promise, new Promise<never>((_, reject) => setTimeout(() => reject(new Error(message)), timeoutMs))]);
+}