本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

# PlayAudio
<a name="play-audio"></a>

在通話的任何腿上播放音訊檔案。音訊可以重複任意次數。可使用 中設定的 DTMF 數字來終止進行中音訊`PlaybackTerminators`。

目前，Amazon Chime SDK 僅支援從 Amazon Simple Storage Service (Amazon S3) 儲存貯體播放音訊檔案。S3 儲存貯體必須屬於與 SIP 媒體應用程式相同的 AWS 帳戶。此外，您必須將 `s3:GetObject`許可授予 Amazon Chime SDK Voice Connector 服務主體。您可以使用 S3 主控台或命令列界面 (CLI) 來執行此操作。

下列程式碼範例顯示典型的儲存貯體政策。

------
#### [ JSON ]

****  

```
{
    "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": "{{111122223333}}"
                }
            }
        }
    ]
}
```

------

Audio Service 會代表 Sip Media Application 讀取和寫入 S3 儲存貯體。若要避免[混淆代理人問題](https://docs.aws.amazon.com/IAM/latest/UserGuide/confused-deputy.html)，您可以限制 S3 儲存貯體存取單一 SIP 媒體應用程式。

------
#### [ JSON ]

****  

```
{
    "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": "{{111122223333}}",
                    "aws:SourceArn": "arn:aws:chime:{{us-east-1}}:{{111122223333}}: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**  
*描述* – 中的`CallId`參與者`CallDetails`。  
*允許的值* – 有效的呼叫 ID。  
*必要* – 否，如果 `ParticipantTag` 存在。  
*預設值* – 無。

**ParticipantTag**  
*描述* – `ParticipantTag` 中其中一個連線參與者的描述`CallDetails`。  
*允許的值* – `LEG-A`或 `LEG-B`。  
*必要* – 否，如果 `CallId` 存在。  
*預設值* – 調用 `ParticipantTag` 的 `callLeg`。如果您指定 ，則忽略`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 Voice Connector 服務主體，也就是 voiceconnector.chime.amazonaws.com。  
*允許的值* – Amazon Chime SDK 可存取 `s3:GetObject`動作的有效 S3 儲存貯體。  
*必要* – 是。  
*預設值* – 無。

**AudioSource.key**  
*描述* – 對於 S3 來源類型，來自 `AudioSource.BucketName` 屬性中指定之 S3 儲存貯體的檔案名稱。  
*允許的值* – 有效的音訊檔案。  
*必要* – 是。  
*預設值* – 無。

SIP 媒體應用程式會嘗試播放來源 URL 的音訊。您可以使用大小不超過 50 MB 的原始未壓縮 PCM .wav 檔案。Amazon Chime SDK 建議 8 KHz 單機。

當撥號計劃中的最後一個指示為 `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 上的工作範例：
+ https：//[https://github.com/aws-samples/amazon-chime-sma-bridging](https://github.com/aws-samples/amazon-chime-sma-bridging)。
+ [https://github.com/aws-samples/amazon-chime-sma-call-forwarding](https://github.com/aws-samples/amazon-chime-sma-call-forwarding)
+ [https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications](https://github.com/aws-samples/amazon-chime-sma-outbound-call-notifications)
+ [https://github.com/aws-samples/amazon-chime-sma-on-demand-recording](https://github.com/aws-samples/amazon-chime-sma-on-demand-recording)
+ [https://github.com/aws-samples/amazon-chime-sma-update-call](https://github.com/aws-samples/amazon-chime-sma-update-call)