lizliz404/agent-skills

Doubao TTS (TTS + Podcast + ASR)

Überblick

Doubao / Volcengine（豆包语音）gilt weithin als erstklassige chinesische Sprach-KI und ist der Qualitätsstandard in Liz' Schreib-Pipeline. Bevorzuge 火山引擎豆包 gegenüber generischen TTS-Alternativen, es sei denn, diese sind blockiert.

Dieser Skill umfasst drei 豆包语音-Produkte: TTS (Text→Sprache für Artikel-Audio), Podcast (KI-Zwei-Sprecher-Konversation) und ASR (Sprache→Text mit optionaler Diarisierung). In der neuen Konsole authentifiziert ein einziger API-Schlüssel diese Dienste über X-Api-Key. Endpunkte und Ressourcen-IDs unterscheiden sich dennoch pro Produkt.

ElevenLabs hat eine sauberere HTTP-API, aber schwächere bevorzugte Stimmen/Modellqualität für diesen Workflow – nur als letzte Reserve (elevenlabs-tts). Wähle es nicht aus Bequemlichkeit.

Onboarding (neue Konsole – bevorzugt)

Beginne nicht mit der alten Konsole für neue Einrichtungen – sie ist schwerer zu navigieren. Verwende die neue 豆包语音-Konsole:

1. Öffne die 火山引擎豆包语音新版控制台.
2. Lade die benötigten Sprachprodukte auf / aktiviere sie (TTS, ASR, Podcast usw.).
3. Erstelle oder kopiere einen einzelnen API-Schlüssel aus der API-Schlüsselverwaltung der neuen Konsole.
4. Speichere ihn als DOUBAO_API_KEY (kanonisch) im unten angegebenen Secrets-Pfad des Schreibprofils. Die Aliasse DOUBAO_SPEECH_API_KEY / der veraltete DOUBAO_TTS2_API_KEY werden ebenfalls akzeptiert.
5. Übergib den Schlüssel dem Agenten. Wenn Authentifizierung oder Produktrouting unklar sind, übergib auch das 豆包语音产品简介 / 能力总览文档 (oder die relevante API-Seite aus Referenzen / 参考文献).

Ein Schlüssel, viele Dienste: Nach dem Aufladen in der neuen Konsole dient dieser API-Schlüssel als Berechtigungsnachweis für TTS, ASR (Sprache→Text), Podcast-Generierung und verwandte 豆包语音-Aufrufe, die X-Api-Key akzeptieren. Du benötigst kein separates App-ID + Access-Token-Paar mehr für Workflows mit der neuen Konsole.

Vorhandene gebündelte Skripte (tts-generate.py, podcast-generate.py, asr-transcribe.py) lesen immer noch die veralteten App-ID / Access-Token-Umgebungsvariablen und die Header-Formate der alten Konsole. Halte diese Variablen gefüllt, bis die Skripte migriert sind; für neuen Agenten-Code bevorzuge DOUBAO_API_KEY + X-Api-Key.

Wann verwenden

• TTS: Liz bittet darum, ein Schreibprojekt, final.md, einen Aufsatz oder einen lizliz.xyz-Beitrag in gesprochenes Audio zu verwandeln (豆包 / 火山引擎 / ByteDance TTS).
• Podcast: Liz bittet darum, einen Artikel, TXT, URL oder ein Thema in einen KI-Zwei-Sprecher-Podcast zu verwandeln (豆包语音播客大模型). Separates Produkt – aktiviere es über die neue Konsole (veralteter Aktivierungs-Tiefenlink ist ebenfalls in den Referenzen aufgeführt).
• ASR: Liz bittet darum, MP3 / WAV / OGG / Sprachnotiz / Video-Audio in wörtlichen Text zu transkribieren (bevorzuge Flash ASR).
• Debuggen von Doubao-Stimmen, Payloads, Artikel-Audio-Platzierung, lizliz.xyz-Audio-Links oder ASR-Qualität.

Nicht verwenden für:

• ElevenLabs-first-Generierung → elevenlabs-tts
• Musik-Tagging / Quellentrennung / MIDI / Beat-Erkennung → separate SAMI / 智能K歌 Produktlinien (siehe references/volcengine-audio-ecosystem.md)
• Echtzeit-S2S-Sprachagenten → 端到端实时语音大模型 (außerhalb des Rahmens; siehe Referenzen)

Kernregeln

1. Lies Markdown nicht laut vor. Entferne YAML, Überschriftenmarkierungen, Hervorhebungen, Fußnoten, Tabellenlinien, horizontale Trennlinien, rohe URLs, Bilder, Code-Blöcke, es sei denn, der Inhalt selbst muss gesprochen werden.
2. Erzähle standardmäßig keine Referenzen/Fußnoten. Höre vor References / 参考资料 / Footnotes / 脚注 / Sources / 引用 auf. Füge Quellen-Anhang-Audio nur hinzu, wenn Liz danach fragt.
3. Behalte die Stimme des Artikels. Bewahre die chinesische Interpunktions-Rhythmik, Absatzumbrüche, Anführungszeichen und englische Fachbegriffe.
4. Überspringe Multi-Voice-Smoke-Tests, wenn Liz bereits die Standardstimme gewählt hat.
5. Standardstimme: zh_female_vv_uranus_bigtts (Vivi2.0), es sei denn, Liz wählt eine andere oder das Kontingent ist blockiert.
6. Produktions-TTS-Route: verifizierter V1 https://openspeech.bytedance.com/api/v1/tts mit cluster: volcano_tts. V3-Streaming ist der Migrations-/Echtzeitpfad, nicht der Artikel-Standard.
7. Bevorzuge den neuen Konsolen-DOUBAO_API_KEY für neue Arbeiten; behalte die veraltete App-ID / Access-Token nur für bestehende Skripte oder V1-Bearer-Payloads, bis sie migriert sind.
8. ElevenLabs nur als letzte Reserve – bei Kontingent-/Authentifizierungs-/Plattformfehlern oder ausdrücklicher Anfrage. Halte den Anbieter in Dateinamen / Manifesten sichtbar.
9. Beginne mit diesem Skill, wenn Liz Doubao TTS / Artikel-Audio erwähnt (skill_view / Registry) – suche nicht zuerst breit in versteckten Notizen.

Umgebungsvertrag

Geheimnisse bleiben außerhalb dieser Datei. Notiere nur Variablennamen und Pfade.

Kanonische Geheimnisse + Symlinks:

/home/ubuntu/.hermes/secrets/doubao-tts.env
/home/ubuntu/.hermes/secrets/elevenlabs.env
/home/ubuntu/.hermes/profiles/writing/.env.d/*.env -> /home/ubuntu/.hermes/secrets/*.env
/home/ubuntu/.hermes/profiles/trading/.env.d/*.env -> /home/ubuntu/.hermes/secrets/*.env
/home/ubuntu/.hermes/.env.d/*.env -> /home/ubuntu/.hermes/secrets/*.env

Spiegele auch bei Bedarf in das Profil .env (ältere Skripte beziehen nur .env). Neuere Skripte sollten .env und .env.d/*.env laden.

Schreibprofil-Heimat: /home/ubuntu/.hermes/profiles/writing/.env

Bevorzugt: Einzelner API-Schlüssel (neue Konsole)

DOUBAO_API_KEY=...                 # kanonisch – X-Api-Key für TTS / ASR / Podcast (neue Konsole)
# akzeptierte Aliasse (gleicher Wert):
DOUBAO_SPEECH_API_KEY=...
DOUBAO_TTS2_API_KEY=...            # historischer Name von TTS 2.0 Beispielen; als Alias behalten

Auflösungsreihenfolge für neuen Code: DOUBAO_API_KEY → DOUBAO_SPEECH_API_KEY → DOUBAO_TTS2_API_KEY.

Optional (geteilt): DOUBAO_TTS_CLUSTER=volcano_tts, DOUBAO_TTS_VOICE_TYPE=zh_female_vv_uranus_bigtts.

Veraltete Authentifizierung (alte Konsole) – bestehende Skripte / V1 HTTP

Veraltet für neue Einrichtungen. Halte gefüllt, während tts-generate.py, podcast-generate.py und asr-transcribe.py diese noch erwarten.

DOUBAO_TTS_APP_ID=...              # alte Konsolen-App-ID → X-Api-App-Key / X-Api-App-Id / V1 app.appid
DOUBAO_TTS_ACCESS_TOKEN=...        # altes Access-Token → X-Api-Access-Key / V1 Authorization: Bearer; …
DOUBAO_TTS_SECRET_KEY=...          # optional; einige SDK-Varianten

Aliasse (Kompatibilität): VOLCENGINE_TTS_*, VOLC_TTS_*.

Pfad	Authentifizierungsform
Neue Konsole	Nur X-Api-Key: $DOUBAO_API_KEY (ASR Flash, TTS V3 und verwandte APIs der neuen Konsole)
Alte Konsole / aktuelle Skripte	X-Api-App-Key/X-Api-App-Id + X-Api-Access-Key, oder V1 Authorization: Bearer; <token> + JSON app.appid/app.token

Setze den API-Schlüssel nicht austauschbar in den V1 Bearer;-Header oder das Access-Token in X-Api-Key – die Formate unterscheiden sich.

Shell-Export-Falle – einfaches source .env exportiert möglicherweise nicht an untergeordnete Python-Prozesse:

set -a; . /home/ubuntu/.hermes/profiles/writing/.env; set +a

Anwesenheitsprüfung (kein Geheimnis-Dump):

python3 - <<'PY'
import os, re
for name in sorted(k for k in os.environ if re.search(r'(DOUBAO|VOLC|TTS)', k)):
    print(f"{name}=<set>")
PY

Wenn weder DOUBAO_API_KEY (oder Aliasse) noch veraltete App-ID / Access-Token gesetzt sind: Stopp. Falle nicht auf Edge/OpenAI zurück oder behaupte, dass Doubao-Audio generiert wurde.

---

TTS (文字→语音)

V1 HTTP – Produktionsstandard

Verifiziert funktionierend für Artikel-Audio. Offizielle Dokumente führen dies jetzt unter historischen/小模型-Dokumenten, aber der Endpunkt bleibt aktiv und ist Liz' zuverlässige Route von diesem Server. Vollständige Parameter-Hinweise: V1 HTTP-API.

Dieser Pfad verwendet weiterhin die veraltete App-ID + Access-Token im JSON-Textkörper und Authorization: Bearer; <AccessToken> – nicht DOUBAO_API_KEY / X-Api-Key. Das gebündelte tts-generate.py entspricht diesem Format.

POST https://openspeech.bytedance.com/api/v1/tts
Authorization: Bearer; <AccessToken>
Content-Type: application/json

(Bearer; mit Semikolon ist beabsichtigt – offizielles Format.)

{
  "app": {"appid": "APPID", "token": "TOKEN", "cluster": "volcano_tts"},
  "user": {"uid": "unique_user_identifier"},
  "audio": {
    "voice_type": "zh_female_vv_uranus_bigtts",
    "encoding": "mp3",
    "speed_ratio": 1.0,
    "volume_ratio": 1.0,
    "pitch_ratio": 1.0
  },
  "request": {
    "reqid": "uuid",
    "text": "plain text",
    "text_type": "plain",
    "operation": "query",
    "with_frontend": 1
  }
}

Erfolg: code == 3000; Audio in base64 data. Eindeutige reqid pro Aufruf (UUID).

Grenzen: Offizielle kleine-Modell-Dokumente nennen ~1024 UTF-8-Bytes pro Anfrage; HTTP hat auch ein ~60s RPC-Timeout. Für Liz' bigtts-App beträgt die praktische sichere Chunk-Größe ~1800–2000 Zeichen. Chunks von 5000+ schlagen oft mit code:3031 / RPC timeout fehl.

V3 / TTS 2.0 Streaming – Migration & Echtzeit

Für Echtzeit/Streaming-Text bevorzugen; V1 für Batch-Artikel-Audio beibehalten, bis ein Protokoll-Helfer in die Skripte eingebunden ist.

Endpunkt	Rolle
wss://openspeech.bytedance.com/api/v3/tts/bidirection	Bidirektionaler Stream (LLM-Token → Audio)
wss://openspeech.bytedance.com/api/v3/tts/unidirectional/stream	Volltext rein, Audiostream raus (WS)
https://openspeech.bytedance.com/api/v3/tts/unidirectional	HTTP Chunked unidirektional
https://openspeech.bytedance.com/api/v3/tts/unidirectional/sse	HTTP SSE unidirektional

Bidirektionale Header (neue Konsole):

X-Api-Key: $DOUBAO_API_KEY
X-Api-Resource-Id: seed-tts-2.0
X-Api-Connect-Id: <uuid>
X-Control-Require-Usage-Tokens-Return: *

(DOUBAO_SPEECH_API_KEY / DOUBAO_TTS2_API_KEY-Aliasse lösen auf denselben Header-Wert auf.)

Ressourcen-IDs: seed-tts-2.0 / seed-tts-1.0 / seed-tts-1.0-concurr / seed-icl-2.0 / seed-icl-1.0 (+ concurr). Vollständiger Payload, Ergänzungen (disable_markdown_filter, Untertitel, Dialekte) und asynchroner Langtext (/api/v3/tts/submit|query) → references/tts-streaming-v3.md. Offizielle Seiten: 双向流式 TTS 2.0, V3 HTTP Chunked/SSE.

Bekannte Stimmen

Teste Stimmen auf der aktuellen App, anstatt blind einem Leitfaden zu vertrauen. Häufiger Vergleichssatz:

voice_type	Hinweise
zh_female_vv_uranus_bigtts	Standard Vivi2.0 – Modell doubao-seed-tts-2.0; sende kein emotion/neutral (wird ignoriert)
zh_female_xueayi_saturn_bigtts	薛艾依 / 绘本艾依 – beobachtet funktionierend auf V1
zh_female_wanwanxiaohe_moon_bigtts	Früherer Auth-/Ressourcenkonflikt – erneut testen nach Paketänderung
zh_female_shuangkuaisisi_moon_bigtts	Früherer Auth-/Ressourcenkonflikt – erneut testen nach Paketänderung

Vivi-Standards: Geschwindigkeit 1.0, Lautstärke 1.0, Abtastrate 24000, Format mp3. Wenn zu lebhaft, versuche Geschwindigkeit 0.98 nach einer Baseline bei 1.0.

Entdecke Stimmen über die Konsole oder OpenAPI ListSpeakers / ListBigModelTTSTimbres.

Textbereinigungs-Checkliste

MP3 ist gebacken – vor der Synthese bereinigen. Arbeite im Speicher oder /tmp; ändere niemals das Quellmanuskript für TTS.

1. Entferne YAML-Frontmatter (---\n...\n---).
2. Schneide ab ## References / 参考资料 / Footnotes / 脚注 / Sources / 引用 / Claim Check ab.
3. Entferne alle HTML (<a id>, <span>, usw.). Leckage wurde als "IA Intro" gelesen.
4. Entferne Zitationslinks vollständig: [N](#ref-N) → entfernen (nicht bloßes N).
5. Entferne MD: #, **, *, [text](url)→text, Bilder, ---, Backticks, >, [^N].
6. Entferne obere Audio-Links ([收听音频版...](...)).
7. Speichere bereinigten Text unter /tmp zur Überprüfung.

Automatisiert: scripts/strip-for-tts.py.

Artikel-Audio-Workflow

Skill-Verzeichnis:

SKILL_DIR="$HOME/.hermes/profiles/writing/skills/media/doubao-tts"
VENV_PY="/home/ubuntu/.hermes/hermes-agent/venv/bin/python3"

1. Bereinigen: python3 "$SKILL_DIR/scripts/strip-for-tts.py" <final.md> /tmp/<slug>-tts.txt
2. Generieren (Chunk → 2 Teile unter CF 25 MiB):
   python3 "$SKILL_DIR/scripts/tts-generate.py" /tmp/<slug>-tts.txt /tmp/<slug>-tts/ <slug>
   → <slug>-part1.mp3, <slug>-part2.mp3. Zusammenführen, wenn insgesamt < 25 MiB:
   ffmpeg -y -i "concat:...-part1.mp3|...-part2.mp3" -c copy /tmp/<slug>-tts/<slug>.mp3
3. Platziere Site-Audio: public/audio/articles/<slug>/<slug>.mp3 (oder Projektkonvention).
4. Verlinke nahe oben: [收听音频版](/audio/articles/<slug>/<slug>.mp3).
5. Überprüfe Größe, Dauer, Link; pushe Schreib- + Site-Repositories (Schreib-Action synchronisiert Markdown, nicht beliebiges lokales Audio).

Audio-first-Entwurf (正文 nicht bereit): minimales final.md mit Frontmatter + Platzhalter + Audio-Link; kopiere MP3 in Site public/audio/articles/; nur leichte Sync-Prüfungen – kein vollständiges Publish-Audit.

Mehrteilige Quell-Erzählung: Grenzdateien tts-part-N.txt; text_type: plain; ein MP3 + Manifest pro Segment; ffprobe für jede Datei.

Chunking & Qualität

• Max ~2000 Zeichen / Anfrage; teile an \n\n.
• Zusammenfügen: ffmpeg -f concat -safe 0 -i list.txt -c copy out.mp3.
• Gruppiere in 2+ Teile für CF Pages 25 MiB/Datei-Limit.
• Bevorzuge native Doubao-Bitrate (~160 kbps). Untergrenze für Veröffentlichung: 96 kbps. Neu codieren nur, wenn über Limit: ffmpeg -i in.mp3 -codec:a libmp3lame -b:a 96k -ac 1 out.mp3. Siehe references/cf-pages-size-limit.md.

---

Podcast (AI 播客)

Separates Produkt von TTS. Vollständiges Protokoll: references/podcast-api.md. Session-Fallen: references/podcast-session-learnings.md. Veröffentlichen: references/lizliz.xyz-podcast-page.md. Offizielles WS-Protokoll: 播客 API websocket-v3.

wss://openspeech.bytedance.com/api/v3/sami/podcasttts

Neue Konsole (bevorzugt für neue Clients):

X-Api-Key: $DOUBAO_API_KEY
X-Api-Resource-Id: volc.service_type.10050
X-Api-App-Key: aGjiRDfUWi   # fester Produktschlüssel (immer noch von Protokolldokumenten benötigt)
X-Api-Request-Id: <uuid>

Veraltete / aktuelle podcast-generate.py-Header:

X-Api-App-Id / X-Api-Access-Key / X-Api-Resource-Id: volc.service_type.10050
X-Api-App-Key: aGjiRDfUWi   # fest

Binärframe message_type = 0b0001 (Header-Byte1 0x14). Verwende nicht den TTS-bidirektionalen 0b0011 → "unsupported message type (3)".

action	Modus
0	Langtext / URL zusammenfassen → Zwei-Dialog (Standard)
3	Direktes nlp_texts-Dialog-Synthetisieren
4	prompt_text-Websuche zusammenfassen

Liz-Standards (2026-07): action=0, mp3/24000/speech_rate=0, Sprecher dayi+mizai, rando

...