streamify-audio 2.2.13 → 2.3.0

package/docs/plans/2026-02-22-stream-revamp-plan.md

@@ -0,0 +1,814 @@
+# Stream System Revamp Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Rewrite the stream system for near-instant playback, proper error handling, URL caching, and aggressive prefetching.
+
+**Architecture:** Two-phase StreamController (prepare + start) with a module-level URL cache. Player does full prefetch (spawn ffmpeg for next track) while current track plays. Timeout rejects instead of resolving silently.
+
+**Key insight:** The old 15s timeout wasn't a "no data" problem — music *did* start playing, but only after ~15s because yt-dlp's format negotiation + piping is slow. The two-phase approach (`--get-url` then direct ffmpeg input) eliminates this bottleneck. The 8s timeout becomes a genuine safety net for truly broken streams, not the normal playback path.
+
+**Tech Stack:** Node.js, yt-dlp (child_process), ffmpeg (child_process), @discordjs/voice
+
+**Design doc:** `docs/plans/2026-02-22-stream-revamp-design.md`
+
+---
+
+### Task 1: Add stream config to config.js
+
+**Files:**
+- Modify: `src/config.js:5-41` (defaults object)
+
+**Step 1: Add the `stream` section to the defaults object**
+
+In `src/config.js`, add `stream` to the `defaults` object after `cache`:
+
+```js
+stream: {
+    dataTimeout: 8000,
+    liveDataTimeout: 15000,
+    urlCacheTTL: 1800,
+    bufferSize: '1M',
+    maxRetries: 2
+}
+```
+
+**Step 2: Add stream config merging in load()**
+
+In the `load()` function's config merge block (around line 82-111), add stream merging alongside the other nested configs:
+
+```js
+stream: {
+    ...defaults.stream,
+    ...fileConfig.stream,
+    ...options.stream
+}
+```
+
+**Step 3: Verify manually**
+
+Run: `node -e "const c = require('./src/config'); const cfg = c.load(); console.log(cfg.stream);"`
+Expected: Prints the stream config object with all defaults.
+
+**Step 4: Commit**
+
+```bash
+git add src/config.js
+git commit -m "feat: add stream config section (timeout, cache TTL, buffer size, retries)"
+```
+
+---
+
+### Task 2: Rewrite Stream.js — StreamURLCache
+
+**Files:**
+- Modify: `src/discord/Stream.js` (top of file, before StreamController class)
+
+**Step 1: Add StreamURLCache at the top of Stream.js**
+
+After the existing imports and `voiceModule` block, add:
+
+```js
+class StreamURLCache {
+    constructor(defaultTTL = 1800000) {
+        this._cache = new Map();
+        this._defaultTTL = defaultTTL;
+        this._cleanupInterval = setInterval(() => this._cleanup(), 300000);
+        if (this._cleanupInterval.unref) this._cleanupInterval.unref();
+    }
+
+    get(key) {
+        const entry = this._cache.get(key);
+        if (!entry) return null;
+        if (Date.now() > entry.expiry) {
+            this._cache.delete(key);
+            return null;
+        }
+        return { url: entry.url, headers: entry.headers };
+    }
+
+    set(key, url, headers = null, ttl = this._defaultTTL) {
+        this._cache.set(key, {
+            url,
+            headers,
+            expiry: Date.now() + ttl
+        });
+    }
+
+    invalidate(key) {
+        this._cache.delete(key);
+    }
+
+    get size() {
+        return this._cache.size;
+    }
+
+    _cleanup() {
+        const now = Date.now();
+        for (const [key, entry] of this._cache) {
+            if (now > entry.expiry) this._cache.delete(key);
+        }
+    }
+}
+
+const urlCache = new StreamURLCache();
+```
+
+**Step 2: Verify it loads**
+
+Run: `node -e "require('./src/discord/Stream'); console.log('OK');"`
+Expected: Prints "OK" without errors.
+
+**Step 3: Commit**
+
+```bash
+git add src/discord/Stream.js
+git commit -m "feat: add StreamURLCache with TTL and auto-cleanup"
+```
+
+---
+
+### Task 3: Rewrite Stream.js — StreamController.prepare()
+
+**Files:**
+- Modify: `src/discord/Stream.js` (StreamController class)
+
+**Step 1: Add `_extractUrl()` private method**
+
+Add this method to StreamController. It spawns `yt-dlp --get-url` to extract a direct stream URL without downloading:
+
+```js
+_extractUrl(videoId, config, isYouTube) {
+    return new Promise((resolve, reject) => {
+        const url = `https://www.youtube.com/watch?v=${videoId}`;
+        const args = [
+            '--get-url',
+            '-f', config.ytdlp.format,
+            '--no-playlist',
+            '--no-check-certificates',
+            '--no-warnings',
+            '--no-cache-dir',
+            url
+        ];
+
+        if (isYouTube) {
+            args.push('--extractor-args', 'youtube:player_client=web_creator');
+        }
+
+        if (config.cookiesPath) {
+            args.unshift('--cookies', config.cookiesPath);
+        }
+
+        if (config.sponsorblock?.enabled !== false && isYouTube) {
+            const categories = config.sponsorblock?.categories || ['sponsor', 'selfpromo'];
+            args.push('--sponsorblock-remove', categories.join(','));
+        }
+
+        const env = { ...process.env, PATH: '/usr/local/bin:/root/.deno/bin:' + process.env.PATH };
+        const proc = spawn(config.ytdlpPath, args, { env });
+
+        let stdout = '';
+        let stderr = '';
+        const timeout = setTimeout(() => {
+            proc.kill('SIGKILL');
+            reject(new Error('URL extraction timed out'));
+        }, 15000);
+
+        proc.stdout.on('data', (data) => { stdout += data; });
+        proc.stderr.on('data', (data) => { stderr += data; });
+
+        proc.on('close', (code) => {
+            clearTimeout(timeout);
+            if (code !== 0) {
+                return reject(new Error(`yt-dlp --get-url failed (code ${code}): ${stderr.slice(-200)}`));
+            }
+            const urls = stdout.trim().split('\n').filter(Boolean);
+            if (urls.length === 0) {
+                return reject(new Error('yt-dlp returned no URLs'));
+            }
+            resolve(urls[0]);
+        });
+
+        proc.on('error', (err) => {
+            clearTimeout(timeout);
+            reject(new Error(`yt-dlp spawn failed: ${err.message}`));
+        });
+    });
+}
+```
+
+**Step 2: Add `prepare()` method**
+
+This is the first phase — resolves Spotify, extracts/caches the direct URL:
+
+```js
+async prepare() {
+    if (this.destroyed) throw new Error('Stream already destroyed');
+
+    this.startTime = Date.now();
+    const source = this.track.source || 'youtube';
+    let videoId = this.track._resolvedId || this.track.id;
+
+    if (source === 'spotify' && !this.track._resolvedId) {
+        log.info('STREAM', `Resolving Spotify track to YouTube: ${this.track.title}`);
+        try {
+            const spotify = require('../providers/spotify');
+            videoId = await spotify.resolveToYouTube(this.track.id, this.config);
+            this.track._resolvedId = videoId;
+            this.metrics.metadata = Date.now() - this.startTime;
+        } catch (error) {
+            throw new Error(`Failed to resolve Spotify track: ${error.message}`);
+        }
+    } else {
+        this.metrics.metadata = 0;
+    }
+
+    if (!videoId || videoId === 'undefined') {
+        throw new Error(`Invalid track ID: ${videoId} (source: ${source})`);
+    }
+
+    this._videoId = videoId;
+    const isYouTube = source === 'youtube' || source === 'spotify';
+    const isLive = this.track.isLive === true || this.track.duration === 0;
+    const isLocal = source === 'local';
+
+    if (isLocal || isLive || !isYouTube) {
+        this._useDirectUrl = false;
+        this._prepared = true;
+        return;
+    }
+
+    const cacheKey = `${videoId}:${this.config.ytdlp.format}`;
+    const cached = urlCache.get(cacheKey);
+
+    if (cached) {
+        log.info('STREAM', `URL cache hit for ${videoId}`);
+        this._directStreamUrl = cached.url;
+        this._directStreamHeaders = cached.headers;
+        this._useDirectUrl = true;
+        this._prepared = true;
+        return;
+    }
+
+    const extractStart = Date.now();
+    const maxRetries = this.config.stream?.maxRetries || 2;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+        try {
+            const extractedUrl = await this._extractUrl(videoId, this.config, isYouTube);
+            this.metrics.urlExtract = Date.now() - extractStart;
+
+            const ttl = (this.config.stream?.urlCacheTTL || 1800) * 1000;
+            urlCache.set(cacheKey, extractedUrl, this.track._headers, ttl);
+
+            this._directStreamUrl = extractedUrl;
+            this._directStreamHeaders = this.track._headers;
+            this._useDirectUrl = true;
+            this._prepared = true;
+
+            log.info('STREAM', `URL extracted for ${videoId} (${this.metrics.urlExtract}ms, attempt ${attempt})`);
+            return;
+        } catch (error) {
+            log.warn('STREAM', `URL extraction attempt ${attempt}/${maxRetries} failed: ${error.message}`);
+            if (attempt === maxRetries) {
+                log.warn('STREAM', `All extraction attempts failed for ${videoId}, falling back to pipe mode`);
+                this._useDirectUrl = false;
+                this._prepared = true;
+                return;
+            }
+        }
+    }
+}
+```
+
+**Step 3: Commit**
+
+```bash
+git add src/discord/Stream.js
+git commit -m "feat: add prepare() phase with URL extraction and caching"
+```
+
+---
+
+### Task 4: Rewrite Stream.js — StreamController.start()
+
+**Files:**
+- Modify: `src/discord/Stream.js` (StreamController class)
+
+**Step 1: Rewrite `_waitForData()` to reject on timeout**
+
+Replace the existing `_waitForData` method entirely:
+
+```js
+_waitForData() {
+    const ffmpeg = this.ffmpeg;
+    const ytdlp = this.ytdlp;
+    const isLive = this.track.isLive === true || this.track.duration === 0;
+    const timeoutMs = isLive
+        ? (this.config.stream?.liveDataTimeout || 15000)
+        : (this.config.stream?.dataTimeout || 8000);
+
+    return new Promise((resolve, reject) => {
+        if (!ffmpeg) return resolve();
+
+        let resolved = false;
+
+        const timeout = setTimeout(() => {
+            if (resolved) return;
+            resolved = true;
+            if (ffmpeg.stdout) ffmpeg.stdout.removeListener('readable', onReadable);
+            reject(new Error(`Stream timed out after ${timeoutMs}ms waiting for audio data`));
+        }, timeoutMs);
+
+        const onReadable = () => {
+            if (resolved) return;
+            resolved = true;
+            this.metrics.firstByte = Date.now() - this._ffmpegSpawnTime;
+            clearTimeout(timeout);
+            if (ffmpeg.stdout) ffmpeg.stdout.removeListener('readable', onReadable);
+            resolve();
+        };
+
+        if (ffmpeg.stdout) {
+            ffmpeg.stdout.on('readable', onReadable);
+        }
+
+        ffmpeg.on('close', (code) => {
+            if (resolved) return;
+            resolved = true;
+            clearTimeout(timeout);
+            if (ffmpeg.stdout) ffmpeg.stdout.removeListener('readable', onReadable);
+
+            if (this.destroyed) {
+                return reject(new Error('Stream destroyed during initialization'));
+            }
+
+            const sourceErr = ytdlp
+                ? `yt-dlp stderr: ${this.ytdlpError.slice(-200) || 'none'}`
+                : `ffmpeg stderr: ${this.ffmpegError.slice(-200) || 'none'}`;
+            reject(new Error(`ffmpeg closed before producing data. ${sourceErr}`));
+        });
+
+        if (ytdlp) {
+            ytdlp.on('close', (code) => {
+                if (!resolved && code !== 0 && code !== null) {
+                    resolved = true;
+                    clearTimeout(timeout);
+                    if (ffmpeg.stdout) ffmpeg.stdout.removeListener('readable', onReadable);
+                    if (this.destroyed) {
+                        return reject(new Error('Stream destroyed during initialization'));
+                    }
+                    reject(new Error(`yt-dlp failed with code ${code}: ${this.ytdlpError.slice(-200)}`));
+                }
+            });
+        }
+    });
+}
+```
+
+**Step 2: Rewrite `create()` → `start()` method**
+
+Replace the existing `create()` method. The new `start()` uses the URL from `prepare()` when available, falls back to yt-dlp pipe for live/unsupported:
+
+```js
+async start(seekPosition = 0) {
+    if (this.destroyed) throw new Error('Stream already destroyed');
+    if (this.resource) return this.resource;
+
+    if (!this._prepared) {
+        await this.prepare();
+    }
+
+    if (!this.startTime) this.startTime = Date.now();
+    const startTimestamp = this.startTime;
+
+    const videoId = this._videoId || this.track._resolvedId || this.track.id;
+    const source = this.track.source || 'youtube';
+    const isLive = this.track.isLive === true || this.track.duration === 0;
+    const isLocal = source === 'local';
+    const isYouTube = source === 'youtube' || source === 'spotify';
+
+    log.info('STREAM', `Creating stream for ${videoId} (${source}, mode: ${this._useDirectUrl ? 'direct' : isLocal ? 'local' : 'pipe'})`);
+
+    const filterNames = Object.keys(this.filters).filter(k => k !== 'start' && k !== '_trigger' && k !== 'volume');
+    if (filterNames.length > 0) {
+        const chain = filterNames.map(name => {
+            const val = this.filters[name];
+            let displayVal = typeof val === 'object' ? JSON.stringify(val) : val;
+            if (displayVal === true || displayVal === 'true') displayVal = 'ON';
+            return `[${name.toUpperCase()} (${displayVal})]`;
+        }).join(' > ');
+        log.info('STREAM', `Filter Chain: ${chain}`);
+    }
+
+    const env = { ...process.env, PATH: '/usr/local/bin:/root/.deno/bin:' + process.env.PATH };
+    const bufferSize = this.config.stream?.bufferSize || '1M';
+
+    if (!this._useDirectUrl && !isLocal) {
+        let url;
+        if (source === 'soundcloud') {
+            url = this.track.uri || `https://api.soundcloud.com/tracks/${videoId}/stream`;
+        } else if (['twitch', 'mixcloud', 'bandcamp', 'http'].includes(source)) {
+            url = this.track.uri || videoId;
+        } else {
+            url = `https://www.youtube.com/watch?v=${videoId}`;
+        }
+
+        const formatString = isLive ? 'bestaudio*/best' : this.config.ytdlp.format;
+        const ytdlpArgs = [
+            '-f', formatString,
+            '--no-playlist',
+            '--no-check-certificates',
+            '--no-warnings',
+            '--no-cache-dir',
+            '--no-mtime',
+            '--buffer-size', bufferSize,
+            '--quiet',
+            '--retries', '3',
+            '--fragment-retries', '3',
+            '-o', '-',
+            ...this.config.ytdlp.additionalArgs,
+            url
+        ];
+
+        if (isLive) {
+            ytdlpArgs.push('--no-live-from-start');
+        } else if (isYouTube) {
+            ytdlpArgs.push('--extractor-args', 'youtube:player_client=web_creator');
+        }
+
+        if (seekPosition > 0) {
+            const seekSeconds = Math.floor(seekPosition / 1000);
+            ytdlpArgs.push('--download-sections', `*${seekSeconds}-`);
+            log.info('STREAM', `Seeking to ${seekSeconds}s`);
+        }
+
+        if (this.config.cookiesPath) {
+            ytdlpArgs.unshift('--cookies', this.config.cookiesPath);
+        }
+
+        if (this.config.sponsorblock?.enabled !== false && isYouTube) {
+            const categories = this.config.sponsorblock?.categories || ['sponsor', 'selfpromo'];
+            ytdlpArgs.push('--sponsorblock-remove', categories.join(','));
+        }
+
+        this.ytdlp = spawn(this.config.ytdlpPath, ytdlpArgs, { env });
+    }
+
+    const ffmpegFilters = { ...this.filters };
+    const ffmpegArgs = buildFfmpegArgs(ffmpegFilters, this.config);
+
+    if (isLocal) {
+        const filePath = this.track.absolutePath || videoId.replace('file://', '');
+        const pipeIndex = ffmpegArgs.indexOf('pipe:0');
+        if (pipeIndex > 0) {
+            ffmpegArgs[pipeIndex] = filePath;
+            if (seekPosition > 0) {
+                const seekSeconds = (seekPosition / 1000).toFixed(3);
+                ffmpegArgs.splice(pipeIndex - 1, 0, '-ss', seekSeconds);
+            }
+        }
+    } else if (this._useDirectUrl) {
+        let inputUrl = this._directStreamUrl;
+
+        if (seekPosition > 0) {
+            const pipeIndex = ffmpegArgs.indexOf('pipe:0');
+            if (pipeIndex > 0) {
+                const seekSeconds = (seekPosition / 1000).toFixed(3);
+                ffmpegArgs.splice(pipeIndex - 1, 0, '-ss', seekSeconds);
+            }
+        }
+
+        const pipeIndex = ffmpegArgs.indexOf('pipe:0');
+        if (pipeIndex > 0) {
+            ffmpegArgs[pipeIndex] = inputUrl;
+            if (this._directStreamHeaders) {
+                const headers = Object.entries(this._directStreamHeaders)
+                    .map(([k, v]) => `${k}: ${v}`)
+                    .join('\r\n');
+                ffmpegArgs.splice(pipeIndex - 1, 0, '-headers', headers);
+            }
+        }
+    }
+
+    this._ffmpegSpawnTime = Date.now();
+    this.ffmpeg = spawn(this.config.ffmpegPath, ffmpegArgs, { env });
+    this.metrics.spawn = Date.now() - startTimestamp - this.metrics.metadata;
+
+    if (this.ytdlp) {
+        this.ffmpeg.stdin.on('error', (err) => {
+            if (err.code !== 'EPIPE' && err.code !== 'ERR_STREAM_DESTROYED') {
+                log.error('STREAM', `ffmpeg stdin error: ${err.message}`);
+            }
+        });
+
+        this.ytdlp.stdout.on('error', (err) => {
+            if (err.code !== 'EPIPE' && err.code !== 'ERR_STREAM_DESTROYED') {
+                log.error('STREAM', `yt-dlp stdout error: ${err.message}`);
+            }
+        });
+
+        this.ytdlp.stdout.pipe(this.ffmpeg.stdin);
+
+        this.ytdlp.stderr.on('data', (data) => {
+            if (this.destroyed) return;
+            const msg = data.toString();
+            this.ytdlpError += msg;
+            if (msg.includes('ERROR:') && !msg.includes('Retrying') && !msg.includes('Broken pipe')) {
+                log.error('YTDLP', msg.trim());
+            }
+        });
+
+        this.ytdlp.on('close', (code) => {
+            if (code !== 0 && code !== null && !this.destroyed) {
+                log.error('STREAM', `yt-dlp failed (code: ${code}) for ${videoId}`);
+            }
+            if (this.ffmpeg && !this.ffmpeg.killed && this.ffmpeg.stdin) {
+                try { this.ffmpeg.stdin.end(); } catch(e) {}
+            }
+        });
+    }
+
+    this.ffmpeg.stderr.on('data', (data) => {
+        if (this.destroyed) return;
+        const msg = data.toString();
+        this.ffmpegError += msg;
+        if ((msg.includes('Error') || msg.includes('error')) && !msg.includes('Connection reset') && !msg.includes('Broken pipe')) {
+            log.error('FFMPEG', msg.trim());
+        }
+    });
+
+    try {
+        await this._waitForData();
+    } catch (error) {
+        if (this._useDirectUrl && error.message.includes('timed out')) {
+            const cacheKey = `${videoId}:${this.config.ytdlp.format}`;
+            urlCache.invalidate(cacheKey);
+            log.warn('STREAM', `Invalidated cached URL for ${videoId} after timeout`);
+        }
+        this.destroy();
+        throw error;
+    }
+
+    if (this.destroyed || !this.ffmpeg) {
+        throw new Error('Stream destroyed during initialization');
+    }
+
+    this.resource = createAudioResource(this.ffmpeg.stdout, {
+        inputType: StreamType.OggOpus,
+        inlineVolume: false,
+        silencePaddingFrames: 5
+    });
+
+    const elapsed = Date.now() - startTimestamp;
+    this.metrics.total = elapsed;
+
+    log.info('STREAM', `Ready ${elapsed}ms | Metrics: [Metadata: ${this.metrics.metadata}ms | URLExtract: ${this.metrics.urlExtract || 0}ms | Spawn: ${this.metrics.spawn}ms | FirstByte: ${this.metrics.firstByte || 0}ms]`);
+
+    return this.resource;
+}
+```
+
+**Step 3: Keep `create()` as an alias for backward compat**
+
+Add a simple alias so Player.js and any other callers still work:
+
+```js
+async create(seekPosition = 0) {
+    return this.start(seekPosition);
+}
+```
+
+**Step 4: Update constructor to initialize new fields**
+
+Add these to the constructor after existing fields:
+
+```js
+this._videoId = null;
+this._directStreamUrl = null;
+this._directStreamHeaders = null;
+this._useDirectUrl = false;
+this._prepared = false;
+this._ffmpegSpawnTime = null;
+this.metrics.urlExtract = 0;
+```
+
+**Step 5: Commit**
+
+```bash
+git add src/discord/Stream.js
+git commit -m "feat: rewrite start() with two-phase pipeline and proper timeout rejection"
+```
+
+---
+
+### Task 5: Rewrite Player.js — Aggressive Prefetch
+
+**Files:**
+- Modify: `src/discord/Player.js:383-405` (`_prefetchNext` method)
+- Modify: `src/discord/Player.js:313-373` (`_playTrack` method)
+
+**Step 1: Rewrite `_prefetchNext()` to do full stream preparation**
+
+Replace the existing `_prefetchNext` method:
+
+```js
+async _prefetchNext() {
+    if (this._prefetching || this.queue.tracks.length === 0) return;
+
+    const nextTrack = this.queue.tracks[0];
+    if (!nextTrack) return;
+
+    if (this._prefetchedTrack?.id === nextTrack.id && this._prefetchedStream) return;
+
+    this._clearPrefetch();
+    this._prefetching = true;
+    log.debug('PLAYER', `Prefetching stream: ${nextTrack.title}`);
+
+    try {
+        const filtersWithVolume = { ...this._filters, volume: this._volume };
+        const stream = createStream(nextTrack, filtersWithVolume, this.config);
+
+        await stream.prepare();
+
+        if (this._destroyed || this.queue.tracks[0]?.id !== nextTrack.id) {
+            stream.destroy();
+            return;
+        }
+
+        await stream.start(0);
+
+        if (this._destroyed || this.queue.tracks[0]?.id !== nextTrack.id) {
+            stream.destroy();
+            return;
+        }
+
+        this._prefetchedStream = stream;
+        this._prefetchedTrack = nextTrack;
+        log.info('PLAYER', `Prefetch ready: ${nextTrack.title} (${stream.metrics.total}ms)`);
+    } catch (error) {
+        log.debug('PLAYER', `Prefetch failed: ${error.message}`);
+    } finally {
+        this._prefetching = false;
+    }
+}
+```
+
+**Step 2: Update `_playTrack()` to use prefetched streams**
+
+Replace the existing `_playTrack` method. Key changes:
+- Checks prefetch match with resource validation
+- Creates two-phase stream on miss
+- Clears prefetch on filter/volume mismatch
+
+```js
+async _playTrack(track, startPosition = 0) {
+    if (!track) return;
+
+    log.info('PLAYER', `Playing: ${track.title} (${track.id})` + (startPosition > 0 ? ` @ ${Math.floor(startPosition / 1000)}s` : ''));
+    this.emit('trackStart', track);
+
+    let newStream = null;
+    let resource = null;
+
+    try {
+        const filtersWithVolume = { ...this._filters, volume: this._volume };
+
+        if (startPosition === 0 && this._prefetchedTrack?.id === track.id && this._prefetchedStream?.resource) {
+            log.info('PLAYER', `Using prefetched stream for ${track.id}`);
+            newStream = this._prefetchedStream;
+            resource = newStream.resource;
+            this._prefetchedStream = null;
+            this._prefetchedTrack = null;
+        } else {
+            this._clearPrefetch();
+            newStream = createStream(track, filtersWithVolume, this.config);
+            resource = await newStream.start(startPosition);
+        }
+
+        const oldStream = this.stream;
+        this.stream = newStream;
+        this.audioPlayer.play(resource);
+
+        if (oldStream && oldStream !== newStream) {
+            oldStream.destroy();
+        }
+
+        this._playing = true;
+        this._paused = false;
+        this._positionMs = startPosition;
+        this._positionTimestamp = Date.now();
+
+        this._prefetchNext();
+        setImmediate(() => this._updateVoiceChannelStatus(track));
+
+        return track;
+    } catch (error) {
+        if (newStream && newStream !== this.stream) {
+            newStream.destroy();
+        }
+
+        if (this._manualSkip || this._changingStream || error.message.includes('Stream destroyed')) {
+            log.debug('PLAYER', `Playback cancelled for ${track.id}`);
+            return;
+        }
+
+        log.error('PLAYER', `Failed to play track: ${error.message}`);
+        this.emit('trackError', track, error);
+
+        const next = this.queue.shift();
+        if (next) {
+            setImmediate(() => this._playTrack(next));
+        } else {
+            this.emit('queueEnd');
+        }
+    }
+}
+```
+
+**Step 3: Clear prefetch on filter/volume changes**
+
+In `setVolume()` (around line 653), add `this._clearPrefetch();` at the start of the method before the `if (this._playing ...)` check.
+
+In `setFilter()` (around line 691), add `this._clearPrefetch();` at the start after setting the filter value.
+
+In `setEffectPresets()` (around line 748), add `this._clearPrefetch();` after recalculating filters.
+
+**Step 4: Commit**
+
+```bash
+git add src/discord/Player.js
+git commit -m "feat: aggressive prefetch with full stream pre-creation"
+```
+
+---
+
+### Task 6: Manual Integration Test
+
+**Step 1: Start the service**
+
+Run: `pm2 restart streamify`
+
+**Step 2: Check logs for startup errors**
+
+Run: `pm2 logs streamify --lines 20`
+Expected: Clean startup, no errors.
+
+**Step 3: Test playback via Discord bot**
+
+Play a YouTube track. Verify in logs:
+- `URL extracted for <id>` (not the old "Creating stream" without extraction)
+- `Ready <time>ms` with timing breakdown including `URLExtract`
+- Stream starts playing without the old 15s timeout warning
+
+**Step 4: Test prefetch**
+
+Queue two tracks. After first starts, verify in logs:
+- `Prefetching stream: <next track title>`
+- `Prefetch ready: <next track title> (<time>ms)`
+- When first track ends/skips: `Using prefetched stream for <id>` — near-instant transition
+
+**Step 5: Test URL cache**
+
+Play the same track again (or seek). Verify:
+- `URL cache hit for <id>` — skips yt-dlp extraction
+
+**Step 6: Test timeout behavior**
+
+This is harder to trigger naturally. But verify in code review that:
+- `_waitForData()` rejects (not resolves) on timeout
+- Player catches the error and auto-skips
+
+**Step 7: Commit any fixes**
+
+```bash
+git add -A
+git commit -m "fix: post-integration test fixes"
+```
+
+---
+
+### Task 7: Cleanup & Final Commit
+
+**Step 1: Remove dead code**
+
+In Stream.js, verify no old methods remain unused. The old `create()` is now an alias for `start()`.
+
+**Step 2: Verify all existing functionality works**
+
+- Seek (creates new stream with position)
+- Volume change (recreates stream)
+- Filter change (recreates stream, clears prefetch)
+- Pause/resume (stream destroy after 5min, recreate on resume)
+- Skip (uses prefetch if available)
+- Stop/destroy (cleans up prefetch)
+- Local files (bypass URL extraction)
+- SoundCloud/Twitch/etc (pipe mode fallback)
+- Live streams (pipe mode, longer timeout)
+
+**Step 3: Final commit**
+
+```bash
+git add -A
+git commit -m "chore: stream system revamp complete — two-phase pipeline, URL cache, aggressive prefetch"
+```