CosyVoice SSML 语音合成标记语言完整教程

SSML 简介

SSML（Speech Synthesis Markup Language）是一种基于 XML 的语音合成标记语言。它不仅能让语音合成大模型读出更丰富的文本内容，还支持对语速、语调、停顿、音量等语音特征进行精细控制，甚至可以添加背景音乐，带来更具表现力的语音效果。

SSML 的优势

• 精细控制：精确控制语速、音调、音量等参数
• 多音字处理：通过拼音标注解决多音字读音问题
• 自然停顿：模拟真实说话中的自然停顿
• 特殊读法：数字、日期、电话号码等按规范读法朗读
• 音效增强：支持添加背景音乐和音效

更多文档

CosyVoice语音合成SSML标记语言使用说明 - 云声配音

CosyVoice语音合成LaTeX公式使用说明 - 云声配音

CosyVoice语音合成指令控制教程说明 - 云声配音

CosyVoice 开发者API对接文档 - 云声配音

CosyVoice 系统音色列表 - 云声配音

CosyVoice声音设计使用教程：如何编写高质量的声音描述？ - 云声配音

CosyVoice语音合成SSML标记语言使用说明 - 云声配音

限制与约束

支持的模型

支持的音色

• 复刻音色（用户自定义克隆的音色）
• 系统音色列表中标记为支持SSML的音色（如 longanyang）

快速开始

基本结构

所有使用 SSML 功能的文本内容必须包含在 <speak></speak> 标签内：

<speak>你好，欢迎使用语音合成服务。</speak>

第一个 SSML 示例

<speak voice="longanyang" rate="1.0" pitch="1.0" volume="50">
    大家好，欢迎使用阿里云语音合成服务。
    <break time="500ms"/>
    <prosody rate="1.2">这是快速朗读的示例文字。</prosody>
</speak>

重要规则

1. 必须包含在 <speak> 标签内
2. 支持多个 <speak> 标签并列，但不支持嵌套
3. 特殊字符需要转义：
   • " → "
   • ' → '
   • & → &
   • < → <
   • > → >

SSML 标签详解

speak 根节点标签

<speak> 是所有 SSML 标签的根节点，任何使用 SSML 功能的文本内容都必须包含在此标签内。

语法

<speak [属性列表]>文本内容</speak>

属性说明

示例

<!-- 基本用法 -->
<speak>这是最简单的SSML文本。</speak>

<!-- 指定音色 -->
<speak voice="longanyang">我是龙眼杨音色。</speak>

<!-- 控制语速 -->
<speak rate="2">我的语速比正常人快。</speak>

<!-- 控制音调 -->
<speak pitch="0.5">我的音高比别人低。</speak>

<!-- 控制音量 -->
<speak volume="80">我的音量很大。</speak>

<!-- 组合属性 -->
<speak voice="longanyang" rate="1.2" pitch="1.1" volume="60">
    综合调整后的语音效果。
</speak>

<!-- 添加音效 -->
<speak effect="robot">你喜欢机器人瓦力吗？</speak>

<!-- 添加背景音乐 -->
<speak bgm="http://your-bucket.oss-cn-beijing.aliyuncs.com/bgm.wav" backgroundMusicVolume="30">
    <break time="2s"/>
    阴崖老木苍苍烟
    <break time="700ms"/>
    雨声犹在竹林间
</speak>

音效类型详解

break 停顿标签

在语音合成过程中添加一段静默时间，模拟自然说话中的停顿效果。

语法

<!-- 空属性，默认停顿1秒 -->
<break/>

<!-- 指定停顿时长 -->
<break time="string"/>

属性说明

取值范围

• 秒(s)：[1, 10] 之间的整数
• 毫秒(ms)：[50, 10000] 之间的整数

示例

<speak>
    请闭上眼睛休息一下
    <break time="500ms"/>
    好了，请睁开眼睛。
</speak>

<speak>
    第一段内容
    <break time="2s"/>
    第二段内容
</speak>

<!-- 使用空属性 -->
<speak>
    开始
    <break/>
    结束
</speak>

注意事项

• 连续多个 <break> 标签的停顿时长会累加
• 总停顿时长超过10秒时，仅生效前10秒

prosody 韵律标签

控制文本的语速、音调和音量，实现更细腻的语音效果。

语法

<prosody [rate="string"] [pitch="string"] [volume="string"]>文本</prosody>

属性说明

示例

<speak>
    <!-- 快速朗读 -->
    <prosody rate="1.5">这是快速朗读的文字。</prosody>

    <!-- 慢速朗读 -->
    <prosody rate="0.7">这是慢速朗读的文字。</prosody>

    <!-- 高音调 -->
    <prosody pitch="1.5">这是音调较高的文字。</prosody>

    <!-- 低音调 -->
    <prosody pitch="0.7">这是音调较低的文字。</prosody>

    <!-- 大音量 -->
    <prosody volume="80">这是音量较大的文字。</prosody>

    <!-- 小音量 -->
    <prosody volume="20">这是音量较小的文字。</prosody>

    <!-- 组合使用 -->
    <prosody rate="0.8" pitch="0.9" volume="40">这是慢速低沉的文字。</prosody>
</speak>

phoneme 发音标签

控制某段文本的具体发音方式，中文可用拼音，英文可用音标，适用于多音字等需要精准发音的场景。

语法

<phoneme alphabet="string" ph="string">文本</phoneme>

属性说明

拼音规则

• 字与字的拼音用空格分隔
• 拼音数目必须与字数一致
• 音调为 1-5 的整数，5 表示轻声

示例

<speak>
    <!-- 中文多音字 -->
    去<phoneme alphabet="py" ph="dian3 dang4 hang2">典当行</phoneme>把这个玩意
    <phoneme alphabet="py" ph="dang4 diao4">当掉</phoneme>。
</speak>

<speak>
    <!-- 英文音标 -->
    How to spell <phoneme alphabet="cmu" ph="S AY N">sin</phoneme>?
</speak>

<speak>
    <!-- 更多多音字示例 -->
    这个人很<phoneme alphabet="py" ph="le4">乐</phoneme>观，喜欢听音<phoneme alphabet="py" ph="yue4">乐</phoneme>。
</speak>

常见多音字拼音参考

sub 替换标签

将某段文本替换为指定的更适合朗读的文本。

语法

<sub alias="string">原文本</sub>

属性说明

示例

<speak>
    <!-- 缩写展开 -->
    <sub alias="网络协议标准">W3C</sub>制定了语音合成标准。
</speak>

<speak>
    <!-- 专业术语替换 -->
    请使用<sub alias="结构化查询语言">SQL</sub>查询数据库。
</speak>

<speak>
    <!-- 英文缩写 -->
    <sub alias="人工智能">AI</sub>技术正在快速发展。
</speak>

say-as 读法标签

告诉大模型文本是什么类型，并按该类型的常规读法进行朗读。

语法

<say-as interpret-as="string">文本</say-as>

属性说明

示例

<speak>
    <!-- 数字读法 -->
    <say-as interpret-as="cardinal">12345</say-as>
    <!-- 输出：一万二千三百四十五 -->

    <!-- 逐个数字 -->
    <say-as interpret-as="digits">12345</say-as>
    <!-- 输出：一二三四五 -->

    <!-- 电话号码 -->
    <say-as interpret-as="telephone">138-0013-8000</say-as>
    <!-- 输出：幺三八 零零幺三 八零零零 -->

    <!-- 日期 -->
    <say-as interpret-as="date">2024-01-15</say-as>
    <!-- 输出：二零二四年一月十五日 -->

    <!-- 时间 -->
    <say-as interpret-as="time">14:30</say-as>
    <!-- 输出：十四点三十分 -->

    <!-- 金额 -->
    <say-as interpret-as="currency">$1,234.56</say-as>
    <!-- 输出：一千二百三十四点五六美元 -->

    <!-- 计量单位 -->
    <say-as interpret-as="measure">100kg</say-as>
    <!-- 输出：一百千克 -->

    <!-- 地址 -->
    <say-as interpret-as="address">北京市海淀区中关村大街1号</say-as>

    <!-- ID -->
    <say-as interpret-as="id">user_12345</say-as>
    <!-- 输出：U S E R 下划线 一二三四五 -->

    <!-- 字符逐个读 -->
    <say-as interpret-as="characters">ABC123</say-as>
    <!-- 输出：A B C 一 二 三 -->
</speak>

soundEvent 音效标签

支持在语音中插入音效文件，如提示音、环境音等。

语法

<soundEvent src="URL"/>

属性说明

音频要求

• 采样率：16kHz
• 声道数：单声道
• 文件格式：WAV
• 文件大小：不超过2MB
• 位深度：16位

音频转换命令

ffmpeg -i 输入音频 -acodec pcm_s16le -ac 1 -ar 16000 输出.wav

示例

<speak>
    一匹马受了惊吓
    <soundEvent src="http://nls.alicdn.com/sound-event/horse-neigh.wav"/>
    人们四散躲避。
</speak>

<speak>
    电话铃响了
    <soundEvent src="http://your-bucket.oss-cn-beijing.aliyuncs.com/ring.wav"/>
    请接听电话。
</speak>

实战案例

案例1：新闻播报

<speak voice="longanyang" rate="1.0">
    <break time="300ms"/>
    各位听众朋友大家好，欢迎收听今日新闻。
    <break time="500ms"/>

    <prosody rate="0.9">
        今天是<say-as interpret-as="date">2024-01-15</say-as>，
        星期一，农历腊月初五。
    </prosody>
    <break time="400ms"/>

    首先关注天气情况。
    <break time="300ms"/>
    北京地区今日晴转多云，气温<say-as interpret-as="cardinal">-5</say-as>到<say-as interpret-as="cardinal">5</say-as>摄氏度。
    <break time="400ms"/>

    下面播报重要新闻。
    <break time="300ms"/>
    <prosody rate="1.0">
        据新华社报道，我国科技创新取得重大突破...
    </prosody>
</speak>

案例2：有声读物

<speak voice="longanyang" rate="0.9">
    <break time="500ms"/>
    <prosody pitch="1.1">
        第一章 初遇
    </prosody>
    <break time="800ms"/>

    <prosody rate="0.85">
        那是一个阳光明媚的早晨，
        <break time="300ms"/>
        小明像往常一样走在上学的路上。
        <break time="400ms"/>

        突然，一个陌生的声音传来：
    </prosody>
    <break time="300ms"/>

    <prosody pitch="1.3" rate="1.1">
        "你好，请问图书馆怎么走？"
    </prosody>
    <break time="400ms"/>

    <prosody rate="0.85">
        小明转过身，看到了一个陌生的女孩。
        <break time="300ms"/>
        她有着一双明亮的眼睛，脸上带着温暖的微笑。
    </prosody>
</speak>

案例3：客服语音

<speak voice="longanyang" rate="1.0">
    <break time="200ms"/>
    您好，欢迎致电客服热线。
    <break time="300ms"/>

    <prosody rate="0.9">
        您的来电对我们非常重要，请耐心等待。
    </prosody>
    <break time="500ms"/>

    为方便为您服务，请输入您的手机号码。
    <break time="300ms"/>

    <prosody rate="0.85">
        如需人工服务，请按<say-as interpret-as="digits">0</say-as>。
        <break time="200ms"/>
        查询订单，请按<say-as interpret-as="digits">1</say-as>。
        <break time="200ms"/>
        售后服务，请按<say-as interpret-as="digits">2</say-as>。
    </prosody>
    <break time="400ms"/>

    感谢您的耐心等待，正在为您转接人工客服...
</speak>

案例4：教育课件

<speak voice="longanyang" rate="0.9">
    <break time="300ms"/>
    <prosody pitch="1.1">
        小学语文第三课：多音字学习
    </prosody>
    <break time="600ms"/>

    同学们好，今天我们来学习几个常见的多音字。
    <break time="400ms"/>

    第一个字是"乐"。
    <break time="300ms"/>

    <prosody rate="0.85">
        当读作<phoneme alphabet="py" ph="le4">乐</phoneme>时，表示快乐、高兴。
        <break time="200ms"/>
        例如：快乐、欢乐。
    </prosody>
    <break time="300ms"/>

    <prosody rate="0.85">
        当读作<phoneme alphabet="py" ph="yue4">乐</phoneme>时，表示音乐。
        <break time="200ms"/>
        例如：音乐、乐器。
    </prosody>
    <break time="400ms"/>

    请跟读：
    <break time="200ms"/>
    <prosody rate="0.8">
        快乐的<phoneme alphabet="py" ph="le4">乐</phoneme>，
        音乐的<phoneme alphabet="py" ph="yue4">乐</phoneme>。
    </prosody>
</speak>

案例5：游戏配音

<speak voice="longanyang" effect="robot">
    <break time="200ms"/>
    <prosody pitch="0.9" rate="0.8">
        警告！警告！
    </prosody>
    <break time="300ms"/>

    <prosody rate="1.0">
        敌军还有<say-as interpret-as="digits">30</say-as>秒到达战场！
    </prosody>
    <break time="500ms"/>

    <prosody pitch="1.2" rate="1.1">
        请所有战士立即就位！
    </prosody>
    <break time="300ms"/>

    <soundEvent src="http://your-bucket.oss-cn-beijing.aliyuncs.com/alarm.wav"/>

    <prosody rate="0.9">
        重复一遍，敌军还有<say-as interpret-as="digits">30</say-as>秒到达战场！
    </prosody>
</speak>

常见问题与解决方案

问题1：SSML文本非法错误

错误信息：SSML text is illegal

原因：

• SSML格式不正确
• 特殊字符未转义
• 标签未正确闭合

解决方案：

<!-- 错误示例 -->
<speak>他说："你好"</speak>

<!-- 正确示例 -->
<speak>他说：&quot;你好&quot;</speak>

问题2：多音字读音错误

原因：模型无法正确识别多音字

解决方案：使用 <phoneme> 标签明确指定读音

<speak>
    去<phoneme alphabet="py" ph="dian3 dang4 hang2">典当行</phoneme>把这个玩意
    <phoneme alphabet="py" ph="dang4 diao4">当掉</phoneme>。
</speak>

问题3：语速/音调控制不生效

原因：

• 属性值超出范围
• 标签嵌套导致优先级问题

解决方案：

<!-- 确保属性值在有效范围内 -->
<speak>
    <!-- rate: 0.5-2 -->
    <prosody rate="1.5">正确的语速设置</prosody>

    <!-- pitch: 0.5-2 -->
    <prosody pitch="1.2">正确的音调设置</prosody>

    <!-- volume: 0-100 -->
    <prosody volume="80">正确的音量设置</prosody>
</speak>

问题4：停顿时间不正确

原因：多个 <break> 标签累加超过10秒限制

解决方案：

<!-- 错误：总停顿超过10秒 -->
<speak>
    开始
    <break time="5s"/>
    <break time="5s"/>
    <break time="5s"/>
    结束
    <!-- 实际只生效10秒 -->
</speak>

<!-- 正确：控制总停顿时间 -->
<speak>
    开始
    <break time="3s"/>
    中间
    <break time="3s"/>
    结束
</speak>

问题5：WebSocket API调用SSML失败

原因：未设置 enable_ssml 参数

解决方案：

{
    "header": {
        "action": "run-task",
        "task_id": "xxx",
        "streaming": "duplex"
    },
    "payload": {
        "task_group": "audio",
        "task": "tts",
        "function": "SpeechSynthesizer",
        "model": "cosyvoice-v3-flash",
        "parameters": {
            "voice": "longanyang",
            "enable_ssml": true
        },
        "input": {}
    }
}

附录

SSML 标签速查表

常用音色列表

参考链接

• CosyVoice 开发者API对接文档
• CosyVoice音色列表
• W3C SSML 1.0规范

文档版本：v1.0
最后更新：2026年
适用模型：cosyvoice-v3-flash, cosyvoice-v3-plus, cosyvoice-v2