A Python demo for Volcengine (ByteDance Cloud) Text-to-Speech APIs, supporting both HTTP REST and WebSocket bidirectional streaming synthesis.

• Features
• Prerequisites
• Installation
• Configuration
  • Obtaining Credentials
  • Credential Reference
• Usage
  • HTTP TTS
  • WebSocket Bidirectional TTS
• Project Structure
• Testing
• Troubleshooting
• License

• HTTP TTS -- Simple one-shot text-to-speech via the REST API (/api/v1/tts)
• WebSocket Bidirectional TTS -- Real-time streaming synthesis over a persistent WebSocket connection (/api/v3/tts/bidirection), with character-by-character streaming and per-sentence audio output
• Binary protocol layer -- Full implementation of the Volcengine binary message protocol for WebSocket communication
• Environment-based configuration -- All credentials loaded from a .env file; nothing hard-coded

• Python 3.9 or higher
• A Volcengine account with the Speech Synthesis (TTS) service activated

# Clone the repository
git clone <repository-url>
cd volcengine_bidirection_demo

# Create and activate a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate   # Linux / macOS
# .venv\Scripts\activate    # Windows

# Install dependencies
pip install -e .

This installs the project in editable mode along with all required packages:

# Copy the example file and fill in your real values
cp .env.example .env

Edit .env:

DOUBAO_APP_ID=your_app_id_here
DOUBAO_ACCESS_TOKEN=your_access_token_here
DOUBAO_API_KEY=your_api_key_here

Security note -- .env is listed in .gitignore and must never be committed. Only .env.example (which contains placeholders) is tracked in version control.

All credentials are obtained from the Volcengine Speech Console:

1. Sign up / Log in at console.volcengine.com.
2. Navigate to Voice Technology (语音技术) and activate the Speech Synthesis service.
3. Create an application -- after activation you will be assigned an App ID and related tokens.
4. Locate your credentials on the application's credential page. The console displays your App ID, Access Token (Token), and API Key after service activation.

For detailed walkthrough, see the official docs:

• Quick Start (New Console)
• Console Usage FAQ

How they relate to the API:

• The HTTP TTS endpoint (/api/v1/tts) uses DOUBAO_API_KEY in the x-api-key request header. No App ID or Access Token is needed.
• The WebSocket bidirectional TTS endpoint (/api/v3/tts/bidirection) uses DOUBAO_APP_ID and DOUBAO_ACCESS_TOKEN as WebSocket upgrade headers. A Resource ID is also required and is auto-detected from the voice type (or can be overridden via --resource_id).

Synthesizes text using a single HTTP POST request and saves the result as an MP3 file.

python tts_http.py

This runs the built-in demo text (a Chinese passage about a Three Kingdoms visualisation) and writes the output to sanguo_intro.mp3.

You can also import and call the function programmatically:

from tts_http import tts_request

audio = tts_request(
    text="你好，世界",
    voice_type="zh_female_vv_uranus_bigtts",
    encoding="mp3",
    speed_ratio=1.0,
)

with open("output.mp3", "wb") as f:
    f.write(audio)

Parameters:

Streams text character-by-character over a WebSocket connection. Each sentence (split on 。) is processed as a separate session, with its audio saved to an individual file.

python examples/volcengine/bidirection.py \
    --text "你好世界。这是一个测试。" \
    --voice_type zh_female_vv_uranus_bigtts

CLI arguments:

Output files are named {voice_type}_session_{index}.{encoding}, e.g. zh_female_vv_uranus_bigtts_session_0.mp3.

.
├── .env.example                        # Template for environment variables
├── .gitignore
├── pyproject.toml                      # Project metadata and dependencies
├── tts_http.py                         # HTTP TTS client (REST API)
├── protocols/
│   ├── __init__.py                     # Public API exports
│   └── protocols.py                    # Binary message protocol implementation
└── examples/
    └── volcengine/
        └── bidirection.py              # WebSocket bidirectional TTS example

Since this project is a demo client for a remote API, testing requires valid credentials.

1. Verify HTTP TTS:

python tts_http.py

Expected: prints Saved to sanguo_intro.mp3 (...) and creates a playable MP3 file.

2. Verify WebSocket TTS:

python examples/volcengine/bidirection.py \
    --text "测试语音合成。" \
    --voice_type zh_female_vv_uranus_bigtts

Expected: prints connection and session logs, creates zh_female_vv_uranus_bigtts_session_0.mp3.

3. Quick smoke test (both modes):

# HTTP -- should exit 0 and create an MP3
python tts_http.py && echo "HTTP TTS: OK"

# WebSocket -- should exit 0 and create per-sentence MP3s
python examples/volcengine/bidirection.py \
    --text "第一句。第二句。" \
    --voice_type zh_female_vv_uranus_bigtts \
  && echo "WebSocket TTS: OK"

This project is provided as a demo. See the Volcengine Terms of Service for API usage terms.