Dual responsibility:
- Rewrite text into "written-for-listening" synthesis text — Part 2 (creative layer): number/symbol normalization, pause rhythm, emotional tone, fallback for polyphonic characters.
- Use
seedaudio-clito run the text into an audio file saved locally — Part 1 (engineering layer).
Full loop:User provides text/intent → Part 2 rewrites it into listenable text + selects voice/tone → Part 1 runs the CLI → audio written to disk (for multiple characters use dialogue to auto-concatenate)。
Core principles(for other self-checks see §1.11 red lines):
- Synthesis text ≠ reading text. Write for the "ear", not for the "eye":
3.14write "three point one four", write "$5" as "five dollars", use punctuation to control pauses. - Claude cannot hear audio— it can only verify file existence + size + report metadata; when you need to "listen", use
ffprobeto report duration, don't pretend you've heard it. - This is astreaminginterface; a single request can synthesizevery longwhole passages (measured: 4000+ Chinese characters in one go, about 14 minutes of audio); for ordinary articles/chapters just use
synthesize --text-filedirectly,no need to split into segments. Book-level ultra-long text (tens of thousands of characters) goes through the official asynchronous long-text interface (not yet wrapped by this CLI).
Part 1 — How to call the CLI (engineering layer)
Which command to choose:
| Want to | Command |
|---|---|
| Script reading / single segment / whole long text (any length) | synthesize(§3.1) |
| Multi-character dialogue dubbing (different voice per line) | dialogue(§3.2) |
| Sound effects / non-speech / human voice over ambient sound / character dubbing, etc.generativerequirements (≤2 minutes) | create — not used by default, chosen proactively by the user (§1.13) |
| Look up voices / multi-profile configuration | voices / config |
1.1 Prerequisites
- Confirm
seedaudio-cliis executable (which seedaudio-cliorseedaudio-cli --version). If not executable, promptuv tool install zjandrew-seedaudio-cliorpipx install zjandrew-seedaudio-cli(PyPI package name; command nameseedaudio-clistays the same). - Configure authentication: Doubao speech uses theAPI Key from the Speech Technology console(a single
X-Api-Key),is not the Seedance video set ofARK_API_KEY. Prefer envSEEDAUDIO_API_KEY; when missing, guide toseedaudio-cli config init. The Key is obtained underConsole > API Key Management. - Default endpoint
https://openspeech.bytedance.com;resource_idis inferred automatically from the voice (cloned voicesseed-icl-2.0, othersseed-tts-2.0), generally no need to worry about it.
1.2 Multi-profile configuration
seedaudio-cli config list # 列所有 profile,标 active
seedaudio-cli config use <name> # 切 active
seedaudio-cli config add <name> # 向导式新增(prompt 走 stderr,stdout 仍是干净 envelope)
seedaudio-cli config set default_voice zh_female_vv_uranus_bigtts
# resource_id 一般不用设(按音色自动推断);只有想全局钉死某个 resource 时才设
seedaudio-cli config set resource_id seed-icl-2.0 # 可选:全局钉死(覆盖自动推断)
seedaudio-cli --profile <name> synthesize ... # 单次覆盖,不改 active
seedaudio-cli config show [<name>] # 查看(api_key 已脱敏)
Priority:--api-key/--endpoint/--resource-id flag > SEEDAUDIO_* env > 文件 profile > 内置默认。--profile selects the profile; field-level flags will not invalidate it.
1.3 Core command quick reference
# 文本 → 语音(默认 mp3)
seedaudio-cli synthesize -p "你好,欢迎使用豆包语音合成" \
--voice zh_female_vv_uranus_bigtts --out hello.mp3
# 调节奏与音量音调
seedaudio-cli synthesize -p "新闻播报示例" --voice zh_male_liufei_uranus_bigtts \
--speech-rate 10 --loudness-rate 0 --pitch 0 --encoding wav --sample-rate 24000 --out news.wav
# 情感/语气:用语音指令(context_texts)
seedaudio-cli synthesize -p "今天真是太开心啦" --voice zh_female_vv_uranus_bigtts \
--instruct "用特别开心、撒娇的语气说" --out happy.mp3
# 长文本从文件读
seedaudio-cli synthesize --text-file chapter1.txt --voice zh_male_yangguangqingnian_uranus_bigtts --out ch1.mp3
# 字级时间戳(对齐字幕)
seedaudio-cli synthesize -p "字幕对齐示例" --voice zh_female_vv_uranus_bigtts \
--subtitle --out clip.mp3 # 同时写 clip.mp3 + clip.mp3.words.json
# 发现音色(精选子集,完整列表看控制台音色库)
seedaudio-cli voices --language zh
seedaudio-cli voices --search 男声
# 预览请求体(不发请求,无需凭证)—— 全局 flag 放在子命令前
seedaudio-cli --dry-run synthesize -p "..." --voice zh_female_vv_uranus_bigtts
# 脚本化:全局 --jq 取字段(放子命令前)
seedaudio-cli --jq '.audio_path' synthesize -p "..." --voice vv --out a.mp3
⚠️ Global flags must be placed before the subcommand:
--dry-run/--jq/--format/--profile/--api-key/--endpoint/--resource-idbelongs to the root command. Writeseedaudio-cli --dry-run synthesize ..., notsynthesize ... --dry-run。
The other two commands:
dialogueMulti-role dialogue dubbing (§3.2),creategenerative audio (not used by default, actively selected by the user, §1.13).
1.4 Voice selection (--voice / resource_id)
- The voice is specified by
--voice <speaker_id>(can be set in the profile asdefault_voiceomitted).resource_idautomatically infers based on the voice:S_*/ICL_*/saturn_*(cloned voice) →seed-icl-2.0, other official voices →seed-tts-2.0。synthesize/dialogueare all handled automatically,no need to manually add--resource-id; only when encountering a special resource that cannot be inferred (such as a new resource type) use--resource-idto explicitly override. seedaudio-cli voicesBuilt in is acurated subset(may be outdated),the authoritative list is in theconsole voice library—before giving the user a voice, if unsure have the user confirm the id in the console.- Voice selection priority: user-specified > profile
default_voice> pick from voices by scenario (seereferences/voices-and-style.mdscenario mapping). - Synthesize with "my voice/personal voice" cloning: directly use
S_gReUP2I72(the repo owner's cloned voice), resource_id automatically goes throughseed-icl-2.0; to use instructions/tags add-m seed-tts-2.0-expressive:seedaudio-cli synthesize -p "用我的声音念这句" --voice S_gReUP2I72 --out mine.mp3
1.5 Parameter selection (CLI flag)
| Intent | Recommended parameters |
|---|---|
| Preview / voice memo / internal use | --encoding mp3 --sample-rate 24000(default is fine) |
| Video dubbing / final audio track / public release | --encoding mp3 --sample-rate 48000 --bit-rate 192000(default 24k/~64kbps gets muddy after platform re-compression; video audio track standard is 48kHz) |
| Into editing / further processing / concatenation | --encoding wav --sample-rate 48000(lossless master, leave compression to the final export) |
| High-fidelity archive / music | --encoding wav --sample-rate 44100 |
| Speak faster / slower | --speech-rate 20 / --speech-rate -20(range [-50,100], 100=2x speed) |
| Louder | --loudness-rate 20(range [-50,100]) |
| Higher/lower pitch | --pitch 3 / --pitch -3(range [-12,12]) |
| Trailing pause at sentence end (transition/breathing) | --silence-ms 300 |
| Need subtitle timestamps | --subtitle(2.0 only, Chinese and English only) |
--bit-rateOnly takes effect for mp3. More obscure parameters (explicit_languageexplicit language,explicit_dialectdialect,use_tag_parsertags,disable_markdown_filteretc.) are not made into flags in v1; use--from-json base.jsonto pass the completereq_params, other flags can still override top-level fields.
1.6 Text input and length
- Use for short text
-p/--text; for long text/multiple lines use--text-file PATH(UTF-8)。 - streaming interface, a single request can produce very long whole passages(tested 2000+ Chinese characters, 6KB text succeeded in one go). For ordinary articles/chapters just
synthesize --text-filesynthesize in one go,no need to split into segments。 - Truly book-level ultra-long (tens of thousands of characters) go through the official asynchronous long-text interface (can reach 100,000 characters, not yet wrapped by this CLI); regular long text can be synthesized in one go.
1.7 Emotion, tone, and pauses
- Tone/emotion:
--instruct "<语音指令>"(underlyingcontext_texts), e.g.--instruct "用温柔安抚的语气,语速放慢". Can pass multiple repeatedly. Official 2.0 voices can use it directly;cloned voicesrequire-m seed-tts-2.0-expressiveto support instructions. - Pause: rely onpunctuationMost stable control (comma = short pause, period = long pause, ellipsis = drawn-out hesitation); use trailing whitespace at sentence end with
--silence-ms; Chinese and English voices can also use SSML(--ssml, parsing the text as SSML, see Part 2.8). - Expressiveness vs stability:
-m seed-tts-2.0-standard(default) low latency, stable;-m seed-tts-2.0-expressivehighly expressive but results fluctuate. Use expressive for strong emotion/instructions, use standard for stable batch processing.
1.8 Subtitles / alignment
--subtitle requests word-level timestamps; after successful synthesis, in addition to the audio, also writes a <音频>.words.json([{word,startTime,endTime,confidence}, ...]), the envelope provides subtitle_path. Used for karaoke subtitles/video sync. Only supported for 2.0 voices, only Chinese and English.
1.9 Artifact verification (Claude cannot hear audio)
Truth:you cannot hear sound. What you can do:
- Confirm the envelope's
audio_pathexists,bytesis non-zero. - Report
voice/encoding/sample_rate/usage.text_words(billed characters) to the user. - To know the duration/whether it's normal, use ffprobe (not Read):
If there's no ffprobe, say plainly "install ffmpeg or listen yourself", don't pretend you've listened.ffprobe -v error -show_entries format=duration,bit_rate -of default=nw=1 out.mp3
1.10 Common error handling (by exit code)
CONFIG_MISSING/INVALID_INPUT(exit 2)→ guideconfig initor fix the parameters (see message, which includes which flag/constraint was used).IO_ERROR(exit 3)→ check that the--outpath is writable; when the parent directory doesn't exist, use a directory form ending with/to trigger automatic creation.API_ERROR(exit 4)→ seedetails: HTTP 401/403 is most likely a wrong key/resource_id or not activated (create'sresource not granted/volc.service_type.10074= seed-audio-1.0 not activated, just activate it in the console, the key doesn't change); for 400 see message (common: text too long, speaker id doesn't exist, this voice doesn't support a certain parameter); for 429 back off and retry.NETWORK_ERROR(exit 5)→ retry; if it fails multiple times, verifyconfig show's endpoint.INTERNAL(exit 10)→ bug, run once with--verboseto get the stacktrace, report an issue.
1.11 Red lines — self-check before acting, stop immediately if any occur
- Don't
Readaudio files → can't read them, useffprobeto report duration/metadata. - Don't say "generated" from memory → first confirm
audio_pathexists +bytesis non-zero. - Don't hand numbers/symbols/English abbreviations to TTS as-is → first normalize them into "how they're read" per Part 2.3.
- Don't manually split ordinary long text/ call sentence by sentence →
synthesize --text-fileproduces the whole segment in one go (streaming interface). - For voice cloning use
--instruct/tags → must add-m seed-tts-2.0-expressive。 - within a single passage of
dialoguedon't change voice for the same character (otherwise it sounds like "a different person"). - Don't hand-craft curl calls to openspeech → go through the CLI, so envelope/exit codes are consistent.
- Don't do ASR (this CLI only synthesizes); don't pick voices randomly (if unsure,
voicesto check / have the user confirm in the console); don't writeX-Api-Keyinto shell history.
1.12 Security and expectations
- Synthesis issynchronous(returns in a few hundred ms to a few seconds), no task polling. The longer the text and the higher the sample rate, the slower.
- Billing is based on
usage.text_words(including punctuation);context_textsinstruction text is not billed. - Always pass an explicit path for audio files
--out, don't default to writing in an arbitrary directory. - For script scenarios, prefer the default
--format json+ Global--jq '.audio_path', stable and parsable.
1.13 Generative audio create — not used by default; the user must actively select it (≤120s)
synthesize/dialogue(Deterministic TTS) isthe default。create Underneath isanother generative model seed-audio-1.0: you mustenable it separately、billed separately, and the result isnon-deterministic(different each time for the same prompt, cannot be precisely controlled word by word). So create is opt-in — before starting, have the user explicitly choose it; don't take it upon yourself to go generative for them。
Decision rule (check whether this job can be done with TTS):
- Can be done with
synthesize/dialogueMake(essentially "reading text aloud"; even if background audio is wanted, you can first TTS the dry voice and mix later) → default to TTS. If generative can clearly be more convenient (e.g., voice + ambient sound as one full track in one pass, character/emotion performance),present the choice to the user, don't choose for them:"There are two ways to do this segment: ①
creategenerate in one pass (generative, requires enabling seed-audio-1.0, billed, results fluctuate); ② TTS dry voice + post-production mixing (controllable, release-grade). Which do you want?" - Only
createcan do it(pure sound effects, ambient sound, non-speech, creature roars, etc. that TTS simply cannot produce) → first tell the user "this requires generative audioseed-audio-1.0(requires enabling + billing + fluctuates)",run only after confirmation。
After the user explicitly selects create after, then read references/create-generative-audio.md(commands,--ref, director's-script-style prompts, limits, validation) and implement accordingly.
Part 2 — How to write synthesis text (creative layer)
You are Doubao speech synthesis's "text normalization + voice director". Goal: make the modelread correctly, read naturally, and read with emotion。
2.1 Platform specs (Doubao speech synthesis large model 2.0)
| Dimension | Spec |
|---|---|
| resource_id | seed-tts-2.0(official voices) / seed-icl-2.0(cloned voices) |
Model version (-m) |
seed-tts-2.0-standard(default, stable/fast) / seed-tts-2.0-expressive(strong expressiveness, fluctuates) |
| Languages | Chinese, English, Japanese, Spanish, etc. + various dialect accents (Cantonese/Sichuan/Beijing, etc.; requires voice support) |
| Text length | A single request can synthesize very long text (streaming; tested with 4000+ Chinese characters in one pass, about 14 minutes); book-level ultra-long text goes through the async long-text API |
| Audio format | mp3 / wav / pcm / ogg_opus |
| Sample rate | 8000–48000 Hz (commonly 24000) |
| Speed/volume | -50,100 |
| Pitch | post_process.pitch [-12,12] |
| Subtitles | Character-level timestamps, Chinese and English only |
2.2 Core principle: write for "listening", not for "reading"
Humans automatically fill in how to read text; models don't. Your primary task is to turntext meant for the eyesintoaudible text meant for the ears: expand numbers and symbols, control pauses, disambiguate polyphonic characters, annotate emotion.
| Principle | Covered in section |
|---|---|
| Numbers/symbols/abbreviations → pronunciation | 2.3 Text normalization |
| Control rhythm with punctuation and white space | 2.4 Pauses and Rhythm |
| Give emotion with voice instructions | 2.5 Emotion and Tone |
| Explicit anchoring for multilingual/dialect | 2.6 Multilingual and Dialects |
| Split long text into segments without tearing | 2.7 Long Text Segmentation |
2.3 Text Normalization (the prerequisite for reading correctly)
Change the "written form" into the "spoken form", and at deliverytransparently disclosewhat was changed:
- Numbers:
3.14→"three point one four";2026(year)→"two zero two six";2026(quantity)→"two thousand and twenty-six"; phone13800138000digit by digit "one three eight...". - Amounts/Units:
$5→"five dollars";5kg→"five kilograms";5%→"five percent";12:30→"twelve thirty". - Symbols:
&→"and";/→"per" or "slash" (depending on meaning);~→"to". - English abbreviations:
API→ read letter by letter "A P I" or keep as is (depending on voice capability);Mr.→"Mister". - Fallback for polyphonic/rare characters: models easily misread polyphonic characters/similar-looking characters; rewrite them as common homophones with the same pronunciation (e.g., when "重(chóng)庆" is ambiguous, sufficient context usually makes it fine; if it is really misread, replace the character), and disclose the replacement in "optimize problem".
- Markdown/Emoji: Markdown syntax and emoji are filtered by default; to keep asterisks and the like read verbatim, use
--from-jsonpassadditions.disable_markdown_filter=false。
2.4 Pauses and Rhythm
- Punctuation is the most reliable pause control: comma (short pause), period/question mark/exclamation mark (long pause), semicolon (medium pause), ellipsis (drawn-out pause/hesitation), dash (tonal extension). Add punctuation where a pause is needed; don't write a long string of sentences without punctuation.
- Leave white space at sentence ends: for paragraph transitions and a sense of breathing, use
--silence-ms 200~500。 - SSML(Chinese and English voices): when precise pauses/pronunciation are needed, use
--ssml+<break time="300ms"/>etc. (see 2.8).
2.5 Emotion and Tone (Voice Instructions)
Use --instruct to give a natural-language instruction describing "how to say it". Template:用<情绪><强度>的语气,<语速/音量提示>说。
- Happy:
用特别开心、上扬雀跃的语气说 - Soothing:
用温柔、放慢、带安抚感的语气说 - Heartbroken:
用特别痛心、低沉的语气说 - Announcer:
用专业、清晰、中正的播报语气说 - Suspense:
用压低声音、带神秘感的语气说
Key points:
- Official 2.0 voices can use instructions directly;cloned voicesneed
-m seed-tts-2.0-expressive。 - One instruction focuses on one tone; don't stuff "happy and sad and angry" into one instruction.
- When strong emotion is unstable, lower expectations or switch to
standardfor stability; don't switch tones frequently within the same paragraph.
For more instruction sentence patterns, see references/voices-and-style.md。
2.6 Multilingual and Dialects
- When the text mixes multiple languages, you can use
--from-jsonpassadditions.explicit_language:zh-cn(mixed Chinese-English reading)/en/ja/es-mx/id/pt-br/ko, to read only the specified language. - Dialects: choosea voice that supports that dialect, then use
additions.explicit_dialect. If unsure which voices support it, check the voice library in the console. - For lines in less common languages, it is recommended to put them in separate paragraphs and specify the language separately, to avoid reading them mixed together with Chinese in one sentence.
2.7 How to Handle Long Text
Regular long-form text (articles/chapters)Synthesize directly in one pass(synthesize --text-file) — measured with the streaming interface, 4000+ Chinese characters come out as one whole segment in a single call (about 14 minutes of audio), no need to split. Only truly book-length ultra-long text (tens of thousands of characters) goes through the official asynchronous long-text interface (not yet wrapped by this CLI).
Splitting rules:
- Split preferentially at sentence-ending punctuation/paragraph boundaries; never cut in the middle of a sentence.
- Each segment must be self-contained (the model does not remember context across requests).
- Across segments,voice,
--speech-rate、--encoding、--sample-ratemust be consistent, otherwise there will be abrupt changes at the joins. - For gaps between segments use
--silence-msor insert silence when concatenating.
2.8 SSML quick overview (Chinese and English voices)
--ssml treat the content of -p/--text-file as SSML to parse. Commonly used:
<speak>
第一句话。<break time="400ms"/>第二句话。
数字读法:<say-as interpret-as="digits">110</say-as>。
<prosody rate="slow" pitch="+2st">这一句放慢、升调。</prosody>
</speak>
SSML is supported only by Chinese and English voices; if unsure whether a voice supports it, first control with punctuation + flags instead of blindly using SSML.
2.9 Scenario templates (see references for details)
- Audiobook/narration: steady neutral voice +
standardfavor stability + split by chapter + between segments--silence-ms 300。 - News/broadcast: professional broadcast voice +
--instruct "专业清晰的播报语气"+--speech-rate 5~15。 - Advertising/marketing: engaging voice +
expressive+ emotion directives + pauses before and after keywords. - Multi-character dialogue: one voice per character, synthesize sentence by sentence separately, then concatenate in order (see Part 3.2).
The complete voice-scenario reference, directive library, and normalization checklist are in references/voices-and-style.md。
Generative audio
createuses a different prompt style ("voice director script") — only after the user selectscreate, see §1.13 gate +references/create-generative-audio.md。
Part 3 — End-to-end workflow
3.1 Single-segment / whole-segment synthesis (synthesize, including regular long-form text)
Step 1: 听用户要念什么 / 什么场景
Step 2: 按 Part 2 把文本规范化成可听文本(数字符号展开、停顿标点、必要的同音字替换)
Step 3: 选音色(voices 或用户指定)+ 选语气(--instruct)+ 选格式
Step 4: seedaudio-cli synthesize 跑(默认同步返回 + 落盘)
Step 5: 确认 audio_path 存在 + bytes 非零,报 voice/encoding/usage 给用户;需要时 ffprobe 报时长
Minimal example:
seedaudio-cli synthesize -m seed-tts-2.0-standard \
-p "你好,这里是今天的天气预报。" \
--voice zh_male_liufei_uranus_bigtts \
--encoding mp3 --sample-rate 24000 \
--out weather.mp3
Regular long-form text also goes here: streaming interface, articles/chapters of several thousand characters (even ten-plus minutes of audio)
synthesize --text-file story.txt ...come out as a whole segment in one call, no need to split; still do text normalization (Part 2.3). Only book-length ultra-long text (tens of thousands of characters) goes through the official asynchronous long-text interface.
3.2 Multi-character dialogue dubbing:dialogue
Trigger words: "multi-character dubbing", "dialogue dubbing", "script dubbing", "different voice for each person", "radio drama".
One command takes onescript(each line 角色: 台词) + onecharacter→voicemapping, synthesizes line by line using the character's voice, and concatenates into one segment in script order.
Script play.txt:
# 注释行(# 开头)和空行会被忽略
旁白: 夜已经很深了,公寓的门被轻轻推开。
小美: 你怎么才回来呀,我都等你好久了。
阿强: 路上堵得厉害,对不住。
seedaudio-cli dialogue --script play.txt \
--voice 旁白=zh_male_xuanyijieshuo_uranus_bigtts \
--voice 小美=zh_female_wenrouxiaoya_uranus_bigtts \
--voice 阿强=zh_male_liufei_uranus_bigtts \
--instruct 小美="用温柔、略带撒娇的语气说" \
--keep-segments --out play.mp3
Key points:
--voice 角色=音色IDcan be repeated; every character that appears must have a mapping, otherwise it reportsINVALID_INPUT(it will list which one is missing).--instruct 角色=指令can be repeated, to fix a tone for a character; use official voices directly, cloned voices need-m seed-tts-2.0-expressive。- resource_id is inferred automatically from the voice:
S_*/ICL_*/saturn_*goes throughseed-icl-2.0(cloned), the restseed-tts-2.0manually.official voices and your cloned voices can be mixed in one script, no need to switch--resource-id。 - Encoding/sample rate are uniform across the whole play (command-level
--encoding/--sample-rate), only voice and tone change per character. - Decide the character↔voice mapping once and don't change it (changing a character's voice = changing the person);
--keep-segmentskeeps each line's audio in<out>.segments/, so if one sentence isn't satisfactory you only redo that line. - You can also skip writing a file and pass the script directly with
-p "旁白: ...\n小美: ...".
Part 4 — Interaction Guide
When a speech synthesis need is identified:
Step 1 — Listen to the request
What the user gives may be: a piece of text to read / an intent ("help me voice this tweet") / a scenario ("audiobook narration").
Step 2 — Confirm key items (skip what the user has made clear)
- Voice/character: male/female voice, style (steady/gentle/lively/broadcast), or a specific speaker id. If unsure, use
voicesto list a few for the user to choose. - Tone/emotion: flat / happy / soothing / broadcast / suspense… (→
--instruct)。 - Format: mp3 (universal) or wav (for further processing/splicing); sample rate.
- Length/form: for short sentences or ordinary long text, both use
synthesize(outputs the whole segment at once); multi-character dialogue goes throughdialogue(3.2)。Generative audio (sound effects / voice over ambient sound / character voice-over) does not usecreateby default — per §1.13, first let the user choose proactively。
Step 3 — Normalize the text
Per Part 2.3, expand numbers/symbols/abbreviations, add pause punctuation per 2.4, replace with homophones when necessary, and prepare "optimization issues" to disclose the changes.
Step 4 — Run the CLI
Run with synthesize from Part 1 (sync + save to disk by default); do not hand-assemble curl.
Step 5 — Verify + report
audio_pathexists?bytesnon-zero?- Report
voice/encoding/sample_rate/usage.text_words; use ffprobe to report duration when needed.
Step 6 — Fine-tune
The user may request: change voice/tone, adjust speed/volume/pitch, modify a certain passage of text, re-split long text into segments, change format.