SuperAPI AI Directory

seedaudio

General & other

View repository

Updated 11-12 21:05

About this skill

seedaudio

Dual responsibility:

  1. Rewrite text into "written-for-listening" synthesis text — Part 2 (creative layer): number/symbol normalization, pause rhythm, emotional tone, fallback for polyphonic characters.
  2. Use seedaudio-cli to 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.14 write "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 ffprobe to 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-file directly,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

  1. Confirm seedaudio-cli is executable (which seedaudio-cli or seedaudio-cli --version). If not executable, prompt uv tool install zjandrew-seedaudio-cli or pipx install zjandrew-seedaudio-cli(PyPI package name; command name seedaudio-cli stays the same).
  2. Configure authentication: Doubao speech uses theAPI Key from the Speech Technology console(a single X-Api-Key),is not the Seedance video set of ARK_API_KEY. Prefer env SEEDAUDIO_API_KEY; when missing, guide to seedaudio-cli config init. The Key is obtained underConsole > API Key Management.
  3. Default endpoint https://openspeech.bytedance.com;resource_id is inferred automatically from the voice (cloned voices seed-icl-2.0, others seed-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-id belongs to the root command. Write seedaudio-cli --dry-run synthesize ..., not synthesize ... --dry-run。

The other two commands:dialogue Multi-role dialogue dubbing (§3.2),create generative 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 as default_voice omitted).resource_id automatically infers based on the voice:S_*/ICL_*/saturn_*(cloned voice) → seed-icl-2.0, other official voices → seed-tts-2.0。synthesize/dialogue are 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-id to explicitly override.
  • seedaudio-cli voices Built 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 (see references/voices-and-style.md scenario mapping).
  • Synthesize with "my voice/personal voice" cloning: directly use S_gReUP2I72(the repo owner's cloned voice), resource_id automatically goes through seed-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-rate Only takes effect for mp3. More obscure parameters (explicit_language explicit language,explicit_dialect dialect,use_tag_parser tags,disable_markdown_filter etc.) are not made into flags in v1; use --from-json base.json to pass the complete req_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-file synthesize 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 "<语音指令>"(underlying context_texts), e.g. --instruct "用温柔安抚的语气,语速放慢". Can pass multiple repeatedly. Official 2.0 voices can use it directly;cloned voicesrequire -m seed-tts-2.0-expressive to 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-expressive highly 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:

  1. Confirm the envelope's audio_path exists,bytes is non-zero.
  2. Report voice / encoding / sample_rate / usage.text_words(billed characters) to the user.
  3. To know the duration/whether it's normal, use ffprobe (not Read):
    ffprobe -v error -show_entries format=duration,bit_rate -of default=nw=1 out.mp3
    
    If there's no ffprobe, say plainly "install ffmpeg or listen yourself", don't pretend you've listened.

1.10 Common error handling (by exit code)

  • CONFIG_MISSING / INVALID_INPUT(exit 2)→ guide config init or fix the parameters (see message, which includes which flag/constraint was used).
  • IO_ERROR(exit 3)→ check that the --out path is writable; when the parent directory doesn't exist, use a directory form ending with / to trigger automatic creation.
  • API_ERROR(exit 4)→ see details: HTTP 401/403 is most likely a wrong key/resource_id or not activated (create 's resource 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, verify config show 's endpoint.
  • INTERNAL(exit 10)→ bug, run once with --verbose to get the stacktrace, report an issue.

1.11 Red lines — self-check before acting, stop immediately if any occur

  • Don't Read audio files → can't read them, use ffprobe to report duration/metadata.
  • Don't say "generated" from memory → first confirm audio_path exists + bytes is 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-file produces 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 dialogue don'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, voices to check / have the user confirm in the console); don't write X-Api-Key into 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_texts instruction 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/dialogue Make(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: ① create generate 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 create can do it(pure sound effects, ambient sound, non-speech, creature roars, etc. that TTS simply cannot produce) → first tell the user "this requires generative audio seed-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"; phone 13800138000 digit 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-json pass additions.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 standard for 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-json pass additions.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:

  1. Split preferentially at sentence-ending punctuation/paragraph boundaries; never cut in the middle of a sentence.
  2. Each segment must be self-contained (the model does not remember context across requests).
  3. Across segments,voice,--speech-rate、--encoding、--sample-rate must be consistent, otherwise there will be abrupt changes at the joins.
  4. For gaps between segments use --silence-ms or 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 + standard favor 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 create uses a different prompt style ("voice director script") — only after the user selects create , 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 角色=音色ID can be repeated; every character that appears must have a mapping, otherwise it reports INVALID_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 through seed-icl-2.0(cloned), the rest seed-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-segments keeps 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)

  1. Voice/character: male/female voice, style (steady/gentle/lively/broadcast), or a specific speaker id. If unsure, use voices to list a few for the user to choose.
  2. Tone/emotion: flat / happy / soothing / broadcast / suspense… (→ --instruct)。
  3. Format: mp3 (universal) or wav (for further processing/splicing); sample rate.
  4. Length/form: for short sentences or ordinary long text, both use synthesize(outputs the whole segment at once); multi-character dialogue goes through dialogue(3.2)。Generative audio (sound effects / voice over ambient sound / character voice-over) does not use createby 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_path exists?bytes non-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.