SocketSVC Docs疑難排解
自動重新連線、/ssvc status、錯誤訊息、開發者模式與常見問題
自動重新連線
語音成功連線後，如果因為網路或語音服務而中斷，只要你還在同一個 Minecraft 伺服器上，用戶端就會自動申請新的一次性權杖並重新連線，不必執行 /ssvc reconnect。
| 項目 | 行為 |
|---|---|
| 重試間隔 | 每次失敗後依序等待 5、10、20、30 秒，之後最多每 30 秒重試一次 |
| 逾時 | 等待權杖回應與開啟 WebSocket 各自在 30 秒後逾時 |
| 退避重設 | 連線維持 30 秒後重設 |
| 斷線偵測 | 每 10 秒送一次 WebSocket ping/pong，即使沒人說話也能發現連線已失效；重試間隔從發現的那一刻起算 |
| 權杖 | 每次嘗試都會申請全新的一次性權杖；失敗的權杖一律不快取、不重複使用。權杖的 30 秒有效期只用於准許連線，已建立的連線不必定期更新 |
| 保留的狀態 | 恢復連線後，靜音／停止接收語音與首次使用的隱私設定都會保留 |
| 通知 | 連續失敗時，聊天室只會通知一次，直到語音恢復為止；設定畫面會顯示「語音將自動重新連線」，HUD 則顯示「重新連線中...」 |
即使代理伺服器沒有公告外掛頻道，只要先前曾連上語音，這次遊戲連線仍可申請新權杖，前提是伺服器支援 socketsvc:handshake_request。沒有安裝 SocketSVC 的伺服器則會安靜地維持離線。
以下情況會停止自動重試：
- 你離開或切換 Minecraft 伺服器（重試排程會清除，舊伺服器遲來的回應也會忽略）
- 明確停止語音
- 連線因為遭到取代、退出、頻率／政策拒絕或不支援的訊息而關閉（關閉代碼 4000/4003/4008/1008/1003）
舊權杖絕不重複使用；伺服器若未確認有執行 SocketSVC，用戶端也絕不會盲目重新連線。重試停止後，可以執行 /ssvc reconnect 手動重新開始。暫時性錯誤與權杖遭拒（4001）則會自動重試。
麥克風斷線時
拔掉耳麥、USB 麥克風重設或藍牙耳機斷訊，都不會中斷語音。用戶端會自行重新開啟麥克風，不必回到設定重新選擇。
| 情況 | 會發生什麼 |
|---|---|
| 麥克風馬上就恢復（短暫重設） | 約半秒內恢復收音，聊天室不會顯示訊息 |
| 你選擇的麥克風不見了，但還有其他麥克風 | 改用系統預設麥克風，並在聊天室告知 |
| 完全沒有麥克風 | 用戶端會持續重試（最多每幾秒一次），並在聊天室告知一次 |
| 你選擇的麥克風重新插回 | 幾秒內自動切換回來，並在聊天室告知麥克風已恢復 |
| 麥克風仍連接著，但不再傳送音訊 | 連續 3 秒沒有音訊就視為斷線，並重新開啟 |
能不能切換回原本的麥克風，要看裝置重新連接後系統是否再次回報。如果麥克風沒有自動恢復，請在 裝置 中重新選擇，這樣一定會重新開啟。
手動重新連線與狀態
| 指令 | 用途 |
|---|---|
/ssvc status | 顯示連線狀態、靜音／停止接收語音、麥克風 RMS 音量與門檻、本次工作階段已傳送的幀數，以及輸入／輸出裝置 |
/ssvc reconnect | 不必離開 Minecraft 就能申請新權杖；伺服器須為新版，最多每 5 秒執行一次 |
詳情請參閱 操作方式。
錯誤訊息
| 訊息 | 意義 |
|---|---|
| 語音伺服器網址無效，請管理員檢查 public-url。 | 伺服器傳來的語音網址格式錯誤，須由伺服器管理員修正 public-url |
| 語音授權已過期或遭拒絕，輸入 /ssvc reconnect 取得新授權。 | 權杖已過期或遭拒絕 |
| 無法連上語音，輸入 /ssvc reconnect 重試。 | 連不上語音監聽器 |
| 無法啟動語音連線，請檢查伺服器網址並輸入 /ssvc reconnect。 | 開啟連線失敗 |
| 語音連線逾時，輸入 /ssvc reconnect 重試。 | 連線沒有在時限內完成 |
| 語音已斷線（原因），輸入 /ssvc reconnect 重試。 | 連線中斷，括號內是原因 |
| 收到無效的語音連線資料，請管理員檢查 SocketSVC。 | 交握資料格式錯誤，通常是伺服器的版本或設定問題 |
| 無法使用麥克風，請重新開啟輸入裝置。 | 麥克風已拔除或無法開啟；請到「一般設定」分頁重新選擇麥克風 |
| 自訂取樣沒有聲音、有雜音，或顯示「無法讀取」 | 舊版會誤讀 24 位元與 32 位元的 WAV，還可能把 WAV 交給 MP3 解碼器處理，這兩個問題都已修正。如果仍有問題，可能是檔名沒有對應到任何鼓；「鼓組音色」設定會列出哪些鼓改用內建音色、哪些檔案沒有用到，以及原因 |
| 無法使用樂器：...line with format PCM_SIGNED... not supported | SocketSVC 試過的錄音格式，裝置全都拒絕。通常是其他程式正在使用這個裝置，最常見的是 DAW 獨佔了錄音介面，請先把它關閉。訊息裡附有裝置自己回報的原因，那才是值得細看的部分 |
自動重新連線期間，提到 /ssvc reconnect 的錯誤通常會自行恢復。
常見問題
| 症狀 | 優先檢查 |
|---|---|
| 在遊戲中但沒有語音 | /ssvc status、伺服器狀態、基礎網址、監聽器是否可連線、代理伺服器協商、首次使用設定與靜音狀態 |
| 首次使用設定期間沒人聽得到我 | 按下「開始使用」關閉設定之前，不會傳送任何麥克風音訊 |
| 在本機可以用，但其他電腦的玩家連不上 | 請伺服器管理員確認 public-host/public-url 是玩家連得到的位址，而不是 localhost（請參閱 架設伺服器） |
| 音訊測試都通過，但實際通話聽起來不對 | 檢查裝置路由與收音／播放設定，並實際找兩位玩家測試；合成測試無法涵蓋所有聲學情況 |
| 其他人聽到自己的回音 | 確認「進階設定」→「迴音消除」已開啟（升級時會保留舊版儲存的「關閉」）；遇到難搞的裝置，可以關閉「自動偵測迴音延遲」改為手動設定。戴耳機是最可靠的解法 |
| 說話的開頭或結尾會斷掉 | 使用「按鍵說話」，或將「語音偵測」設為「手動」並調低門檻 |
| 別人聽得到背景噪音或遊戲聲音 | 開啟「雜訊抑制」；在支援的平台上可下載「進階雜訊消除」模型 |
| 玩家音量顯示「等待玩家名單；舊版伺服器不支援此功能。」 | 伺服器版本太舊；語音仍可使用，只是沒有玩家名單。請把用戶端和伺服器都更新 |
| 名牌上從不顯示停止接收語音的圖示 | 用戶端和伺服器都要更新，才會同步停止接收語音的狀態 |
| 分辨不出聲音在前方還是後方 | 使用立體聲耳機，並停用其他環繞音效處理；定位只分水平方向，請參閱 耳機空間音訊 |
| 「進階雜訊消除」顯示「此平台不支援」 | 只支援 Windows x64、Linux x64 與 macOS Apple Silicon；其他平台使用 RNNoise |
| 「進階雜訊消除」模型下載失敗 | 點一下即可重試；下載期間與失敗後會改用 RNNoise |
語音連上時遊戲當機，hs_err_pid 記錄檔寫著 socketsvc-mic-capture 執行緒在 msvcp140.dll 發生 EXCEPTION_ACCESS_VIOLATION | 只發生在 Windows：你的 Java 內附的 Microsoft C++ 執行階段比「進階雜訊消除」模型（ONNX Runtime）需要的舊，會直接讓遊戲當機而不是失敗。請關閉「進階雜訊消除」。更新後的用戶端會自動偵測，改用預設的雜訊抑制，並顯示「因舊版 Windows 執行階段被封鎖」。若仍想使用這個模型，請改用較新的 Java 21 版本；如果舊檔是 Windows 本身的，則安裝最新的 Microsoft Visual C++ 可轉散發套件 |
| 標題畫面出現「偵測到其他語音聊天模組」 | 同時裝了 Simple Voice Chat 或 Plasmo Voice。兩個都可以保留，在沒有 SocketSVC 的伺服器上 SocketSVC 會自動讓開（請參閱 相容性） |
| 看不到 SocketSVC 圖示、按鍵沒反應 | Simple Voice Chat 或 Plasmo Voice 已連上這台伺服器，而伺服器沒有 SocketSVC，所以 SocketSVC 自動讓開。這是正常的 |
| 看不到 Simple Voice Chat 或 Plasmo Voice 圖示、按鍵沒反應 | 那個模組沒有連上，所以 SocketSVC 把它的按鍵關掉。如果伺服器確實有裝它，代表它連線失敗，請從模組清單開啟它的設定畫面 |
| 按 V 打不開 Simple Voice Chat 或 Plasmo Voice 選單 | Minecraft 把重複的按鍵交給了 SocketSVC，請在「控制」設定中改掉其中一個（請參閱 相容性） |
| 把世界開放給區域網路，但訪客沒有語音 | 訪客要安裝符合自己載入器的 SocketSVC 用戶端模組，而且必須開啟 進階設定 → 區域網路主持 → 在區域網路主持語音聊天；請參閱 區域網路與單人遊戲 |
| 聊天室說正在使用系統預設麥克風 | 你選擇的麥克風已拔除或無法使用；恢復後會自動切換回去，請參閱 麥克風斷線時 |
| 音效板顯示「此伺服器尚未支援音效板頻道…」 | 伺服器版本太舊；音效會走你的麥克風頻道，無法同時播放 |
| 其他人聽不到我的音效板 | 伺服器可能設定了 soundboard-enabled: false，或拒絕了你的 socketsvc.soundboard 權限；此外，停止接收語音的玩家本來就聽不到 |
| 網址下載顯示無法自動下載 ffmpeg | macOS 請自行安裝 ffmpeg（例如 brew install ffmpeg）並重新啟動遊戲 |
| 在沒有 SocketSVC 的伺服器上顯示斷線圖示 | 正常：沒有東西可以連線。按 H 可隱藏 HUD |
| 在沒有 SocketSVC 的伺服器上，HUD 顯示「連線中...」 | 現在不應該再發生：要等伺服器宣告 SocketSVC 或送出交握，才會出現「連線中...」。如果還是出現，代表伺服器（或前面的代理伺服器）宣告了 SocketSVC 的頻道卻沒有執行它 |
開發者模式
開啟「進階設定」→「診斷」→「開發者模式」後，右上角會顯示本機語音統計資料，每秒更新兩次；這個設定會保留下來：
- 每秒傳送（指已進入 WebSocket 傳送佇列）與接收的封包數，以及本次工作階段的總數
- 本機 TX 丟棄數與百分比
- 播放佇列幀數、音源數、重新緩衝目標、溢出丟棄與延遲修剪
- 已解碼幀數、解碼錯誤與無效封包
- 緩衝區耗盡次數（包含一般說話時的停頓）以及距離上一個音訊封包的時間
- 麥克風 RMS，以及目前是否正在傳送
- 迴音消除狀態（關閉／已鎖定並顯示延遲／未鎖定、學習中或壓低中）
- 協商出的通訊協定版本（v1/v2）、遺失幀、PLC 成功補償的幀，以及過時／重複的幀
解讀這些數值時請注意：
- 「已傳送」只代表封包已進入 WebSocket 傳送佇列，不代表已確認送達。
- 遺失幀是播放／應用層的序號缺口，不是真正的 TCP 網路遺失。疊加畫面看不到端對端延遲，也看不到伺服器的丟棄遙測資料。
- 什麼都沒收到，可能只是附近沒有人在說話。
- 延遲修剪是為了消除緩衝延遲而刻意跳過的幀，不是連線弄丟的幀。數字持續小幅增加，表示音訊一直成批抵達；數字不再增加，表示佇列已穩定在目標值。
- 每次重新嘗試連線時計數器都會歸零；連線失敗後仍會繼續顯示。
- 不會顯示任何權杖、伺服器網址或玩家身分。
回報問題時，也請開啟「詳細記錄」，把連線、音訊與網路的追蹤資訊寫進 latest.log。
網路延遲與緩衝
以下都是用戶端內建的行為，不需要任何設定：
- 播放時會依封包抵達的抖動程度，在 60 到 400 毫秒之間調整起始預緩衝；每位說話者的積壓上限固定為 1 秒（50 幀）。封包抵達出現空檔時，目標值會迅速提高，維持一秒後再每 250 毫秒降低一幀。
- 卡頓後留在佇列裡的延遲會逐步消除。佇列沒辦法自己消化，因為每 20 毫秒抵達一幀、也只播放一幀；所以卡頓後堆積的音訊會以溫和的速度跳過（每 240 毫秒跳過一個 20 毫秒的幀，落後很多時會更快），直到佇列回到目標值。沒有積壓的連線則完全不會修剪。如果你以前經由通道或反向代理伺服器使用語音，一開始正常、但越講越延遲，現在應該會看到改善。
- 樂器的線路輸入在收音端也用同樣的方式消化，所以自己電腦短暫卡頓時，樂器聲不會再一直落後於你的演奏。
- 1–3 幀（最多 60 毫秒）的空缺以 Opus PLC 補償；更長的空缺則會重設解碼器，再從真實音訊接著播放。
- WebSocket 暫時出現背壓時，傳送端每位說話者最多保留 25 個封包，總共最多 256 個；尚未送出的音訊一旦超過 600 毫秒，就會捨棄最舊的封包。
緩衝有限，無法掩蓋任意長的 TCP 卡頓；真正的跨區域連線仍需實際測試。