byted-text-to-speech

Byted-Text-to-Speech Skill

Based onVolcano Engine Doubao speech synthesis(HTTP Chunked/SSE one-way streaming-V3) converts text to speech and saves it as an audio file.

When to use

Use this skill preferentially when the user has the following needs:

• Need to convert a piece of text into speech or reading audio
• Need to generate dubbing, narration, announcements, or audiobook clips
• Need to convert code comments, documents, articles, and other content into audio for easy listening
• Need to generate multilingual speech (Chinese, English, etc.)
• The user mentions "text to speech", "TTS", "speech synthesis", "read aloud", "dubbing", "read it out", or "read it to me"
• When the user does not explicitly say "speech synthesis" but the task essentially requires converting text content into playable audio

Pre-use check

First check whether the following credentials are configured:

• MODEL_SPEECH_API_KEY

If credentials are missing, open references/setup-guide.md to view the activation, application, and configuration methods, and give the user activation suggestions

Script parameters

Parameter	Short form	Required	Description
--text	-t	Yes	The text content to synthesize
--output	-o	No	Output audio file path (automatically generated by default)
--speaker	-s	No	Speaker, default zh_female_vv_uranus_bigtts，voice list
--format		No	Audio format:mp3(default),pcm、ogg_opus
--sample-rate		No	Sampling rate, such as 16000, 24000 (default 24000)
--speech-rate		No	Speech rate [-50, 100], 100 means 2.0x speed, -50 means 0.5x speed, default 0
--pitch-rate		No	Pitch [-12, 12], default 0
--loudness-rate		No	Volume [-50, 100], 100 means 2.0x volume, -50 means 0.5x volume, default 0
--bit-rate		No	Bitrate, effective for mp3 and ogg_opus formats (such as 64000, 128000), default 64000
--filter-markdown		No	Filter markdown syntax (such as **你好** read as "hello"), disabled by default
--enable-latex		No	Enable LaTeX formula reading (uses latex_parser v2, automatically enables markdown filtering), disabled by default

Return value description

The script outputs JSON, including:

• status: "success" or "error"
• local_path: local audio file path
• format: audio format
• error: error message on failure

Please return local_path or an accessible audio URL to the user for playback or download.

Error handling

• If it reports error PermissionError: MODEL_SPEECH_API_KEY ... 需在环境变量中配置: prompt the user to obtain it in API Key Management and configure MODEL_SPEECH_API_KEY, write it to the environment variable file under the workspace, and retry.
• If it returns 4xx/5xx or a business error code: based on the error message, prompt the user to check the text content, speaker ID, and whether the account has activated the Doubao speech service.

Troubleshooting

• Missing credentials: open references/setup-guide.md
• Need to look up API parameters, fields, error codes: open references/docs-index.md
• If the script returns a permission error, first check whether the service has been activated and whether the credentials are valid, and give the user clear operational guidance

Reference materials

Open the following files as needed; there is no need to load all of them by default:

• references/setup-guide.md: service activation, credential application, environment variable configuration
• references/docs-index.md: API documentation index, parameter descriptions, voice list, error code quick reference

Example

# 基本用法
python scripts/text_to_speech.py -t "欢迎使用火山引擎语音合成服务。"

# 指定发音人与输出格式
python scripts/text_to_speech.py -t "这是一段测试语音。" -s zh_female_vv_uranus_bigtts -o output.mp3 --format mp3

# 指定语速与采样率
python scripts/text_to_speech.py -t "语速和音调可调。" --speech-rate 10 --sample-rate 16000