PlayAudio - Amazon Chime SDK

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

PlayAudio

在调用的任一分支上播放音频文件。音频可以重复播放任意次数。可以使用 PlaybackTerminators 中设置的 DTMF 数字终止正在播放的音频。

目前，Amazon Chime SDK 仅支持从 Amazon Simple Storage Service (Amazon S3) 存储桶播放音频文件。S3 存储桶必须与 SIP 媒体应用程序属于同一个 AWS 账户。此外，您必须向 Amazon Chime SDK 语音连接器服务主体授予 s3:GetObject 权限。您可以使用 S3 控制台或命令行界面 (CLI) 完成此操作。

以下代码示例显示典型的存储桶策略。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*",
                "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "aws-account-id"
                }
            }
        }
    ]
}

音频服务代表您的 Sip 媒体应用程序对 S3 存储桶进行读写操作。为避免混淆代理问题，您可以将 S3 存储桶的访问限制为单个 SIP 媒体应用程序。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*",
                "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "aws-account-id",
                    "aws:SourceArn": "arn:aws:chime:region:aws-account-id:sma/sip-media-application-id"
                }
            }
        }
    ]
}

以下代码示例显示典型的操作。

{
    "Type": "PlayAudio",
    "Parameters": {
        "CallId": "call-id-1",
        "ParticipantTag": "LEG-A",
        "PlaybackTerminators": ["1", "8", "#"],
        "Repeat": "5",
        "AudioSource": {
            "Type": "S3",
            "BucketName": "valid-S3-bucket-name",
            "Key": "wave-file.wav"
        }
    }
}
CallID

描述 — CallDetails 中的参与者的 CallId。

允许的值 — 有效的调用 ID。

必填 — 否，如 ParticipantTag 已存在。

默认值 — 无。

ParticipantTag

描述 — CallDetails 中一个已连接参与者的 ParticipantTag。

允许的值 — LEG-A 或 LEG-B。

必填 — 否，如 CallId 已存在。

默认值 — 被调用的 callLeg 的 ParticipantTag。如果您指定 CallId，则忽略该值。

PlaybackTerminator

描述 — 使用用户的 DTMF 输入终止正在播放的音频

允许的值 — 由以下值组成的数组：“0”“1”、“2”、“3”、“4”、“5”、“6”、“7”、“8”、“9”、“#”、“*”

必填 — 否

默认值 – 无

Repeat

描述 — 将音频重复播放指定次数

允许的值 — 大于零的整数

必填 — 否

默认值 — 1

AudioSource.Type

描述 — 音频文件来源的类型。

允许的值 — S3。

必填 — 是。

默认值 — 无。

AudioSource.BucketName

描述-对于 S3 源类型，S3 存储桶必须与 SIP 应用程序属于同一个 AWS 账户。存储桶必须有权访问 Amazon Chime SDK 语音连接器服务主体，即 voiceconnector.chime.amazonaws.com。

允许的值 — Amazon Chime SDK 有权访问 s3:GetObject 操作的有效 S3 存储桶。

必填 — 是。

默认值 — 无。

AudioSource.key

描述 — 对于 S3 源类型，AudioSource.BucketName 属性中指定的 S3 存储桶中的文件名。

允许的值 — 有效的音频文件。

必填 — 是。

默认值 — 无。

SIP 媒体应用程序尝试从来源 URL 播放音频。您可以使用大小不超过 50MB 未压缩的原始 PCM .wav 文件。Amazon Chime SDK 推荐 8kHz 单声道。

当拨号计划中的最后一条指令是，PlayAudio并且文件已完成播放时，或者如果用户按下键停止播放，则应用程序将使用以下示例所示的事件调用该 AWS Lambda 函数。

{
    "SchemaVersion": "1.0",
    "Sequence": INTEGER,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
        "Type": "PlayAudio",
        "Parameters" : {
            "CallId": "call-id-1",
            "AudioSource": {
                "Type": "S3",
                "BucketName": "valid-S3-bucket-name",
                "Key": "wave-file.wav",
         }           
     }
}

终止数字停止音频后，音频将不会重复播放。

错误处理

当验证文件包含错误或运行操作时出现错误时，SIP 媒体应用程序会调用带有相应错误代码的 AWS Lambda 函数。

错误 消息 Reason

InvalidAudioSource

音频来源参数无效。

出现此错误可能基于多种原因。例如，由于权限问题或 URL 问题，SIP 媒体应用程序无法访问文件。或者，由于格式、持续时间、大小等原因，音频文件可能无法通过验证。

SystemException

运行操作时出现系统错误。

运行操作时出现另一个系统错误。

InvalidActionParameter

CallId 或操作 ParticipantTag 参数无效。

该操作包含无效参数。

以下代码示例显示典型的调用失败。

{
    "SchemaVersion": "1.0",
    "Sequence": 2,
    "InvocationEventType": "ACTION_FAILED",
    "ActionData": {
        "Type": "PlayAudio",
        "Parameters" : {
            "CallId": "call-id-1",
            "AudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file.wav"
            },
        },
        "ErrorType": "InvalidAudioSource",
        "ErrorMessage": "Audio Source parameter value is invalid."
    }
    "CallDetails": {
        ...
    }
}

参见以下方面的工作示例 GitHub：