streamify-audio 2.0.0

package/docs/examples/lavalink.md

@@ -0,0 +1,156 @@
+# HTTP Server with Lavalink
+
+Use Streamify's HTTP server as a stream source for Lavalink.
+
+## Why?
+
+- Lavalink's YouTube plugin can be unreliable
+- Streamify uses yt-dlp which handles YouTube's restrictions better
+- Get audio filters without Lavalink's filter support
+
+## Setup
+
+### 1. Start Streamify Server
+
+```javascript
+// streamify-server.js
+const Streamify = require('streamify-audio');
+
+const streamify = new Streamify({
+    port: 8787,
+    cookiesPath: './cookies.txt',
+    spotify: {
+        clientId: process.env.SPOTIFY_CLIENT_ID,
+        clientSecret: process.env.SPOTIFY_CLIENT_SECRET
+    }
+});
+
+streamify.start().then(() => {
+    console.log('Streamify running at http://127.0.0.1:8787');
+});
+```
+
+### 2. Configure Lavalink
+
+In `application.yml`, allow local addresses:
+
+```yaml
+lavalink:
+  server:
+    sources:
+      http: true
+```
+
+### 3. Bot Integration
+
+```javascript
+const { Client } = require('discord.js');
+const { Manager } = require('erela.js'); // or your Lavalink client
+
+const client = new Client({ /* intents */ });
+
+// Initialize Streamify client
+const Streamify = require('streamify-audio');
+const streamify = new Streamify({ port: 8787 });
+
+// Initialize Lavalink
+const lavalinkManager = new Manager({
+    nodes: [{ host: 'localhost', port: 2333, password: 'youshallnotpass' }],
+    send: (id, payload) => {
+        const guild = client.guilds.cache.get(id);
+        if (guild) guild.shard.send(payload);
+    }
+});
+
+client.on('ready', async () => {
+    await streamify.start();
+    lavalinkManager.init(client.user.id);
+});
+
+client.on('raw', d => lavalinkManager.updateVoiceState(d));
+
+// Play command
+client.on('messageCreate', async (message) => {
+    if (!message.content.startsWith('!play')) return;
+
+    const query = message.content.slice(6);
+    const vc = message.member.voice.channel;
+
+    // Search using Streamify
+    const results = await streamify.youtube.search(query);
+    if (!results.tracks.length) return message.reply('No results');
+
+    const track = results.tracks[0];
+
+    // Get stream URL from Streamify
+    const streamUrl = streamify.youtube.getStreamUrl(track.id, {
+        bass: 5  // Optional: apply filters
+    });
+
+    // Create Lavalink player
+    const player = lavalinkManager.create({
+        guild: message.guild.id,
+        voiceChannel: vc.id,
+        textChannel: message.channel.id
+    });
+
+    if (player.state !== 'CONNECTED') {
+        player.connect();
+    }
+
+    // Load Streamify URL in Lavalink
+    const res = await lavalinkManager.search(streamUrl, message.author);
+    player.queue.add(res.tracks[0]);
+
+    if (!player.playing) player.play();
+
+    message.reply(`Playing: **${track.title}**`);
+});
+
+client.login(process.env.TOKEN);
+```
+
+## With Filters
+
+```javascript
+// Apply filters via Streamify URL
+const streamUrl = streamify.youtube.getStreamUrl(trackId, {
+    bass: 10,
+    nightcore: true,
+    volume: 80
+});
+
+// Lavalink plays the already-filtered audio
+const res = await lavalinkManager.search(streamUrl, user);
+```
+
+## Changing Filters Mid-Song
+
+```javascript
+// Get current position from Streamify's stream tracking
+const position = await streamify.getPosition(currentStreamId);
+
+// Create new URL with filters + position
+const newUrl = streamify.youtube.getStreamUrl(trackId, {
+    bass: 10,
+    nightcore: true,
+    start: Math.floor(position)  // Seek to current position
+});
+
+// Tell Lavalink to switch
+const res = await lavalinkManager.search(newUrl, user);
+player.play(res.tracks[0]);
+// Seamless transition with new filters
+```
+
+## Benefits
+
+1. **Reliable extraction** - yt-dlp handles YouTube's anti-bot
+2. **Cookie support** - Play age-restricted content
+3. **Pre-applied filters** - Don't need Lavalink filter support
+4. **Spotify support** - Automatic YouTube resolution
+5. **Sponsorblock** - Skip sponsors before Lavalink receives audio
+
+## Note
+
+This approach adds one network hop (Lavalink fetches from Streamify). For direct playback without Lavalink, use Streamify's [Discord Player mode](../discord/manager.md) instead.

package/docs/filters.md

@@ -0,0 +1,309 @@
+# Audio Filters
+
+Filters are applied in real-time via ffmpeg. When you change a filter during playback, Streamify recreates the stream and seeks to the current position.
+
+## Available Filters
+
+| Filter | Type | Range | Description |
+|--------|------|-------|-------------|
+| `bass` | number | -20 to 20 | Bass boost/cut in dB |
+| `treble` | number | -20 to 20 | Treble boost/cut in dB |
+| `speed` | number | 0.5 to 2.0 | Playback speed |
+| `pitch` | number | 0.5 to 2.0 | Pitch shift |
+| `volume` | number | 0 to 200 | Volume percentage |
+| `tremolo` | object | see below | Volume oscillation |
+| `vibrato` | object | see below | Pitch oscillation |
+| `rotation` | object | see below | Audio rotation (8D) |
+| `lowpass` | number | 100 to 20000 | Low-pass filter (Hz) |
+| `highpass` | number | 20 to 10000 | High-pass filter (Hz) |
+| `karaoke` | boolean | — | Reduce vocals |
+| `nightcore` | boolean | — | Speed + pitch up preset |
+| `vaporwave` | boolean | — | Speed + pitch down preset |
+| `bassboost` | boolean | — | Strong bass boost preset |
+| `8d` | boolean | — | 8D panning effect |
+
+## Usage (Discord Player)
+
+```javascript
+// Set individual filters
+await player.setFilter('bass', 10);
+await player.setFilter('treble', 5);
+await player.setFilter('speed', 1.25);
+await player.setFilter('volume', 120);
+
+// Object filters
+await player.setFilter('tremolo', { frequency: 4, depth: 0.5 });
+await player.setFilter('vibrato', { frequency: 4, depth: 0.5 });
+await player.setFilter('rotation', { speed: 0.125 });
+
+// Frequency filters
+await player.setFilter('lowpass', 1000);   // Cut above 1000Hz
+await player.setFilter('highpass', 200);   // Cut below 200Hz
+
+// Presets (boolean)
+await player.setFilter('nightcore', true);
+await player.setFilter('vaporwave', true);
+await player.setFilter('bassboost', true);
+await player.setFilter('karaoke', true);
+await player.setFilter('8d', true);
+
+// Clear all filters
+await player.clearFilters();
+
+// Get current filters
+console.log(player.filters);
+// { bass: 10, nightcore: true, ... }
+```
+
+## Usage (HTTP Server)
+
+```javascript
+// Add filters as query parameters
+const url = streamify.youtube.getStreamUrl('dQw4w9WgXcQ', {
+    bass: 10,
+    speed: 1.25,
+    nightcore: true
+});
+// http://127.0.0.1:8787/youtube/stream/dQw4w9WgXcQ?bass=10&speed=1.25&nightcore=true
+```
+
+## Filter Details
+
+### Tremolo
+Volume oscillation effect.
+
+```javascript
+await player.setFilter('tremolo', {
+    frequency: 4,    // 0.1 to 20 Hz
+    depth: 0.5       // 0 to 1
+});
+```
+
+### Vibrato
+Pitch oscillation effect.
+
+```javascript
+await player.setFilter('vibrato', {
+    frequency: 4,    // 0.1 to 14 Hz
+    depth: 0.5       // 0 to 1
+});
+```
+
+### Rotation
+Advanced 8D effect with configurable speed.
+
+```javascript
+await player.setFilter('rotation', {
+    speed: 0.125     // 0.01 to 5 rotations per second
+});
+```
+
+### Karaoke
+Reduces vocals by removing the center channel. Works best on stereo tracks with centered vocals.
+
+```javascript
+await player.setFilter('karaoke', true);
+```
+
+## Presets
+
+### Nightcore
+Speeds up and raises pitch for that anime soundtrack feel.
+
+- Speed: 1.25x
+- Pitch: 1.25x
+
+### Vaporwave
+Slows down and lowers pitch for that aesthetic.
+
+- Speed: 0.8x
+- Pitch: 0.8x
+
+### Bassboost
+Strong bass boost (+10dB).
+
+### 8D
+Audio pans around in a circle. Same as `rotation` with speed 0.125.
+
+## Combining Filters
+
+Filters can be combined:
+
+```javascript
+await player.setFilter('bass', 10);
+await player.setFilter('speed', 1.25);
+await player.setFilter('8d', true);
+// All three active simultaneously
+```
+
+Note: `nightcore` and `vaporwave` both modify speed/pitch, so using both may produce unexpected results.
+
+## 15-Band Equalizer
+
+Fine-grained control over frequency response with 15 bands.
+
+### Bands
+
+| Band | Frequency |
+|------|-----------|
+| 0 | 25 Hz |
+| 1 | 40 Hz |
+| 2 | 63 Hz |
+| 3 | 100 Hz |
+| 4 | 160 Hz |
+| 5 | 250 Hz |
+| 6 | 400 Hz |
+| 7 | 630 Hz |
+| 8 | 1000 Hz |
+| 9 | 1600 Hz |
+| 10 | 2500 Hz |
+| 11 | 4000 Hz |
+| 12 | 6300 Hz |
+| 13 | 10000 Hz |
+| 14 | 16000 Hz |
+
+### Usage
+
+```javascript
+// Set custom EQ (15 band values, -0.25 to 1.0)
+await player.setEQ([
+    0.3,   // 25 Hz (sub bass)
+    0.25,  // 40 Hz
+    0.2,   // 63 Hz
+    0.1,   // 100 Hz
+    0,     // 160 Hz
+    -0.1,  // 250 Hz
+    0,     // 400 Hz
+    0.1,   // 630 Hz
+    0.2,   // 1000 Hz
+    0.25,  // 1600 Hz
+    0.3,   // 2500 Hz
+    0.3,   // 4000 Hz
+    0.25,  // 6300 Hz
+    0.2,   // 10000 Hz
+    0.15   // 16000 Hz
+]);
+
+// Clear EQ
+await player.clearEQ();
+```
+
+## EQ Presets
+
+Built-in presets for common genres and use cases.
+
+### Available Presets
+
+| Preset | Description |
+|--------|-------------|
+| `flat` | No EQ changes |
+| `rock` | Enhanced mids and highs |
+| `pop` | Balanced with slight bass |
+| `jazz` | Warm, smooth sound |
+| `classical` | Wide, natural sound |
+| `electronic` | Heavy bass, crisp highs |
+| `hiphop` | Deep bass, clear vocals |
+| `acoustic` | Natural, warm |
+| `rnb` | Smooth bass, warm mids |
+| `latin` | Punchy, rhythmic |
+| `loudness` | Overall boost |
+| `piano` | Clear mids |
+| `vocal` | Enhanced vocal range |
+| `bass_heavy` | Maximum bass |
+| `treble_heavy` | Maximum highs |
+
+### Usage
+
+```javascript
+// Apply preset
+await player.setPreset('rock');
+await player.setPreset('electronic');
+
+// List available presets
+const presets = player.getPresets();
+// ['flat', 'rock', 'pop', ...]
+
+// Clear preset
+await player.clearEQ();
+```
+
+## Biquad Filters
+
+Professional-grade frequency filters.
+
+### Bandpass
+
+Only allows frequencies within a range.
+
+```javascript
+await player.setFilter('bandpass', {
+    frequency: 1000,  // Center frequency (Hz)
+    width: 200        // Bandwidth (Hz)
+});
+```
+
+### Band Reject (Notch)
+
+Removes frequencies within a range.
+
+```javascript
+await player.setFilter('bandreject', {
+    frequency: 1000,
+    width: 200
+});
+```
+
+### Low Shelf
+
+Boosts or cuts frequencies below a point.
+
+```javascript
+await player.setFilter('lowshelf', {
+    frequency: 200,   // Cutoff frequency (Hz)
+    gain: 6           // dB (-20 to 20)
+});
+```
+
+### High Shelf
+
+Boosts or cuts frequencies above a point.
+
+```javascript
+await player.setFilter('highshelf', {
+    frequency: 3000,
+    gain: 6
+});
+```
+
+### Peaking EQ
+
+Boosts or cuts a specific frequency range.
+
+```javascript
+await player.setFilter('peaking', {
+    frequency: 1000,  // Center frequency
+    gain: 6,          // dB
+    q: 1              // Width (higher = narrower)
+});
+```
+
+## Additional Effects
+
+| Effect | Description |
+|--------|-------------|
+| `flanger` | Sweeping comb filter effect |
+| `phaser` | Phase-shifting effect |
+| `chorus` | Thickens sound with slight detuning |
+| `compressor` | Dynamic range compression |
+| `normalizer` | Loudness normalization |
+| `mono` | Convert stereo to mono |
+| `surround` | Surround sound effect |
+
+```javascript
+await player.setFilter('flanger', true);
+await player.setFilter('phaser', true);
+await player.setFilter('chorus', true);
+await player.setFilter('compressor', true);
+await player.setFilter('normalizer', true);
+await player.setFilter('mono', true);
+```

package/docs/http/endpoints.md

@@ -0,0 +1,199 @@
+# HTTP Endpoints
+
+## YouTube
+
+### Search
+
+```
+GET /youtube/search?q=query&limit=10
+```
+
+**Response:**
+```json
+{
+    "tracks": [
+        {
+            "id": "dQw4w9WgXcQ",
+            "title": "Rick Astley - Never Gonna Give You Up",
+            "author": "Rick Astley",
+            "duration": 213,
+            "thumbnail": "https://...",
+            "uri": "https://youtube.com/watch?v=dQw4w9WgXcQ",
+            "streamUrl": "/youtube/stream/dQw4w9WgXcQ",
+            "source": "youtube"
+        }
+    ],
+    "source": "youtube",
+    "searchTime": 1234
+}
+```
+
+### Get Info
+
+```
+GET /youtube/info/:videoId
+```
+
+**Response:**
+```json
+{
+    "id": "dQw4w9WgXcQ",
+    "title": "Rick Astley - Never Gonna Give You Up",
+    "author": "Rick Astley",
+    "duration": 213,
+    "thumbnail": "https://...",
+    "uri": "https://youtube.com/watch?v=dQw4w9WgXcQ",
+    "streamUrl": "/youtube/stream/dQw4w9WgXcQ",
+    "source": "youtube"
+}
+```
+
+### Stream
+
+```
+GET /youtube/stream/:videoId
+GET /youtube/stream/:videoId?bass=10&nightcore=true&start=30
+```
+
+**Query Parameters:**
+- All [filters](../filters.md) are supported
+- `start` - Seek to position in seconds
+
+**Response:** Audio stream (`audio/ogg`)
+
+## Spotify
+
+### Search
+
+```
+GET /spotify/search?q=query&limit=10
+```
+
+### Get Info
+
+```
+GET /spotify/info/:trackId
+```
+
+### Stream
+
+```
+GET /spotify/stream/:trackId
+GET /spotify/stream/:trackId?bass=10
+```
+
+Spotify tracks are resolved to YouTube and streamed from there.
+
+## SoundCloud
+
+### Search
+
+```
+GET /soundcloud/search?q=query&limit=10
+```
+
+### Stream
+
+```
+GET /soundcloud/stream/:trackUrl
+```
+
+Note: `trackUrl` should be URL-encoded.
+
+## Stream Management
+
+### List Active Streams
+
+```
+GET /streams
+```
+
+**Response:**
+```json
+{
+    "streams": [
+        {
+            "id": "yt-dQw4w9WgXcQ-1234567890",
+            "source": "youtube",
+            "trackId": "dQw4w9WgXcQ",
+            "filters": { "bass": 10 },
+            "startTime": 1234567890,
+            "bytesReceived": 1048576,
+            "bytesSent": 524288
+        }
+    ],
+    "count": 1
+}
+```
+
+### Get Stream Info
+
+```
+GET /streams/:streamId
+```
+
+**Response:**
+```json
+{
+    "id": "yt-dQw4w9WgXcQ-1234567890",
+    "source": "youtube",
+    "trackId": "dQw4w9WgXcQ",
+    "filters": { "bass": 10 },
+    "startTime": 1234567890,
+    "elapsed": 45000,
+    "bytesReceived": 1048576,
+    "bytesSent": 524288
+}
+```
+
+### Get Stream Position
+
+```
+GET /streams/:streamId/position
+```
+
+**Response:**
+```json
+{
+    "position": 45.5,
+    "elapsed": 45000
+}
+```
+
+Position is in seconds, useful for seeking when applying filters.
+
+## Filter Parameters
+
+All stream endpoints accept filter query parameters:
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `bass` | number | -20 to 20 |
+| `treble` | number | -20 to 20 |
+| `speed` | number | 0.5 to 2.0 |
+| `pitch` | number | 0.5 to 2.0 |
+| `volume` | number | 0 to 200 |
+| `nightcore` | boolean | true |
+| `vaporwave` | boolean | true |
+| `bassboost` | boolean | true |
+| `8d` | boolean | true |
+| `start` | number | Seek seconds |
+
+**Example:**
+```
+GET /youtube/stream/dQw4w9WgXcQ?bass=10&speed=1.25&nightcore=true&start=30
+```
+
+## Error Responses
+
+```json
+{
+    "error": "Track not found",
+    "code": 404
+}
+```
+
+Common error codes:
+- `400` - Invalid parameters
+- `404` - Track/stream not found
+- `500` - Internal error (yt-dlp/ffmpeg failure)