語音

discli 的語音模組讓你的機器人具備：加入伺服器語音頻道、即時轉譯所有說話人、以 TTS 說話、播放音訊。完成本指南後，你會建立一個會議逐字稿工具：把每位發言者標註寫入檔案，並在停止時請 Claude 產生會議摘要。

你將建置的範例

一個會加入語音頻道、輸出以下格式逐行記錄的機器人：

- **[14:32:08] Roy:** so what's our plan for the migration
- **[14:32:14] Sara:** I'd start with the read path first
- **[14:32:21] Roy:** good idea — can we ship that this sprint?

…輸出到主控台與 ~/.discli/transcripts/meeting-<timestamp>.md，按 Ctrl+C 時會叫用 Claude 產出結構化摘要。

步驟 1 — 安裝語音相關附加元件

discord-cli-agent 的核心安裝預設為文字專用；語音堆疊會額外載入 PyNaCl、discord-ext-voice-recv、davey（Discord 的端對端語音加密函式庫）與 audioop-lts。你在需要語音時安裝對應 extras：

pip install 'discord-cli-agent[voice,deepgram]'

uv add 'discord-cli-agent[voice,deepgram]'
# 或在原始碼目錄中：
uv sync --extra voice --extra deepgram

你也需要安裝：

• libopus：apt install libopus0（Debian/Ubuntu）、brew install opus（macOS）、Windows 版由 discord.py wheel 一併提供。
• ffmpeg：若要使用 voice play（檔案/URL 播放）或 TTS 播放，需將其放入 PATH，可用 apt install ffmpeg / brew install ffmpeg / winget install ffmpeg。

各 provider 的可選 extras：

步驟 2 — 執行診斷

在你開始除錯「沒有任何輸出」前，先跑：

discli doctor

doctor 會回報語音堆疊所需元件狀態。正常的輸出應如下：

CORE
  [ok] python — Python 3.12.1
  [ok] bot token — 已設定
  [ok] discord.py — v2.7.1

VOICE
  [ok] libopus — 已載入
  [ok] PyNaCl — v1.5.0
  [ok] discord-ext-voice-recv — v0.5.2a179
  [ok] davey (DAVE crypto) — v0.1.5
  [ok] DAVE/Opus patches — 安裝正常

STT
  [ok] DEEPGRAM_API_KEY — 已設定
  [--] OPENAI_API_KEY (Whisper) — 未設定

TTS
  [--] ELEVENLABS_API_KEY — 未設定
  [--] OPENAI_API_KEY (TTS) — 未設定
  [ok] DEEPGRAM_API_KEY (Aura) — 已設定

TOOLS
  [ok] ffmpeg — /usr/bin/ffmpeg

正常 — 未發現問題（略過 3 個選用檢查）。

可使用 --json 取得機械可讀輸出（例如 CI）：

discli doctor --json

步驟 3 — 加入語音頻道

先取得一個語音頻道 ID（Discord 啟用開發者模式後，右鍵頻道複製 ID，或用 discli channel list）：

discli voice join "<channel name or id>"

voice join 是一次性指令：它會連線、回報後結束。若要保持連線，需要互動式流程（下一步）或使用 discli serve（見 Serve 模式）。

步驟 4 — 監聽並轉譯

用兩個終端機啟動一次轉譯會話。

終端機 1：讓機器人停留在語音頻道：

discli voice join "general"

終端機 2：用 Deepgram 串流 STT 開始監聽：

export DEEPGRAM_API_KEY=...
discli voice listen

你會看到類似：

[123456789012345678] hello can you hear me
[987654321098765432] yes loud and clear

每行格式為 [user_id] text。按 Ctrl+C 可停止。

步驟 5 — 使用 TTS 說話

export ELEVENLABS_API_KEY=...
discli voice speak "joining the call now"

可透過 --server 設定或環境變數指定 provider：

可用 --voice <id> 指定聲線，用 --speed 0.8 調整語速。

步驟 6 — 播放音訊

discli voice play /path/to/file.mp3
discli voice play https://example.com/stream.opus

播放透過 ffmpeg 進行，只要是 ffmpeg 可辨識的格式都可以。可用 voice stop、voice pause、voice resume 操作播放。

步驟 7 — 建置會議逐字稿

discli 內建完整範例：examples/meeting_transcriber.py。範例會加入伺服器語音頻道、以顯示名稱逐人轉譯並寫入 ~/.discli/transcripts/meeting-<timestamp>.md，Ctrl+C 時呼叫 Claude 產生結構化摘要。

安裝與啟動：

pip install 'discord-cli-agent[voice,deepgram]' claude-agent-sdk
discli config set token YOUR_BOT_TOKEN
export DEEPGRAM_API_KEY=...

執行：

python examples/meeting_transcriber.py <voice_channel_id>

會議期間輸出範例：

Connected as MyBot#1234 (12345)
Listening to #standup. Transcript: /home/me/.discli/transcripts/meeting-20260514-103000.md
Press Ctrl+C to stop and generate a summary.

- **[10:30:14] Roy:** ok let's go around — what did everyone do yesterday
- **[10:30:22] Sara:** finished the auth migration, started on the rate limiter
- **[10:30:35] Roy:** nice

按下 Ctrl+C 後：

停止監聽…
共處理 47 行文字…
摘要成本：$0.0084

=== 會議摘要 ===

## 摘要
團隊回顧昨日工作並規劃今日任務。Sara 已完成 auth 移轉，接下來進行 rate limiter。

## 關鍵決策
- 在本次移轉中先採用 read-path-first 流程。

## 行動項目
- Sara：今天完成 rate limiter。
- Roy：在週五前完成移轉 runbook 文件。

## 未解決問題
- 舊的會議會話要補回填，還是直接過期？

摘要會附加回同一份逐字稿。你也可以日後將該 markdown 再交給 Claude 重做一次摘要。

背後機制：DAVE 加密

新版 Discord 採用 DAVE（Discord Audio and Video Encryption，Discord 的端對端語音加密）。discord-ext-voice-recv 雖可處理舊式 SecretBox 層，但不認識 DAVE，導致 libopus 將每個封包視為 corrupted stream 而拒絕。

discli 在執行期修補 PacketDecoder._decode_packet，在 SecretBox 與 libopus 之間加入 davey.DaveSession.decrypt(...)，並包裝 pop_data，防止單一壞封包讓 listener 崩潰。這些修補會在首次呼叫 VoiceEngine.listen_start(...) 時懶載入，不需使用者手動啟用。

若 discli doctor 顯示 [FAIL] DAVE/Opus patches，代表架構層面的語音聆聽失效，請附帶診斷資訊建立 issue。

權限

chat 權限組別會拒絕語音相關行為；使用 chat 的代理無法加入或發聲。請使用 voice、moderation 或 full 取得語音能力：

discli --profile voice voice join general
# 或
DISCLI_PROFILE=voice discli voice listen

readonly 可用於查詢語音狀態（voice status、voice where、voice members），讓唯讀代理可回答「誰在語音中」，但無法加入。

詳細權限定義請見 權限設定檔。

疑難排解

完整清單請參考 常見問題。

後續步驟

• 閱讀 會議逐字稿使用情境，取得更完整的實作示範。
• 建置可持續執行、同時具備語音與文字功能的代理，請參考 建構代理 與 Serve 模式。
• 參考 CLI 命令 查閱所有語音指令。
• 參考 Serve 動作 與 Serve 事件 瞭解語音流程。