Generate Chinese and English narration with the local script

This standalone project tool prepares narration for videos and demos. It is not an in-app Sharp Stock feature. Install Python 3.10 or later; no additional Python packages are required. Use PowerShell on Windows or Terminal on Mac.

Configure the API key

1. Open the new Doubao Voice console.
2. Enable Doubao Speech Synthesis 2.0 in the intended project and check quota and voice access.
3. Open API Key management and create or copy a Voice API key with access to that project. The script uses X-Api-Key; AppID and Access Token are not required.
4. Set the environment variable in the terminal running the script. Replace the placeholder with your key. Keep it out of the script and Git.

Windows PowerShell, current window:

$env:DOUBAO_TTS_API_KEY = 'your-voice-api-key'

To persist this value in your Windows user environment, after setting it above:

[Environment]::SetEnvironmentVariable('DOUBAO_TTS_API_KEY', $env:DOUBAO_TTS_API_KEY, 'User')

New terminals inherit the saved value. Restart the terminal host application if it was already running.

Mac Terminal, current window:

export DOUBAO_TTS_API_KEY='your-voice-api-key'

The script reads environment variables only; it does not load project .env files.

Generate narration

Run from the project root. On Mac, replace python with python3 if necessary.

python scripts/doubao-tts.py --lang zh --text "欢迎使用 Sharp Stock。" --output output/voice_zh.wav
python scripts/doubao-tts.py --lang en --text "Welcome to Sharp Stock." --output output/voice_en.wav

--lang zh selects Yangguang Qingnian 2.0; --lang en selects Ryan (American English). The parameter selects the voice; language is not inferred from the text. Mixed text uses the selected voice. Both use seed-tts-2.0 through the V3 HTTP unidirectional streaming endpoint.

For multiline text or text containing quotes, use a UTF-8 text file:

python scripts/doubao-tts.py --lang en --text-file output/narration.txt --output output/narration.wav

Supply exactly one of --text and --text-file. UTF-8 BOM files are supported. Each command sends one synthesis request without automatic splitting. If the service rejects long text, split the narration into passages and generate them separately.

Audio settings and notes

• Default output: 24 kHz, 16-bit, mono WAV. The script receives PCM and writes a single WAV header locally.
• Set --sample-rate 48000 for 48 kHz. Supported rates: 8000, 16000, 22050, 24000, 32000, 44100, 48000.
• --speech-rate 0 is normal speed. Range: -50 (0.5x) to 100 (2x).
• --timeout 120 sets the network wait timeout in seconds, default 120. It is not a total task deadline.
• Output directories are created automatically. Existing files are rejected before an API request and never overwritten.
• Missing completion markers, damaged audio and network errors do not produce a WAV. There are no automatic retries.
• Audio is held in memory until completion. Generate narration in passages; memory usage grows with audio duration.
• Missing key: check DOUBAO_TTS_API_KEY in the current terminal. HTTP 401/403: check the Voice key, project and enabled service. Code 45000000: check voice permissions. For quota or concurrency errors, inspect console usage.
• Show all options: python scripts/doubao-tts.py --help.

References: official V3 API, official voice list. Ryan uses en_male_ryan_uranus_bigtts; Yangguang Qingnian uses zh_male_yangguangqingnian_uranus_bigtts. Ryan requires unidirectional streaming, which this script uses.