streamify-audio 2.0.0

package/docs/http/server.md

@@ -0,0 +1,172 @@
+# HTTP Server
+
+The HTTP server mode provides a REST API for audio streaming. Use it with Lavalink, web apps, or any HTTP client.
+
+## Starting the Server
+
+```javascript
+const Streamify = require('streamify-audio');
+
+const streamify = new Streamify({
+    port: 8787,
+    host: '0.0.0.0',
+    cookiesPath: './cookies.txt',
+    spotify: {
+        clientId: process.env.SPOTIFY_CLIENT_ID,
+        clientSecret: process.env.SPOTIFY_CLIENT_SECRET
+    }
+});
+
+await streamify.start();
+console.log(`Server running at ${streamify.getBaseUrl()}`);
+// Server running at http://127.0.0.1:8787
+```
+
+## Configuration
+
+```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',
+
+    // Spotify
+    spotify: {
+        clientId: 'xxx',
+        clientSecret: 'xxx'
+    },
+
+    // Audio output
+    audio: {
+        bitrate: '128k',
+        format: 'opus'  // opus, mp3, aac
+    },
+
+    // Logging
+    logLevel: 'info',
+    silent: false,
+    colors: true
+});
+```
+
+## Methods
+
+### start()
+
+Starts the HTTP server.
+
+```javascript
+await streamify.start();
+```
+
+### stop()
+
+Stops the HTTP server.
+
+```javascript
+await streamify.stop();
+```
+
+### getBaseUrl()
+
+Returns the server URL.
+
+```javascript
+const url = streamify.getBaseUrl();
+// http://127.0.0.1:8787
+```
+
+## Programmatic API
+
+### Search
+
+```javascript
+// General
+const results = await streamify.search('youtube', 'query', 10);
+
+// Shorthand
+const results = await streamify.youtube.search('query');
+const results = await streamify.spotify.search('query');
+const results = await streamify.soundcloud.search('query');
+```
+
+### Get Info
+
+```javascript
+const info = await streamify.getInfo('youtube', 'dQw4w9WgXcQ');
+const info = await streamify.youtube.getInfo('dQw4w9WgXcQ');
+```
+
+### Get Stream URL
+
+```javascript
+// Without filters
+const url = streamify.youtube.getStreamUrl('dQw4w9WgXcQ');
+
+// With filters
+const url = streamify.youtube.getStreamUrl('dQw4w9WgXcQ', {
+    bass: 10,
+    nightcore: true,
+    start: 30
+});
+// http://127.0.0.1:8787/youtube/stream/dQw4w9WgXcQ?bass=10&nightcore=true&start=30
+```
+
+### Get Raw Stream
+
+```javascript
+const stream = await streamify.youtube.getStream('dQw4w9WgXcQ');
+// Returns a readable stream
+```
+
+## Events
+
+```javascript
+streamify.on('streamStart', (event) => {
+    console.log(`Stream started: ${event.trackId}`);
+    // { id, source, trackId, filters, startTime }
+});
+
+streamify.on('streamEnd', (event) => {
+    console.log(`Stream ended: ${event.trackId} (${event.duration}ms)`);
+    // { id, source, trackId, filters, startTime, duration, code }
+});
+
+streamify.on('streamError', (event) => {
+    console.error(`Stream error: ${event.error.message}`);
+    // { id, source, trackId, filters, startTime, error }
+});
+```
+
+## Active Streams
+
+```javascript
+// Get all active streams
+const streams = await streamify.getActiveStreams();
+
+// Get specific stream info
+const info = await streamify.getStreamInfo(streamId);
+
+// Get stream position
+const position = await streamify.getPosition(streamId);
+```
+
+## CLI Usage
+
+```bash
+# Install globally
+npm install -g streamify-audio
+
+# Run
+streamify --port 8787 --cookies ./cookies.txt
+
+# With environment variables
+PORT=8787 COOKIES_PATH=./cookies.txt streamify
+```

package/docs/quick-start.md

@@ -0,0 +1,92 @@
+# Quick Start
+
+## Installation
+
+```bash
+npm install streamify-audio @discordjs/voice @discordjs/opus
+```
+
+## Requirements
+
+- Node.js 18+
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) — `pip install yt-dlp`
+- [ffmpeg](https://ffmpeg.org/) — `apt install ffmpeg`
+
+## Discord Bot (5 minutes)
+
+```javascript
+const { Client, GatewayIntentBits } = require('discord.js');
+const Streamify = require('streamify-audio');
+
+const client = new Client({
+    intents: [
+        GatewayIntentBits.Guilds,
+        GatewayIntentBits.GuildVoiceStates,
+        GatewayIntentBits.GuildMessages,
+        GatewayIntentBits.MessageContent
+    ]
+});
+
+const manager = new Streamify.Manager(client, {
+    ytdlpPath: '/usr/local/bin/yt-dlp',
+    ffmpegPath: '/usr/bin/ffmpeg'
+});
+
+client.on('messageCreate', async (message) => {
+    if (!message.content.startsWith('!')) return;
+
+    const [cmd, ...args] = message.content.slice(1).split(' ');
+    const query = args.join(' ');
+
+    if (cmd === 'play') {
+        const vc = message.member.voice.channel;
+        if (!vc) return message.reply('Join a voice channel first!');
+
+        const result = await manager.search(query);
+        if (!result.tracks.length) return message.reply('No results found.');
+
+        const player = await manager.create(message.guild.id, vc.id, message.channel.id);
+
+        player.on('trackStart', (track) => {
+            message.channel.send(`Now playing: **${track.title}**`);
+        });
+
+        await player.play(result.tracks[0]);
+    }
+
+    if (cmd === 'skip') {
+        const player = manager.get(message.guild.id);
+        if (player) await player.skip();
+    }
+
+    if (cmd === 'stop') {
+        const player = manager.get(message.guild.id);
+        if (player) player.destroy();
+    }
+});
+
+client.login(process.env.TOKEN);
+```
+
+## HTTP Server (3 minutes)
+
+```javascript
+const Streamify = require('streamify-audio');
+
+const streamify = new Streamify({ port: 8787 });
+await streamify.start();
+
+// Search
+const results = await streamify.youtube.search('never gonna give you up');
+console.log(results.tracks[0].title);
+
+// Get stream URL
+const url = streamify.youtube.getStreamUrl(results.tracks[0].id);
+// http://127.0.0.1:8787/youtube/stream/dQw4w9WgXcQ
+```
+
+## Next Steps
+
+- [Configuration](./configuration.md) — Add Spotify, cookies, filters
+- [Discord Player](./discord/manager.md) — Full player documentation
+- [HTTP Server](./http/server.md) — API endpoints

package/docs/sources.md

@@ -0,0 +1,141 @@
+# Sources
+
+Streamify supports YouTube, Spotify, and SoundCloud.
+
+## Supported Features
+
+| Source | Search | Track URL | Playlist | Album |
+|--------|:------:|:---------:|:--------:|:-----:|
+| YouTube | ✅ | ✅ | ✅ | — |
+| Spotify | ✅ | ✅ | ✅ | ✅ |
+| SoundCloud | ✅ | ✅ | ❌ | — |
+
+## YouTube
+
+YouTube is the primary source. All audio is streamed directly from YouTube.
+
+```javascript
+// Search
+const result = await manager.search('never gonna give you up');
+const result = await manager.search(query, { source: 'youtube' });
+
+// Direct URL
+const result = await manager.resolve('https://youtube.com/watch?v=dQw4w9WgXcQ');
+const result = await manager.resolve('https://youtu.be/dQw4w9WgXcQ');
+const result = await manager.resolve('https://music.youtube.com/watch?v=dQw4w9WgXcQ');
+
+// Playlist
+const result = await manager.loadPlaylist('https://youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf');
+```
+
+### Supported URL Formats
+
+- `youtube.com/watch?v=VIDEO_ID`
+- `youtu.be/VIDEO_ID`
+- `youtube.com/shorts/VIDEO_ID`
+- `music.youtube.com/watch?v=VIDEO_ID`
+- `youtube.com/playlist?list=PLAYLIST_ID`
+
+### Cookies
+
+For age-restricted or region-locked videos, provide YouTube cookies:
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    cookiesPath: './cookies.txt'
+});
+```
+
+See [Configuration](./configuration.md#youtube-cookies) for setup instructions.
+
+## Spotify
+
+Spotify tracks are resolved to YouTube for playback. Requires API credentials.
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    spotify: {
+        clientId: process.env.SPOTIFY_CLIENT_ID,
+        clientSecret: process.env.SPOTIFY_CLIENT_SECRET
+    }
+});
+```
+
+```javascript
+// Search
+const result = await manager.search('never gonna give you up', { source: 'spotify' });
+
+// Direct URL
+const result = await manager.resolve('https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8');
+
+// Playlist
+const result = await manager.loadPlaylist('https://open.spotify.com/playlist/37i9dQZF1DXcBWIGoYBM5M');
+
+// Album
+const result = await manager.loadPlaylist('https://open.spotify.com/album/4LH4d3cOWNNsVw41Gqt2kv');
+```
+
+### Supported URL Formats
+
+- `open.spotify.com/track/TRACK_ID`
+- `open.spotify.com/playlist/PLAYLIST_ID`
+- `open.spotify.com/album/ALBUM_ID`
+- `spotify:track:TRACK_ID`
+
+### How Resolution Works
+
+1. Fetch track metadata from Spotify API
+2. Search YouTube for `{artist} - {title}`
+3. Use the first result for playback
+
+The resolved YouTube ID is cached for 5 minutes.
+
+## SoundCloud
+
+SoundCloud tracks are streamed via yt-dlp.
+
+```javascript
+// Search
+const result = await manager.search('never gonna give you up', { source: 'soundcloud' });
+
+// Direct URL
+const result = await manager.resolve('https://soundcloud.com/rick-astley-official/never-gonna-give-you-up');
+```
+
+### Supported URL Formats
+
+- `soundcloud.com/USER/TRACK`
+
+## Auto-Detection
+
+The `resolve()` method auto-detects the source from URLs:
+
+```javascript
+// All of these work
+await manager.resolve('https://youtube.com/watch?v=dQw4w9WgXcQ');
+await manager.resolve('https://open.spotify.com/track/4PTG3Z6ehGkBFwjybzWkR8');
+await manager.resolve('https://soundcloud.com/rick-astley-official/never-gonna-give-you-up');
+
+// Falls back to YouTube search
+await manager.resolve('never gonna give you up');
+```
+
+## Track Object
+
+All sources return the same track structure:
+
+```javascript
+{
+    id: 'dQw4w9WgXcQ',
+    title: 'Rick Astley - Never Gonna Give You Up',
+    author: 'Rick Astley',
+    duration: 213,           // seconds
+    thumbnail: 'https://...',
+    uri: 'https://...',      // Original URL
+    source: 'youtube',       // youtube, spotify, soundcloud
+
+    // Spotify only
+    album: 'Whenever You Need Somebody',
+    _resolvedId: 'dQw4w9WgXcQ'  // YouTube ID
+}
+```

package/docs/sponsorblock.md

@@ -0,0 +1,95 @@
+# Sponsorblock
+
+Streamify integrates with [SponsorBlock](https://sponsor.ajay.app/) to automatically skip sponsored segments in YouTube videos.
+
+## Configuration
+
+```javascript
+const manager = new Streamify.Manager(client, {
+    sponsorblock: {
+        enabled: true,
+        categories: ['sponsor', 'selfpromo', 'intro', 'outro']
+    }
+});
+```
+
+## Categories
+
+| Category | Description |
+|----------|-------------|
+| `sponsor` | Paid promotion, sponsored content |
+| `selfpromo` | Self-promotion, merchandise, Patreon |
+| `intro` | Intro animation, opening sequence |
+| `outro` | Outro, end cards, credits |
+| `preview` | Preview of other videos |
+| `filler` | Tangents, jokes, off-topic |
+| `interaction` | Subscribe reminders, like requests |
+| `music_offtopic` | Non-music sections in music videos |
+
+## Default Categories
+
+By default, Streamify skips:
+- `sponsor`
+- `selfpromo`
+
+```javascript
+// Default behavior
+sponsorblock: {
+    enabled: true,
+    categories: ['sponsor', 'selfpromo']
+}
+```
+
+## Skip Everything
+
+```javascript
+sponsorblock: {
+    enabled: true,
+    categories: [
+        'sponsor',
+        'selfpromo',
+        'intro',
+        'outro',
+        'preview',
+        'filler',
+        'interaction',
+        'music_offtopic'
+    ]
+}
+```
+
+## Music Videos
+
+For music, you might want:
+
+```javascript
+sponsorblock: {
+    enabled: true,
+    categories: ['sponsor', 'selfpromo', 'intro', 'outro', 'music_offtopic']
+}
+```
+
+## Disabling
+
+```javascript
+sponsorblock: {
+    enabled: false
+}
+```
+
+Or omit the `sponsorblock` config entirely.
+
+## How It Works
+
+1. When a YouTube stream starts, yt-dlp queries the SponsorBlock API
+2. Segment timestamps are fetched for the video
+3. yt-dlp removes those segments during download
+4. Audio plays seamlessly without the sponsored content
+
+## Notes
+
+- Only works with YouTube (Spotify/SoundCloud unaffected)
+- Segments are crowdsourced and may not exist for all videos
+- Popular videos have more complete segment data
+- Occasionally segments may be slightly inaccurate
+- No additional latency - segments are fetched during stream initialization