streamify-audio 2.0.0

package/docs/discord/manager.md

@@ -0,0 +1,180 @@
+# Manager
+
+The Manager handles player creation, searching, and playlist loading.
+
+## Creating a Manager
+
+```javascript
+const Streamify = require('streamify-audio');
+
+const manager = new Streamify.Manager(client, {
+    ytdlpPath: '/usr/local/bin/yt-dlp',
+    ffmpegPath: '/usr/bin/ffmpeg',
+    cookiesPath: './cookies.txt',
+    spotify: {
+        clientId: process.env.SPOTIFY_CLIENT_ID,
+        clientSecret: process.env.SPOTIFY_CLIENT_SECRET
+    }
+});
+```
+
+See [Configuration](../configuration.md) for all options.
+
+## Methods
+
+### create(guildId, voiceChannelId, textChannelId)
+
+Creates or retrieves a player for a guild.
+
+```javascript
+const player = await manager.create(
+    message.guild.id,
+    voiceChannel.id,
+    message.channel.id
+);
+```
+
+If a player already exists for the guild, returns the existing player. If the voice channel differs, disconnects and reconnects.
+
+### get(guildId)
+
+Gets an existing player without creating one.
+
+```javascript
+const player = manager.get(message.guild.id);
+if (!player) {
+    return message.reply('No player in this server.');
+}
+```
+
+### destroy(guildId)
+
+Destroys a player and disconnects from voice.
+
+```javascript
+manager.destroy(message.guild.id);
+```
+
+### destroyAll()
+
+Destroys all players. Useful for graceful shutdown.
+
+```javascript
+process.on('SIGINT', () => {
+    manager.destroyAll();
+    process.exit();
+});
+```
+
+### search(query, options?)
+
+Searches for tracks.
+
+```javascript
+// Basic search (YouTube)
+const result = await manager.search('never gonna give you up');
+
+// With options
+const result = await manager.search('never gonna give you up', {
+    source: 'spotify',  // youtube, spotify, soundcloud
+    limit: 10
+});
+
+// Result
+{
+    loadType: 'search',  // search, empty, error
+    tracks: [{
+        id: 'dQw4w9WgXcQ',
+        title: 'Rick Astley - Never Gonna Give You Up',
+        author: 'Rick Astley',
+        duration: 213,
+        thumbnail: 'https://...',
+        uri: 'https://youtube.com/...',
+        source: 'youtube'
+    }]
+}
+```
+
+### resolve(query)
+
+Resolves a URL or falls back to search.
+
+```javascript
+// URL - loads directly
+const result = await manager.resolve('https://youtube.com/watch?v=dQw4w9WgXcQ');
+// { loadType: 'track', tracks: [track] }
+
+// Search query - searches
+const result = await manager.resolve('never gonna give you up');
+// { loadType: 'search', tracks: [...] }
+```
+
+### loadPlaylist(url)
+
+Loads a playlist or album.
+
+```javascript
+// YouTube playlist
+const result = await manager.loadPlaylist('https://youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf');
+
+// Spotify playlist
+const result = await manager.loadPlaylist('https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M');
+
+// Spotify album
+const result = await manager.loadPlaylist('https://open.spotify.com/album/4LH4d3cOWNNsVw41Gqt2kv');
+
+// Result
+{
+    loadType: 'playlist',
+    playlist: {
+        id: 'PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf',
+        title: 'My Playlist',
+        author: 'User',
+        thumbnail: 'https://...',
+        source: 'youtube'
+    },
+    tracks: [...]
+}
+```
+
+### getRelated(track, limit?)
+
+Gets related tracks for autoplay.
+
+```javascript
+const result = await manager.getRelated(currentTrack, 5);
+// { tracks: [...] }
+```
+
+### getStats()
+
+Gets manager statistics.
+
+```javascript
+const stats = manager.getStats();
+// {
+//     players: 5,
+//     playingPlayers: 3,
+//     memory: { heapUsed: 52428800, ... }
+// }
+```
+
+## Events
+
+```javascript
+manager.on('playerCreate', (player) => {
+    console.log(`Player created: ${player.guildId}`);
+});
+
+manager.on('playerDestroy', (player) => {
+    console.log(`Player destroyed: ${player.guildId}`);
+});
+```
+
+## Properties
+
+```javascript
+manager.players      // Map<guildId, Player>
+manager.client       // Discord.js client
+manager.config       // Resolved configuration
+```

package/docs/discord/player.md

@@ -0,0 +1,180 @@
+# Player
+
+The Player handles playback, filters, and voice connection for a single guild.
+
+## Getting a Player
+
+```javascript
+// Create new or get existing
+const player = await manager.create(guildId, voiceChannelId, textChannelId);
+
+// Get existing only
+const player = manager.get(guildId);
+```
+
+## Playback Methods
+
+### play(track)
+
+Plays a track immediately. If something is playing, adds to queue and skips.
+
+```javascript
+const result = await manager.search('never gonna give you up');
+await player.play(result.tracks[0]);
+```
+
+### pause()
+
+Pauses playback and destroys the stream to save resources.
+
+```javascript
+player.pause();
+```
+
+### resume()
+
+Resumes playback by recreating the stream and seeking to the saved position.
+
+```javascript
+await player.resume();
+```
+
+### skip()
+
+Skips to the next track in queue.
+
+```javascript
+await player.skip();
+```
+
+### previous()
+
+Goes back to the previous track.
+
+```javascript
+await player.previous();
+```
+
+### stop()
+
+Stops playback and clears the queue.
+
+```javascript
+player.stop();
+```
+
+### seek(positionMs)
+
+Seeks to a position in milliseconds.
+
+```javascript
+await player.seek(30000);  // Seek to 30 seconds
+```
+
+## Volume
+
+```javascript
+// Set volume (0-200)
+player.setVolume(80);
+
+// Get current volume
+console.log(player.volume);  // 80
+```
+
+## Filters
+
+```javascript
+// Set a filter
+await player.setFilter('bass', 10);
+await player.setFilter('nightcore', true);
+
+// Clear all filters
+await player.clearFilters();
+
+// Get current filters
+console.log(player.filters);  // { bass: 10, nightcore: true }
+```
+
+See [Filters](../filters.md) for all available filters.
+
+## Loop Modes
+
+```javascript
+player.setLoop('off');     // No looping
+player.setLoop('track');   // Loop current track
+player.setLoop('queue');   // Loop entire queue
+```
+
+## Toggles
+
+```javascript
+// Autoplay (play related tracks when queue ends)
+player.setAutoplay(true);
+player.setAutoplay(false);
+
+// Auto-pause (pause when channel empty)
+player.setAutoPause(true);
+player.setAutoPause(false);
+```
+
+## Connection
+
+```javascript
+// Connect to voice
+await player.connect();
+
+// Disconnect (keeps player)
+player.disconnect();
+
+// Destroy player completely
+player.destroy();
+```
+
+## State Properties
+
+```javascript
+player.connected    // true if connected to voice
+player.playing      // true if playing (not paused)
+player.paused       // true if paused
+player.position     // Current position in ms
+player.volume       // Current volume (0-200)
+player.filters      // Current filters object
+
+player.guildId          // Guild ID
+player.voiceChannelId   // Voice channel ID
+player.textChannelId    // Text channel ID
+
+player.autoplay     // { enabled, maxTracks }
+player.autoPause    // { enabled, minUsers }
+player.autoLeave    // { enabled, emptyDelay, inactivityTimeout }
+```
+
+## Queue Access
+
+```javascript
+player.queue.current   // Currently playing track
+player.queue.tracks    // Upcoming tracks
+player.queue.previous  // Previously played tracks
+```
+
+See [Queue](./queue.md) for queue methods.
+
+## Serialization
+
+```javascript
+const json = player.toJSON();
+// {
+//     guildId: '...',
+//     voiceChannelId: '...',
+//     connected: true,
+//     playing: true,
+//     paused: false,
+//     volume: 80,
+//     position: 45000,
+//     filters: { bass: 10 },
+//     queue: { current: {...}, tracks: [...] },
+//     autoplay: { enabled: false },
+//     autoPause: { enabled: true },
+//     autoLeave: { enabled: true }
+// }
+```

package/docs/discord/queue.md

@@ -0,0 +1,197 @@
+# Queue
+
+The Queue manages tracks for a player.
+
+## Accessing the Queue
+
+```javascript
+const player = manager.get(guildId);
+const queue = player.queue;
+```
+
+## Properties
+
+```javascript
+queue.current      // Currently playing track (or null)
+queue.tracks       // Array of upcoming tracks
+queue.previous     // Array of previously played tracks
+queue.size         // Number of upcoming tracks
+queue.isEmpty      // true if no upcoming tracks
+queue.totalDuration // Total duration in ms (current + upcoming)
+queue.repeatMode   // 'off', 'track', or 'queue'
+```
+
+## Adding Tracks
+
+### add(track, position?)
+
+Add a single track.
+
+```javascript
+// Add to end
+queue.add(track);
+
+// Add at specific position
+queue.add(track, 0);  // Next up
+queue.add(track, 2);  // Third in queue
+```
+
+### addMany(tracks, position?)
+
+Add multiple tracks.
+
+```javascript
+// Add to end
+queue.addMany(tracks);
+
+// Add at position
+queue.addMany(tracks, 0);
+```
+
+## Removing Tracks
+
+### remove(index)
+
+Remove a track by index.
+
+```javascript
+const removed = queue.remove(0);  // Remove next track
+console.log(removed.title);
+```
+
+### clear()
+
+Clear all upcoming tracks.
+
+```javascript
+const count = queue.clear();
+console.log(`Cleared ${count} tracks`);
+```
+
+## Reordering
+
+### shuffle()
+
+Randomize track order.
+
+```javascript
+queue.shuffle();
+```
+
+### move(from, to)
+
+Move a track to a different position.
+
+```javascript
+queue.move(5, 0);  // Move track 5 to next up
+queue.move(0, 3);  // Move next track to position 3
+```
+
+## Loop Mode
+
+```javascript
+queue.setRepeatMode('off');    // No looping
+queue.setRepeatMode('track');  // Repeat current track
+queue.setRepeatMode('queue');  // Repeat entire queue
+```
+
+Or use the player shorthand:
+
+```javascript
+player.setLoop('queue');
+```
+
+## Internal Methods
+
+These are used internally by the Player:
+
+### shift()
+
+Moves current to previous, gets next track as current.
+
+```javascript
+const next = queue.shift();  // Returns next track or null
+```
+
+### unshift()
+
+Goes back to previous track.
+
+```javascript
+const prev = queue.unshift();  // Returns previous track or null
+```
+
+### setCurrent(track)
+
+Sets the current track directly.
+
+```javascript
+queue.setCurrent(track);
+```
+
+## Example: Queue Display
+
+```javascript
+function displayQueue(player) {
+    const { current, tracks } = player.queue;
+
+    let text = '';
+
+    if (current) {
+        text += `**Now Playing:** ${current.title}\n\n`;
+    }
+
+    if (tracks.length > 0) {
+        text += '**Up Next:**\n';
+        tracks.slice(0, 10).forEach((track, i) => {
+            text += `${i + 1}. ${track.title}\n`;
+        });
+        if (tracks.length > 10) {
+            text += `... and ${tracks.length - 10} more`;
+        }
+    } else {
+        text += 'Queue is empty.';
+    }
+
+    return text;
+}
+```
+
+## Example: Playlist Loading
+
+```javascript
+async function loadPlaylist(player, url) {
+    const result = await manager.loadPlaylist(url);
+
+    if (result.loadType === 'error') {
+        throw new Error(result.error);
+    }
+
+    const tracks = result.tracks;
+
+    if (player.queue.current) {
+        // Add all to queue
+        player.queue.addMany(tracks);
+        return `Added ${tracks.length} tracks to queue`;
+    } else {
+        // Play first, queue rest
+        const first = tracks.shift();
+        player.queue.addMany(tracks);
+        await player.play(first);
+        return `Playing **${result.playlist.title}** (${tracks.length + 1} tracks)`;
+    }
+}
+```
+
+## Serialization
+
+```javascript
+const json = queue.toJSON();
+// {
+//     current: { id, title, ... },
+//     tracks: [...],
+//     previous: [...],
+//     repeatMode: 'off',
+//     size: 5
+// }
+```