streamify-audio 2.0.0

package/docs/automation.md

@@ -0,0 +1,186 @@
+# Automation
+
+Streamify includes built-in automation features for common scenarios.
+
+## Auto-Pause
+
+Automatically pauses playback when users leave the voice channel and resumes when they return.
+
+### Configuration
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    autoPause: {
+        enabled: true,
+        minUsers: 1    // Pause when users drop below this
+    }
+});
+```
+
+### Behavior
+
+1. User count drops below `minUsers`
+2. Playback pauses immediately
+3. Stream is destroyed (saves resources)
+4. Position is saved
+5. When users rejoin and count reaches `minUsers`:
+6. Stream recreates with seek
+7. Playback resumes
+
+### Events
+
+```javascript
+player.on('autoPause', (userCount) => {
+    channel.send(`Paused (${userCount} users in channel)`);
+});
+
+player.on('autoResume', (userCount) => {
+    channel.send(`Resumed (${userCount} users now)`);
+});
+```
+
+### Runtime Toggle
+
+```javascript
+player.setAutoPause(false);  // Disable
+player.setAutoPause(true);   // Enable
+```
+
+## Auto-Leave
+
+Automatically leaves the voice channel after a period of inactivity.
+
+### Configuration
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    autoLeave: {
+        enabled: true,
+        emptyDelay: 30000,         // Leave 30s after channel empty
+        inactivityTimeout: 300000  // Leave after 5min of not playing
+    }
+});
+```
+
+### Behavior
+
+**Empty Channel:**
+1. All users leave
+2. 30 second countdown starts
+3. If no one rejoins, player destroys
+
+**Inactivity:**
+1. Queue ends, nothing playing
+2. 5 minute countdown starts
+3. If nothing plays, player destroys
+
+### Events
+
+```javascript
+player.on('channelEmpty', () => {
+    channel.send('Everyone left. Leaving in 30 seconds...');
+});
+
+player.on('destroy', () => {
+    channel.send('Disconnected due to inactivity.');
+});
+```
+
+## Autoplay
+
+Automatically plays related tracks when the queue ends.
+
+### Configuration
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    autoplay: {
+        enabled: false,   // Off by default
+        maxTracks: 5      // How many related tracks to fetch
+    }
+});
+```
+
+### Behavior
+
+1. Queue ends (last track finishes)
+2. Fetch related tracks from YouTube Mix or Spotify Recommendations
+3. Add to queue and start playing
+4. Repeat when those tracks end
+
+### Events
+
+```javascript
+player.on('autoplayStart', (lastTrack) => {
+    console.log(`Finding tracks like: ${lastTrack.title}`);
+});
+
+player.on('autoplayAdd', (tracks) => {
+    channel.send(`Autoplay added ${tracks.length} tracks`);
+});
+```
+
+### Runtime Toggle
+
+```javascript
+player.setAutoplay(true);   // Enable
+player.setAutoplay(false);  // Disable
+```
+
+### Track Identification
+
+Autoplay tracks are marked:
+
+```javascript
+player.on('trackStart', (track) => {
+    if (track.isAutoplay) {
+        channel.send(`Autoplay: **${track.title}**`);
+    } else {
+        channel.send(`Now playing: **${track.title}**`);
+    }
+});
+```
+
+## Combining Features
+
+All automation features work together:
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    autoPause: {
+        enabled: true,
+        minUsers: 1
+    },
+    autoLeave: {
+        enabled: true,
+        emptyDelay: 30000,
+        inactivityTimeout: 300000
+    },
+    autoplay: {
+        enabled: true,
+        maxTracks: 5
+    }
+});
+```
+
+**Scenario: User leaves during playback**
+1. `autoPause` triggers → pauses playback
+2. `autoLeave` starts 30s countdown
+3. User rejoins within 30s
+4. `autoResume` triggers → playback continues
+5. Countdown cancelled
+
+**Scenario: Queue ends**
+1. `autoplay` fetches related tracks
+2. Playback continues with recommendations
+3. If autoplay disabled, `autoLeave` inactivity timeout starts
+
+## Disabling All Automation
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    autoPause: { enabled: false },
+    autoLeave: { enabled: false },
+    autoplay: { enabled: false }
+});
+```

package/docs/configuration.md

@@ -0,0 +1,169 @@
+# Configuration
+
+## Discord Player Mode
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    // Paths (required)
+    ytdlpPath: '/usr/local/bin/yt-dlp',
+    ffmpegPath: '/usr/bin/ffmpeg',
+
+    // YouTube cookies (optional)
+    cookiesPath: './cookies.txt',
+
+    // Providers (optional - all enabled by default)
+    providers: {
+        youtube: { enabled: true },
+        spotify: { enabled: true },
+        soundcloud: { enabled: true }
+    },
+
+    // Spotify credentials (optional)
+    spotify: {
+        clientId: process.env.SPOTIFY_CLIENT_ID,
+        clientSecret: process.env.SPOTIFY_CLIENT_SECRET
+    },
+
+    // Audio settings
+    audio: {
+        bitrate: '128k',      // Audio bitrate
+        format: 'opus'        // opus, mp3, aac
+    },
+
+    // Defaults
+    defaultVolume: 80,        // 0-200
+    maxPreviousTracks: 25,    // History size
+
+    // Sponsorblock
+    sponsorblock: {
+        enabled: true,
+        categories: ['sponsor', 'selfpromo', 'intro', 'outro']
+    },
+
+    // Auto-leave
+    autoLeave: {
+        enabled: true,
+        emptyDelay: 30000,        // Leave 30s after channel empty
+        inactivityTimeout: 300000 // Leave after 5min idle
+    },
+
+    // Auto-pause
+    autoPause: {
+        enabled: true,
+        minUsers: 1               // Pause when users drop below this
+    },
+
+    // Autoplay
+    autoplay: {
+        enabled: false,
+        maxTracks: 5              // Related tracks to fetch
+    }
+});
+```
+
+## HTTP Server Mode
+
+```javascript
+const streamify = new Streamify({
+    // Server
+    port: 8787,
+    host: '0.0.0.0',
+
+    // Paths
+    ytdlpPath: '/usr/local/bin/yt-dlp',
+    ffmpegPath: '/usr/bin/ffmpeg',
+
+    // YouTube cookies
+    cookiesPath: './cookies.txt',
+    // Or direct string:
+    cookies: '# Netscape HTTP Cookie File\n...',
+
+    // Providers (optional - all enabled by default)
+    providers: {
+        youtube: { enabled: true },
+        spotify: { enabled: true },
+        soundcloud: { enabled: true }
+    },
+
+    // Spotify
+    spotify: {
+        clientId: 'xxx',
+        clientSecret: 'xxx'
+    },
+
+    // Audio
+    audio: {
+        bitrate: '128k',
+        format: 'opus'
+    },
+
+    // Logging
+    logLevel: 'info',    // none, error, warn, info, debug
+    silent: false,
+    colors: true
+});
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `SPOTIFY_CLIENT_ID` | Spotify API client ID |
+| `SPOTIFY_CLIENT_SECRET` | Spotify API client secret |
+| `YTDLP_PATH` | Path to yt-dlp binary |
+| `FFMPEG_PATH` | Path to ffmpeg binary |
+| `COOKIES_PATH` | Path to YouTube cookies file |
+| `PORT` | HTTP server port |
+
+## YouTube Cookies
+
+For age-restricted or region-locked videos:
+
+1. Install browser extension "Get cookies.txt"
+2. Visit youtube.com while logged in
+3. Export cookies in Netscape format
+4. Save as `cookies.txt`
+
+```javascript
+// File path
+cookiesPath: './cookies.txt'
+
+// Or direct string
+cookies: `# Netscape HTTP Cookie File
+.youtube.com	TRUE	/	TRUE	0	COOKIE_NAME	COOKIE_VALUE`
+```
+
+## Spotify Setup
+
+1. Go to [Spotify Developer Dashboard](https://developer.spotify.com/dashboard)
+2. Create an app
+3. Copy Client ID and Client Secret
+
+```javascript
+spotify: {
+    clientId: process.env.SPOTIFY_CLIENT_ID,
+    clientSecret: process.env.SPOTIFY_CLIENT_SECRET
+}
+```
+
+Spotify tracks are resolved to YouTube for playback.
+
+## Providers
+
+Enable or disable individual providers:
+
+```javascript
+providers: {
+    youtube: { enabled: true },
+    spotify: { enabled: true },
+    soundcloud: { enabled: false }  // Disabled
+}
+```
+
+All providers are enabled by default. When a disabled provider is accessed, an error is thrown:
+
+```
+Error: SoundCloud provider is disabled
+```
+
+This is useful if you only want to support specific platforms.

package/docs/discord/events.md

@@ -0,0 +1,206 @@
+# Events
+
+## Manager Events
+
+```javascript
+manager.on('playerCreate', (player) => {
+    console.log(`Player created for guild ${player.guildId}`);
+});
+
+manager.on('playerDestroy', (player) => {
+    console.log(`Player destroyed for guild ${player.guildId}`);
+});
+```
+
+## Player Events
+
+### Track Events
+
+#### trackStart
+
+Fired when a track starts playing.
+
+```javascript
+player.on('trackStart', (track) => {
+    channel.send({
+        embeds: [{
+            title: 'Now Playing',
+            description: `**${track.title}**\nby ${track.author}`,
+            thumbnail: { url: track.thumbnail }
+        }]
+    });
+});
+```
+
+#### trackEnd
+
+Fired when a track finishes.
+
+```javascript
+player.on('trackEnd', (track, reason) => {
+    // reason: 'finished' | 'skipped' | 'stopped'
+    console.log(`Track ended: ${track.title} (${reason})`);
+});
+```
+
+#### trackError
+
+Fired when a track fails to play.
+
+```javascript
+player.on('trackError', (track, error) => {
+    channel.send(`Failed to play **${track.title}**: ${error.message}`);
+});
+```
+
+#### queueEnd
+
+Fired when the queue is empty and playback stops.
+
+```javascript
+player.on('queueEnd', () => {
+    channel.send('Queue finished. Add more songs or enable autoplay!');
+});
+```
+
+### Voice Events
+
+#### userJoin
+
+Fired when a user joins the voice channel.
+
+```javascript
+player.on('userJoin', (member, count) => {
+    console.log(`${member.user.tag} joined (${count} users now)`);
+});
+```
+
+#### userLeave
+
+Fired when a user leaves the voice channel.
+
+```javascript
+player.on('userLeave', (member, count) => {
+    console.log(`${member.user.tag} left (${count} users remaining)`);
+});
+```
+
+#### channelEmpty
+
+Fired when all users leave the voice channel.
+
+```javascript
+player.on('channelEmpty', () => {
+    channel.send('Everyone left. I\'ll leave in 30 seconds...');
+});
+```
+
+#### channelMove
+
+Fired when the bot is moved to a different voice channel.
+
+```javascript
+player.on('channelMove', (newChannelId) => {
+    console.log(`Moved to channel ${newChannelId}`);
+});
+```
+
+### Automation Events
+
+#### autoPause
+
+Fired when playback is automatically paused.
+
+```javascript
+player.on('autoPause', (userCount) => {
+    channel.send(`Paused (${userCount} users in channel)`);
+});
+```
+
+#### autoResume
+
+Fired when playback is automatically resumed.
+
+```javascript
+player.on('autoResume', (userCount) => {
+    channel.send(`Resumed (${userCount} users rejoined)`);
+});
+```
+
+#### autoplayStart
+
+Fired when autoplay starts fetching related tracks.
+
+```javascript
+player.on('autoplayStart', (lastTrack) => {
+    console.log(`Finding tracks related to: ${lastTrack.title}`);
+});
+```
+
+#### autoplayAdd
+
+Fired when autoplay adds tracks to the queue.
+
+```javascript
+player.on('autoplayAdd', (tracks) => {
+    channel.send(`Autoplay added ${tracks.length} tracks`);
+});
+```
+
+### Lifecycle Events
+
+#### destroy
+
+Fired when the player is destroyed.
+
+```javascript
+player.on('destroy', () => {
+    console.log('Player destroyed');
+});
+```
+
+## Example: Full Event Setup
+
+```javascript
+function setupPlayerEvents(player, textChannel) {
+    player.on('trackStart', (track) => {
+        const embed = {
+            color: 0x00ff00,
+            title: track.isAutoplay ? 'Autoplay' : 'Now Playing',
+            description: `**${track.title}**\nby ${track.author}`,
+            thumbnail: { url: track.thumbnail }
+        };
+        textChannel.send({ embeds: [embed] });
+    });
+
+    player.on('trackError', (track, error) => {
+        textChannel.send(`Failed to play **${track.title}**: ${error.message}`);
+    });
+
+    player.on('queueEnd', () => {
+        if (!player.autoplay.enabled) {
+            textChannel.send('Queue ended. Use `!autoplay` to keep the music going!');
+        }
+    });
+
+    player.on('channelEmpty', () => {
+        textChannel.send('Channel empty. Leaving in 30 seconds...');
+    });
+
+    player.on('autoPause', () => {
+        textChannel.send('Paused - everyone left the channel.');
+    });
+
+    player.on('autoResume', () => {
+        textChannel.send('Resumed - welcome back!');
+    });
+
+    player.on('destroy', () => {
+        textChannel.send('Disconnected.');
+    });
+}
+
+// Usage
+const player = await manager.create(guildId, vcId, tcId);
+setupPlayerEvents(player, textChannel);
+```