# Creating media capture pipelines for Amazon Chime SDK meetings
Media capture pipelines capture audio, video, and content share streams, plus meeting events and data messages. All media capture pipelines save their data to an [Amazon Simple Storage Service](https://aws.amazon.com/s3/) (S3) bucket that you create. You can create one media capture pipeline per Amazon Chime SDK meeting.
The following sections explain how to create a media capture pipeline. Follow them in the order listed.
**Topics**
+ [
# Creating an Amazon S3 bucket for Amazon Chime SDK media capture pipelines
](create-s3-bucket.md)
+ [
# Enabling server-side encryption for an Amazon S3 bucket for Amazon Chime SDK media capture pipelines
](sse-kms.md)
+ [
# Enabling object level server-side encryption with AWS KMS key
](using-kms-keys-for-encryption.md)
+ [
# Creating the Amazon Chime SDK media capture pipeline
](create-capture-pipe.md)
+ [
# Working with Amazon Chime SDK media capture artifacts
](artifacts.md)
+ [
# Configuring the audio folder for Amazon Chime SDK media capture pipelines
](configure-audio.md)
+ [
# Configuring the video folder for Amazon Chime SDK media capture pipelines
](configure-video.md)
+ [
# Understanding messages in the data-channel folder for Amazon Chime SDK media capture pipelines
](data-channel.md)
+ [
# Understanding the Amazon S3 bucket folder structure for Amazon Chime SDK media capture pipelines
](capture-folder-structure.md)
+ [
# Understanding meeting event files for Amazon Chime SDK media capture pipelines
](meeting-events.md)
+ [
# Understanding transcription files for Amazon Chime SDK media capture pipelines
](transcription-messages.md)
+ [
# Concatenating data streams for Amazon Chime SDK media capture pipelines
](concatenate-streams.md)
# Creating an Amazon S3 bucket for Amazon Chime SDK media capture pipelines
You can use the Amazon S3 console the AWS SDKs, or the AWS CLI to to create an Amazon S3 bucket. For more information, refer to [Creating a bucket](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html), in the *Amazon Simple Storage Service (S3) User Guide*.
The Amazon S3 bucket for your media capture pipeline must belong to the same AWS account as the Amazon Chime SDK meeting. In addition, you must give the `s3:PutObject` and `s3:PutObjectAcl` permission to the Amazon Chime SDK service principal [mediapipelines.chime.amazonaws.com](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html). You can do that with the Amazon S3 console or the AWS Command Line Interface (AWS CLI). The Amazon S3 bucket must belong to one of the available [Amazon Chime SDK media Regions](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html).
**Note**
Make sure to add a policy to your IAM user to grant access to your bucket. Also, if you use a Region that AWS disables by default, you must have an Amazon S3 bucket in that Region.
By default, AWS disables the following Regions, and you can't host meeting resources in them until you enable them:
Africa (Cape Town)
Asia Pacific (Hong Kong)
Asia Pacific (Jakarta)
Europe (Milan)
Middle East (Bahrain)
If you use one of those Regions, it must have an Amazon S3 bucket. This applies even if you use the Amazon S3 APIs to communicate with Regions that aren't blocked by default and already have a bucket. For more information about enabling blocked regions, refer to [Managing AWS Regions](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) in the *AWS General Reference*.
Once you create a bucket, record its ARN. You use it to create a media capture pipeline.
The following example shows an Amazon S3 bucket policy.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Id": "AWSChimeMediaCaptureBucketPolicy",
"Statement": [
{
"Sid": "AWSChimeMediaCaptureBucketPolicy",
"Effect": "Allow",
"Principal": {
"Service": "mediapipelines.chime.amazonaws.com"
},
"Action": [ "s3:PutObject", "s3:PutObjectAcl" ],
"Resource": "arn:aws:s3:::Bucket_Name/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "123456789012"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:chime:*:123456789012:*"
}
}
}
]
}
```
------
# Enabling server-side encryption for an Amazon S3 bucket for Amazon Chime SDK media capture pipelines
To enable server-side encryption for an Amazon Simple Storage Service (Amazon S3) bucket, you can use these types of encryption keys:
+ An Amazon S3 managed key
+ A customer managed key in the AWS Key Management Service (KMS)
**Note**
The Key Management Service supports two types of keys, customer managed keys and AWS managed keys. Amazon Chime SDK meetings only support customer managed keys.
## Using an Amazon S3 managed key
You use the Amazon S3 console, CLI, or REST API to enable server-side encryption for an Amazon S3 bucket. In both cases, choose **Amazon S3 Key** as encryption key type. No further action is needed. When you use the bucket for media capture, the artifacts are uploaded and encrypted on server-side. For more information, refer to [ Specifying Amazon S3 encryption](https://docs.aws.amazon.com/AmazonS3/latest/userguide/specifying-s3-encryption.html) in the *Amazon S3 User Guide*.
## Using a key that you own
To enable encryption with a key that you manage, you need to enable the Amazon S3 bucket’s server-side encryption with a Customer Managed Key, then add a statement to the key policy that allows Amazon Chime to use the key and encrypt any uploaded artifacts.
1. Create a Customer Managed Key in KMS. For information about doing so, see [Specifying server-side encryption with AWS KMS (SSE-KMS)](https://docs.aws.amazon.com/AmazonS3/latest/userguide/specifying-kms-encryption.html) in the *Amazon S3 User Guide*.
1. Add a statement to the key policy that allows the `GenerateDataKey` action to generate a key for use by the Amazon Chime SDK service principal, `mediapipelines.chime.amazonaws.com`.
This example shows a typical statement.
```
...
{
"Sid": "MediaPipelineSSEKMS",
"Effect": "Allow",
"Principal": {
"Service": "mediapipelines.chime.amazonaws.com"
},
"Action": "kms:GenerateDataKey",
"Resource": "*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": "Account_Id"
},
"ArnLike": {
"aws:SourceArn": "arn:aws:chime:*:Account_Id:*"
}
}
}
...
```
1. If you use a media concatenation pipeline, add a statement to the key policy that allows the Amazon Chime SDK service principal, `mediapipelines.chime.amazonaws.com`, to use the `kms:Decrypt` action.
1. Configure the Amazon S3 bucket to enable server-side encryption with the key.
# Enabling object level server-side encryption with AWS KMS key
Media Capture Pipeline and Media Concatenation Pipeline can use AWS Key Management Service (AWS KMS) customer managed keys to enable server-side encryption (SSE) for individual objects in an Amazon S3 bucket. To configure this, you must use the [CreateMediaCapturePipeline](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaCapturePipeline.html) API call. The Media Concatenation Pipeline will use the server-side encryption parameters from the associated Media Capture Pipeline.
To enable SSE for individual objects (object-level SSE) using your AWS KMS customer managed key, you must provide the `SseAwsKeyManagementParams` structure and the `SinkIamRoleArn` during the [CreateMediaCapturePipeline](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaCapturePipeline.html) API call:
1. Use the `AwsKmsKeyId` parameter in the `SseAwsKeyManagementParams` structure to specify the AWS KMS key. You can specify the key ID using the key's ID, ARN, or alias.
1. Use the `SinkIamRoleArn` parameter to specify the IAM role to access the AWS KMS key and the sink Amazon S3 bucket.
1. Optionally, you can use the `AwsKmsEncryptionContext` parameter in the `SseAwsKeyManagementParams` structure to specify the encryption context to be used along with AWS KMS key artifacts for enhanced security.
**Note**
The `AwsKmsKeyId` and `SinkIamRoleArn` parameters are co-dependent. When both are present and valid, the Media Capture Pipeline will assume the role and place each artifact into the specified Amazon S3 bucket-sink with the specified AWS KMS key. The [CreateMediaConcatenationPipeline](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html) API call doesn’t have new parameters but will use the aforementioned parameters if specified. If you plan on concatenating artifacts, ensure your resources configuration is set as described in the following [Configuration](#using-kms-keys-for-encryption-config) section, and are persistent over time.
## Configuration
The `SinkIamRoleArn` must have the same permissions and access as the principal to put artifacts into the Amazon S3 bucket. For more information about the expected default permissions in the Amazon S3 bucket, see [Creating an Amazon S3 bucket for Amazon Chime SDK Media Capture Pipelines](https://docs.aws.amazon.com/chime-sdk/latest/dg/create-s3-bucket.html). To enable SSE for individual objects, your Amazon S3 bucket must allow the IAM role specified using the `SinkIamRoleArn` to perform the same set of actions you would expect from the calling IAM identity. You can achieve this by adding the following principal to your Amazon S3 bucket permission policy.
```
...
"Principal": {
...
"AWS": "arn:aws:iam::;:role/"
...
},
...
```
The `AwsKmsKeyId` should point to a key that permits the `SinkIamRoleArn` to perform `GenerateDataKey`. If Media Concatenation Pipeline is going to be used, the AWS KMS key should also permit the use of the `Decrypt` action. See the following example.
**Note**
The resource is set to use wildcard `“*”`, which in this context of a AWS KMS key policy signifies “itself”.
```
{
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam:::role/"
},
"Action": [
"kms:GenerateDataKey",
"kms:Decrypt"
],
"Resource": "*"
}
```
The `SinkIamRoleArn` role must have a trust relationship allowing the service to assume it. See the following example.
```
{
"Effect": "Allow",
"Principal": {
"Service": "mediapipelines.chime.amazonaws.com"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"aws:SourceAccount": ""
},
"ArnLike": {
"aws:SourceArn": "arn:aws:chime:*::*"
}
}
}
```
The `SinkIamRoleArn` should have the following minimum permissions policy for Media Capture Pipeline. See the following example.
```
{
"Effect": "Allow",
"Action": "kms:GenerateDataKey",
"Resource": "arn:aws:kms:::key/",
"Condition": {
"StringEquals": {
"aws:SourceAccount": ""
},
"ArnLike": {
"aws:SourceArn": "arn:aws:chime:*::*"
}
}
},
{
"Effect": "Allow",
"Action": ["s3:PutObject", "s3:PutObjectAcl"],
"Resource": "arn:aws:s3:::/*",
"Condition": {
"StringEquals": {
"aws:SourceAccount": ""
},
"ArnLike": {
"aws:SourceArn": "arn:aws:chime:*::*"
}
}
}
```
Additionally, the caller must be allowed to pass `SinkIamRoleArn` to the service. In cases when the caller doesn’t have such permission it should be added explicitly. See the following example.
```
{
"Effect": "Allow",
"Action": "iam:PassRole",
"Resource": "",
"Condition": {
"ArnLike": {
"iam:AssociatedResourceArn": "arn:aws:chime:*::media-pipeline/*"
},
"StringEquals": {
"iam:PassedToService": "mediapipelines.chime.amazonaws.com"
}
}
}
```
## Media concatenation implementation
If you plan on using Media Concatenation Pipeline after Media Capture, see [Building an Amazon Chime SDK media concatenation pipeline](create-concat-pipe-steps.md) to understand the required permissions. To make the pipeline work with the AWS KMS key for object-level SSE, the `SinkIamRoleArn` permissions (allowed actions) must be expanded for the AWS KMS key and Amazon S3 bucket. See the following example.
```
...
{
...
{
...
"Action": ["kms:GenerateDataKey","kms:Decrypt"]
"Resource": "arn:aws:kms:::key/",
...
}
...
{
"Action": [ "s3:PutObject", "s3:PutObjectAcl", "s3:GetObject", "s3:ListBucket"],
"Resource": "arn:aws:s3:::/*",
}
...
}
...
```
# Creating the Amazon Chime SDK media capture pipeline
After you create and configure your Amazon S3 bucket or buckets, you create a media capture pipeline.
**To create a media capture pipeline**
+ Call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaCapturePipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaCapturePipeline.html) API.
Use the bucket ARN as the `SinkArn` parameter.
Once successful, the Amazon Chime SDK creates an attendee that joins and captures the meeting.
After you create a media capture pipeline and set its permissions, you create a media concatenation pipeline to concatenate the 5-second media chunks into a single file. For more information, refer to [Creating media concatenation pipelines for Amazon Chime SDK meetings](create-concat-pipe.md), later in this section.
# Working with Amazon Chime SDK media capture artifacts
During an Amazon Chime SDK meeting, a media capture pipeline creates the following types of artifacts.
+ Audio
+ Video
+ Data channel messages
+ Meeting events
+ Transcription messages
The pipeline creates the artifacts in a set of folders in your Amazon S3 bucket, and you can configure the audio and video folders to limit certain types of artifacts. The following sections explain the folder structure, how to configure folders, how to set permissions for your Amazon S3 bucket, and how to concatenate the artifact files.
# Configuring the audio folder for Amazon Chime SDK media capture pipelines
The audio folder contains 5-second MP4 files of the mixed audio stream, meaning they contain audio from all attendees, plus the active speaker’s video. The folder contains files for the entire meeting. As desired, you can configure the folder to contain just the audio artifacts. Each file name contains a *yyyy-mm-dd-hour-min-seconds-milleseconds* timestamp. The timestamp is in UTC, and it marks the start time. You can configure the folder to only contain audio artifacts.
```
"ArtifactsConfiguration": {
"Audio": {
"MuxType": "AudioOnly"
},
"Content": {
"State": "Disabled"
},
"Video": {
"State": "Disabled"
}
}
```
# Configuring the video folder for Amazon Chime SDK media capture pipelines
The video folder contains 5-second MP4 files that contain video streams, plus content share streams if they’re specified in the API request. Each file name contain a - timestamp with an attendee ID. The content share video chunk is appended as -\$1content.mp4. You can configure the folder to only contain video artifacts.
```
"ArtifactsConfiguration": {
"Audio": {
"MuxType": "AudioOnly"
},
"Content": {
"State": "Disabled"
},
"Video": {
"MuxType": "VideoOnly"
"State": "Enabled"
}
}
```
# Understanding messages in the data-channel folder for Amazon Chime SDK media capture pipelines
The data-channel folder contains data messages in the .txt format, and each message is a JSON object. Messages are visible with all configurations options. File names contain the *yyyy-mm-dd-hour-min-seconds-milleseconds* timestamp. This example shows the data fields in a message.
```
{
"Timestamp": "string",
"Topic": "string",
"Data": "string",
"SenderAttendeeId": "string"
}
```
# Understanding the Amazon S3 bucket folder structure for Amazon Chime SDK media capture pipelines
The Amazon S3 buckets for media capture pipelines use this folder structure.
```
S3 bucket path/
audio
video
data-channel
meeting-events
transcription-messages
```
# Understanding meeting event files for Amazon Chime SDK media capture pipelines
The meeting-events folder contains meeting events in the .txt format, and each event is a JSON object. Messages are visible with all configurations options. File names contain the timestamp. This example shows the fields and data in a typical event file.
```
{
"Timestamp": "string",
"EventType": "AttendeeJoined | AttendeeLeft | AttendeeVideoJoined | AttendeeVideoLeft | ActiveSpeaker | CaptureStarted | CaptureEnded | AudioTrackMute | AudioTrackUnmute",
"EventParameters": {
# ...
}
}
```
# Understanding transcription files for Amazon Chime SDK media capture pipelines
The transcription-messages folder contains transcription files in the .txt format. However, the folder only receives files when you enable live transcription. For more information about enabling live transcription, see [Using Amazon Chime SDK live transcription](meeting-transcription.md).
The folder includes all partial and complete transcription messages, and each message is a JSON object. File names contain the timestamp. You can see transcription file examples at [Processing a received Amazon Chime SDK live transcript event](delivery-examples.md).
# Concatenating data streams for Amazon Chime SDK media capture pipelines
**Note**
To automate the process of concatenating media capture artifacts, refer to [Creating media concatenation pipelines for Amazon Chime SDK meetings](create-concat-pipe.md) in this guide.
This example uses ffmpeg to concatenate video or audio files into a single mp4 file. First, create a filelist.txt file that contains all the input files. Use this format:
```
file 'input1.mp4'
file 'input2.mp4'
file 'input3.mp4'
```
Next, use this command to concatenate the input file:
```
ffmpeg -f concat -i filelist.txt -c copy output.mp4
```
For more information about media concatenation pipelines, refer to [Creating media concatenation pipelines for Amazon Chime SDK meetings](create-concat-pipe.md) in this guide.