ziplayer 0.2.7 → 0.3.1

package/AI-Guide.md

@@ -1,956 +1,624 @@
-# ZiPlayer — AI Developer Guide
-
-<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.
-
----
-
-## 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. Package 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           |
-
----
-
-## 2. Installation
-
-```bash
-npm install ziplayer @ziplayer/plugin @ziplayer/extension @ziplayer/infinity @discordjs/voice discord.js opusscript
-```
-
----
-
-## 3. Core 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
-
-```
-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
-```
-
----
-
-## 4. PlayerManager
-
-### Construction
-
-```typescript
-import { PlayerManager } from "ziplayer";
-import { YouTubePlugin, SoundCloudPlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
-import { InfinityPlugin } from "@ziplayer/infinity";
-import { voiceExt, lyricsExt } from "@ziplayer/extension";
-
-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 })],
-});
-```
-
-### Key methods
-
-| 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) |
-
-### PlayerManager options
-
-```typescript
-interface PlayerManagerOptions {
-	plugins?: SourcePluginLike[];
-	extensions?: any[];
-	extractorTimeout?: number; // ms, default 10000
-}
-```
-
----
-
-## 5. Player
-
-### 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
-	},
-});
-```
-
-### Connecting
-
-```typescript
-await player.connect(voiceChannel); // discord.js VoiceChannel
-```
-
-### Playing
-
-```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);
-```
-
-### Playback controls
-
-```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)
-```
-
-### Information
-
-```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" }],
-});
-```
-
-### Inserting tracks mid-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);
-```
-
-### Removing a track
-
-```typescript
-const removed = player.queue.remove(2); // removes track at index 2
-```
-
-### Destroying
-
-```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.
-```
-
-### Extension management
-
-```typescript
-player.attachExtension(myExt);
-player.detachExtension(myExt);
-player.getExtensions(); // readonly BaseExtension[]
-```
-
-### Filter management (see §9)
-
-```typescript
-await player.filter.applyFilter("bassboost");
-await player.filter.removeFilter("bassboost");
-await player.filter.clearAll();
-player.filter.getActiveFilters(); // AudioFilter[]
-player.filter.hasFilter("nightcore"); // boolean
-player.filter.getAvailableFilters();
-player.filter.getFiltersByCategory("eq");
-```
-
----
-
-## 6. Queue
-
-Access via `player.queue`.
-
-### Adding
-
-```typescript
-player.queue.add(track);
-player.queue.addMultiple([track1, track2]);
-player.queue.insert(track, 0); // 0 = next up
-player.queue.insertMultiple([t1, t2], 0);
-```
-
-### Removing / navigating
-
-```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
-
-```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
-```
-
-### 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
-```
-
----
-
-## 7. Plugins
-
-### Built-in plugins (`@ziplayer/plugin`)
-
-#### YouTubePlugin
-
-```typescript
-new YouTubePlugin({
-	searchLimit: 10, // max search results
-	// fallbackStream: fn(Track) => Promise<StreamInfo>
-	// fistStream: fn(Track) => Promise<StreamInfo>
-});
-```
-
-Handles: `youtube.com`, `youtu.be`, `music.youtube.com`, any free text search.
-
-#### SoundCloudPlugin
-
-```typescript
-new SoundCloudPlugin();
-```
-
-Handles: `soundcloud.com` URLs, free text search (if not a URL for another service).
-
-#### SpotifyPlugin
-
-```typescript
-new SpotifyPlugin();
-```
-
-Handles: `spotify:track:...`, `open.spotify.com/...` ⚠️ Metadata only — does NOT stream. Relies on YouTube/SoundCloud fallback for
-audio.
-
-#### TTSPlugin
-
-```typescript
-new TTSPlugin({
-	defaultLang: "vi", // language code
-	slow: false,
-	createStream: async (text, ctx) => {
-		// return Readable | URL string | Buffer
-	},
-});
-```
-
-Query formats:
-
-- `tts: <text>` — uses defaultLang
-- `tts:<lang>:<text>` — e.g., `tts:en:Hello`
-- `tts:<lang>:<slow>:<text>` — e.g., `tts:en:1:Hello` (slow=true)
-
-#### AttachmentsPlugin
-
-```typescript
-new AttachmentsPlugin({
-	maxFileSize: 25 * 1024 * 1024, // 25 MB
-	allowedExtensions: ["mp3", "wav", "ogg", "m4a", "flac"],
-	debug: false,
-});
-```
-
-Handles: Discord CDN URLs (`cdn.discordapp.com`), direct audio file URLs.
-
-### Writing a custom plugin
-
-```typescript
-import { BasePlugin, Track, SearchResult, StreamInfo } from "ziplayer";
-import { Readable } from "stream";
-
-export class MyRadioPlugin extends BasePlugin {
-	name = "myradio";
-	version = "1.0.0";
-	priority = 5; // lower = tried first in fallback; default 0
-
-	canHandle(query: string): boolean {
-		return query.startsWith("radio:");
-	}
-
-	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" };
-	}
-
-	// Optional: fallback when getStream fails
-	async getFallback(track: Track): Promise<StreamInfo> {
-		/* ... */
-	}
-
-	// 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[]> {
-		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.
-
-```typescript
-new MyPlugin({ priority: 10 }); // tried last in fallback
-```
-
----
-
-## 8. Extensions
-
-### Built-in extensions (`@ziplayer/extension`)
-
-#### 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:
-
-```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
-});
-```
-
-#### lyricsExt — Auto lyrics
-
-```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,
-});
-```
-
-Events:
-
-```typescript
-manager.on("lyricsCreate", (player, track, result) => {
-	console.log(result.text); // plain text
-	console.log(result.synced); // LRC string
-});
-
-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);
-});
-```
-
-#### 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,
-});
-```
-
-### 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",
-});
-
-// 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
-
-### Manager events (recommended — all player events forwarded here)
-
-```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) => {});
-```
-
-### Direct player events
-
-```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>;
-}
-
-interface SearchResult {
-	tracks: Track[];
-	playlist?: { name: string; url: string; thumbnail?: string };
-}
-
-interface StreamInfo {
-	stream: Readable;
-	type: "webm/opus" | "ogg/opus" | "arbitrary";
-	metadata?: Record<string, any>;
-}
-
-type LoopMode = "off" | "track" | "queue";
-
-interface AudioFilter {
-	name: string;
-	ffmpegFilter: string;
-	description: string;
-	category?: string;
-}
-```
-
----
-
-## 12. Common Patterns & Recipes
-
-### Basic Discord bot setup (TypeScript)
-
-```typescript
-import { Client, GatewayIntentBits } from "discord.js";
-import { PlayerManager } from "ziplayer";
-import { YouTubePlugin, SoundCloudPlugin, SpotifyPlugin } from "@ziplayer/plugin";
-
-const client = new Client({
-	intents: [
-		GatewayIntentBits.Guilds,
-		GatewayIntentBits.GuildVoiceStates,
-		GatewayIntentBits.GuildMessages,
-		GatewayIntentBits.MessageContent,
-	],
-});
-
-const manager = new PlayerManager({
-	plugins: [new YouTubePlugin({}), new SoundCloudPlugin(), new SpotifyPlugin()],
-});
-
-manager.on("trackStart", (player, track) => {
-	(player.userdata?.channel as any)?.send(`▶ **${track.title}**`);
-});
-
-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}**`);
-});
-
-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);
-	}
-});
-```
-
-### Autoplay (related tracks)
-
-```typescript
-player.queue.autoPlay(true);
-// When queue empties, willNextTrack() is used (set by generateWillNext internally)
-// ZiPlayer auto-fetches related tracks via pluginManager.getRelatedTracks()
-```
-
-### Loop patterns
-
-```typescript
-player.loop("track"); // repeat current song forever
-player.loop("queue"); // loop entire playlist
-player.loop("off"); // no loop (default)
-```
-
-### Progress bar in embeds
-
-```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.
-
-// Or via manager (no player needed):
-const result = await manager.search("lofi hip hop", userId);
-```
-
-### Custom extension for auto-announce
-
-```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;
-	}
-}
-
-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
-
-```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}`);
-}
-
-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
-
-| ❌ 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);
-});
-```
-
----
-
-## 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
-```
+# 🤖 AI Guide for ZiPlayer
+
+A comprehensive guide for AI assistants and developers working with ZiPlayer - a powerful Discord music player library.
+
+## 📋 Table of Contents
+
+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)
+
+---
+
+## 🎯 Project Overview
+
+**ZiPlayer** is an extensible Discord music engine built on `@discordjs/voice`.
+
+### Key Features
+
+- Plugin-driven architecture (YouTube, SoundCloud, Spotify, TTS)
+- Extension system (voice commands, lyrics, Lavalink)
+- Audio filters (bassboost, nightcore, etc.)
+- Smart caching and fallback system
+
+### Tech Stack
+
+- TypeScript
+- `@discordjs/voice` for audio
+- FFmpeg for audio processing
+- Node.js EventEmitter for events
+
+---
+
+### Component Responsibilities
+
+| Component          | Responsibility                                     |
+| ------------------ | -------------------------------------------------- |
+| `PlayerManager`    | Creates/manages players, global event bus          |
+| `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                               |
+| `StreamManager`    | Centralized stream management/Auto cleanup         |
+
+---
+
+## 🧠 Core Concepts
+
+### 1. Player Lifecycle
+
+```typescript
+// 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();
+```
+
+### 2. Queue Loop Modes
+
+```typescript
+player.loop("off"); // No loop (default)
+player.loop("track"); // Repeat current track
+player.loop("queue"); // Repeat entire queue
+```
+
+### 3. Event Flow
+
+```
+trackStart → playing → trackEnd → playNext → (loop/autoplay)
+                                    ↓
+                              queueEnd → leave
+```
+
+### 4. Plugin Priority & Fallback
+
+```typescript
+// 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
+
+| 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 |
+
+---
+
+## 📚 API Reference
+
+### PlayerManager
+
+#### Constructor Options
+
+```typescript
+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
+}
+```
+
+#### Player Runtime Options (Performance Profile)
+
+```typescript
+interface PlayerOptions {
+	lowPerformance?: boolean; // Default: false (or true when quality === "low")
+	preload?: {
+		enabled?: boolean; // Default: true
+		autoDisableInLowPerformance?: boolean; // Default: true
+	};
+	crossfade?: {
+		enabled?: boolean; // Explicit on/off
+		autoEnable?: boolean; // Default: true when enabled is undefined
+		autoDisableInLowPerformance?: boolean; // Default: true
+		durationMs?: number; // Default: 5000
+	};
+	smartTransition?: {
+		enabled?: boolean;
+		genreAware?: boolean;
+		beatAlign?: boolean;
+		baseDurationMs?: number;
+		minDurationMs?: number;
+		maxDurationMs?: number;
+		genreDurations?: Record<string, number>;
+		beatAlignMaxWaitMs?: number;
+	};
+	antiStuck?: {
+		enabled?: boolean;
+		maxRetries?: number;
+		retryDelayMs?: number;
+		reusePreloadFirst?: boolean;
+		reduceQualityOnRetry?: boolean;
+		controlledSkipThreshold?: number;
+	};
+	loudnessNormalization?: {
+		enabled?: boolean;
+		targetLUFS?: number;
+		maxBoostDb?: number;
+		maxCutDb?: number;
+		limiterCeiling?: number;
+	};
+}
+```
+
+- If `lowPerformance=true`, preload and crossfade are auto-disabled by default.
+- `crossfade.autoEnable=true` allows crossfade to be enabled automatically when `crossfade.enabled` is not explicitly set.
+- You can still force behavior by setting `enabled` flags directly.
+- Runtime behavior: crossfade is used for next-track transitions and `skip()`.
+- Smart transition can tune fade by `metadata.genre` and beat-align by `metadata.bpm`.
+- Loudness normalization uses `metadata.lufs` with limiter ceiling protection.
+- Anti-stuck retries in-place before controlled skip to avoid skip storms.
+
+#### Key Methods
+
+| 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 |
+
+### Player
+
+#### Core Methods
+
+| 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.queueSize; // number
+player.isPlaying; // boolean
+player.isPaused; // boolean
+player.volume; // number
+player.upcomingTracks; // Track[]
+player.previousTracks; // Track[]
+player.relatedTracks; // Track[] | null
+```
+
+### Queue
+
+#### Methods
+
+| 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 |
+
+#### Properties
+
+```typescript
+queue.size; // number
+queue.isEmpty; // boolean
+queue.currentTrack; // Track | null
+queue.nextTrack; // Track | null
+queue.lastTrack; // Track | null
+queue.previousTracks; // Track[]
+```
+
+### FilterManager
+
+```typescript
+// Apply filters
+await player.filter.applyFilter("bassboost");
+await player.filter.applyFilters(["bassboost", "nightcore"]);
+
+// Available filters
+// bassboost, trebleboost, nightcore, lofi, vaporwave,
+// echo, reverb, chorus, karaoke, normalize, compressor, limiter
+
+// Clear filters
+await player.filter.clearAll();
+await player.filter.clear("bassboost");
+
+// Get current filters
+const filterString = player.filter.getFilterString(); // "bassboost,nightcore"
+```
+
+## 🔧 Common Patterns
+
+### 1. Basic Music Bot Setup
+
+```typescript
+import { Client, GatewayIntentBits } from "discord.js";
+import { PlayerManager } from "ziplayer";
+import { YouTubePlugin, SpotifyPlugin } from "@ziplayer/plugin";
+
+const client = new Client({
+	intents: [GatewayIntentBits.Guilds, GatewayIntentBits.GuildVoiceStates],
+});
+
+const manager = new PlayerManager({
+	plugins: [new YouTubePlugin(), new SpotifyPlugin()],
+	autoCleanup: true,
+});
+
+client.on("ready", async () => {
+	// Auto-load saved players
+	await manager.loadAllPlayers();
+});
+
+client.on("messageCreate", async (msg) => {
+	if (msg.content.startsWith("!play")) {
+		const player = await manager.create(msg.guildId);
+		const voiceChannel = msg.member?.voice.channel;
+
+		if (!player.connection) {
+			await player.connect(voiceChannel);
+		}
+
+		const query = msg.content.slice(6);
+		await player.play(query, msg.author.id);
+	}
+});
+
+const player = await manager.create(guildId, {
+	lowPerformance: false,
+	preload: { enabled: true, autoDisableInLowPerformance: true },
+	crossfade: { autoEnable: true, autoDisableInLowPerformance: true, durationMs: 5000 },
+	smartTransition: {
+		enabled: true,
+		genreAware: true,
+		beatAlign: true,
+		baseDurationMs: 5000,
+		genreDurations: { chill: 7000, edm: 2200 },
+	},
+	antiStuck: {
+		enabled: true,
+		maxRetries: 2,
+		retryDelayMs: 900,
+		reusePreloadFirst: true,
+		reduceQualityOnRetry: true,
+		controlledSkipThreshold: 3,
+	},
+	loudnessNormalization: {
+		enabled: true,
+		targetLUFS: -14,
+		limiterCeiling: 0.95,
+	},
+});
+```
+
+### 2. Progress Bar with Time Format
+
+```typescript
+// 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"
+
+// Progress bar
+const progressBar = player.getProgressBar({
+	size: 20,
+	barChar: "▬",
+	progressChar: "🔘",
+	timeFormat: "compact",
+	showPercentage: true,
+});
+// Output: "1:22:12 ▬▬▬▬▬▬▬▬▬🔘▬▬▬▬▬▬▬▬ 3:45:30 (36%)"
+```
+
+### 3. Queue Management Commands
+
+```typescript
+// Skip to specific track
+await player.skip(3); // Skip to index 3
+
+// Move track to front
+player.queue.move(5, 0);
+
+// Remove all tracks from specific source
+player.queue.removeWhere((t) => t.source === "soundcloud");
+
+// Jump back 2 tracks
+await player.queue.jumpToHistory(2);
+
+// Insert as next track
+await player.insert("song name", 0, userId);
+```
+
+### 4. Custom Plugin Implementation
+
+```typescript
+import { BasePlugin, Track, StreamInfo } from "ziplayer";
+
+class CustomPlugin extends BasePlugin {
+	name = "CustomPlugin";
+	priority = 5;
+
+	canHandle(query: string): boolean {
+		return query.startsWith("custom:");
+	}
+
+	async search(query: string, requestedBy: string): Promise<SearchResult> {
+		// Implementation
+		return { tracks: [] };
+	}
+
+	async getStream(track: Track, signal: AbortSignal): Promise<StreamInfo> {
+		// Return audio stream
+		return { stream: readableStream, type: "arbitrary" };
+	}
+
+	async getRelatedTracks(track: Track): Promise<Track[]> {
+		// Return recommendations
+		return [];
+	}
+}
+```
+
+### 5. Custom Extension Implementation
+
+```typescript
+import { BaseExtension, ExtensionContext } from "ziplayer";
+
+class LoggerExtension extends BaseExtension {
+	name = "Logger";
+	priority = 10;
+
+	async beforePlay(context: ExtensionContext, request: any) {
+		console.log(`Playing: ${request.query}`);
+		return { handled: false };
+	}
+
+	async afterPlay(context: ExtensionContext, payload: any) {
+		if (payload.success) {
+			console.log(`Successfully played ${payload.tracks?.length} tracks`);
+		}
+	}
+}
+```
+
+### 6. Event Handling
+
+```typescript
+manager.on("trackStart", (player, track) => {
+	console.log(`Now playing: ${track.title}`);
+});
+
+manager.on("queueEnd", (player) => {
+	console.log("Queue finished!");
+});
+
+manager.on("playerError", (player, error, track) => {
+	console.error(`Error on ${track?.title}:`, error.message);
+});
+
+manager.on("playerSaved", (guildId) => {
+	console.log(`Saved state for guild ${guildId}`);
+});
+
+manager.on("stats", (stats) => {
+	console.log(`Active players: ${stats.activePlayers}`);
+});
+```
+
+---
+
+## 🐛 Troubleshooting
+
+### Common Issues
+
+| 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           |
+| **Memory leak**          | Enable `autoCleanup`, call `player.destroy()` when done     |
+| **Rate limiting**        | Use search cache, increase `extractorTimeout`               |
+
+### Debug Mode
+
+```typescript
+// Enable debug logging
+manager.on("debug", (message) => {
+	console.log("[DEBUG]", message);
+});
+
+// Or check debug flag
+if (manager.debugEnabled) {
+	// Debug-specific logic
+}
+```
+
+### Performance Tips
+
+1. **Enable caching** for search and stream results
+2. **Set appropriate timeouts** based on network conditions
+3. **Batch operations** when modifying queue
+4. **Destroy players** when no longer needed
+
+---
+
+## 📝 Code Examples
+
+### Full Bot Example
+
+```typescript
+import { Client, GatewayIntentBits, EmbedBuilder } from "discord.js";
+import { PlayerManager } from "ziplayer";
+import { YouTubePlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
+
+const client = new Client({
+	intents: [
+		GatewayIntentBits.Guilds,
+		GatewayIntentBits.GuildVoiceStates,
+		GatewayIntentBits.GuildMessages,
+		GatewayIntentBits.MessageContent,
+	],
+});
+
+const manager = new PlayerManager({
+	plugins: [new YouTubePlugin(), new SpotifyPlugin(), new TTSPlugin()],
+	autoCleanup: true,
+	extractorTimeout: 30000,
+});
+
+client.on("messageCreate", async (msg) => {
+	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);
+```
+
+---
+
+## 🔗 Quick Reference
+
+### Import Paths
+
+```typescript
+// Core
+import { PlayerManager, Player, Queue } from "ziplayer";
+
+// Types
+import type { Track, SearchResult, LoopMode, StreamInfo } from "ziplayer";
+
+// Plugins (external package)
+import { YouTubePlugin, SpotifyPlugin, TTSPlugin } from "@ziplayer/plugin";
+
+// infinity plugin support stream audio from YouTube, TikTok, Instagram, Twitter/X, SoundCloud, Reddit, Twitch, Bilibili, and 1000+ other sites
+
+import { InfinityPlugin } from "@ziplayer/infinity";
+
+// Extensions (external package)
+import { voiceExt, lyricsExt, lavalinkExt } from "@ziplayer/extension";
+```
+
+### Type Definitions
+
+```typescript
+interface Track {
+	id: string;
+	title: string;
+	url: string;
+	source: string;
+	duration: number;
+	thumbnail?: string;
+	requestedBy?: string;
+	isLive?: boolean;
+}
+
+type LoopMode = "off" | "track" | "queue";
+
+interface SearchResult {
+	tracks: Track[];
+	playlist?: { name: string; url?: string };
+}
+```
+
+---
+
+## 📖 Additional Resources
+
+- [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)
+
+---
+
+_This guide is maintained for AI assistants and developers. For questions or contributions, please open an issue on GitHub._