Turn Chinese text into two-person conversational podcast audio, with the interface wrapped in scripts/generate_podcast.py。
Acceptance Criteria (self-check before each generation completes)
- The audio file has been written to disk; reportthe actual path and file sizeback to the user
- Input text ≤25,000 characters (if too long, you must first confirm a splitting plan with the user; do not let the model silently truncate)
- When generation is interrupted, retry_info was used to resume rather than starting over
- Parameter choices are justified: use mp3 for distribution, pcm for post-processing; speech rate around -20 for teaching content
- When credentials are missing, did not force a trial: tell the user to obtain them from the Volcano Engine console (speech/service/10028)
What Not to Do
- Do not write podcast scripts—the quality of the input text is an upstream task (for script creation, find a writing-type skill)
- Do not do single-person read-aloud, dubbing, or sound effects production
- Do not echo the user's ACCESS_KEY in the output
Workflow
1. Prepare input
Required: Chinese text (≤25k characters) + APP_ID + ACCESS_KEY (if absent, tell the user how to obtain them and stop). Optional: format (default mp3) / sample rate (default 24000) / speech rate (-50~100, 0=normal, 100=2x speed) / voice / opening music (default off).
Best text length is 500-3000 characters—the optimal range for podcast duration and listening experience; for a long article, it is recommended to summarize first and then generate.
2. Generate
python scripts/generate_podcast.py \
--text "播客话题或内容文本" \
--output "/path/to/output.mp3" \
--app-id "$VOLC_APP_ID" --access-key "$VOLC_ACCESS_KEY" \
--format mp3 --sample-rate 24000 --speech-rate 0
The script streams audio, shows progress by round, and returns statistics after writing to disk (size/round count).
For Python module calls, custom voice IDs, and how to write retry_info for resumable transfer, see the docstring in the script and references/api_reference.md。
3. Deliver
Report the file path, size, and estimated duration; on failure, give the specific error and next step (see the pitfalls table).
Known Pitfalls
| Pitfall | Specific manifestation | Response |
|---|---|---|
| Silent truncation when too long | >25k characters causes the model to truncate directly, and the podcast lacks an ending | Validate length before generation; if too long, first confirm splitting or summarization with the user |
| WebSocket cannot connect | Connection error/timeout | Troubleshoot in order: whether credentials are correct → network → whether the firewall allows WebSocket |
| Retry from the beginning after interruption | Long text generation breaks halfway, and rerunning burns double the quota | Get task_id and last_finished_round_id from the logs, and resume using retry_info |
| Output path is not writable | Generation completes but saving fails | Before generation, check that the directory exists and is writable and that disk space is sufficient |
| Poor text structure produces a bad draft | Conversation generated from rambling text is stiff | Use clearly structured Chinese text as input; if the result is poor, revise the text first before adjusting parameters |
Dependencies and credentials
pip install websockets
Credentials are obtained from the Volcengine console (console.volcengine.com/speech/service/10028). It is recommended to use environment variables; do not hardcode them into the code.
Reference documentation (load as needed)
references/api_reference.md— Complete parameter specifications, WebSocket protocol details, event types, error codes; read during protocol-level debuggingscripts/generate_podcast.py— CLI and module dual interfaces, including automatic retry and streaming receive implementation