当用户对你的产品发出语音问句时，即需透过SpeechSynthesizer接口来取得TVS的语音回复。例如，当某个用户问了TVS：「杭州的天气怎样？」TVS将会回复一个带有二进制音频附件的Speak指令给客户端，客户端应该处理此指令并播放该音频。

状态

SpeechSynthesizer有以下状态：
PLAYING：当TmallGenie正在说话时，SpeechSynthesizer应该处在playing状态。当TmallGenie的语音播放完成后，SpeechSynthesizer应该转移至 finished 状态。
FINISHED：当TmallGenie说完话后，SpeechSynthesizer应该转移至 finished 状态，并随后上报 SpeechFinished 事件。

SpeechSynthesizer上下文

TmallGenie预期客户端在每个需要上下文的事件中都为当前播放的TTS上报 playerActivity（播放状态）与 offsetInMilliseconds 。

Sample Message

{
    "header": {
        "namespace": "SpeechSynthesizer",
        "name": "SpeechState"
    },
    "payload": {
        "token": "{{STRING}}",
        "offsetInMilliseconds": {{LONG}},
        "playerActivity": "{{STRING}}"
    }
}

Payload参数

参数	描述	型态
token	在 Speak 指令中所提供的opaque token。	字串
offsetInMilliseconds	用以标记目前TTS的offset	长整数
playerActivity	用以识别SpeechSynthesizer的状态。 允许值： PLAYING或FINISHED	字串

播放器行为	描述
PLAYING	语音正在播放中。
FINISHED	语音播放结束。

Speak指令

此指令会在用户的问句需要TmallGenie的语音回复时由TVS下发至客户端。大多数情况下，Speak指令是作为用户请求的回复而下发的，例如Recognize事件。然而，Speak 指令也有可能作为接下来会进行动作的开场白，例如当用户想设置计时器时，TVS除了会下发 SetAlert 指令要求客户端设置闹钟外，也会下发一个 Speak 指令来播放语音，用以提醒用户计时器成功设置。

此指令会以multipart报文的形式下发给客户端：一部分是JSON格式指令，另一部分为二进制音频附件。

Http1.1 Sample Message

{
    "directive": {
        "header": {
            "namespace": "SpeechSynthesizer",
            "name": "Speak",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "url": "{{STRING}}",
            "format": "{{STRING}}",
            "token": "{{STRING}}"
        }
    }
}

Http2.0 Sample Message

{
	"directive": {
		"header": {
			"name": "Speak",
			"namespace": "SpeechSynthesizer",
			"messageId": "{{STRING}}",
			"dialogRequestId": "{{STRING}}"
		},
		"payload": {
			"url": "{{STRING}}",
			"format": "{{STRING}}",
			"token": "{{STRING}}",
			"ttsText": "{{STRING}}",
			"text": "{{STRING}}"
		}
	}
}

二进制音频附件

每个Speak指令都会有一个对应的二进制音频附件作为multipart报文中的其中一部分。以下headers会置于该附件之前：

Content-Type: application/octet-stream
Content-ID: {{Audio Item CID}}

{{BINARY AUDIO ATTACHMENT}}

Header参数

参数	描述	型态
messageId	用以代表一个特定报文的唯一ID。	字串
dialogRequestId	由客户端为每一个发送给TVS的 Recognize 事件所生成的唯一ID。此参数用以将TVS所下发的指令与某个特定Recognize事件进行关连。	字串

Payload参数

参数	描述	型态
url	对音频内容的唯一识别符。此URL总是使用cid:前缀 Example: cid:{{STRING}}	字串
format	回传音频的格式。 允许值： “AUDIO_MPEG”	长整数
token	用来表示目前合成语音 (Text-to-Speech; TTS) 对象的一个opaque token	字串
ttsText	返回文案	字串
text	返回文案	字串

SpeakUrl指令（扩展）

与Speak指令使用流式音频不同的是，SpeakUrl指令直接播放一个url，适合不支持流式TTS音频播放的设备使用。

Sample Message

{
    "directive": {
        "header": {
            "namespace": "SpeechSynthesizer",
            "name": "SpeakUrl",
            "messageId": "{{STRING}}",
            "dialogRequestId": "{{STRING}}"
        },
        "payload": {
            "url": "{{STRING}}",
            "format": "{{STRING}}",
            "effectiveCount": 3,
        }
    }
}

Header参数

参数	描述	型态
messageId	用以代表一个特定message的唯一ID。	字串
dialogRequestId	由客户端为每一个发送给TVS的 Recognize 事件所生成的唯一ID。此参数用以将TVS所下发的指令与某个特定Recognize事件。	字串

Payload参数

参数	描述	型态
url	TTS音频播放地址	string
format	音频的格式。 允许值：AUDIO_MPEG	string
effectiveCount	有效播放次数，默认为3	int

SpeechStarted事件

在处理了 Speak 指令并开始合成语音的播报后，客户端应该上报 SpeechStarted 事件给TVS。

Sample Message

{
    "event": {
        "header": {
            "namespace": "SpeechSynthesizer",
            "name": "SpeechStarted",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "token": "{{STRING}}"
        }
    }
}

Header参数

参数	描述	型态
messageId	用以代表一个特定报文的唯一ID。	字串

Payload参数

参数	描述	型态
token	由 Speak 指令所提供的opaque token。	字串

SpeechFinished事件

在处理了 Speak 指令而且TmallGenie TTS已经完整播放给用户后，客户端必须上报 SpeechFinished 事件。

Sample Message

{
    "event": {
        "header": {
            "namespace": "SpeechSynthesizer",
            "name": "SpeechFinished",
            "messageId": "{{STRING}}"
        },
        "payload": {
            "token": "{{STRING}}"
        }
    }
}

Header参数

参数	描述	型态
messageId	用以代表一个特定报文的唯一ID。	字串

Payload参数

参数	描述	型态
token	由 Speak 指令所提供的opaque token。	字串

FAQ

关于此文档暂时还没有FAQ