DJ Donut v1.5.5 — 消除 FFmpeg 管道異常與語音連線防禦修復

DJ Donut v1.5.5 更新日誌 (2026-10-20)

🐛 關鍵錯誤修復 (Critical Bug Fixes)

• 徹底消除 FFmpeg Pipe Reader 崩潰報錯：移除了 FFmpegPCMAudio 中不當傳入的 參數。在 discord.py 底層機制中，傳入整數 file descriptor 會導致內部 執行緒執行 拋出 並頻繁中斷音訊讀取；FFmpeg 輸出原音訊參數中已妥善由 完全靜音處理。
• 全方位強化 safe_disconnect 斷線防御機制：修復 Discord 語音伺服器遭遇網路波動或 1006 異常重連時，因頻道狀態率先脫落為 None 導致 拋出 並跳過底層緩存清理的漏洞。現已將斷線呼叫全面隔離，保證即使遭遇異常也能 100% 清理 殘留連線。
• 嚴謹語音連線判定：於 中新增 防禦檢測，確保語音房已中斷時能立即觸發無縫重連與清理。

DJ Donut v1.5.4 — 叢集架構調校與極限零損耗音訊引擎

DJ Donut v1.5.4 更新日誌 (2026-10-20)

🎛️ 多機矩陣與控制器防串線 (Multi-Node Voice Cross-Talk Elimination)

• 獨立語音控制器精準路由：修正多機進駐時，互動式按鈕控制器（播放/暫停、下一首、上一首、重播、音量調節、停止）誤將指令發往預設節點的串線缺陷；現已全面重構為動態定位當前房間實際連線的專屬 Node Bot。
• 全方位活躍時間重置：所有互動按鈕及操作皆會即時更新 state.last_active，防止正在操作中被定時清理任務誤收。

⚡ 極限零延遲音訊時鐘 (Zero-Latency Audio Clock & Non-Blocking Buffer)

• 非阻塞緩衝讀取：徹底改造 BufferedAudioSource.read()，將原先具有鎖爭用與 time.sleep 的阻塞邏輯改為 get_nowait()。在瞬時緩衝下溢時安全回傳 Opus 靜音幀（3840 bytes），徹底根除 Discord 20ms 音訊時鐘執行緒卡頓與微斷音。
• 雙重 play_next 競態鎖定：切歌與 Seeking 轉換時引入 state.is_seeking = True 與專屬清理回調，徹底消除非同步回調競態導致的雙重跳曲問題。

🚀 執行緒池動態擴展與 API 隔離 (Thread Pool Scaling & API Isolation)

• 執行緒池擴展：將 MEDIA_EXECUTOR 擴充至 25 條平行工作執行緒，大幅提升 yt-dlp 串流解析並行吞吐量。
• 外部 API 專屬隔離池：新增 API_EXECUTOR (10 workers) 專門處理 Spotify、Apple Music 與網易雲音樂的非同步 Metadata 解析，避免外部 HTTP API 延遲阻塞核心音訊管線。

💾 原子化設定檔寫入與啟動預載 (Atomic Guild Settings Persistence)

• 原子化置換防損壞：伺服器語言、音量與 24/7 等持久化設定改用 tempfile 寫入後透過 os.replace 進行作業系統級原子置換，搭配進程內快取與執行緒鎖，杜絕併發寫入損壞 JSON。
• 啟動語系全域預載：重構 i18n.py 在機器人啟動時即自動預載所有伺服器設定，徹底解決首次指令時語言判斷偏差。

🛡️ 自主離線守護與狀態防洩漏 (Autonomous Empty Room Detection & 24/7 Guard)

• 全自動無人退房：當語音頻道內所有真人聽眾離開時，若未開啟 24/7 模式，啟動 60 秒倒數計時守護任務；若期間有聽眾返回則自動取消，無人則優雅釋放資源退房。
• 伺服器移除清理：實作 on_guild_remove，在機器人離開或被移除伺服器時立即銷毀該伺服器全部播放狀態與佇列，釋放記憶體。

🔗 動態邀請連結與智慧快取 (Dynamic Invite URLs & Suggestion Caching)

• 動態 Application ID 識別：/status 儀表板中的未加入機器人邀請連結改為直接讀取即時 b.application_id 與 b.user.id，完美適配所有自託管與客製化部署環境。
• 搜尋提示雙層快取：為 /play 與 /search 斜線指令的即時輸入自動補全導入 120 秒 TTL 快取，大幅降低使用者打字時對 Google Suggest 伺服器的無效請求。

🐳 容器安全加固 (Security & Docker Hardening)

• 權限最小化：Dockerfile 採用非 root 專屬使用者 botuser (UID 1000) 運行容器。
• 敏感資訊遮蔽：新增 .dockerignore 確保 .env、git 物件與快取不會外洩進 Docker Image。
• 容器持久化掛載：更新 docker-compose.yml 將 guild_settings.json 與 Lavalink 進行本機回環隔離保護 (127.0.0.1:2333)。

v1.5.3 - Voice Kick Recovery, Extended Pause Re-anchoring & Cute Departure Alert

🍩 DJ-Donut v1.5.3 更新說明 (Release Notes)

🐾 管理員踢出後自我修復與可愛提示 (Admin Kick Recovery & Cute Alert)

• 語音客戶端乾淨註銷 (VoiceClient Deregistration): 過去當管理員從語音房手動踢出機器人 ( 中 ) 時，discord.py 內部連線池仍滯留該 Guild 的幽靈連線，導致後續 跳出 癱瘓機器人。本次更新於踢出當下全面強制銷毀語音線程、執行清理並自連線池移除，永不再卡死！
• 自動容錯修復連線 (): 、、 全面換裝智慧安全連線器，即便檢測到滯留死鎖也會自動強制拔除並重試連線。
• 超萌離場提示 (Cute Departure Notification): 機器人被管理員踢出語音房時，會自動在文字頻道發送粉嫩可愛通知 與 ，並提示大家隨時輸入 </play:0> 就能一秒把它召喚回來！

⏸️ 暫停太久無縫修復與音訊重新錨定 (Extended Pause Stream Re-Anchoring)

• 快取主動失效與新鮮 CDN 抓取: 解決暫停時間過長導致 YouTube 串流 Token 失效或 TCP 斷線問題；恢復播放時主動清除過期快取並並行提取最新即時音訊流。
• AudioPlayer 線程等待與防衝突: 暫停太久恢復時，安全等待舊有播放器線程結束釋放，徹底杜絕 拋錯。
• 自動語音斷線重連 (Auto Voice Reconnect on Resume): 若長時間暫停期間 Discord 伺服器因閒置切斷語音連接，使用者點擊「恢復」按鈕或 時，機器人將智慧重連並直接自暫停秒數無縫續播！

v1.5.2: Long Pause Stream Re-anchoring & Controller Fix

🚀 v1.5.2 Patch Release: Long Pause Stream Re-anchoring & Interactive View Fix

This patch resolves the issue where pausing playback for extended periods caused playback to terminate, skip, or interactive buttons to stop responding.

🛠️ Key Improvements & Fixes

• Infinite Controller Lifespan: Updated MusicControllerView to timeout=None and eliminated automatic button disabling. The interactive now-playing control panel remains permanently responsive regardless of how long playback is paused.
• Smart Stale TCP Re-anchoring: In native playback, pausing for an extended duration previously caused remote HTTP/TCP sockets (Google Video CDN) to time out and disconnect. On resume after >= 15s, the player automatically validates the stream URL (refreshing expired tokens if necessary) and seamlessly re-anchors playback at the exact elapsed second.
• Dynamic Play/Pause Toggle: Interactive controller button dynamically switches emoji between ▶️ (play/resume) and ⏸️ (pause) based on live playback state.
• Added /pause and /resume Commands: Added dedicated slash commands with DJ permission enforcement, voice room routing, and multi-bot cluster support.

📦 Update Instructions

git pull origin main
docker compose down && docker compose up -d --build

v1.5.1: YouTube Stream Extraction Fix & URL Robustness

🚀 v1.5.1 Patch Release: YouTube Stream Extraction Fix & Robust URL Handling

This patch fixes the issue where music tracks failed stream extraction in Docker and server environments (yielding 無法提取串流 errors).

🛠️ Key Improvements & Fixes

• Extractor Client Update: Changed yt-dlp extractor to use mobile player clients (['android', 'ios']), bypassing the web BotGuard and GVS PO Token restrictions that caused 403 errors and empty format lists in Docker / cloud environments without cookies.
• Enabled HLS Streams: Removed skip: ['hls'] to allow FFmpeg to seamlessly ingest HLS streams if available.
• Robust URL Resolution: Fixed Song.__init__ and playlist parsing to strictly validate 11-character video IDs before prepending YouTube URLs, preventing query strings (ytsearch5:...) from being corrupted into invalid watch URLs.
• Smart Multilingual Title Fallback: Search fallback handles Chinese/CJK full-width brackets (【】, 「」, 『』) and cleans noise while retaining song identifiers, followed by SoundCloud audio fallback.
• Format Filtering: Excluded storyboard image mosaics (sb0-sb3) from audio format candidate selection to ensure pure audio streams are selected.

📦 Update Instructions

git pull origin main
docker compose down && docker compose up -d --build

v1.3.0 — Modular Architecture & Centralized Configuration

What's Changed in v1.3.0

Modular Codebase Architecture

The monolithic 3,500+ line main.py has been fully decomposed into a clean, decoupled modular layout:

• core/: Audio pipeline engine (player.py), room dispatcher (dispatcher.py), cluster node bot (node.py), and state models (models.py).
• platforms/: Standalone music resolvers for YouTube, Spotify, NetEase, and Apple Music.
• ui/: Interactive 10-button controller view (views.py), search select dropdowns, embed builders, and dynamic progress bar (embeds.py).
• commands/: Categorized slash commands (music.py, audio.py, admin.py).
• config.py: Centralized environment configurations, thread pools, DSP equalizer presets, and persistent guild settings.

Standardized Exceptions & Structured Logging

• Replaced bare terminal prints with Python's standard logging module configured under the DJDonut logger.
• Introduced custom BotError exception hierarchy (AudioSourceError, TrackNotFoundError, VoiceConnectionError, PermissionDeniedError) for streamlined error trapping and circuit breaking.

Backwards Compatibility

• Both python3 main.py and python3 bot.py work out of the box with zero changes required for existing installations or game panel configurations.
• Verified clean compilation and zero circular imports.

Full Changelog: v1.2.0...v1.3.0

DJ Donut v1.2.0 — Interactive Search, Queue Reordering & DJ Permissions

What's Changed in v1.2.0

Highlights

• Interactive Search Menu: Added /search <query> to search YouTube and pick tracks from an interactive Discord UI drop-down menu showing title, duration, and artist.
• Queue Reordering: Added /move <from> <to> to freely reposition songs inside the upcoming queue without restarting playback.
• History Replay: Added /replay [index] to quickly re-queue songs directly from room history.
• DJ Permission Roles: Added /dj [role] [clear] to configure dedicated DJ roles. When set, only DJs and server administrators can skip, stop, or clear the queue in shared rooms.
• Smart Query Autocomplete: Added autocomplete suggestions to /play with listening history matches and popular genre queries.
• Memory & Resource Reclamation: Implemented a 10-minute periodic task to automatically garbage-collect idle room states (> 30 mins) and added a 5-minute timeout to player views.
• Playlist Stream Stability: Resolved audio thread deadlocks and aligned User-Agent headers across yt-dlp and FFmpeg to prevent runaway skipping on long playlists.

---

Quick Start

1. Download discord-music-bot-v1.2.0.zip from the Assets section below.
2. Unzip into your project directory.
3. Configure your Discord Bot tokens in .env.
4. Run:

python3 main.py

DJ Donut v1.1.0 — Performance Engine & Queue Management

What's Changed in v1.1.0

Highlights

• Dedicated Media Worker Pool: Offloaded Spotify, NetEase, Apple Music, and yt-dlp metadata extraction to a 10-worker ThreadPoolExecutor, preventing the main asyncio event loop from stalling during heavy track resolution.
• Extractor Caching: Added thread-local YoutubeDL instances (threading.local) and a 30-minute in-memory stream URL cache to cut query resolution times and reduce memory allocations.
• Queue Controls: Added /seek (timestamp seeking in seconds or mm:ss), /shuffle (randomize current queue), /remove (delete track by index), /clear (wipe upcoming queue), and /history (view recently played tracks).
• Audio Stream & Playlist Stability: Resolved a thread deadlock in after_callback and aligned yt-dlp / FFmpeg HTTP headers to prevent premature queue completion when importing large playlists.
• Auto-Recovery & Failure Breaker: Added exponential backoff retries on broken stream connections, and an automatic circuit-breaker that pauses playback after consecutive resolution failures to prevent runaway skip loops.
• Settings Persistence: Guild settings (default volume, language, 24/7 permanence, bass boost level, and audio filter) now save to guild_settings.json and persist across bot restarts.
• Cleaner Shutdowns: Implemented __del__ cleanup on BufferedAudioSource to guarantee background reader threads and audio buffers terminate promptly when skipping or stopping tracks.

---

Quick Start

1. Download discord-music-bot-v1.1.0.zip from the Assets section below.
2. Unzip into your project directory.
3. Configure your Discord Bot tokens in .env.
4. Run:

python3 main.py