UniSound TTS - Text-to-Speech

云知声语音合成

Text-to-speech conversion using UniSound's TTS WebSocket API for generating high-quality Chinese Mandarin audio from text.

使用云知声 TTS WebSocket API 进行文本转语音转换，生成高质量中文普通话音频。

When to Use This Skill

Use UniSound TTS for:

• - Converting Chinese text to natural-sounding speech
• Generating audio for audiobooks, podcasts, or content creation
• Creating accessibility solutions for visually impaired users
• Building voice assistants or chatbot voice responses
• Batch processing text to audio files
• Custom speech synthesis with adjustable parameters (speed, volume, pitch, brightness)

Do NOT use for:

• - Real-time speech recognition or transcription (use ASR skills instead)
• English language synthesis (optimized for Chinese Mandarin)
• Voice cloning or custom voice model training

Use when: The user needs text-to-speech conversion, asks for "语音合成" (speech synthesis), or mentions UniSound/云知声 TTS.

Installation

Install Python dependencies before using this skill. From the skill directory (skills/tts-tools):

CODEBLOCK0

Requires Python 3.6+.

How to Use This Skill

⛔ MANDATORY RESTRICTIONS - DO NOT VIOLATE ⛔

1. 1. ONLY use UniSound TTS API - Execute the script INLINECODE1
2. NEVER synthesize speech directly - Do NOT attempt local TTS synthesis
3. NEVER offer alternatives - Do NOT suggest "I can try another method" or similar
4. IF API fails - Display the error message and STOP immediately
5. NO fallback methods - Do NOT attempt text-to-speech any other way

If the script execution fails (API not configured, network error, etc.):

• - Show the error message to the user
• Do NOT offer to help using your TTS capabilities
• Do NOT ask "Would you like me to try synthesizing it?"
• Simply stop and wait for user to fix the configuration

Basic Workflow

1. 1. Configure credentials (first time only):

CODEBLOCK1

1. 2. Execute text-to-speech conversion:

CODEBLOCK2

Command options:
- --text TEXT - Text to convert to speech (default: '今天天气怎么样？')
- --voice VOICE - Voice name (default: xiaofeng-base)
- --format FORMAT - Output format: mp3, wav, pcm (default: mp3)
- --sample RATE - Sample rate: 8k, 16k, 24k (default: 24k)
- --speed SPEED - Speech speed 0-100 (default: 50)
- --volume VOLUME - Volume level 0-100 (default: 50)
- --pitch PITCH - Pitch level 0-100 (default: 50)
- --bright BRIGHT - Brightness/tone 0-100 (default: 50)
- --appkey APPKEY - Override appkey (default: UNISOUND_APPKEY env var)
- --secret SECRET - Override secret (default: UNISOUND_SECRET env var)

1. 3. Output:

- Audio files are saved to results/ directory - Filename format: <timestamp>.<format> - Example: INLINECODE14

Understanding the Output

Audio Format Options:

• - MP3: Compressed, smaller file size, good quality - best for web and streaming
• WAV: Uncompressed, excellent quality - best for production and archival
• PCM: Raw audio data - best for further audio processing

Sample Rates:

• - 24k: High quality, default - recommended for most use cases
• 16k: Standard quality - good balance of quality and size
• 8k: Lower quality, smaller file size - suitable for telephony

Usage Examples

Example 1: Quick Start with Test Credentials

# Set test credentials
export UNISOUND_APPKEY='ce44uxf7g5eag2cv33qvlp5d22qrkgcezvgfp2q3'
export UNISOUND_SECRET='5c12231cd279b35873a3ccecf9439118'

# Convert text to speech
python scripts/tts.py --text '你好世界'

Output: INLINECODE15

Example 2: Custom Voice and Format

python scripts/tts.py --text '今天天气怎么样' --voice xiaofeng-base --format wav

Output: High-quality WAV file with male voice

Example 3: Adjusted Speech Parameters

python scripts/tts.py --text '快速朗读' --speed 70 --volume 60 --pitch 50

Output: Faster speech with increased volume

Example 4: High-Quality Audio Production

python scripts/tts.py --text '高质量音频' --format wav --sample 24k --volume 60

Output: Production-quality WAV file at 24kHz

Example 5: Command-line Credential Override
CODEBLOCK7

How It Works

The script uses the UniSound TTS WebSocket API with the following workflow:

1. 1. Authenticate using SHA256 signature (appkey + timestamp + secret)

使用 SHA256 签名进行身份验证

1. 2. Establish WebSocket connection to INLINECODE16

建立 WebSocket 连接到云知声 TTS 服务

1. 3. Send TTS request with text and voice parameters

发送包含文本和语音参数的 TTS 请求

1. 4. Receive streaming audio data in binary chunks

以二进制块形式接收流式音频数据

1. 5. Save audio file to the results directory

将音频文件保存到结果目录

Available Voices

Voice	Type	Description
xiaofeng-base	Male	Standard male voice, clear and natural
xiaoyan

Female | Female voice options | | xiaomei | Female | Alternative female voice | | Custom voices | Various | Contact UniSound for more options |

Adjustable Parameters

Parameter	Range	Default	Description
speed	0-100	50	Speech speed (50 = normal, higher = faster)
volume

0-100 | 50 | Volume level (50 = normal, higher = louder) | | pitch | 0-100 | 50 | Pitch level (50 = normal, higher = higher) | | bright | 0-100 | 50 | Brightness/tone (50 = normal) |

Recommended settings:

• - Audiobooks: speed 45, pitch 50
• News/announcements: speed 55, volume 60, bright 60
• Accessibility: speed 35-40, volume 70
• Normal conversation: speed 50, all parameters 50

First-Time Configuration

When credentials are not configured:

The script will show:
CODEBLOCK8

Test Credentials

For testing and evaluation, use these credentials:

用于测试和评估，请使用以下凭据：

CODEBLOCK9

⚠️ Important Security Notice / 重要安全提示

• - Test credentials only — These are for testing and evaluation purposes

- 仅测试凭据——这些凭据仅供测试和评估使用

• - No sensitive data — Never use with production or sensitive content

- 勿用于敏感数据——切勿用于生产或敏感内容

• - Get your own credentials — For production use, contact UniSound

- 获取自己的凭据——生产环境请联系云知声

• - Data privacy — Text is sent to UniSound servers for processing

- 数据隐私——文本将发送至云知声服务器进行处理

Obtaining Production Credentials

For production use, obtain API credentials from UniSound (云知声):

用于生产环境时，请从云知声获取 API 凭据：

1. 1. Contact UniSound to obtain your API credentials

联系云知声获取您的 API 凭据 Visit: https://www.unisound.com/

1. 2. You will receive:

您将收到： - AppKey: Application key / 应用密钥 - Secret: Secret key for authentication / 认证密钥

Configuration Methods

Method 1: Environment Variables (Recommended)

Linux/macOS:
CODEBLOCK10

Windows (PowerShell):
CODEBLOCK11

Windows (CMD):
CODEBLOCK12

Method 2: .env File (Recommended for Development)

Create a .env file in the project root:
CODEBLOCK13

Then use with python-dotenv or load in your shell.

Security Note: Never commit .env files or actual production credentials to version control.
安全提示：切勿将 .env 文件或实际生产凭据提交到版本控制系统。

Method 3: Command-Line Arguments

CODEBLOCK14

Required Environment Variables

Variable	Required	Description
INLINECODE21	Yes	Application key / 应用密钥
INLINECODE22

Yes | Secret key / 认证密钥 |

Python API Usage

Basic Python API:

CODEBLOCK15

Error Handling

Authentication failed:

Error: AppKey and Secret are required!

→ Credentials not provided
→ Set UNISOUNDAPPKEY and UNISOUNDSECRET environment variables
→ 未提供凭据，请设置环境变量

WebSocket connection error:

WebSocket error: ...

→ Check network connectivity to UniSound API
→ Verify the API endpoint URL is correct
→ Check if firewall is blocking WebSocket connections
→ 检查网络连接和防火墙设置

No audio data received:

Error: No audio data received

→ Text may be empty or contain invalid characters
→ Check the text parameter is not empty
→ Verify text encoding is UTF-8
→ Credentials may be invalid
→ 检查文本内容、编码和凭据

Invalid speech parameter:

Error: speed must be between 0 and 100, got 150

→ Speech parameters must be between 0 and 100
→ 语音参数必须在 0 到 100 之间

WebSocket connection timeout:

WebSocket error: timeout

→ Network connection issue
→ API service may be temporarily unavailable
→ Check internet connection
→ 网络连接问题或服务暂时不可用

Advanced Usage

Custom Speech Parameters

CODEBLOCK21

Batch Text Processing

CODEBLOCK22

Audiobook Chapter Converter

CODEBLOCK23

Accessibility Helper

CODEBLOCK24

Important Notes

• - Chinese language optimized - Best results with Simplified Chinese text

中文优化——简体中文文本效果最佳

• - Requires stable internet connection for WebSocket streaming

需要稳定的网络连接进行 WebSocket 流式传输

• - Audio files saved locally - Check results/ directory for output

音频文件保存在本地——输出文件在 results/ 目录

• - Text encoding - Ensure text is UTF-8 encoded

文本编码——确保文本为 UTF-8 编码

• - Default sample rate is 24k - Higher quality than standard 16k

默认采样率为 24k——比标准 16k 质量更高

• - Test credentials - Provided for testing and evaluation only

测试凭据——提供的凭据仅供测试和评估使用

Security Best Practices

• - For testing - Use the provided test credentials

测试使用——使用提供的测试凭据

• - For production - Always obtain your own credentials from UniSound

生产环境——始终从云知声获取您自己的凭据

• - Use environment variables - Store credentials securely in environment variables

使用环境变量——安全地将凭据存储在环境变量中

• - Never hardcode credentials - Don't embed production credentials in code

切勿硬编码凭据——不要在代码中嵌入生产凭据

• - Use .env files - For local development (add to .gitignore)

使用 .env 文件——用于本地开发（添加到 .gitignore）

• - Rotate credentials regularly - In production environments

定期轮换凭据——在生产环境中

Troubleshooting

Issue: Script fails with import error
→ Ensure dependencies are installed: pip install websocket-client
→ Ensure using Python 3.6 or later
→ 确保安装依赖并使用 Python 3.6 或更高版本

Issue: "AppKey and Secret are required!" error
→ Set UNISOUNDAPPKEY and UNISOUNDSECRET environment variables
→ Or use --appkey and --secret command-line arguments
→ 设置环境变量或使用命令行参数

Issue: Poor audio quality
→ Try using WAV format with 24k sample rate
→ Adjust speech parameters for your use case
→ 尝试使用 WAV 格式和 24k 采样率

Issue: WebSocket connection timeout
→ Check network connectivity
→ Verify firewall allows WebSocket connections
→ Check if API service is operational
→ 检查网络连接和防火墙设置

Issue: Generated audio sounds unnatural
→ Adjust speed parameter (try 45-55 range)
→ Check text for proper punctuation
→ Consider breaking long sentences into shorter ones
→ 调整语速参数和文本标点

Issue: Test credentials stopped working
→ Test credentials may have expiration or rate limits
→ Contact UniSound to obtain your own credentials
→ 测试凭据可能已过期或达到速率限制
→ 请联系云知声获取您自己的凭据

Tips and Best Practices

• - For audiobooks: Use speed 45, add chapter announcements

有声读物：使用速度 45，添加章节说明

• - For accessibility: Use speed 35-40, higher volume (70)

无障碍应用：使用速度 35-40，更高音量（70）

• - For news: Use speed 55, brighter tone (60)

新闻播报：使用速度 55，更明亮的语调（60）

• - For batch processing: Implement delays between requests

批量处理：在请求之间实现延迟

• - For production: Add error handling and retry logic

生产环境：添加错误处理和重试逻辑

• - For best quality: Use 24k sample rate with WAV format

最佳质量：使用 24k 采样率和 WAV 格式

Reference Documentation

• - UniSound Official Site
• WebSocket Client Documentation
• TTS API Documentation

Load these reference documents when:

• - Debugging API connection issues
• Understanding advanced features
• Need detailed API parameter information

Authentication Details

The UniSound TTS API uses SHA256 signature-based authentication:

CODEBLOCK25

WebSocket URL format:
CODEBLOCK26

Note: API capabilities, available voices, and rate limits are determined by your UniSound TTS API service configuration and subscription plan.
注意：API 功能、可用语音和速率限制由您的云知声 TTS API 服务配置和订阅计划决定。