ziplayer 0.2.7-dev.0 → 0.2.7-dev.2

package/AI-Guide.md

@@ -1,725 +1,464 @@
-# ZiPlayer — AI Developer Guide
+# 🤖 AI Guide for ZiPlayer
 
-<img width="1175" height="305" alt="logo" src="https://raw.githubusercontent.com/ZiProject/ZiPlayer/refs/heads/main/publish/logo.png" />
-> A complete reference for AI assistants helping developers build Discord music bots with the `ziplayer` ecosystem.
+A comprehensive guide for AI assistants and developers working with ZiPlayer - a powerful Discord music player library.
 
----
+## 📋 Table of Contents
 
-## Table of Contents
-
-1. [Package Overview](#1-package-overview)
-2. [Installation](#2-installation)
-3. [Core Architecture](#3-core-architecture)
-4. [PlayerManager](#4-playermanager)
-5. [Player](#5-player)
-6. [Queue](#6-queue)
-7. [Plugins](#7-plugins)
-8. [Extensions](#8-extensions)
-9. [Audio Filters](#9-audio-filters)
-10. [Events Reference](#10-events-reference)
-11. [TypeScript Types](#11-typescript-types)
-12. [Common Patterns & Recipes](#12-common-patterns--recipes)
-13. [Error Handling](#13-error-handling)
-14. [Anti-Patterns to Avoid](#14-anti-patterns-to-avoid)
+1. [Project Overview](#project-overview)
+2. [Architecture](#architecture)
+3. [Core Concepts](#core-concepts)
+4. [API Reference](#api-reference)
+5. [Common Patterns](#common-patterns)
+6. [Troubleshooting](#troubleshooting)
+7. [Code Examples](#code-examples)
 
 ---
 
-## 1. Package Overview
+## 🎯 Project Overview
 
-| Package                | Role                                                            | npm                |
-| ---------------------- | --------------------------------------------------------------- | ------------------ |
-| `ziplayer`             | Core player engine                                              | Required           |
-| `@ziplayer/plugin`     | Source plugins (YouTube, SoundCloud, Spotify, TTS, Attachments) | Required for audio |
-| `@ziplayer/extension`  | Extensions (voice STT, Lavalink, lyrics)                        | Optional           |
-| `@ziplayer/infinity`   | Cobalt-powered multi-platform plugin                            | Optional           |
-| `@ziplayer/ytexecplug` | yt-dlp fallback for YouTube                                     | Optional           |
-| `@discordjs/voice`     | Discord voice layer                                             | Peer dep           |
-| `discord.js`           | Discord bot framework                                           | Peer dep           |
+**ZiPlayer** is an extensible Discord music engine built on `@discordjs/voice`.
 
----
+### Key Features
 
-## 2. Installation
+- Plugin-driven architecture (YouTube, SoundCloud, Spotify, TTS)
+- Extension system (voice commands, lyrics, Lavalink)
+- Audio filters (bassboost, nightcore, etc.)
+- Auto-save/restore (persistence)
+- Smart caching and fallback system
 
-```bash
-npm install ziplayer @ziplayer/plugin @ziplayer/extension @ziplayer/infinity @discordjs/voice discord.js opusscript
-```
+### Tech Stack
+
+- TypeScript
+- `@discordjs/voice` for audio
+- FFmpeg for audio processing
+- Node.js EventEmitter for events
 
 ---
 
-## 3. Core Architecture
+## 🧱 Architecture
 
 ```
-PlayerManager            ← singleton-like, manages all guilds
-  └── Player (per guild) ← controls audio for one server
-        ├── Queue        ← ordered list of tracks
-        ├── PluginManager← resolves queries → streams
-        ├── ExtensionManager ← hooks into lifecycle
-        └── FilterManager← real-time FFmpeg audio effects
-```
 
-### Lifecycle flow
+┌─────────────────────────────────────────────────────────────┐ │ PlayerManager (Global) │ │
+┌─────────────────────────────────────────────────────────┐│ │ │ PersistenceManager (Auto-save) ││ │
+└─────────────────────────────────────────────────────────┘│ │ │ │ │ ┌────────────┴────────────┐ │ │ ▼ ▼ │ │ ┌──────────────┐
+┌──────────────┐ │ │ │ Player 1 │ │ Player 2 │ │ │ │ (Guild A) │ │ (Guild B) │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ │
+┌───────┴────────┐ ┌───────┴────────┐ │ │ ▼ ▼ ▼ ▼ │ │ Queue Filter Queue Filter │ │ PluginMgr ExtMgr PluginMgr ExtMgr │
+└─────────────────────────────────────────────────────────────┘
 
 ```
-manager.create(guildId, opts)
-  → Player constructed → extensions attached
-  → player.connect(voiceChannel)
-  → player.play(query, userId)
-      → extensionManager.BeforePlayHooks()   ← extensions may intercept
-      → pluginManager.search() / getStream()
-      → AudioResource created (with filters)
-      → audioPlayer.play(resource)
-      → events: queueAdd → trackStart → trackEnd → queueEnd
-  → player.destroy()
-      → extensions.onDestroy() → voice disconnected → cleanup
-```
+
+### Component Responsibilities
+
+| Component            | Responsibility                                         |
+| -------------------- | ------------------------------------------------------ |
+| `PlayerManager`      | Creates/manages players, global event bus, persistence |
+| `Player`             | Per-guild audio playback, controls, event emission     |
+| `Queue`              | Track management, loop modes, history, auto-play       |
+| `PluginManager`      | Audio source resolution, streaming, fallback logic     |
+| `ExtensionManager`   | Custom hooks (search, stream, before/after play)       |
+| `FilterManager`      | FFmpeg audio effects                                   |
+| `PersistenceManager` | Auto-save/restore player state                         |
 
 ---
 
-## 4. PlayerManager
+## 🧠 Core Concepts
 
-### Construction
+### 1. Player Lifecycle
 
 ```typescript
-import { PlayerManager } from "ziplayer";
-import { YouTubePlugin, SoundCloudPlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
-import { InfinityPlugin } from "@ziplayer/infinity";
-import { voiceExt, lyricsExt } from "@ziplayer/extension";
+// Create → Connect → Play → (Auto-save) → Destroy
+const player = await manager.create(guildId, options);
+await player.connect(voiceChannel);
+await player.play(query, userId);
+// ... auto-saves periodically
+player.destroy();
+```
 
-const manager = new PlayerManager({
-	plugins: [
-		new TTSPlugin({ defaultLang: "en" }),
-		new YouTubePlugin({}),
-		new SoundCloudPlugin(),
-		new InfinityPlugin(),
-		new SpotifyPlugin(),
-	],
-	extensions: [new voiceExt(null, { lang: "en-US" }), new lyricsExt(null, { provider: "lrclib", includeSynced: true })],
-});
+### 2. Queue Loop Modes
+
+```typescript
+player.loop("off"); // No loop (default)
+player.loop("track"); // Repeat current track
+player.loop("queue"); // Repeat entire queue
 ```
 
-### Key methods
+### 3. Event Flow
 
-| Method    | Signature                                      | Description                                          |
-| --------- | ---------------------------------------------- | ---------------------------------------------------- |
-| `create`  | `(guildOrId, options?) → Promise<Player>`      | Creates (or returns existing) player for a guild     |
-| `get`     | `(guildOrId) → Player \| undefined`            | Gets existing player                                 |
-| `has`     | `(guildOrId) → boolean`                        | Checks if player exists                              |
-| `delete`  | `(guildOrId) → boolean`                        | Destroys and removes a player                        |
-| `getall`  | `() → Player[]`                                | All active players                                   |
-| `destroy` | `() → void`                                    | Destroys ALL players                                 |
-| `search`  | `(query, requestedBy) → Promise<SearchResult>` | Search without a player (uses first matching plugin) |
+```
+trackStart → playing → trackEnd → playNext → (loop/autoplay)
+                                    ↓
+                              queueEnd → leave
+```
 
-### PlayerManager options
+### 4. Plugin Priority & Fallback
 
 ```typescript
-interface PlayerManagerOptions {
-	plugins?: SourcePluginLike[];
-	extensions?: any[];
-	extractorTimeout?: number; // ms, default 10000
-}
+// Plugins are tried in priority order (higher = first)
+// If primary fails, fallback plugins are attempted sequentially
+// Failed plugins don't block the queue
+
+plugin.priority = 10; // Higher priority
 ```
 
----
+### 5. Caching Strategy
 
-## 5. Player
+| Cache Type      | TTL     | Purpose                     |
+| --------------- | ------- | --------------------------- |
+| Search cache    | 2 min   | Avoid duplicate API calls   |
+| Stream cache    | 5 min   | Cache resolved streams      |
+| Extension cache | 1-5 min | Extension operation results |
 
-### Creating a player
+---
 
-```typescript
-const player = await manager.create(guildId, {
-	leaveOnEnd: true, // leave voice when queue ends
-	leaveTimeout: 30_000, // ms before leaving (default 100000)
-	volume: 100, // 0–200, default 100
-	quality: "high", // "high" | "low"
-	selfDeaf: true,
-	selfMute: false,
-	extractorTimeout: 50_000, // ms per plugin operation
-	userdata: { channel: textChannel }, // arbitrary data, access via player.userdata
-	extensions: ["voiceExt", "lyricsExt"], // activate by name or instance
-	filters: ["bassboost", "normalize"], // pre-apply audio filters
-	tts: {
-		createPlayer: true, // pre-create TTS AudioPlayer
-		interrupt: true, // pause music → play TTS → resume
-		volume: 100, // TTS volume (0–200)
-		Max_Time_TTS: 60_000, // max TTS playback time ms
-	},
-});
-```
+## 📚 API Reference
 
-### Connecting
+### PlayerManager
+
+#### Constructor Options
 
 ```typescript
-await player.connect(voiceChannel); // discord.js VoiceChannel
+interface PlayerManagerOptions {
+	plugins?: SourcePlugin[]; // Audio source plugins
+	extensions?: BaseExtension[]; // Custom extensions
+	extractorTimeout?: number; // Default: 10000ms
+	autoCleanup?: boolean; // Default: true
+	cleanupInterval?: number; // Default: 60000ms
+	enableSearchCache?: boolean; // Default: true
+	enableStatsCollection?: boolean; // Default: false
+	persistence?: PersistenceOptions; // Auto-save config
+}
 ```
 
-### Playing
+#### Key Methods
 
-```typescript
-// All of these work:
-await player.play("Never Gonna Give You Up", userId); // text search
-await player.play("https://youtube.com/watch?v=...", userId); // direct URL
-await player.play("https://youtube.com/playlist?list=...", userId); // playlist
-await player.play("tts: Hello everyone!", userId); // TTS
-await player.play(trackObject, userId); // Track object
-await player.play(searchResult, userId); // SearchResult object
-await player.play(null); // resume from queue
-
-//InfinityPlugin:
-await player.play("https://www.youtube.com/watch?v=dQw4w9WgXcQ", userId);
-await player.play("https://www.tiktok.com/@user/video/123", userId);
-await player.play("https://soundcloud.com/artist/track", userId);
-await player.play("https://twitter.com/user/status/123", userId);
-```
+| Method                       | Description                |
+| ---------------------------- | -------------------------- |
+| `create(guildId, options)`   | Create new player          |
+| `get(guildId)`               | Get existing player        |
+| `delete(guildId)`            | Destroy and remove player  |
+| `getAll()`                   | Get all players            |
+| `broadcast(action, ...args)` | Send action to all players |
+| `saveAllPlayers()`           | Manual save all players    |
+| `loadAllPlayers()`           | Manual load all players    |
 
-### Playback controls
+### Player
 
-```typescript
-player.pause(); // → boolean
-player.resume(); // → boolean
-player.skip(); // → boolean (skip to next)
-player.skip(2); // → boolean (skip to index 2)
-await player.previous(); // → boolean (go back one)
-player.stop(); // → boolean (stop + clear queue)
-await player.seek(30_000); // → boolean (seek to 30s)
-player.setVolume(75); // 0–200, returns boolean
-player.shuffle(); // shuffles queue
-player.clearQueue();
-player.loop("off"); // "off" | "track" | "queue"
-player.loop(0); // same as "off"
-player.autoPlay(true); // enable auto-play (related tracks)
-```
+#### Core Methods
 
-### Information
+| Method                         | Description             | Returns             |
+| ------------------------------ | ----------------------- | ------------------- |
+| `play(query, userId)`          | Play track/search/queue | `Promise<boolean>`  |
+| `pause()`                      | Pause current           | `boolean`           |
+| `resume()`                     | Resume playback         | `boolean`           |
+| `skip(index?)`                 | Skip to next/index      | `boolean`           |
+| `stop()`                       | Stop and clear queue    | `boolean`           |
+| `seek(position)`               | Seek to position (ms)   | `Promise<boolean>`  |
+| `previous()`                   | Play previous track     | `Promise<boolean>`  |
+| `setVolume(vol)`               | Set volume (0-200)      | `boolean`           |
+| `loop(mode)`                   | Set loop mode           | `LoopMode`          |
+| `shuffle()`                    | Shuffle queue           | `void`              |
+| `insert(query, index, userId)` | Insert at position      | `Promise<boolean>`  |
+| `save(track, options)`         | Save track to stream    | `Promise<Readable>` |
+
+#### Getters
 
 ```typescript
 player.currentTrack; // Track | null
-player.previousTrack; // Track | null (last played)
-player.upcomingTracks; // Track[]
-player.previousTracks; // Track[]
-player.relatedTracks; // Track[] | null
 player.queueSize; // number
-player.volume; // number
 player.isPlaying; // boolean
 player.isPaused; // boolean
-player.availablePlugins; // string[] (plugin names)
-player.userdata; // Record<string, any>
-
-player.getProgressBar(); // "0:00 | ▬▬▬🔘▬ | 3:32"
-player.getProgressBar({ size: 30, barChar: "━", progressChar: "⬤" });
-player.getTime(); // { current: ms, total: ms, format: "1:23" }
-player.formatTime(90_000); // "01:30"
-```
-
-### Saving a track stream
-
-```typescript
-const stream = await player.save(track);
-stream.pipe(fs.createWriteStream("output.mp3"));
-
-// With options:
-const stream = await player.save(track, {
-	filename: "my-song.mp3",
-	seek: 30_000, // start at 30s
-	filter: [{ name: "normalize", ffmpegFilter: "loudnorm", description: "Normalize" }],
-});
+player.volume; // number
+player.upcomingTracks; // Track[]
+player.previousTracks; // Track[]
+player.relatedTracks; // Track[] | null
 ```
 
-### Inserting tracks mid-queue
+### Queue
 
-```typescript
-// Insert at position 0 = plays after current track
-await player.insert("song name", 0, userId);
-await player.insert(trackObject, 0);
-await player.insert([track1, track2], 0);
-```
+#### Methods
 
-### Removing a track
+| Method                    | Description          |
+| ------------------------- | -------------------- |
+| `add(track)`              | Add single track     |
+| `addMultiple(tracks)`     | Add multiple tracks  |
+| `insert(track, index)`    | Insert at position   |
+| `remove(index)`           | Remove at index      |
+| `removeMultiple(indices)` | Remove multiple      |
+| `removeWhere(predicate)`  | Remove by condition  |
+| `move(from, to)`          | Move track           |
+| `swap(a, b)`              | Swap tracks          |
+| `shuffle()`               | Randomize order      |
+| `clear()`                 | Clear all tracks     |
+| `loop(mode)`              | Set loop mode        |
+| `autoPlay(enabled)`       | Enable/disable       |
+| `previous()`              | Get previous track   |
+| `jumpToHistory(steps)`    | Jump back in history |
 
-```typescript
-const removed = player.queue.remove(2); // removes track at index 2
-```
-
-### Destroying
+#### Properties
 
 ```typescript
-player.destroy();
-// Stops audio, disconnects voice, clears queue, fires onDestroy on all extensions.
-// After this call, do NOT reuse the player instance — call manager.create() again.
+queue.size; // number
+queue.isEmpty; // boolean
+queue.currentTrack; // Track | null
+queue.nextTrack; // Track | null
+queue.lastTrack; // Track | null
+queue.previousTracks; // Track[]
 ```
 
-### Extension management
+### FilterManager
 
 ```typescript
-player.attachExtension(myExt);
-player.detachExtension(myExt);
-player.getExtensions(); // readonly BaseExtension[]
-```
+// Apply filters
+await player.filter.applyFilter("bassboost");
+await player.filter.applyFilters(["bassboost", "nightcore"]);
 
-### Filter management (see §9)
+// Available filters
+// bassboost, trebleboost, nightcore, lofi, vaporwave,
+// echo, reverb, chorus, karaoke, normalize, compressor, limiter
 
-```typescript
-await player.filter.applyFilter("bassboost");
-await player.filter.removeFilter("bassboost");
+// Clear filters
 await player.filter.clearAll();
-player.filter.getActiveFilters(); // AudioFilter[]
-player.filter.hasFilter("nightcore"); // boolean
-player.filter.getAvailableFilters();
-player.filter.getFiltersByCategory("eq");
-```
+await player.filter.clear("bassboost");
 
----
-
-## 6. Queue
+// Get current filters
+const filterString = player.filter.getFilterString(); // "bassboost,nightcore"
+```
 
-Access via `player.queue`.
+### PersistenceManager
 
-### Adding
+#### Options
 
 ```typescript
-player.queue.add(track);
-player.queue.addMultiple([track1, track2]);
-player.queue.insert(track, 0); // 0 = next up
-player.queue.insertMultiple([t1, t2], 0);
+interface PersistenceOptions {
+	enabled: boolean; // Enable persistence
+	provider: "file" | "redis" | "database";
+	filePath?: string; // For file provider
+	saveInterval?: number; // Auto-save interval (ms)
+	autoLoad?: boolean; // Auto-load on start
+	compress?: boolean; // Compress data
+	maxBackups?: number; // Max backup files
+}
 ```
 
-### Removing / navigating
+#### Methods
 
 ```typescript
-player.queue.remove(index)           // Track | null
-player.queue.next(ignoreLoop?)       // Track | null — advances queue
-player.queue.previous()              // Track | null — goes back in history
-player.queue.clear()
-player.queue.shuffle()
-```
-
-### State / getters
+const persistence = manager.getPersistence();
 
-```typescript
-player.queue.size; // number of upcoming tracks
-player.queue.isEmpty; // boolean
-player.queue.currentTrack; // Track | null
-player.queue.nextTrack; // Track | null (peek)
-player.queue.previousTracks; // Track[] (history, max 200)
-player.queue.getTracks(); // Track[] (all upcoming)
-player.queue.getTrack(index); // Track | null
-player.queue.willNextTrack(); // Track | null (autoplay hint)
-player.queue.relatedTracks(); // Track[] | null
+await persistence.savePlayer(player);
+await persistence.saveAll();
+await persistence.loadPlayer(guildId, restorePosition);
+await persistence.loadAll();
+await persistence.deletePlayer(guildId);
+await persistence.restoreBackup(guildId, timestamp);
 ```
 
-### Loop & autoplay
+---
 
-```typescript
-player.queue.loop(); // get current mode
-player.queue.loop("track"); // "off" | "track" | "queue"
-player.queue.autoPlay(); // get state
-player.queue.autoPlay(true); // enable/disable
-```
+## 🔧 Common Patterns
 
----
+### 1. Basic Music Bot Setup
 
-## 7. Plugins
+```typescript
+import { Client, GatewayIntentBits } from "discord.js";
+import { PlayerManager } from "ziplayer";
+import { YouTubePlugin, SpotifyPlugin } from "@ziplayer/plugin";
 
-### Built-in plugins (`@ziplayer/plugin`)
+const client = new Client({
+	intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
+});
 
-#### YouTubePlugin
+const manager = new PlayerManager({
+	plugins: [new YouTubePlugin(), new SpotifyPlugin()],
+	autoCleanup: true,
+	persistence: {
+		enabled: true,
+		filePath: "./data/players",
+	},
+});
 
-```typescript
-new YouTubePlugin({
-	searchLimit: 10, // max search results
-	// fallbackStream: fn(Track) => Promise<StreamInfo>
-	// fistStream: fn(Track) => Promise<StreamInfo>
+client.on("ready", async () => {
+	// Auto-load saved players
+	await manager.loadAllPlayers();
 });
-```
 
-Handles: `youtube.com`, `youtu.be`, `music.youtube.com`, any free text search.
+client.on("messageCreate", async (msg) => {
+	if (msg.content.startsWith("!play")) {
+		const player = await manager.create(msg.guildId);
+		const voiceChannel = msg.member?.voice.channel;
 
-#### SoundCloudPlugin
+		if (!player.connection) {
+			await player.connect(voiceChannel);
+		}
 
-```typescript
-new SoundCloudPlugin();
+		const query = msg.content.slice(6);
+		await player.play(query, msg.author.id);
+	}
+});
 ```
 
-Handles: `soundcloud.com` URLs, free text search (if not a URL for another service).
-
-#### SpotifyPlugin
+### 2. Progress Bar with Time Format
 
 ```typescript
-new SpotifyPlugin();
-```
+// Get formatted time
+const time = player.getTime();
+console.log(`Current: ${time.formatted.current}`); // "1:22:12"
+console.log(`Total: ${time.formatted.total}`); // "3:45:30"
 
-Handles: `spotify:track:...`, `open.spotify.com/...` ⚠️ Metadata only — does NOT stream. Relies on YouTube/SoundCloud fallback for
-audio.
+// Progress bar
+const progressBar = player.getProgressBar({
+	size: 20,
+	barChar: "▬",
+	progressChar: "🔘",
+	timeFormat: "compact",
+	showPercentage: true,
+});
+// Output: "1:22:12 ▬▬▬▬▬▬▬▬▬🔘▬▬▬▬▬▬▬▬ 3:45:30 (36%)"
+```
 
-#### TTSPlugin
+### 3. Queue Management Commands
 
 ```typescript
-new TTSPlugin({
-	defaultLang: "vi", // language code
-	slow: false,
-	createStream: async (text, ctx) => {
-		// return Readable | URL string | Buffer
-	},
-});
-```
+// Skip to specific track
+await player.skip(3); // Skip to index 3
 
-Query formats:
+// Move track to front
+player.queue.move(5, 0);
 
-- `tts: <text>` — uses defaultLang
-- `tts:<lang>:<text>` — e.g., `tts:en:Hello`
-- `tts:<lang>:<slow>:<text>` — e.g., `tts:en:1:Hello` (slow=true)
+// Remove all tracks from specific source
+player.queue.removeWhere((t) => t.source === "soundcloud");
 
-#### AttachmentsPlugin
+// Jump back 2 tracks
+await player.queue.jumpToHistory(2);
 
-```typescript
-new AttachmentsPlugin({
-	maxFileSize: 25 * 1024 * 1024, // 25 MB
-	allowedExtensions: ["mp3", "wav", "ogg", "m4a", "flac"],
-	debug: false,
-});
+// Insert as next track
+await player.insert("song name", 0, userId);
 ```
 
-Handles: Discord CDN URLs (`cdn.discordapp.com`), direct audio file URLs.
-
-### Writing a custom plugin
+### 4. Custom Plugin Implementation
 
 ```typescript
-import { BasePlugin, Track, SearchResult, StreamInfo } from "ziplayer";
-import { Readable } from "stream";
+import { BasePlugin, Track, StreamInfo } from "ziplayer";
 
-export class MyRadioPlugin extends BasePlugin {
-	name = "myradio";
-	version = "1.0.0";
-	priority = 5; // lower = tried first in fallback; default 0
+class CustomPlugin extends BasePlugin {
+	name = "CustomPlugin";
+	priority = 5;
 
 	canHandle(query: string): boolean {
-		return query.startsWith("radio:");
+		return query.startsWith("custom:");
 	}
 
 	async search(query: string, requestedBy: string): Promise<SearchResult> {
-		const track: Track = {
-			id: query,
-			title: "My Radio Station",
-			url: "https://stream.myradio.com/live.mp3",
-			duration: 0, // 0 for live streams
-			requestedBy,
-			source: this.name,
-			metadata: { isLive: true },
-		};
-		return { tracks: [track] };
-	}
-
-	async getStream(track: Track): Promise<StreamInfo> {
-		const response = await fetch(track.url);
-		const stream = Readable.fromWeb(response.body as any);
-		return { stream, type: "arbitrary" };
+		// Implementation
+		return { tracks: [] };
 	}
 
-	// Optional: fallback when getStream fails
-	async getFallback(track: Track): Promise<StreamInfo> {
-		/* ... */
+	async getStream(track: Track, signal: AbortSignal): Promise<StreamInfo> {
+		// Return audio stream
+		return { stream: readableStream, type: "arbitrary" };
 	}
 
-	// Optional: related track suggestions for autoplay
-	async getRelatedTracks(track: Track, opts = {}): Promise<Track[]> {
-		return [];
-	}
-
-	// Optional: extract all tracks from a playlist URL
-	async extractPlaylist(url: string, requestedBy: string): Promise<Track[]> {
+	async getRelatedTracks(track: Track): Promise<Track[]> {
+		// Return recommendations
 		return [];
 	}
 }
 ```
 
-### Plugin priority & fallback order
-
-When `getStream` fails on the primary plugin, ZiPlayer tries all other plugins in order of `priority` (ascending — lower = higher
-priority). Within the same priority group, `Promise.any` races them.
+### 5. Custom Extension Implementation
 
 ```typescript
-new MyPlugin({ priority: 10 }); // tried last in fallback
-```
-
----
-
-## 8. Extensions
+import { BaseExtension, ExtensionContext } from "ziplayer";
 
-### Built-in extensions (`@ziplayer/extension`)
+class LoggerExtension extends BaseExtension {
+	name = "Logger";
+	priority = 10;
 
-#### voiceExt — Speech-to-Text
-
-```typescript
-import { voiceExt } from "@ziplayer/extension";
-
-new voiceExt(null, {
-	lang: "en-US", // Google Speech language
-	ignoreBots: true,
-	focusUser: "userId", // only listen to one user
-	minimalVoiceMessageDuration: 1, // seconds
-	postSilenceDelayMs: 2000, // wait after silence before STT
-	profanityFilter: false,
-	key: process.env.GSPEECH_V2_KEY, // own API key (recommended)
-	resolveSpeech: async (monoBuffer, opts) => "custom transcript",
-	onVoiceChange: async ({ userId, guildId, current }) => {
-		// return partial overrides per session
-		return { lang: "vi-VN" };
-	},
-});
-```
-
-Listen for results:
+	async beforePlay(context: ExtensionContext, request: any) {
+		console.log(`Playing: ${request.query}`);
+		return { handled: false };
+	}
 
-```typescript
-manager.on("voiceCreate", (player, evt) => {
-	console.log(evt.userId, evt.content, evt.channelId, evt.guildId);
-	// evt.user and evt.channel if client was passed
-});
+	async afterPlay(context: ExtensionContext, payload: any) {
+		if (payload.success) {
+			console.log(`Successfully played ${payload.tracks?.length} tracks`);
+		}
+	}
+}
 ```
 
-#### lyricsExt — Auto lyrics
+### 6. Event Handling
 
 ```typescript
-import { lyricsExt } from "@ziplayer/extension";
-
-new lyricsExt(null, {
-	provider: "lrclib", // "lrclib" | "lyricsovh"
-	includeSynced: true, // prefer LRC synced lyrics
-	autoFetchOnTrackStart: true,
-	sanitizeTitle: true, // clean title before querying
-	maxLength: 32_000,
+manager.on("trackStart", (player, track) => {
+	console.log(`Now playing: ${track.title}`);
 });
-```
-
-Events:
 
-```typescript
-manager.on("lyricsCreate", (player, track, result) => {
-	console.log(result.text); // plain text
-	console.log(result.synced); // LRC string
+manager.on("queueEnd", (player) => {
+	console.log("Queue finished!");
 });
 
-manager.on("lyricsChange", (player, track, result) => {
-	// Fires per line when synced lyrics available
-	console.log(result.current, result.previous, result.next);
-	console.log(result.lineIndex, result.timeMs);
+manager.on("playerError", (player, error, track) => {
+	console.error(`Error on ${track?.title}:`, error.message);
 });
-```
 
-#### lavalinkExt — Lavalink server
-
-```typescript
-import { lavalinkExt } from "@ziplayer/extension";
-
-new lavalinkExt(null, {
-	nodes: [{ host: "localhost", port: 2333, password: "youshallnotpass", secure: false }],
-	client: discordClient, // discord.js Client (for voice events)
-	userId: "botUserId", // auto-detected from client if omitted
-	searchPrefix: "scsearch", // default search prefix for Lavalink
-	nodeSort: "players", // "players" | "cpu" | "memory" | "random"
-	requestTimeoutMs: 10_000,
-	updateInterval: 5_000,
-	debug: false,
+manager.on("playerSaved", (guildId) => {
+	console.log(`Saved state for guild ${guildId}`);
 });
-```
-
-### Writing a custom extension
-
-```typescript
-import { BaseExtension, Player, ExtensionContext } from "ziplayer";
 
-export class MyExtension extends BaseExtension {
-	name = "myExtension";
-	version = "1.0.0";
-	player: Player | null = null;
-
-	// Called to check if extension should activate for this player
-	active(ctx: { player: Player; manager: any }): boolean {
-		if (!this.player) this.player = ctx.player;
-		return true;
-	}
-
-	// Called once when registered to a player
-	onRegister(ctx: ExtensionContext): void {
-		ctx.player.on("trackStart", (track) => {
-			console.log("Custom ext: now playing", track.title);
-		});
-	}
-
-	// Called when player is destroyed
-	onDestroy(ctx: ExtensionContext): void {
-		// cleanup
-	}
-
-	// Intercept play requests BEFORE they resolve
-	async beforePlay(ctx, payload) {
-		// Can mutate payload.query, return tracks, or set handled: true
-		return undefined; // let normal flow continue
-	}
-
-	// Called AFTER play resolves (success or failure)
-	async afterPlay(ctx, payload) {
-		console.log("Played:", payload.tracks?.length, "tracks, success:", payload.success);
-	}
-
-	// Provide search results (skips plugins if returns tracks)
-	async provideSearch(ctx, { query, requestedBy }) {
-		return null; // return SearchResult to intercept
-	}
-
-	// Provide audio stream (skips plugins if returns stream)
-	async provideStream(ctx, { track }) {
-		return null; // return StreamInfo to intercept
-	}
-}
-```
-
----
-
-## 9. Audio Filters
-
-ZiPlayer applies FFmpeg filters in real-time. Filters are re-applied immediately to the current track.
-
-### Predefined filters
-
-| Name          | Category | Description            |
-| ------------- | -------- | ---------------------- |
-| `bassboost`   | eq       | Bass boost             |
-| `trebleboost` | eq       | Treble boost           |
-| `normalize`   | volume   | Loudness normalization |
-| `nightcore`   | speed    | Speed + pitch up       |
-| `lofi`        | speed    | Slow + lo-fi effect    |
-| `vaporwave`   | speed    | Vaporwave aesthetic    |
-| `8D`          | effect   | 8D surround effect     |
-| `echo`        | effect   | Echo/reverb            |
-| `reverb`      | effect   | Reverb                 |
-| `chorus`      | effect   | Chorus                 |
-| `karaoke`     | vocal    | Remove vocals          |
-| `slow`        | speed    | 0.5× speed             |
-| `fast`        | speed    | 2.0× speed             |
-| `mono`        | channel  | Mono output            |
-| `compressor`  | dynamics | Dynamic compression    |
-| `limiter`     | dynamics | Limiter                |
-
-### Usage
-
-```typescript
-// Apply
-await player.filter.applyFilter("bassboost");
-await player.filter.applyFilter("nightcore");
-
-// Custom filter
-await player.filter.applyFilter({
-	name: "custom",
-	ffmpegFilter: "volume=1.5,treble=g=5",
-	description: "Volume + treble boost",
-	category: "custom",
+manager.on("stats", (stats) => {
+	console.log(`Active players: ${stats.activePlayers}`);
 });
-
-// Multiple at once
-await player.filter.applyFilters(["bassboost", "normalize"]);
-
-// Remove
-await player.filter.removeFilter("bassboost");
-await player.filter.clearAll();
-
-// Query
-player.filter.hasFilter("nightcore"); // boolean
-player.filter.getActiveFilters(); // AudioFilter[]
-player.filter.getFilterString(); // raw FFmpeg string
-player.filter.getAvailableFilters(); // all predefined
-player.filter.getFiltersByCategory("eq");
 ```
 
 ---
 
-## 10. Events Reference
+## 🐛 Troubleshooting
 
-### Manager events (recommended — all player events forwarded here)
+### Common Issues
 
-```typescript
-manager.on("trackStart", (player, track) => {});
-manager.on("trackEnd", (player, track) => {});
-manager.on("queueEnd", (player) => {});
-manager.on("willPlay", (player, track, upcomingTracks) => {});
-manager.on("queueAdd", (player, track) => {});
-manager.on("queueAddList", (player, tracks) => {});
-manager.on("queueRemove", (player, track, index) => {});
-manager.on("playerPause", (player, track) => {});
-manager.on("playerResume", (player, track) => {});
-manager.on("playerStop", (player) => {});
-manager.on("playerDestroy", (player) => {});
-manager.on("playerError", (player, error, track?) => {});
-manager.on("connectionError", (player, error) => {});
-manager.on("volumeChange", (player, oldVolume, newVolume) => {});
-manager.on("ttsStart", (player, { track }) => {});
-manager.on("ttsEnd", (player) => {});
-manager.on("voiceCreate", (player, evt) => {}); // voiceExt
-manager.on("lyricsCreate", (player, track, result) => {}); // lyricsExt
-manager.on("lyricsChange", (player, track, result) => {}); // lyricsExt
-manager.on("debug", (message, ...args) => {});
-```
+| Issue                      | Solution                                                    |
+| -------------------------- | ----------------------------------------------------------- |
+| **No audio**               | Check `player.connection` exists, voice channel permissions |
+| **Plugin not working**     | Verify `canHandle()` returns true, check priority           |
+| **Filters not applying**   | Call `refreshPlayerResource(true)` after applying           |
+| **Persistence not saving** | Check `enabled: true`, file path writable                   |
+| **Memory leak**            | Enable `autoCleanup`, call `player.destroy()` when done     |
+| **Rate limiting**          | Use search cache, increase `extractorTimeout`               |
 
-### Direct player events
+### Debug Mode
 
 ```typescript
-player.on("trackStart", (track) => {});
-player.on("trackEnd", (track) => {});
-player.on("queueEnd", () => {});
-player.on("willPlay", (track, upcomingTracks) => {});
-player.on("playerError", (error, track?) => {});
-player.on("ttsStart", ({ track }) => {});
-player.on("ttsEnd", () => {});
-player.on("debug", (message) => {});
-// ... same names as manager, minus the leading `player` param
-```
-
----
-
-## 11. TypeScript Types
-
-```typescript
-interface Track {
-	id: string;
-	title: string;
-	url: string;
-	duration: number; // milliseconds (some plugins use seconds — check source)
-	thumbnail?: string;
-	requestedBy: string;
-	source: string; // plugin name: "youtube" | "soundcloud" | "tts" | ...
-	metadata?: Record<string, any>;
-}
+// Enable debug logging
+manager.on("debug", (message) => {
+	console.log("[DEBUG]", message);
+});
 
-interface SearchResult {
-	tracks: Track[];
-	playlist?: { name: string; url: string; thumbnail?: string };
+// Or check debug flag
+if (manager.debugEnabled) {
+	// Debug-specific logic
 }
+```
 
-interface StreamInfo {
-	stream: Readable;
-	type: "webm/opus" | "ogg/opus" | "arbitrary";
-	metadata?: Record<string, any>;
-}
+### Performance Tips
 
-type LoopMode = "off" | "track" | "queue";
-
-interface AudioFilter {
-	name: string;
-	ffmpegFilter: string;
-	description: string;
-	category?: string;
-}
-```
+1. **Enable caching** for search and stream results
+2. **Use persistence** to avoid re-fetching on restart
+3. **Set appropriate timeouts** based on network conditions
+4. **Batch operations** when modifying queue
+5. **Destroy players** when no longer needed
 
 ---
 
-## 12. Common Patterns & Recipes
+## 📝 Code Examples
 
-### Basic Discord bot setup (TypeScript)
+### Full Bot Example
 
 ```typescript
-import { Client, GatewayIntentBits } from "discord.js";
+import { Client, GatewayIntentBits, EmbedBuilder } from "discord.js";
 import { PlayerManager } from "ziplayer";
-import { YouTubePlugin, SoundCloudPlugin, SpotifyPlugin } from "@ziplayer/plugin";
+import { YouTubePlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
 
 const client = new Client({
 	intents: [
@@ -731,226 +470,138 @@ const client = new Client({
 });
 
 const manager = new PlayerManager({
-	plugins: [new YouTubePlugin({}), new SoundCloudPlugin(), new SpotifyPlugin()],
-});
-
-manager.on("trackStart", (player, track) => {
-	(player.userdata?.channel as any)?.send(`▶ **${track.title}**`);
+	plugins: [new YouTubePlugin(), new SpotifyPlugin(), new TTSPlugin()],
+	autoCleanup: true,
+	extractorTimeout: 30000,
+	persistence: {
+		enabled: true,
+		filePath: "./player_data",
+		saveInterval: 60000,
+		autoLoad: true,
+	},
 });
 
 client.on("messageCreate", async (msg) => {
-	if (msg.author.bot || !msg.guildId) return;
-	if (!msg.content.startsWith("!play ")) return;
-
-	const query = msg.content.slice(6).trim();
-	const voiceChannel = (msg.member as any)?.voice?.channel;
-	if (!voiceChannel) return msg.reply("Join a voice channel first!");
-
-	const player = await manager.create(msg.guildId, {
-		leaveOnEnd: true,
-		leaveTimeout: 30_000,
-		userdata: { channel: msg.channel },
-	});
-
-	if (!player.connection) await player.connect(voiceChannel);
-	await player.play(query, msg.author.id);
-	msg.reply(`Queued: **${query}**`);
+	if (!msg.guildId || msg.author.bot) return;
+
+	const args = msg.content.slice(1).split(" ");
+	const command = args[0].toLowerCase();
+	const query = args.slice(1).join(" ");
+
+	const player = await manager.create(msg.guildId);
+	const voiceChannel = msg.member?.voice.channel;
+
+	switch (command) {
+		case "play":
+			if (!voiceChannel) return msg.reply("Join a voice channel!");
+			if (!player.connection) await player.connect(voiceChannel);
+			await player.play(query, msg.author.id);
+			break;
+
+		case "pause":
+			player.pause();
+			break;
+
+		case "resume":
+			player.resume();
+			break;
+
+		case "skip":
+			player.skip();
+			break;
+
+		case "stop":
+			player.stop();
+			break;
+
+		case "volume":
+			const vol = parseInt(query);
+			if (isNaN(vol)) return msg.reply("Volume must be a number!");
+			player.setVolume(vol);
+			break;
+
+		case "queue":
+			const tracks = player.upcomingTracks.slice(0, 10);
+			const embed = new EmbedBuilder()
+				.setTitle("Queue")
+				.setDescription(tracks.map((t, i) => `${i + 1}. ${t.title}`).join("\n") || "Empty");
+			msg.reply({ embeds: [embed] });
+			break;
+
+		case "nowplaying":
+			const track = player.currentTrack;
+			if (!track) return msg.reply("Nothing playing!");
+
+			const progress = player.getProgressBar({ size: 15 });
+			const time = player.getTime();
+
+			const embed = new EmbedBuilder()
+				.setTitle(track.title)
+				.setURL(track.url)
+				.setThumbnail(track.thumbnail)
+				.setDescription(`\`${progress}\`\n${time.formatted.current} / ${time.formatted.total}`);
+			msg.reply({ embeds: [embed] });
+			break;
+	}
 });
 
 client.login(process.env.DISCORD_TOKEN);
 ```
 
-### TTS with music interrupt
-
-```typescript
-const player = await manager.create(guildId, {
-	tts: { createPlayer: true, interrupt: true, volume: 100 },
-});
-
-// This pauses music, speaks, then auto-resumes:
-await player.play("tts: Now playing your requested song!", userId);
-```
-
-### Voice-controlled bot
+---
 
-```typescript
-manager.on("voiceCreate", (player, evt) => {
-	const text = evt.content.toLowerCase();
-
-	if (text.includes("skip")) player.skip();
-	else if (text.includes("pause")) player.pause();
-	else if (text.includes("resume")) player.resume();
-	else if (text.includes("stop")) player.stop();
-	else if (text.startsWith("play ")) {
-		player.play(text.slice(5), evt.userId);
-	}
-});
-```
+## 🔗 Quick Reference
 
-### Autoplay (related tracks)
+### Import Paths
 
 ```typescript
-player.queue.autoPlay(true);
-// When queue empties, willNextTrack() is used (set by generateWillNext internally)
-// ZiPlayer auto-fetches related tracks via pluginManager.getRelatedTracks()
-```
+// Core
+import { PlayerManager, Player, Queue } from "ziplayer";
 
-### Loop patterns
+// Types
+import type { Track, SearchResult, LoopMode, StreamInfo } from "ziplayer";
 
-```typescript
-player.loop("track"); // repeat current song forever
-player.loop("queue"); // loop entire playlist
-player.loop("off"); // no loop (default)
-```
+// Plugins (external package)
+import { YouTubePlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
 
-### Progress bar in embeds
+// infinity plugin support stream audio from YouTube, TikTok, Instagram, Twitter/X, SoundCloud, Reddit, Twitch, Bilibili, and 1000+ other sites
 
-```typescript
-manager.on("trackStart", (player, track) => {
-	const progress = player.getProgressBar({
-		size: 20,
-		barChar: "▬",
-		progressChar: "🔘",
-	});
-	// "0:00 | ▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬▬🔘 | 3:32"
-});
-```
-
-### Search without playing
-
-```typescript
-const result = await player.search("lofi hip hop", userId);
-// result.tracks[0].title, .duration, .thumbnail, .url, etc.
+import { InfinityPlugin } from "@ziplayer/infinity";
 
-// Or via manager (no player needed):
-const result = await manager.search("lofi hip hop", userId);
+// Extensions (external package)
+import { voiceExt, lyricsExt, lavalinkExt } from "@ziplayer/extension";
 ```
 
-### Custom extension for auto-announce
+### Type Definitions
 
 ```typescript
-class AutoAnnounceExt extends BaseExtension {
-	name = "autoAnnounce";
-	version = "1.0.0";
-	player: Player | null = null;
-
-	active(ctx: any): boolean {
-		if (!this.player) this.player = ctx.player;
-		const p = this.player!;
-		if ((p as any).__announced) return true;
-		(p as any).__announced = true;
-
-		p.on("trackStart", (track) => {
-			p.userdata?.channel?.send(`▶ Now playing: **${track.title}**`);
-		});
-		p.on("queueEnd", () => {
-			p.userdata?.channel?.send("Queue finished.");
-		});
-		return true;
-	}
+interface Track {
+	id: string;
+	title: string;
+	url: string;
+	source: string;
+	duration: number;
+	thumbnail?: string;
+	requestedBy?: string;
+	isLive?: boolean;
 }
 
-const manager = new PlayerManager({ extensions: [new AutoAnnounceExt()] });
-const player = await manager.create(guildId, { extensions: ["autoAnnounce"] });
-```
-
-### Getting global manager from anywhere
-
-```typescript
-import { getManager, getPlayer } from "ziplayer";
-
-const manager = getManager(); // PlayerManager | null
-const player = getPlayer("guild-id"); // Player | null
-```
-
----
-
-## 13. Error Handling
-
-### Recommended pattern
+type LoopMode = "off" | "track" | "queue";
 
-```typescript
-try {
-	await player.connect(voiceChannel);
-	const success = await player.play(query, userId);
-	if (!success) channel.send("❌ Could not play that.");
-} catch (err) {
-	channel.send(`❌ Error: ${(err as Error).message}`);
+interface SearchResult {
+	tracks: Track[];
+	playlist?: { name: string; url?: string };
 }
-
-manager.on("playerError", (player, error, track) => {
-	console.error(`[${player.guildId}] Error on "${track?.title}":`, error.message);
-	// ZiPlayer auto-skips to next track after playerError
-});
-
-manager.on("connectionError", (player, error) => {
-	console.error(`[${player.guildId}] Voice error:`, error.message);
-	player.destroy();
-});
-```
-
-### Plugin timeout
-
-```typescript
-// Per-player timeout for plugin operations:
-const player = await manager.create(guildId, {
-	extractorTimeout: 15_000, // 15 seconds (default: 50000)
-});
 ```
 
 ---
 
-## 14. Anti-Patterns to Avoid
+## 📖 Additional Resources
 
-| ❌ Wrong                                               | ✅ Correct                                 |
-| ------------------------------------------------------ | ------------------------------------------ |
-| Reusing `player` after `player.destroy()`              | Call `manager.create()` again              |
-| Creating a new `PlayerManager` per command             | One manager for the whole bot              |
-| Not awaiting `player.connect()` before `player.play()` | Always `await connect()` first             |
-| Ignoring `playerError` events                          | Always attach an error handler             |
-| Calling `player.play()` with empty string              | Validate input before calling              |
-| Setting `leaveTimeout: 0`                              | Use `leaveOnEnd: false` instead            |
-| Using `player.queue.next()` directly                   | Use `player.skip()` to preserve events     |
-| Forgetting `disconnect()` on bot shutdown              | Call `manager.destroy()` in SIGINT handler |
-
-```typescript
-// Clean shutdown
-process.on("SIGINT", () => {
-	manager.destroy();
-	client.destroy();
-	process.exit(0);
-});
-```
+- [GitHub Repository](https://github.com/ZiProject/ZiPlayer)
+- [npm Package](https://www.npmjs.com/package/ziplayer)
+- [Examples Folder](https://github.com/ZiProject/ZiPlayer/tree/main/examples)
 
 ---
 
-## Quick Reference Card
-
-```
-CREATE    manager.create(guildId, opts) → Player
-CONNECT   player.connect(voiceChannel)
-PLAY      player.play(query | Track | SearchResult | null, userId?)
-PAUSE     player.pause()
-RESUME    player.resume()
-SKIP      player.skip(index?)
-PREVIOUS  player.previous()
-STOP      player.stop()           // also clears queue
-SEEK      player.seek(ms)
-VOLUME    player.setVolume(0–200)
-LOOP      player.loop("off"|"track"|"queue")
-SHUFFLE   player.shuffle()
-AUTOPLAY  player.autoPlay(bool)
-DESTROY   player.destroy()
-
-FILTER    player.filter.applyFilter("bassboost")
-          player.filter.removeFilter("nightcore")
-          player.filter.clearAll()
-
-QUEUE     player.queue.size / isEmpty / currentTrack / nextTrack
-          player.queue.add(track) / insert(track, 0) / remove(index)
-          player.queue.getTracks() / getTrack(index)
-
-INFO      player.currentTrack / previousTrack / upcomingTracks
-          player.getProgressBar() / getTime()
-          player.isPlaying / isPaused / volume
-```
+_This guide is maintained for AI assistants and developers. For questions or contributions, please open an issue on GitHub._