streamify-audio 2.3.0 → 2.3.2

package/docs/http/endpoints.md

@@ -1,224 +0,0 @@
-# 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.
-
-## Generic Routes
-
-### Search
-
-```
-GET /search?q=query&source=youtube&limit=10
-```
-
-**Query Parameters:**
-- `q` - Search query
-- `source` - `youtube`, `spotify`, `soundcloud`, `twitch`, `mixcloud`, `bandcamp`, `local`, `http`
-- `limit` - Number of results
-
-### Stream
-
-```
-GET /stream/:source/:id
-```
-
-**Example:**
-```
-GET /stream/twitch/monstercat
-GET /stream/local/L2hvbWUvdXNlci9tdXNpYy9zbmFyZS53YXY= (Base64 path)
-```
-
-## 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)

package/docs/http/server.md

@@ -1,174 +0,0 @@
-# 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');
-const info = await streamify.twitch.getInfo('channel');
-const url = streamify.local.getStreamUrl('/path/to/file.mp3');
-```
-
-### 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/plans/2026-02-22-stream-revamp-design.md

@@ -1,88 +0,0 @@
-# Stream System Revamp — Design Document
-
-## Problem Statement
-
-The current stream system has critical issues:
-1. `_waitForData()` resolves on timeout (15s), allowing broken/silent streams to start playback
-2. yt-dlp spawns per-play are slow — format negotiation adds seconds of latency
-3. No URL caching — direct URLs aren't reused for replays/seeks
-4. Prefetch only resolves metadata, doesn't prepare the actual stream pipeline
-5. Error swallowing hides real failures from yt-dlp/ffmpeg stderr
-
-## Architecture: Two-Phase StreamController
-
-### Phase 1: `prepare()` — URL Extraction
-- Check `StreamURLCache` for cached direct URL
-- Cache miss → spawn `yt-dlp --get-url -f bestaudio` to extract direct stream URL
-- Cache the URL (key: `{videoId}:{format}`, TTL: 30 min)
-- For Spotify: resolve to YouTube ID first (existing behavior)
-- For live streams: skip (can't pre-extract live URLs)
-
-### Phase 2: `start()` — Stream Creation
-- Spawn ffmpeg with `-i <directURL>` (no yt-dlp pipe for non-live)
-- Wait for first byte with configurable timeout (default: 8s, live: 15s)
-- **Reject on timeout** — never proceed without data
-- Return AudioResource ready for playback
-
-### Fallback for live/non-YouTube sources
-- Spawn yt-dlp piped to ffmpeg (current behavior)
-- Same timeout/rejection behavior
-
-## StreamURLCache
-
-Module-level cache in Stream.js:
-- `Map<string, { url, headers, expiry }>`
-- `get(key)` — returns null if expired
-- `set(key, url, headers, ttl)`
-- `invalidate(key)` — for 403/gone errors
-- Auto-cleanup every 5 minutes
-
-## Player.js — Aggressive Prefetch
-
-### `_prefetchNext()` Rewrite
-- Triggers on `trackStart` (current track begins)
-- Creates full StreamController for queue[0]
-- Runs `prepare()` + `start()` — ffmpeg spawned, audio buffered
-- Stores as `_prefetchedStream` / `_prefetchedTrack`
-
-### `_playTrack()` Changes
-- Check prefetch match → instant play (zero startup)
-- Otherwise: create StreamController, prepare() + start()
-- On error: emit trackError, auto-skip
-
-### Prefetch Lifecycle
-- Clear on: filter/volume change, stop, destroy, queue reorder
-- Ignore failures: log and fall back to normal creation
-
-## Config Additions
-
-```js
-stream: {
-    dataTimeout: 8000,       // ms to wait for first byte
-    liveDataTimeout: 15000,  // ms for live streams
-    urlCacheTTL: 1800,       // 30 min
-    bufferSize: '1M',        // yt-dlp buffer (up from 256K)
-    maxRetries: 2            // extraction retries before skip
-}
-```
-
-## Error Handling
-
-- `_waitForData()`: reject on timeout (not resolve)
-- URL extraction failure: retry once before giving up
-- 403/expired URL: invalidate cache, retry with fresh extraction
-- ffmpeg stderr: parse for actionable errors, log properly
-- yt-dlp stderr: count "Retrying fragment" occurrences, fail after threshold
-
-## Files Modified
-
-1. `src/discord/Stream.js` — Full rewrite (StreamController + StreamURLCache)
-2. `src/discord/Player.js` — Prefetch rewrite, _playTrack changes
-3. `src/config.js` — New `stream` config section
-
-## Files NOT Modified
-
-- `src/filters/ffmpeg.js` — Unchanged (filter building is solid)
-- `src/providers/youtube.js` — Unchanged (search/info/playlist untouched)
-- `src/discord/Queue.js` — Unchanged
-- `src/discord/Manager.js` — Unchanged