streamify-audio 2.3.0 → 2.3.2

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

@@ -1,814 +0,0 @@
-# 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"
-```