# Using Amazon Chime SDK meetings
<a name="mtgs-sdk-mtgs"></a>

The topics in this section explain how to use Amazon Chime SDK meetings to create custom meeting applications. We recommend following these topics in the order listed. 

**Topics**
+ [Migrating to the Amazon Chime SDK meetings namespace](meeting-namespace-migration.md)
+ [Using meeting Regions for Amazon Chime SDK meetings](chime-sdk-meetings-regions.md)
+ [Creating meetings using the Amazon Chime SDK](create-mtgs.md)
+ [Selecting meeting features using the Amazon Chime SDK](js-meeting-features.md)
+ [How Amazon Chime SDK meetings use WebRTC media](webrtc-media.md)
+ [Configuring video codecs for Amazon Chime SDK meetings](js-meeting-manage-codecs.md)
+ [Configuring your network for Amazon Chime SDK meetings](network-config.md)
+ [Understanding Amazon Chime SDK meeting lifecycle events](using-events.md)
+ [Understanding Amazon CloudWatch metrics for Amazon Chime SDK meetings](sdk-usage-metrics.md)
+ [Creating Amazon Chime SDK media pipelines](media-pipelines.md)
+ [Using Amazon Chime SDK live transcription](meeting-transcription.md)
+ [Using media replication for Amazon Chime SDK meetings](media-replication.md)
+ [Troubleshooting and debugging Amazon Chime SDK meetings](troubleshoot-sdk-meetings.md)

# Migrating to the Amazon Chime SDK meetings namespace
<a name="meeting-namespace-migration"></a>

The [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace is a dedicated place for the APIs that create and manage Amazon Chime SDK meeting resources. You use the namespace to address Amazon Chime SDK meeting API endpoints in any AWS Region in which they're available. Use this namespace if you're just starting to use the Amazon Chime SDK. For more information about Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md) in this guide.

Existing applications that use the [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) namespace should plan to migrate to the dedicated namespace in order to use the latest APIs and features.

**Topics**
+ [Reasons to migrate](#migration-reasons)
+ [Before you migrate](#before-migrating)
+ [Differences between the namespaces](#namespace-differences)

## Reasons to migrate
<a name="migration-reasons"></a>

We encourage you to migrate to the [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace for these reasons:

**Choice of API Endpoint**  
The Amazon Chime SDK Meetings namespace is the only API namespace which can use API endpoints in any [region that makes them available](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html). If you want to use API endpoints other than `us-east-1`, you must use the Amazon Chime SDK Meetings namespace.  
For more information about how Amazon Chime SDK meetings use AWS Regions, refer to [Meeting Regions](https://docs.aws.amazon.com/chime-sdk/latest/dg/chime-sdk-meetings-regions.html) in this guide.

**Updated and new meeting APIs**  
We only add or update meeting APIs in the Amazon Chime SDK Meetings namespace.

## Before you migrate
<a name="before-migrating"></a>

Before you migrate, be aware of the differences between the namespaces. The following table lists and describes them.


|  | Amazon Chime SDK Meetings namespace | Amazon Chime namespace | 
| --- | --- | --- | 
| AWS SDK namespace | ChimeSDKMeetings | Chime | 
| Regions | Multiple | us-east-1 only | 
| Endpoints | https://meetings-chime.region.amazonaws.com | https://service.chime.aws.amazon.com | 
| Service principal | meetings.chime.amazonaws.com | chime.amazonaws.com | 
| APIs | Only APIs for meetings | APIs for meetings and other parts of Amazon Chime | 
| [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html) | ExternalMeetingId and MediaRegion are required. | ExternalMeetingId and MediaRegion are optional. | 
| [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeetingWithAttendees.html) | ExternalMeetingId and MediaRegion are required.  | ExternalMeetingId and MediaRegion are optional. | 
| ListMeetings | Not available | Available | 
| ExternalMeetingId | Validation includes pattern matching | Available | 
| ExternalUserId | Validation includes pattern matching  | Available | 
| Meeting Tags APIs | TagResource, UntagResource, ListTagsForResource | TagMeeting, UntagMeeting, ListMeetingTags | 
| Attendee Tags | Not available | Available | 
| Echo reduction | Available | Not available | 
| Live transcription language identification | Available | Not available | 
| Attendee capabilities | Available | Not available | 
| Media replication | Available | Not available | 
| AppKeys and TenantIds | Available | Not available | 
| Media pipelines | Media pipelines support multiple regions in the Amazon Chime SDK Meetings namespace. For more information, see [Migrating to the Amazon Chime SDK media pipelines namespace](migrate-pipelines.md). | Available via the us-east-1 endpoint | 
| SIP media application | JoinChimeMeeting action requires MeetingId | JoinChimeMeeting action does not require MeetingId | 
|  **Direct SIP integration**  | Not available | Available | 

## Differences between the namespaces
<a name="namespace-differences"></a>

The following sections explain the differences between the `Amazon Chime` and `Amazon Chime SDK Meetings` namespaces.

### AWS SDK namespace
<a name="namespace-diffs"></a>

The Amazon Chime SDK namespace uses the `Chime` formal name. The Amazon Chime SDK Meetings namespace uses the `ChimeSDKMeetings` formal name. The precise format of the name varies by platform.

For example, if you use the AWS SDK in Node.js to create meetings, you use a line of code to address the namespace.

```
const chimeMeetings = AWS.Chime();
```

To migrate to the Amazon Chime Meetings SDK, update this line of code with the new namespace and the endpoint region.

```
const chimeMeetings = AWS.ChimeSDKMeetings({ region: "eu-central-1" });
```

### Regions
<a name="region-diffs"></a>

The [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) namespace can only address API endpoints in the us-east-1 Region. The [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace can address Amazon Chime SDK meeting API endpoints in any Region they are available. For a current list of meeting Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md) in this guide.

### Endpoints
<a name="endpoint-diffs"></a>

The [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace uses different API endpoints than the [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) namespace.

Only the endpoint used to create a meeting can be used to modify it. This means a meeting created via an endpoint in EU-CENTRAL-1 can only be modified via EU-CENTRAL-1. It also means you cannot address a meeting created via the `Chime` namespace with the `ChimeSDKMeetings` namespace in `US-EAST-1`. For more information about the current endpoints, refer to [API mapping](migrate-from-chm-namespace.md#name-end-map) in this guide.

### Service principal
<a name="service-principal-diffs"></a>

The [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace uses a new service principal: `meetings.chime.amazonaws.com`. If you have SQS, SNS, or other IAM access policies that grant access to the service, you need to update those polices to grant access to the new service principal.

### APIs
<a name="api-diffs"></a>

The [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace only contains APIs for creating and managing meetings. The [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) namespace includes APIs for meetings and other parts of the Amazon Chime service.

### CreateMeeting required fields
<a name="create-meeting-diffs"></a>

In the Amazon Chime SDK Meetings namespace, the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) and [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html) APIs require the `ExternalMeetingId` and `MediaRegion` fields to be specified.

### External ID values
<a name="external-id-diffs"></a>

The [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace enforces addition validation on the values that can be used for `ExternalMeetingId` and `ExternalUserId`.

### Echo reduction
<a name="echo-reduction-diffs"></a>

[Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace offers machine learning-based echo reduction to help remove noise and sound from the local loudspeaker from circulating back into the meeting. Refer to the guide on GitHub for more information.

### Attendee capabilities
<a name="capabilities-diffs"></a>

[Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace provides granular control over an attendees capabilities within a meeting to send and receive audio, video and content.

### Media replication
<a name="media-replication-diffs"></a>

[Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace offers media replication to link a primary meeting to replica meetings to bring together up to 10,000 people for a real-time session. Participants connected to a replica session receive the media of the presenters connected to the primary session, but they can be promoted to the primary meeting. For more information, refer to [Using media replication for Amazon Chime SDK meetings](media-replication.md) in this guide.

### AppKeys and TenantIds
<a name="app-keys-diffs"></a>

[Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace provides a way to limit access from a network to specific Amazon Chime SDK meetings. For more information, refer to [Using AppKeys and TenantIDs for Amazon Chime SDK](app-keys-tenant-ids.md) in this guide.

### Media pipelines
<a name="media-pipe-diffs"></a>

Amazon Chime SDK media pipelines work with meetings created by any meetings endpoint, with either the [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) or the [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) namespace. Refer to [Available regions](https://docs.aws.amazon.com/chime-sdk/latest/dg/sdk-available-regions.html) for the latest list of media pipeline regions.

### SIP media applications
<a name="sip-app-diffs"></a>

Amazon Chime SDK SIP media applications work with meetings created by any meetings endpoint, with either the [Amazon Chime SDK Meetings](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) or the [Amazon Chime](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime.html) namespace. When using SIP media applications with a meeting created through the Amazon Chime SDK Meetings namespace, the [JoinChimeMeeting](join-chime-meeting.md) action requires the `MeetingId` parameter.

### Additional APIs
<a name="additional-api-diffs"></a>

The Meetings namespace has a growing list of APIs that the Chime namespace does not have. If you are getting started with the Amazon Chime SDK, use the Meetings namespace to access the latest features. 

# Using meeting Regions for Amazon Chime SDK meetings
<a name="chime-sdk-meetings-regions"></a>

Amazon Chime SDK meetings have *control* Regions and *media* Regions. Control Regions have an API endpoint used to create, update, and delete meetings. Media Regions host the actual meetings.

Typically, your application service uses the [AWS SDK](https://aws.amazon.com/tools/) to [sign and call](https://docs.aws.amazon.com/general/latest/gr/signature-version-4.html) APIs in control Regions. Your application client uses the Amazon Chime SDK client libraries for [JavaScript](js-sdk-intro.md), [iOS](sdk-for-ios.md), or [Android](sdk-for-android.md) to connect to the meeting in media Regions.

A control region can create a meeting in any media Region in the same AWS partition. However, you can only update a meeting in the control region used to create it. To find the media Region closest to a customer, call [https://nearest-media-region.l.chime.aws](https://nearest-media-region.l.chime.aws).

Meeting [events](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html#sdk-events) such as `AttendeeJoined` call [EventBridge, Amazon Simple Queue Service (SQS), or Amazon Simple Notification Service (SNS)](https://docs.aws.amazon.com/chime-sdk/latest/dg/mtgs-sdk-notifications.html) in the meeting control Region.

 For a list of available Amazon Chime SDK meeting control and media Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md) in this guide.

This diagram shows the typical flow of data through the control and media Regions.

![\[Diagram showing the flow of data through the Amazon Chime SDK control and media Regions.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/control-media-regions.png)


## Choosing a control region
<a name="choose-meeting-region"></a>

Remember these factors when choosing a control Region for an Amazon Chime SDK meeting:
+ **Regulatory requirements**. Is your application required to be within a geopolitical border, or use an endpoint with FIPS 140-2 validated cryptographic modules?
+ **API latency**. Using the control Region nearest to the AWS Region of your application service can help reduce the APIs' network latency. In turn, that helps reduce the time needed to create meetings, and let users join meetings faster.
+ **High Availability**. You can use multiple control Regions to implement a high availability architectures. However each control Region operates independently. Also, you can only update meetings in the control Region used to create them. Further, you must use that same region to consume meeting events with [ EventBridge, Amazon Simple Queue Service (SQS), or Amazon Simple Notification Service (SNS)](https://docs.aws.amazon.com/chime-sdk/latest/dg/mtgs-sdk-notifications.html).

## Choosing a media region
<a name="choose-media-region"></a>

**Note**  
We recommend that you always specify a value in the `MediaRegion` parameter in the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html) API action. For more information about the Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md).

When choosing a media Region to use for your Amazon Chime SDK meeting, consider these common factors:

**Regulatory requirements**  
If your Amazon Chime SDK meetings are subject to regulations requiring them to be hosted within a geopolitical border, consider hard coding the meeting Region based on fixed application logic.  
For example, a telemedicine application might require all meetings to be hosted within the medical practitioner's jurisdiction. If the application supports clinics located in both Europe and the United States, you can use each clinic's address to select a Region within its jurisdiction. 

**Meeting quality**  
When an Amazon Chime SDK meeting is hosted in a media Region, each attendee's audio and video is sent and received from that Region. As the distance between the attendee and the Region increases, meeting quality can be affected by network latency. Specifying a Region for your Amazon Chime SDK meeting can help enhance the meeting quality for your attendees, whether they are located near each other or distributed geographically.

You can use one of the following methods to choose a media Region for your Amazon Chime SDK meeting:

**Hard code a media Region**  
Recommended if your Amazon Chime SDK meetings are all hosted within a specific AWS Region.

**Choose the nearest media Region**  
Recommended if your Amazon Chime SDK meeting attendees are located in the same AWS Region, but your meetings are hosted in different Regions.

## Finding the nearest media Region
<a name="choose-nearest-media-region"></a>

To find the nearest media Region capable of hosting an Amazon Chime SDK meeting, call [https://nearest-media-region.l.chime.aws](https://nearest-media-region.l.chime.aws). This endpoint returns a single Region, such as `{"region": "us-west-2"}`. Call the URL from your client application to identify the Region closest to the user, and then use the result in the `MediaRegion` parameter of the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) API to create the meeting in that Region.

You usually call the URL when the client application starts, or its network connection changes. By predetermining the nearest Region, you avoid adding the call’s latency at the time of meeting creation.

## Finding the nearest AWS GovCloud (US) media Region
<a name="choose-gov-cloud-region"></a>

To find the nearest AWS GovCloud (US) Region that can host an Amazon Chime SDK meeting, call [https://nearest-us-gov-media-region.l.chime.aws](https://nearest-us-gov-media-region.l.chime.aws). This endpoint returns the nearest region, such as `{"region": "us-gov-west-1"}`. Call the URL from your client application to identify the AWS GovCloud (US) closest to the user, and use the result in the `MediaRegion` parameter of the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) API to create the meeting in that Region.

You usually call the URL when the client application starts, or its network connection changes. By predetermining the nearest Region, you avoid adding the call’s latency at the time of meeting creation.

## JavaScript example
<a name="region-javascript"></a>

The following example uses HTML and JavaScript to return the nearest media Region and AWS GovCloud (US) media Region.

```
<html>
<head>
  <title>Amazon Chime SDK - Nearest Media Region</title>
  <script>

async function getNearestMediaRegion(partition)  {

    console.log('Nearest media region partition: ' + partition);

    const url = ('aws-us-gov' == partition) ? 'https://nearest-us-gov-media-region.l.chime.aws' : 'https://nearest-media-region.l.chime.aws';
    let result = ('aws-us-gov' == partition) ? 'us-gov-west-1' : 'us-west-2';

    try { //Find the nearest media region
        console.log('Nearest media region URL: ' + url);
        const response = await fetch(url, {method: 'GET'} );
        const body = await response.json();
        result = body.region;
    } catch (error) {
        console.log(error.message);
    } finally {
        console.log('Nearest media region found: ' + result);
        return result;
    }
}

async function findRegions(partition) {
  aws.innerText = await getNearestMediaRegion();
  awsusgov.innerText = await getNearestMediaRegion('aws-us-gov');
}
  </script>
</head>
<body>
  <h3>Nearest media region, by AWS partition</h3>
  <table>
    <tr><th>Partition</th><th>Media Region</th></tr>
    <tr><td>aws</td><td id="aws">Finding...</td></tr>
    <tr><td>aws-us-gov</td><td id="awsusgov">Finding...</td></tr>
  </table>
  <script>
    findRegions();
  </script>
</body>
</html>
```

## Checking Region status
<a name="region-status"></a>

Call [https://region.status.chime.aws/](https://region.status.chime.aws/) to retrieve the health of the Amazon Chime SDK service in each Region. The result shows the recommended Regions. If a media Region has a status other than **recommended**, the nearest media Region endpoint will not return that Region.

The following example shows a typical result.

```
{
  "MeetingsControlRegions": {
    "us-east-1": "recommended",
    "us-west-2": "recommended",
    "eu-central-1": "recommended",
    "eu-west-2": "recommended",
    "ap-south-1": "recommended",
    "ap-southeast-1": "recommended",
    "ap-southeast-2": "recommended",
    "ap-northeast-1": "recommended",
    "ap-northeast-2": "recommended",
    "il-central-1": "recommended",
    "ca-central-1": "recommended",
    "af-south-1": "recommended"
  },
  "MeetingsMediaRegions": {
    "af-south-1": "recommended",
    "ap-northeast-1": "recommended",
    "ap-northeast-2": "recommended",
    "ap-south-1": "recommended",
    "ap-southeast-1": "recommended",
    "ap-southeast-2": "recommended",
    "ca-central-1": "recommended",
    "eu-central-1": "recommended",
    "eu-north-1": "recommended",
    "eu-south-1": "recommended",
    "eu-west-1": "recommended",
    "eu-west-2": "recommended",
    "eu-west-3": "recommended",
    "sa-east-1": "recommended",
    "us-east-1": "recommended",
    "us-west-2": "recommended",
    "us-east-2": "recommended",
    "us-west-1": "recommended",
    "il-central-1": "recommended"
  },
  "MediaPipelineControlRegions": {
    "us-east-1": "recommended",
    "us-west-2": "recommended",
    "eu-central-1": "recommended",
    "eu-west-2": "recommended",
    "ap-south-1": "recommended",
    "ap-southeast-1": "recommended",
    "ap-southeast-2": "recommended",
    "ap-northeast-1": "recommended",
    "ap-northeast-2": "recommended",
    "ca-central-1": "recommended"
  },
  "MediaPipelineDataRegions": {
    "af-south-1": "recommended",
    "ap-northeast-1": "recommended",
    "ap-northeast-2": "recommended",
    "ap-south-1": "recommended",
    "ap-southeast-1": "recommended",
    "ap-southeast-2": "recommended",
    "ca-central-1": "recommended",
    "eu-central-1": "recommended",
    "eu-north-1": "recommended",
    "eu-south-1": "recommended",
    "eu-west-1": "recommended",
    "eu-west-2": "recommended",
    "eu-west-3": "recommended",
    "sa-east-1": "recommended",
    "us-east-1": "recommended",
    "us-west-2": "recommended",
    "us-east-2": "recommended",
    "us-west-1": "recommended"
  }
}
```

# Creating meetings using the Amazon Chime SDK
<a name="create-mtgs"></a>

The following procedure demonstrates how to create a meeting with audio and video for your server and client applications. Before you begin, you must integrate your client application with an Amazon Chime SDK client library. For more information, refer to [Learn about the Amazon Chime SDK client libraries](mtgs-sdk-client-lib.md).

**To create a meeting with audio and video**

1. Complete the following steps from your server application:

   1. Use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html) API action in the *Amazon Chime SDK API Reference* to create a meeting. Specify an AWS Region using the `MediaRegion` parameter. For more information about choosing a meeting Region, refer to [Meeting Regions](sdk-available-regions.md#sdk-meeting-regions).

   1. Add attendees to the meeting using the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html) API action or the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html) API action. Securely transfer the meeting and attendee from your server application to the client authorized as the respective attendee. For more information about meetings and attendees, refer to [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Meeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Meeting.html) and [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Attendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Attendee.html) in the *Amazon Chime SDK API Reference*.

1. Complete the following steps from your client application:

   1. Use an Amazon Chime SDK client library to construct a `MeetingSessionConfiguration` object. Use the meeting and attendee information from the previous steps.

   1. Implement the `AudioVideoObserver` interface.

   1. Create a `MeetingSession` using the `MeetingSessionConfiguration`.

   1. Use the `AudioVideoFacade` from the `MeetingSession` to control real-time media.

      1. Register an instance of the `AudioVideoObserver` interface. This lets you receive events when the meeting state changes.

      1. Select initial devices for the audio input, audio output, and video input.

      1. Start the audiovisual session.

      1. Start local video capture when the user wants to share video.

      1. To show video tiles, manage video tile events, and bind the tiles to video surfaces in the client application.

      1. Manage other user interactions such as muting and unmuting, or starting and stopping local video capture.

      1. To leave the meeting, stop the audiovisual session.

   1. (Optional) Use the `AudioVideoFacade` from the `MeetingSession` to share media content, such as screen captures, with other clients.

      1. Start the screen share session. The content joins the meeting as an additional attendee.

      1. To view the shared content, manage video tile events and bind the tiles to surfaces in the client application.

      1. Manage other interactions, such as pausing, restarting, or stopping the content share.

Meetings end when you run the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteMeeting.html) API action. Also, meetings end automatically when:
+ The meeting time exceeds 24 hours.
+ The meeting is a [replica meeting](media-replication.md) and the primary meeting ends.
+ In a non-replica meeting, no attendees connected for five continuous minutes.

# Selecting meeting features using the Amazon Chime SDK
<a name="js-meeting-features"></a>

When you call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) API, you can specify features to make available to the clients that join the session. Note that some feature options incur additional billing.

The following features are available for sessions:
+ `Audio.EchoReduction` – Machine learning echo reduction.
+ `Video.MaxResolution` – Maximum webcam video resolution.
+ `Content.MaxResolution` – Maximum content sharing resolution..
+ `Attendees.MaxCount` – Mmaximum number of attendees.

**Topics**
+ [Using Audio.EchoReduction](#audio-echo-reduction)
+ [Using Video.MaxResolution](#video-max-resolution)
+ [Using Content.MaxResolution](#js-content-resolution)
+ [Using Attendees.MaxCount](#js-max-attendees)
+ [Using meeting features in a client app](#meeting-features-client-app)

## Using Audio.EchoReduction
<a name="audio-echo-reduction"></a>

Use `Audio.EchoReduction` to help keep sound from a user’s loudspeaker from circulating back into meeting.

Echo reduction is ideal for situations in which a user's loudspeaker will be the primary output device for meeting audio. For example, when multiple users are attending a meeting from the same device in a conference room, or when an individual remote attendee is not wearing headphones.

Echo reduction is available in the JavaScript and React client libraries. For more information, refer to the [documentation on GitHub](https://aws.github.io/amazon-chime-sdk-js/modules/amazonvoice_focus.html#what-is-echo-reduction). Additional costs apply, refer to the [Amazon Chime SDK Pricing page](https://aws.amazon.com/chime/chime-sdk/pricing/) for details.

## Using Video.MaxResolution
<a name="video-max-resolution"></a>

Use `Video.MaxResolution` to specify the maximum webcam video resolution for the meeting. The feature provides the following options:
+ `None`: no camera video allowed
+ `HD`: high-definition camera video (1280x720p)
+ `FHD`: full-high-definition camera video (1920x1080)

If FHD (1080p) Video is requested, a high-definition WebRTC session is created. Refer to the [Amazon Chime SDK Pricing page](https://aws.amazon.com/chime/chime-sdk/pricing/) for details.

If a client attemps to send webcam video above a specified maximum, the service rejects the video and sends the following error:

`Disabled video/content send capability, reason: Video resolution is above limit of current meeting feature selection.`

## Using Content.MaxResolution
<a name="js-content-resolution"></a>

Use `Content.MaxResolution` to specify the maximum content share resolution for the meeting. The feature provides the following options: 
+ `None`: no content share allowed
+ `FHD`: full-high-definition content share (1920x1080)
+ `UHD`: ultra-high-definition content share (3840x2160)

If UHD (4K) content is requested, a high-definition WebRTC session is created.

If a client attems to send a content share beyond the maximum resolution, that resolution is scaled down to the specified maximum. You scale by applying `MediaTrackConstraints` to the content share track. The following examples shows how to scale a share track.

```
const constraint: MediaTrackConstraints = {
    width: { ideal: videoQualitySettings.videoWidth },
    height: { ideal: videoQualitySettings.videoHeight },
    frameRate: { ideal: videoQualitySettings.videoFrameRate },
  };
  this.context.logger.info(
    `Video track (content = ${isContentAttendee}) with constraint: ${JSON.stringify(
      constraint
    )}, trackSettings: ${JSON.stringify(trackSettings)}`
  );
  try {
    await mediaStreamTrack.applyConstraints(constraint);
  } catch (error) {
    this.context.logger.info(
      `Could not apply constraint for video track (content = ${isContentAttendee})`
    );
  }
```

The following table shows the expected behavior for content sharing.


| Content feature | Content share native resolution | Scaling | Content coding resolution | 
| --- | --- | --- | --- | 
|  FHD | 1280x720  | No | 1280x720 | 
| FHD | 1920x1080 | No | 1920x1080 | 
| FHD | 3840x2160 | Yes | 1920x1080 | 
| UHD | 1920x1080 | No | 1920x1080 | 
| UHD | 3840x2160 | No | 3840x2160 | 
| UHD | 4200x2400 | Yes | 3780x2160 | 

## Using Attendees.MaxCount
<a name="js-max-attendees"></a>

Use `Attendee.MaxCount` to specify the maximum number of attendees allowed into a meeting. The upper limit of Attendee.MaxCount depends on the session type. For a standard session, you can select a maximum of 250 attendees. For a high-definition session, you *must* select a value of up to 25 attendees. 

If you request FHD (1080p) video or UHD (4K) content, your session will be a high-definition session.

Attendee capacity costs apply for high-definition sessions. Refer to the [Amazon Chime SDK Pricing page](https://aws.amazon.com/chime/chime-sdk/pricing/) for details.

## Using meeting features in a client app
<a name="meeting-features-client-app"></a>



### Creating a meeting with specified features
<a name="js-create-meetings-sdk-namespace"></a>

To create a meeting, call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) API and specify the desired meeting features. The following example shows how to specify all the features.

```
// You must migrate to the Amazon Chime SDK Meetings namespace.
const chime = AWS.ChimeSDKMeetings({ region: "eu-central-1" });

// Create meeting 
const meetingInfo = await chime.createMeeting({
    ...
    MeetingFeatures: {
      Audio: {
        EchoReduction: 'AVAILABLE' 
      },
      Video: {
        MaxResolution: 'FHD' 
      },
      Content: {
        MaxResolution: 'UHD' 
      },
      Attendee: {
        MaxCount: 25 
      },
    } 
  }).promise();
```

### Using meeting features in a client
<a name="js-client-level"></a>

After you create a meeting with the desired features, you can pass in the `joinInfo` when you create the `MeetingSessionConfiguration` object. The meeting features are used at `meetingSession` creation to set webcam video resolution and bitrate, and the content share resolution and bitrate.

```
const configuration = new MeetingSessionConfiguration(this.joinInfo.Meeting, this.joinInfo.Attendee);

this.meetingSession = new DefaultMeetingSession(
    configuration,
    this.meetingLogger,
    this.deviceController,
    new DefaultEventController(configuration, this.meetingLogger, this.eventReporter)
);
```

# How Amazon Chime SDK meetings use WebRTC media
<a name="webrtc-media"></a>

The Amazon Chime SDK supports two types of WebRTC sessions, standard and high-definition. The following topics describe the media available in each type of session when using the Amazon Chime SDK client libraries for JavaScript, React, iOS, and Android.

**Topics**
+ [Audio](#webrtc-audio)
+ [Video](#video)
+ [Content share](#content-share)
+ [Data messages](#data-messages)

## Audio
<a name="webrtc-audio"></a>

Each Amazon Chime client sends one audio stream to the sessions and receives one audio stream from the session. Typically, microphones on local devices generate the audio. The audio received is a mix of the audio sent from the other session clients.

Both session types support sample rates up to 48kHz and up to 2 channels (stereo) encoded with bitrates up to 128kbps using the Opus codec. However, the audio streams sent and received vary by client library type:
+ The Amazon Chime SDK client libraries for JavaScript and React support sending and receiving mono and stereo audio at the highest sample rate supported by the device and browser, up to a maximum of 48kHz.
+ The Amazon Chime SDK client libraries for iOS and Android support sending mono audio up to 48kHz, and receiving stereo audio at 48kHz.

## Video
<a name="video"></a>

Each Amazon Chime client can send one video stream to the session and receive up to 25 video streams from the session. The video sent is typically sourced from the local device's webcam. Each client can select up to 25 video streams to receive, and change the selection at any time during the session. 

Standard sessions support video resolutions up to 1280x720 at 30 frames per second encoded with bitrates up to 1500kbps using H.264, VP8, VP9, and AV1.

High-definition sessions support video resolutions up to 1920x1080 at 30 frames per second encoded with bitrates up to 2500kbps using H.264, VP8, VP9, and AV1.

The Amazon Chime SDK client libraries for JavaScript and React support sending video in simulcast at 15 frames per second, or with scalable video coding (SVC). SVC encodes a single video stream with three spatial layers and three temporal layers at 100%, 50%, and 25% of your target values. The service automatically selects the layer to send to each viewer based on the viewers' available bandwidth.

The Amazon Chime SDK client libraries for iOS and Android support sending up to 15 frames per second. However, the actual frame rate and resolution is automatically managed by the Amazon Chime SDK.

Video encoding and decoding uses hardware acceleration where available to improve performance.

 If a client sends video with a bitrate greater than the maximum allowed bitrate, the session first starts sending the client Receiver Estimated Maximum Bitrate messages via the Real-Time Control Protocol. If the client continues to send video with a bitrate greater than the maximum allowed bitrate, the session discards the incoming video stream packets.

## Content share
<a name="content-share"></a>

Up to two clients can share content to the session. A content share can include a video track, an audio track, or both. A common example of a content share is screen share, which uses screen capture as the source of the content. Another example is sharing prerecorded content with video and audio tracks.

Content audio is mixed into the audio stream sent by the session. Content audio supports sample rates up to 48kHz and up to 2 channels (stereo) encoded with bitrates up to 128kbps using the Opus codec.

Video content is sent to the session and forwarded to clients in a separate video stream. Standard sessions support content video up to 1920x1080 at 30 frames per second. High-definition sessions support content video up to 3840 x 2160 at 30 frames per second.

Screen capture for content sharing uses the resolution of the screen or window being captured, up to the maximum content resolution for the session type, and up to 30 frames per second. However, device and browser capabilities may limit those values.

The Amazon Chime SDK client libraries for JavaScript and React support content share from screen capture and other sources.

The Amazon Chime SDK client libraries for iOS and Android only support content share from screen capture.

## Data messages
<a name="data-messages"></a>

Data messages provide a way for a client to broadcast information to other clients in the session. For example, an application may use data messages to share emoji reactions during a session.

Each data message includes:
+ A topic, a string of up to 64 characters.
+ Up to 2 KB of data, including the topic.

A client sends a data message to the session, and the session sends the data message to all connected clients.

The session can optionally cache the data message for up to five minutes. If a client joins or reconnects to a session, the session will automatically send the client any cached data messages that have not been previously sent. The session cache stores a maximum of 1024 data messages.

A session supports up to 100 sent data messages per second. When using [live transcription](https://docs.aws.amazon.com/chime-sdk/latest/dg/meeting-transcription.html), each client receives [transcription messages](https://docs.aws.amazon.com/chime-sdk/latest/dg/process-msgs.html) via data messages, which are counted towards the total sent messages per second.

# Configuring video codecs for Amazon Chime SDK meetings
<a name="js-meeting-manage-codecs"></a>

A client device uses a video codec to compress raw video before it is sent to the service, and to decompress received video before it's rendered.

When using the Amazon Chime SDK client library for JavaScript, you can specify your codec preferences for sending video. 

The Amazon Chime SDK client libraries for iOS and Android automatically select the codec for you, based on the device’s capabilities.

## Setting video codec preferences
<a name="codec-list"></a>

In the Amazon Chime SDK client library for JavaScript, you can specify independent video codec preferences for webcam and content video. 

Use the [ AudioVideoControllerFacade.setVideoCodecSendPreferences ](https://aws.github.io/amazon-chime-sdk-js/interfaces/audiovideocontrollerfacade.html#setvideocodecsendpreferences) function to set your codec preferences for sending webcam video. The link takes you to GitHub.

Your preferences are passed as an ordered array, with your most preferred codec first and your least preferred codec last. 

When providing multiple codec preferences, the service automatically selects the most preferred codec that all session attendees can decode.

The following example shows how to set a video codec preference for VP9 with a fallback option of VP8:

```
// A meeting session has already been created and stored in `this.meetingSession`
this.meetingSession.audioVideo.setVideoCodecSendPreferences(
	[
		VideoCodecCapability.vp9(), 
		VideoCodecCapability.vp8()
	]
);
```

The following scenarios apply to the preferences:
+ **Optimal ** – The client encodes video using the VP9 codec.
+ **Local Fallback** – If the client doesn't support VP9 encoding, it falls back to VP8 encoding. If the client does not support VP8 encoding, it falls back to any codec supported by the browser and the service.
+ **Remote Fallback** – If another client in the session does not have a VP9 decoder, this client falls back to VP8 encoding.
+ **Local Failure** – If the client does not support VP9 or VP8 encoding, it will not send video.

To set preferences for content sharing, use the [ ContentShareControllerFacade.setContentShareVideoCodecPreferences ](https://aws.github.io/amazon-chime-sdk-js/interfaces/contentsharecontrollerfacade.html#setcontentsharevideocodecpreferences) function to set your codec preferences for sending content video. This link takes you to GitHub.

 The following example sets a content video codec preference for VP9 with a fallback option of VP8.

```
// A meeting session has already been created and stored in `this.meetingSession`
    this.meetingSession.audioVideo.setContentShareVideoCodecPreferences(
	[
	VideoCodecCapability.vp9(), 
	VideoCodecCapability.vp8()
	]
);
```

# Configuring your network for Amazon Chime SDK meetings
<a name="network-config"></a>

When you integrate the Amazon Chime SDK into your client application, the SDK connects to its back-end service to send and receive audio, video, content sharing, and data messages. If your users' network blocks traffic to the Amazon Chime SDK service, their ability to use the service will be impaired. Network administrators can use this information to reconfigure their network to allow access to the Amazon Chime SDK service.

**Note**  
When you configure your network, you must enable Extension Mechanisms for DNS (EDNS0) by default. This enables your application to reach the Amazon Chime SDK services by ensuring that host information is the correct size for UDP packets.

**Topics**
+ [Configuring for media and signaling](#media-signaling)
+ [Configuring for Amazon Voice Focus](#voice-focus-config)
+ [Configuring for echo reduction](#echo-reduction)
+ [Configuring for background replacement and blur](#config-blur)
+ [Configuring browser content security policies](#configure-browser-policy)
+ [Using AppKeys and TenantIDs for Amazon Chime SDK](app-keys-tenant-ids.md)

## Configuring for media and signaling
<a name="media-signaling"></a>

Amazon Chime SDK audio, video, and content use User Datagram Protocol (UDP) transport whenever possible. If UDP is blocked, the Amazon Chime SDK tries to establish a Transport Layer Security (TLS) connection for bidirectional media transport. Amazon Chime SDK signaling and data messages use Transmission Control Protocol (TCP) and WebSocket connections.

The following diagram shows a typical network with an application that runs the Amazon Chime SDK. 

![\[A network configured to run an Amazon Chime SDK application, with two-way communication between the SDK and a meeting.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/net-config-diagram.png)


The Amazon Chime SDK uses the following destinations and ports for media and signaling.


| Domain | IPv4 Subnet | IPv6 Subnet | Ports | 
| --- | --- | --- | --- | 
| \$1.chime.aws | 99.77.128.0/18 | 2600:f0f0:4100::/40 | TCP:443 UDP:3478 | 

This subnet is the `CHIME_MEETINGS` service in the [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html).

## Configuring for Amazon Voice Focus
<a name="voice-focus-config"></a>

The Amazon Chime SDK client libraries for iOS and Android include the Amazon Voice Focus module. The Amazon Chime SDK client library for JavaScript downloads the Amazon Voice Focus module from Amazon CloudFront. The Amazon Chime SDK client library for Windows doesn't support Voice Focus.

Amazon Voice Focus uses the following destinations and ports.


| Domain | Ports | 
| --- | --- | 
| \$1.sdkassets.chime.aws | TCP:443 | 

This subnet is the `CLOUDFRONT` service in the [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html).

## Configuring for echo reduction
<a name="echo-reduction"></a>

The Amazon Chime SDK client library for JavaScript downloads the echo reduction module from Amazon CloudFront.

Echo reduction uses the following destinations and ports.


| Domain | Ports | 
| --- | --- | 
| \$1.sdkassets.chime.aws | TCP:443 | 

This subnet is the `CLOUDFRONT` service in the [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html).

## Configuring for background replacement and blur
<a name="config-blur"></a>

The Amazon Chime SDK client library for JavaScript downloads the background replacement and blur module from Amazon CloudFront.

Background replacement and blur uses the following destinations and ports.


| Domain | Ports | 
| --- | --- | 
| \$1.sdkassets.chime.aws | TCP:443 | 

This subnet is the `CLOUDFRONT` service in the [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html).

## Configuring browser content security policies
<a name="configure-browser-policy"></a>

When you build an application with the Amazon Chime SDK client library for JavaScript, you need to configure the browser content security policies in your application. For more information, refer to the [Content Security Policy Guide](https://aws.github.io/amazon-chime-sdk-js/modules/contentsecurity_policy.html) on GitHub. 

# Using AppKeys and TenantIDs for Amazon Chime SDK
<a name="app-keys-tenant-ids"></a>

You can use AppKeys and TenantIDs to limit access *from a network* to specific applications' Amazon Chime SDK WebRTC media sessions.

Developers use the Amazon Chime SDK to create applications that send and receive real-time video over UDP. Application users require UDP access to the [https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) subnet. Organizations (network owners) can use AppKeys and TenantIDs to limit access from their network to only a specific application's WebRTC media sessions.

**Example 1: Using AppKeys**  
If App-A and App-B use the Amazon Chime SDK, an organization can allow App-A to access the WebRTC media sessions from their network, but block App-B and any other applications that use the Amazon Chime SDK. Organizations can do that with App-A's AppKey and an HTTPS proxy. For more information, refer to [Limiting access to a specific application](#limit-app-access), later in this topic.

**Example 2: Using AppKeys and TenantIDs**  
If App-A is publicly available and used by many customers, an organization may want to allow App-A to access WebRTC media sessions from their network only when their users are part of the session, and block access to all other App-A sessions. Organizations can do this by using the application's AppKey, the organization's TenantID, and an HTTPS proxy. For more information, refer to [Limiting access to a specific tenant](#limit-tenant-access), later in this topic.

To use AppKeys and TenantIDs, you must have an HTTPS proxy server that allows adding HTTPS headers to a request. The following diagram shows how AppKeys and TenantIDs work.

![\[Diagram showing how AppKeys and TenantIDs control application and tenant access to a WebRTC session.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/app-key-diagram.png)


In the image, App-A has tenants A-1 and A-2, and App-B has tenants B-1 and B-2. In this case, the AppKey only allows App-A to connect to the WebRTC media session, and the tenant ID only admits Tenant A-1 to the session.

**Topics**
+ [Limiting access to a specific application](#limit-app-access)
+ [Limiting access to a specific tenant](#limit-tenant-access)
+ [HTTPS header examples](#header-examples)

## Limiting access to a specific application
<a name="limit-app-access"></a>

An *AppKey* is a consistent, unique 256-bit value that Amazon Chime creates for each AWS account. If you don't have an AppKey, you can request one from Amazon Support. If you have multiple AWS accounts, you can request a common AppKey for all your accounts.

**Note**  
You can safely share your AppKeys publicly and enable other organizations to limit access from their networks. 

The Amazon Chime SDK automatically associates each WebRTC media sessions with an AppKey based on the AWS account ID used to create the session. To limit access *from your network* to specific applications, do the following:

1. Route all outbound requests to the `CHIME_MEETINGS` subnet through an HTTPS proxy server. 

1. Configure the proxy server to add the following header to all outbound requests to the `CHIME_MEETINGS` subnet:

   `X-Amzn-Chime-App-Keys:` *comma-separated list of allowed AppKeys*.

   For example, `X-Amzn-Chime-App-Keys:AppKey-A,AppKey-B,AppKey-C` allows the apps associated with those AppKeys to access the subnet.

The Amazon Chime SDK inspects inbound WebRTC media session connections for the `X-Amzn-Chime-App-Keys` header and applies the following logic:

1. If the `X-Amzn-Chime-App-Keys` header is present and includes the session's AppKey, accept the connection.

1. If the `X-Amzn-Chime-App-Keys` header is present but does not include the session's AppKey, reject the connection with a 403 error.

1. If the `X-Amzn-Chime-App-Keys` header is not present, accept the connection. If users can access the application from outside the organization's network, they can also access the session.

## Limiting access to a specific tenant
<a name="limit-tenant-access"></a>

A *TenantID* is an opaque identifier created by developers. Remember the following about TenantIDs:
+ TenantIDs are not guaranteed to be unique between applications, so you must specify an AppKey for each TenantID list. 
+ TenantIDs are case senstitive. Enter them exactly as prescribed by the developer.
+ An organization can limit access to multiple applications, but only specify TenantIDs for some of those applications. Applications without TenantIDs can connect to all WebRTC media sessions. 

To associate a media session with TenantIDs, a developer must first add the `TenantIds` property and a list of TenantIDs to a [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) or [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html) request.

For example:

`CreateMeeting(..., TenantIds : [ tenantId1, tenantId2 ] )`

To limit access from an organization's network to their WebRTC media session in specific applications, do the following:

1. Follow the steps in [Limiting access to a specific application](#limit-app-access).

1. Configure the HTTPS proxy server to add an `X-Amzn-Chime-Tenants` header on outbound connections. Include a list of AppKeys and TenantIDs, delimited as shown in this example: `X-Amzn-Chime-Tenants: AppKey-A:tenantId-A-1,tenantId-A-2;AppKey-B:tenantId-B-1,tenantId-B-2`

The Amazon Chime SDK inspects inbound WebRTC media session connections for the `X-Amzn-Chime-Tenants` header and applies the following logic:
+ If the header includes the session's `AppKey:tenantId`, accept the connection.
+ If the header includes the session's `AppKey` but no matching `tenantId`, reject the connection with a 403 error.
+ If the header does *not* include the session's `AppKey`, accept the connection.
+ If the header includes the session's `AppKey`, but the session doesn't have at least one allowed `tenantId`, reject the connection with a 403 error. This may be a developer bug.
+ If the header is not present, accept the connection. If users can access the application from outside the organization's network, they can also access all sessions.

## HTTPS header examples
<a name="header-examples"></a>

The following examples show some of the ways to use AppKeys and TenantIDs in HTTPS headers.

**One app with one tenant**  
`X-Amzn-Chime-App-Keys: AppKey`  
`X-Amzn-Chime-Tenants: AppKey:orgId`  
Users can access only the organization's WebRTC media sessions in the specified app. All other apps are blocked.

**One app with two tenants**  
`X-Amzn-Chime-App-Keys: AppKey`  
`X-Amzn-Chime-Tenants: AppKey:engineeringId,salesId`  
Users can access only the media sessions for engineering and sales in the specified app. All other apps are blocked.

**Two Apps, One limited to a Tenant**  
`X-Amzn-Chime-App-Keys: AppKey1,AppKey2`  
`X-Amzn-Chime-Tenants: AppKey1:orgId`  
Users can access only the organization's media sessions in App 1, and any session in App 2. All other apps are blocked.

# Understanding Amazon Chime SDK meeting lifecycle events
<a name="using-events"></a>

The Amazon Chime SDK sends meeting lifecycle events, which you can use to trigger notifications and initiate downstream workflows. Some examples of using meeting events include: 
+ Updating metadata when an attendee joins or leaves an Amazon Chime SDK meeting.
+ Implementing push notifications or rosters for an Amazon Chime SDK meeting.
+ Measuring the usage of video and content sharing in Amazon Chime SDK meetings.

You can send events to Amazon EventBridge, Amazon Simple Notification Service (SNS), and Amazon Simple Queue Service (SQS). For more information, refer to [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) in the *Amazon EventBridge User Guide*.

## Amazon Chime SDK meeting starts
<a name="sdk-start-mtg"></a>

The Amazon Chime SDK sends this event when a new meeting starts.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:MeetingStarted",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",    
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK meeting ends
<a name="sdk-end-mtg"></a>

The Amazon Chime SDK sends this event when an active meeting ends.

**Note**  
For efficiency, the service also sends this event when you call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteMeeting.html) API.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:MeetingEnded",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",    
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee is added
<a name="sdk-add-attendee"></a>

The Amazon Chime SDK sends this event when a new attendee is added to an active meeting.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeAdded",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee is deleted
<a name="sdk-remove-attendee"></a>

The Amazon Chime SDK sends this event when you use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteAttendee.html) API to remove an attendee from an active meeting. 

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333", 
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeDeleted",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee is authorized
<a name="sdk-auth-attendee"></a>

The Amazon Chime SDK sends this event when a user, already joined to the meeting, uses the same join token to join the meeting again. For example, a user may switch from a desktop machine to a mobile device. This effectively "hands off" the meeting to the new device. 

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeAuthorized",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee joins a meeting
<a name="sdk-join-attendee"></a>

The Amazon Chime SDK sends this event when an existing attendee joins an Amazon Chime SDK meeting using the specified network transport.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333", 
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeJoined",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",    
    "networkType": "Voip",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee leaves a meeting
<a name="sdk-leave-attendee"></a>

The Amazon Chime SDK sends this event when an existing attendee leaves an Amazon Chime SDK meeting using the specified network transport.

**Note**  
The service never sends `chime:AttendeeLeft` AND `chime:AttendeeDropped` events for the same "leave" action. Dropping and leaving are different actions, and the system sends the event that corresponds to each action.  
For example, say an attendee with a poor connection joins a meeting at 11 AM. You can expect the following actions:  

```
11:00 API – CreateAttendee, CreateMeetingWithAttendee, or BatchCreateAttendee
11:00   Event – chime:AttendeeAdded
11:01 Action – user joins meeting
11:01   Event – chime:AttendeeJoined
11:02 Action – user's connection drops
11:02   Event – chime:AttendeeDropped
11:03 Action – user's connection restored
11:03   Event – chime:AttendeeJoined
11:30 Action – user leaves meeting
11:30   Event – chime:AttendeeLeft
```

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeLeft",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "networkType": "Voip",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee is dropped from a meeting
<a name="sdk-drop-attendee"></a>

The Amazon Chime SDK sends this event when a current attendee is dropped from an Amazon Chime SDK meeting, usually because of a poor connection. When the service doesn't receive packets for 10-15 seconds, it considers the cient dropped and issues the event.

The service usually triggers drop actions, but clients can also trigger them. For example, say a user switches their laptop from Wi-Fi to Ethernet. That constitutes a network adapter change, and the connection is reset. In turn, that resets the websocket and triggers a combined drop-join action.

**Note**  
The service never sends `chime:AttendeeLeft` AND `chime:AttendeeDropped` events for the same "leave" action. Dropping and leaving are different actions, and the system sends the event that corresponds to each action.  
For example, say an attendee with a poor connection joins a meeting at 11 AM. You can expect the following actions:  

```
11:00 API – CreateAttendee, CreateMeetingWithAttendee, or BatchCreateAttendee
11:00   Event – chime:AttendeeAdded
11:01 Action – user joins meeting
11:01   Event – chime:AttendeeJoined
11:02 Action – user's connection drops
11:02   Event – chime:AttendeeDropped
11:03 Action – user's connection restored
11:03   Event – chime:AttendeeJoined
11:30 Action – user leaves meeting
11:30   Event – chime:AttendeeLeft
```

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeDropped",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",  
    "networkType": "Voip",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee starts streaming video
<a name="sdk-attendee-video-start"></a>

The Amazon Chime SDK sends this event when an existing attendee starts streaming video.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333", 
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeVideoStarted",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee stops streaming video
<a name="sdk-attendee-video-stop"></a>

The Amazon Chime SDK sends this event when an existing attendee stops streaming video.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333", 
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeVideoStopped",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee starts sharing screen
<a name="sdk-attendee-screenshare-start"></a>

The Amazon Chime SDK sends this event when an existing attendee starts sharing their screen.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentVideoStarted",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee stops sharing screen
<a name="sdk-attendee-screenshare-stop"></a>

The Amazon Chime SDK sends this event when an existing attendee stops sharing their screen.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentVideoStopped",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee capabilities updated
<a name="sdk-attendee-capability-updated"></a>

The Amazon Chime SDK sends this event when an existing attendee's capabilities are updated.

**Example Event data**  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",
  "id": "12345678-1234-1234-1234-111122223333",
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": [],
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeCapabilitiesUpdated",
    "success": "1", // value can be 1 or 0. 1 means success, 0 means failure
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "mymeeting",
    "attendeeId": "attendeeId",
    "externalUserId": "externalUserId"
    "mediaRegion": "us-east-1"
    "attendeeCapabilities": {
    "audio": "SendReceive",
    "video": "SendReceive",
    "content": "SendReceive"
   }
  }
}
```

## Amazon Chime SDK attendee content joins a meeting
<a name="sdk-content-join"></a>

The Amazon Chime SDK sends this event when a content share joins an Amazon Chime SDK meeting using the specified network transport.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentJoined",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "networkType": "Voip",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee content leaves a meeting
<a name="sdk-content-leave"></a>

The Amazon Chime SDK sends this event when a content share leaves an Amazon Chime SDK meeting using the specified network transport.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentLeft",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "networkType": "Voip",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee content drops from a meeting
<a name="sdk-content-drop"></a>

The Amazon Chime SDK sends this event when a content share drops from an Amazon Chime SDK meeting, typically because of low bandwidth.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentDropped",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "networkType": "Voip",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee content starts streaming video
<a name="sdk-content-start-stream"></a>

The Amazon Chime SDK sends this event when a content share starts streaming video.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333",  
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentVideoStarted",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

## Amazon Chime SDK attendee content stops streaming video
<a name="sdk-content-stop-stream"></a>

The Amazon Chime SDK sends this event when a content share stops streaming video.

**Example Event data**  
The following example shows the data for this event.  

```
{
  "version": "0",
  "source": "aws.chime",
  "account": "111122223333", 
  "region": "us-east-1",
  "detail-type": "Chime Meeting State Change",
  "time": "yyyy-mm-ddThh:mm:ssZ",
  "resources": []
  "detail": {
    "version": "0",
    "eventType": "chime:AttendeeContentVideoStopped",
    "timestamp": 12344566754,
    "meetingId": "87654321-4321-4321-1234-111122223333",
    "attendeeId": "87654321-4321-4321-1234-111122223333",
    "externalUserId": "87654321-4321-4321-1234-111122223333",
    "externalMeetingId": "87654321-4321-4321-1234-111122223333",
    "mediaRegion": "us-east-1"
  }
}
```

# Understanding Amazon CloudWatch metrics for Amazon Chime SDK meetings
<a name="sdk-usage-metrics"></a>

When you use the Amazon Chime SDK, it sends service and usage metrics to CloudWatch. The metrics enable you to use CloudWatch graphs and dashboards to monitor how you consume Amazon Chime SDK services. The metrics capture data for each API that you call.

The following sections list and describe the metrics.

**Topics**
+ [Service metrics](#service-metrics)
+ [API usage metrics](#usage-metrics)

## Service metrics
<a name="service-metrics"></a>

The Amazon Chime SDK publishes to the following service metrics to the `AWS/ChimeSDK` namespace:


| Metric | Unit | Description | 
| --- | --- | --- | 
| `AttendeeAuthorizationSuccess` | Count | Total count of successful authorization attempts. Success means that an attendee was allowed to join the meeting. | 
| `AttendeeAuthorizationError` | Count | Total count of authorization failures, indicates that the attendee couldn't join the meeting. | 
| `AttendeeAudioDrops` | Count | Total count of audio drops. | 
| `AttendeeContentDrops` | Count | Total count of content share drops. | 
| `MeetingSQSNotificationErrors` | Count | Total count of SQS Notification errors. | 
| `MeetingSNSNotificationErrors` | Count | Total count of SNS Notification errors. | 

## API usage metrics
<a name="usage-metrics"></a>

The API usage metrics correspond to the AWS service quotas. You can configure alarms that alert you when your usage approaches a service quota. For more information about CloudWatch integration with service quotas, see [AWS usage metrics](https://docs.aws.amazon.com/AmazonCloudWatch/latest/monitoring/CloudWatch-Service-Quota-Integration.html) in the *Amazon CloudWatch User Guide*.

The Amazon Chime SDK publishes the following API metrics in the `AWS/Usage` namespace, with the `ChimeSDK` service name.


| Metric | Description | 
| --- | --- | 
| `CallCount` | The total number of calls made to an API in the Amazon Chime SDK. SUM represents the total number of calls to the API during the specified period. | 
| `ErrorCount` | The total number of errors thrown by an API in the Amazon Chime SDK. SUM represents the total number of calls to the API during the specified period. | 
| `ThrottleCount` | The total number of throttling errors thrown by an API in the Amazon Chime SDK. SUM which represents the total number of calls to the API during the specified period. | 

The Amazon Chime SDK publishes usage metrics to the `AWS/Usage` namespace with the following dimensions:


| Dimension | Description | 
| --- | --- | 
| Service | The name of the AWS service containing the resource. For Amazon Chime SDK usage metrics, the value for this dimension is `ChimeSDK`. | 
| Type | The type of entity being reported. The only valid value for Amazon Chime SDK usage metrics is `API`. | 
| Resource | The type of resource reporting the metric. For Amazon Chime SDK usage metrics, the value for this dimension is the name of the API. | 
| Class | The class of resource being tracked. The only valid value for Amazon Chime SDK metrics is `None`. | 

# Creating Amazon Chime SDK media pipelines
<a name="media-pipelines"></a>

In this section, we show you how to create media pipelines, which are used to capture or stream an Amazon Chime SDK meeting. Before you begin, you must integrate your client application with the Amazon Chime SDK client library. For more information, see [Learn about the Amazon Chime SDK client libraries](mtgs-sdk-client-lib.md). For more information about media pipelines, see [Capture Amazon Chime SDK Meetings Using media pipelines](https://aws.amazon.com/blogs//business-productivity/capture-amazon-chime-sdk-meetings-using-media-capture-pipelines/) in the *AWS Business Productivity Blog*.

**Important**  
You and your end users must understand that recording Amazon Chime SDK meetings may be subject to laws or regulations regarding the recording of electronic communications. It is your and your end users’ responsibility to comply with all applicable laws regarding the recordings, including properly notifying all participants in a recorded session that the session or communication is being recorded, and obtain their consent.   
You and your end users are responsible for all content streaming using the media live connector service, and must ensure that such content does not violate the law, infringe or misappropriate the rights of any third party, or otherwise violate a material term of your agreement with Amazon.

**Topics**
+ [Considerations for creating Amazon Chime SDK media pipelines](creating-media-pipelines-considerations.md)
+ [Understanding the default limits for active Amazon Chime SDK media pipelines](media-pipelines-limits.md)
+ [Migrating to the Amazon Chime SDK media pipelines namespace](migrate-pipelines.md)
+ [Understanding Amazon Chime SDK media pipeline creation](create-pipeline.md)
+ [Creating media capture pipelines for Amazon Chime SDK meetings](capture-pipe-config.md)
+ [Creating media concatenation pipelines for Amazon Chime SDK meetings](create-concat-pipe.md)
+ [Creating media live connector pipelines for Amazon Chime SDK meetings](connector-pipe-config.md)
+ [Creating media stream pipelines using the Amazon Chime SDK](create-media-stream-pipeline.md)
+ [Compositing audio and video into a single view in Amazon Chime SDK meetings](pipeline-compositing.md)
+ [Creating a service-linked role for Amazon Chime SDK media pipelines](create-pipeline-role.md)
+ [Using Amazon Chime SDK media pipeline events](media-pipe-events.md)
+ [Best practices for stopping Amazon Chime SDK media pipelines](stop-pipe-best-practices.md)

# Considerations for creating Amazon Chime SDK media pipelines
<a name="creating-media-pipelines-considerations"></a>

A media pipeline can consist of one of these pipelines: 
+ **Media capture** – Use media capture pipelines to capture audio, video, and content share streams, plus meeting events and data messages. All media capture pipelines save their data to [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. For more information, refer to [Understanding Amazon Chime SDK media pipeline creation](create-pipeline.md).
+ **Media concatenation** – Use media concatenation pipelines to concatenate the artifacts from a media capture pipeline. Concatenation pipelines work independently of media capture and live connector pipelines. For more information, refer to [Creating media concatenation pipelines for Amazon Chime SDK meetings](create-concat-pipe.md).
+ **Media live connector** – Use media live connector pipelines to connect to services that enable you to stream Amazon Chime SDK meetings to an RTMP endpoint. You can create up to one media live connector pipeline per Amazon Chime SDK meeting. For more information, refer to [Creating media live connector pipelines for Amazon Chime SDK meetings](connector-pipe-config.md).
+ **Media stream** – Use media stream pipelines to capture individual audio for all the attendees in a meeting, plus the mixed audio generated by a media concatenation pipeline. All media stream pipelines save their data to [ Amazon Kinesis Video Streams](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/what-is-kinesis-video.html) (KVS). For more information, refer to [Creating media stream pipelines using the Amazon Chime SDK](create-media-stream-pipeline.md).

The pipelines you create depend on the namespace you use. If you use the `Chime` namespace, you can only create media capture pipelines. If you use the `ChimeSdkMediaPipelines` namespace, you can also create media concatenation and media live connector pipelines, and use compositing features. If you want to migrate to the `ChimeSdkMediaPipelines` namespace, refer to [Migrating to the Amazon Chime SDK media pipelines namespace](migrate-pipelines.md).

# Understanding the default limits for active Amazon Chime SDK media pipelines
<a name="media-pipelines-limits"></a>

The following table lists the default limits for active media pipelines in each Region. Each type of pipeline counts toward the limit. If you exceed the limit for any Region, 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), [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html), and [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaLiveConnectorPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaLiveConnectorPipeline.html) APIs will throw **Resource Limit Exceeded** exceptions.

You can use the **Service Quotas** page in the AWS console to adjust your active pipeline limits, or you can contact your [customer support representative](https://docs.aws.amazon.com/awssupport/latest/user/getting-started.html). For more information about the Amazon Chime SDK meeting limits, see [Quotas for the Amazon Chime SDK](meetings-sdk.md#mtg-limits).


| Region | Default active pipeline limit | 
| --- | --- | 
| us-east-1 | 100 | 
| us-west-2 | 10 | 
| ap-northeast-1 | 10 | 
| ap-northeast-2 | 10 | 
| ap-south-1 | 10 | 
| ap-southeast-1 | 10 | 
| ap-southeast-2 | 10 | 
| ca-central-1 | 10 | 
| eu-central-1 | 10 | 
| eu-west-2 | 10 | 

# Migrating to the Amazon Chime SDK media pipelines namespace
<a name="migrate-pipelines"></a>

You use the `ChimeSdkMediaPipelines` namespace to address media pipeline API endpoints in any AWS Region in which they're available. Use this namespace if you're just starting to use the Amazon Chime SDK. For more information about Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md) in this guide.

Existing applications that use the [Amazon Chime](https://docs.aws.amazon.com/chime/latest/APIReference/API_Operations_Amazon_Chime.html) namespace should plan to migrate to the dedicated namespace.

**Topics**
+ [Reasons to migrate your pipelines](#pipeline-migration-reasons)
+ [Before you migrate your pipelines](#migration-prerequisites)

## Reasons to migrate your pipelines
<a name="pipeline-migration-reasons"></a>

We encourage you to migrate to the `ChimeSdkMediaPipelines` namespace for these reasons:

**Choice of API Endpoint**  
The Amazon Chime SDK Media Capture namespace is the only API namespace which can use API endpoints in any Region that makes them available. For more information about Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md). If you want to use API endpoints other than `us-east-1`, you must use the `ChimeSdkMediaPipelines` namespace. For more information about the current endpoints, refer to [API mapping](migrate-from-chm-namespace.md#name-end-map) in this guide.

**Updated and new media pipeline APIs**  
We only add or update media pipeline APIs in the `ChimeSdkMediaPipelines` namespace.

## Before you migrate your pipelines
<a name="migration-prerequisites"></a>

Before you migrate, be aware of the differences between the namespaces. The following table lists and describes them.


| Item | Media pipelines namespace | Chime namespace | 
| --- | --- | --- | 
|  Namespace names  |  ChimeSdkMediaPipelines  |  Chime  | 
|  Regions  |  Multiple  |  us-east-1 only  | 
|  Endpoints  |  https://media-pipelines-chime.*region*.amazonaws.com  |  https://service.chime.aws.amazon.com  | 
|  Service principal  |  mediapipelines.chime.amazonaws.com  |  chime.amazonaws.com  | 
|  APIs  |  Only APIs for media pipelines  |  APIs for media pipelines and other parts of Amazon Chime  | 
|  Meetings  |  Media pipelines in the `us-west-2`, `ap-southeast-1`, and `eu-central-1` regions only work with meetings created in the Amazon Chime SDK Meetings namespace. Media pipelines in the `us-east-1` region work with meetings created by any meeting endpoint in either namespace.  |  Media pipelines work with meetings created by any meetings endpoint in either namespace.  | 
| Default active media pipelines | 100 in the us-east-1 Region, and 10 in the us-west-2, ap-southeast-1, and eu-central-1 Regions.  | 100 in us-east-1 only. | 
|  Service-linked role  |  AWSServiceRoleForAmazonChimeSDKMediaPipelines  |     | 
|  Tags  |  Available  |  Not available for the media pipeline APIs.  | 
| CloudTrail event source | chime-sdk-media-pipelines.amazonaws.com | chime.amazonaws.com. | 
| Media live connector | Available |  Not available for the media pipeline APIs.  | 
| Compositing | Available |  Not available for the media pipeline APIs.  | 
| Concatenation | Available | Not available. | 

The following list provides more information about the differences between the Chime and AWSChimeSdkMediaPipelines namespaces.

**Namespace names**  
The Amazon Chime SDK namespace uses the `AWS.Chime` formal name. The Amazon Chime SDK Media Pipelines namespace uses the `AWS.ChimeSDKMediaPipelines` formal name. The precise format of the name varies by platform.  
For example, this line of Node.js code addresses the `chime` namespace:  

```
const chimeMediaPipelines = AWS.Chime();
```
To migrate to the Media Pipelines SDK namespace, update that code with the new namespace and the endpoint region.  

```
const chimeMediaPipelines = AWS.ChimeSDKMediaPipelines({ region: "eu-central-1" });
```

**Regions**  
The Amazon Chime namespace only addresses API endpoints in the US-EAST-1 region. The Amazon Chime SDK Media Pipelines namespace addresses Amazon Chime SDK media pipeline API endpoints in any Region that has them. For a current list of media pipeline Regions, see [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md) in this guide.

**Endpoints**  
To modify a media capture pipeline, you must use the same endpoint that you created the pipeline in. For example, if you created pipelines via an endpoint in eu-central-1, you must use eu-central-1 to interact with that pipeline. For more information about the current endpoints, refer to [API mapping](migrate-from-chm-namespace.md#name-end-map) in this guide.

**Service principal**  
The [Amazon Chime SDK Media Pipelines](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace uses a new service principal: `mediapipelines.chime.amazonaws.com`. If you have Amazon S3 bucket or other IAM policies that grant access to services, you need to update those polices to grant access to the new service principal.  
For example, when you create a media pipelines, you must add the policy permissions listed in [Creating an Amazon S3 bucket for Amazon Chime SDK media capture pipelines](create-s3-bucket.md) to the new service principal. For more information about policies, see [ AWS JSON policy elements: Principal](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_elements_principal.html) in the IAM User Guide.

**APIs**  
The Amazon Chime SDK Media Pipelines namespace only contains APIs that create and manage media pipelines. The Amazon Chime namespace includes APIs for media pipelines, meetings, and other parts of the Amazon Chime service.

**Meetings**  
Media pipelines in the IAD region work with meetings created by any meetings endpoint with either namespace.

**Service-linked role**  
Only for the Amazon Chime SDK Media Pipelines namespace. Create the *AWSServiceRoleForAmazonChimeSDKMediaPipelines* role.

**Tags**  
The [Amazon Chime SDK Media Pipelines](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Meetings.html) namespace supports tags. The role must have permission to call the `TagResource` operation when calling the [CreateMediaCapturePipeline](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaCapturePipeline.html) or [CreateMediaLiveConnectorPipeline](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaLiveConnectorPipeline.html) APIs with one or more tags.

# Understanding Amazon Chime SDK media pipeline creation
<a name="create-pipeline"></a>

You follow a multi-step process to create an Amazon Chime SDK media pipeline, and you can create several types of pipelines. The following list outlines the creation process and provide links to more information about creating the various types of pipelines. 
+ Create an Amazon S3 bucket. You must create the bucket in the same AWS Region as the meeting. For more information, refer to [Creating an Amazon S3 bucket for Amazon Chime SDK media capture pipelines](create-s3-bucket.md).
+ Create a service-linked role named `AWSServiceRoleForAmazonChimeSDKMediaPipelines`. This allows media pipelines to access meetings on your behalf. For more information, refer to [Creating a service-linked role for Amazon Chime SDK media pipelines](create-pipeline-role.md).
+ Create an IAM role with sufficient permission to interact with the [ Amazon Chime SDK media pipeline APIs ](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_Operations_Amazon_Chime_SDK_Media_Pipelines.html). To create that role, we recommend adding the [AmazonChimeSDK](https://docs.aws.amazon.com/chime-sdk/latest/ag/security_iam_id-based-policy-examples.html#security_iam_id-based-policy-examples-chime-sdk) managed policy from the IAM console. The policy contains the necessary APIs.

  Your IAM role must also have permission to call the Amazon S3 [https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketPolicy.html](https://docs.aws.amazon.com/AmazonS3/latest/API/API_GetBucketPolicy.html) API on all resources. The following example shows a typical policy for doing so.

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

****  

  ```
  {
      "Version":"2012-10-17",		 	 	 
      "Statement": [
          {
              "Action": "s3:GetBucketPolicy",
              "Effect": "Allow",
              "Resource": "*"
          }
      ]
  }
  ```

------

Once you have those items, see these topics for information on creating pipelines.
+ [Creating media capture pipelines for Amazon Chime SDK meetings](capture-pipe-config.md)
+ [Creating media concatenation pipelines for Amazon Chime SDK meetings](create-concat-pipe.md)
+ [Creating media live connector pipelines for Amazon Chime SDK meetings](connector-pipe-config.md)
+ [Creating media stream pipelines using the Amazon Chime SDK](create-media-stream-pipeline.md)

# Creating media capture pipelines for Amazon Chime SDK meetings
<a name="capture-pipe-config"></a>

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
<a name="create-s3-bucket"></a>

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
<a name="sse-kms"></a>

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
<a name="s3-keys"></a>

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
<a name="customer-key"></a>

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
<a name="using-kms-keys-for-encryption"></a>

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
<a name="using-kms-keys-for-encryption-config"></a>

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::<YOUR_ACCOUNT_ID>;:role/<SINK_IAM_ROLE_NAME>"
    ...
},
...
```

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::<YOUR_ACCOUNT_ID>:role/<YOUR_CUSTOMER_ROLE_ID>"
    },
    "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": "<YOUR_ACCOUNT_ID>"
        },
        "ArnLike": {
            "aws:SourceArn": "arn:aws:chime:*:<YOUR_ACCOUNT_ID>:*"
        }
    }
}
```

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:<KMS_KEY_REGION>:<KMS_KEY_ACCOUNT_ID>:key/<MS_KEY_ID>",
    "Condition": {
        "StringEquals": {
            "aws:SourceAccount": "<YOUR_ACCOUNT_ID>"
        },
        "ArnLike": {
            "aws:SourceArn": "arn:aws:chime:*:<YOUR_ACCOUNT_ID>:*"
        }
    }
},
{
    "Effect": "Allow",
    "Action": ["s3:PutObject", "s3:PutObjectAcl"],
    "Resource": "arn:aws:s3:::<YOUR_DEDICATED_KMS_BUCKET_ID>/*",
    "Condition": {
        "StringEquals": {
            "aws:SourceAccount": "<YOUR_ACCOUNT_ID>"
        },
        "ArnLike": {
            "aws:SourceArn": "arn:aws:chime:*:<YOUR_ACCOUNT_ID>:*"
        }
    }
}
```

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": "<SINK_IAM_ROLE_ARN>",
    "Condition": {
        "ArnLike": {
            "iam:AssociatedResourceArn": "arn:aws:chime:*:<YOUR_ACCOUNT_ID>:media-pipeline/*"
        },
        "StringEquals": {
            "iam:PassedToService": "mediapipelines.chime.amazonaws.com"
        }
    }
}
```

## Media concatenation implementation
<a name="media-concatenation-implementatoin"></a>

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:<KMS_KEY_REGION>:<KMS_KEY_ACCOUNT_ID>:key/<KMS_KEY_ID>",
        ...
    }
    ...
    {
        "Action": [ "s3:PutObject", "s3:PutObjectAcl", "s3:GetObject", "s3:ListBucket"],
        "Resource": "arn:aws:s3:::<YOUR_DEDICATED_KMS_BUCKET_ID>/*",
    }
    ...
}
...
```

# Creating the Amazon Chime SDK media capture pipeline
<a name="create-capture-pipe"></a>

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
<a name="artifacts"></a>

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
<a name="configure-audio"></a>

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
<a name="configure-video"></a>

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 <yyyy-mm-dd-hour-min-seconds-milleseconds>-<attendeeID> timestamp with an attendee ID. The content share video chunk is appended as <yyyy-mm-dd-hour-min-seconds-milleseconds>-<attendeeID>\$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
<a name="data-channel"></a>

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
<a name="capture-folder-structure"></a>

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
<a name="meeting-events"></a>

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 <yyyy-mm-dd-hour-min-seconds-milleseconds> 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
<a name="transcription-messages"></a>

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 <yyyy-mm-dd-hour-min-seconds-milleseconds> 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
<a name="concatenate-streams"></a>

**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.

# Creating media concatenation pipelines for Amazon Chime SDK meetings
<a name="create-concat-pipe"></a>

You use media concatenation pipelines to concatenate the artifacts (files) generated by media capture pipelines.

Media capture pipelines capture the contents of a meeting by chunking the media streams and storing those artifacts in your Amazon S3 bucket. Media capture pipelines create the following types of artifacts: 
+ Audio
+ Video
+ Content shares
+ Data channel messages
+ Transcription messages
+ Meeting events
+ Composited video, meaning content shares and multiple video streams displayed in a grid as video tiles.

Media concatenation pipelines allow you to concatenate each type of artifact into a single file, and then store those larger files in your Amazon S3 bucket. You can create a media concatenation pipeline without waiting for the media capture event to end, but the concatenation pipeline only starts concatenating when the capture pipeline stops.

**Note**  
Media capture pipelines, media concatenation pipelines, and Amazon S3 buckets must reside in the same AWS account.

**Topics**
+ [Amazon Chime SDK concatenation pipeline architecture](concat-architecture.md)
+ [Building an Amazon Chime SDK media concatenation pipeline](create-concat-pipe-steps.md)
+ [Understanding the Amazon S3 bucket folder structure for Amazon Chime SDK concatenation pipelines](concat-folder-structure.md)

# Amazon Chime SDK concatenation pipeline architecture
<a name="concat-architecture"></a>

The following diagram shows the architecture of a media concatenation pipeline.

![\[Diagram showing the architecture of a media concatenation pipeline.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/concatenation-pipe-architecture-2.png)


In the diagram, on receiving a [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) request, the media pipeline control plane starts a media capture pipeline in the media pipeline data plane. The data plane then pushes captured chunks to the capture bucket every 5 seconds. On receiving a [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html) request, the media pipeline control plane waits for the specified media capture pipeline to finish, then starts a media concatenation pipeline in the media pipeline data plane. The data plane then reads the captured chunks in the bucket and pushes the concatenated artifacts to the concatenation bucket.

# Building an Amazon Chime SDK media concatenation pipeline
<a name="create-concat-pipe-steps"></a>

You follow a multi-step process to create an Amazon Chime SDK media concatenation pipeline. The following steps describe the process.

1. Create an Amazon S3 bucket for use as the media capture pipeline’s data sink, and then configure the bucket policy. For information about enabling server-side encryption for the Amazon S3 bucket, refer to [Enabling server-side encryption for an Amazon Amazon S3 bucket](https://docs.aws.amazon.com/chime-sdk/latest/dg/sse-kms.html) in this guide. If you created an Amazon Amazon S3 bucket for use with media capture pipelines, you must add the `s3:GetObject` and `s3:ListBucket` actions to that bucket's policy. The `s3:ListBucket` action requires permission on the bucket. The other actions require permission on the objects in the bucket. You must use two different Amazon Resource Names (ARNs) to specify bucket-level and object-level permissions.

   The following example shows the bucket policy. Copy and paste this example as needed.

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

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Id": "AWSChimeMediaCaptureBucketPolicy",
       "Statement": [
           {
               "Sid": "AWSChimeMediaCaptureBucketPolicy",
               "Effect": "Allow",
               "Principal": {
                   "Service": [
                       "mediapipelines.chime.amazonaws.com"
                   ]
               },
               "Action": [
                   "s3:PutObject",
                   "s3:PutObjectAcl",
                   "s3:GetObject",
                   "s3:ListBucket"
               ],
               "Resource": [
                   "arn:aws:s3:::[Bucket-Name]/*",
                   "arn:aws:s3:::[Bucket-Name]"
               ],
               "Condition": {
                   "StringEquals": {
                       "aws:SourceAccount": "123456789012"
                   },
                   "ArnLike": {
                   "aws:SourceArn": "arn:aws:chime:*:123456789012:*"
                   }
               }
           }
       ]
   }
   ```

------

1.  Create an Amazon Amazon S3 bucket for use as the media concatenation pipeline’s data sink, and then configure the bucket policy. For information about enabling server-side encryption for the Amazon S3 bucket, refer to [Enabling server-side encryption for an Amazon Amazon S3 bucket](https://docs.aws.amazon.com/chime-sdk/latest/dg/sse-kms.html) in this guide. 

   The following example shows the policy.

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

****  

   ```
   {
       "Version":"2012-10-17",		 	 	 
       "Id": "AWSChimeMediaConcatenationBucketPolicy",
       "Statement": [
           {
               "Sid": " AWSChimeMediaConcatenationBucketPolicy ",
               "Effect": "Allow",
               "Principal": {
                   "Service": [
                       "mediapipelines.chime.amazonaws.com"
                   ]
               },
               "Action": [
                   "s3:PutObject",
                   "s3:PutObjectAcl",
                   "s3:GetObject",
                   "s3:ListBucket"
               ],
               "Resource": [
                   "arn:aws:s3:::[Bucket-Name]/*",
                   "arn:aws:s3:::[Bucket-Name]"
               ],
               "Condition": {
                   "StringEquals": {
                   "aws:SourceAccount": "123456789012"
                   },
                   "ArnLike": {
                   "aws:SourceArn": "arn:aws:chime:*:123456789012:*"
                   }
               }
           }
       ]
   }
   ```

------
**Note**  
You can use a single Amazon S3 bucket for media capture and media concatenation pipelines. However, if you do that, you must add the `s3:GetObject` and `s3:ListBucket` permissions to the media concatenation bucket policy shown in step 2. If you don't want the concatenation bucket policy to have those permissions, then create separate buckets for each pipeline. 

1. Use 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 to create a media capture pipeline. As part of that, get the pipeline's ARN. For information about getting the ARN, refer to [Understanding Amazon Chime SDK media pipeline creation](create-pipeline.md). You use the ARN in the next step.

1. Use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaConcatenationPipeline.html) API to create a concatenation pipeline.

   The following example shows a request body. The *Path* field is optional, and it defaults to the concatenation pipeline's ID.
**Note**  
You must use a `MediaPipelineArn` created within the last 30 days.

   ```
   {
       "Sources": [
           {
               "Type": "MediaCapturePipeline",
               "MediaCapturePipelineSourceConfiguration": {
                   "MediaPipelineArn": "Media_Pipeline_Arn",  //must be <30 days old
                   "ChimeSdkMeetingConfiguration": {
                       "ArtifactsConfiguration": {
                           "Audio": {
                               "State": "Enabled"
                           },
                           "Video": {
                               "State": "Enabled | Disabled"
                           },
                           "Content": {
                               "State": "Enabled | Disabled"
                           },
                           "DataChannel": {
                               "State": "Enabled | Disabled"
                           },
                           "TranscriptionMessages": {
                               "State": "Enabled | Disabled"
                           },
                           "MeetingEvents": {
                               "State": "Enabled | Disabled"
                           },
                           "CompositedVideo": {
                               "State": "Enabled | Disabled"
                           }
                       }
                   }
               }
           }
       ],
       "Sinks": [
           {
               "Type": "S3Bucket",
               "S3BucketSinkConfiguration": {
                   "Destination": "arn:aws:s3:::[Bucket_Name]/[Path]"
               }
           }
       ]
   }
   ```

   Concatenation starts whenever the capture pipeline stops. The concatenation pipeline stops after completing the concatenation.

# Understanding the Amazon S3 bucket folder structure for Amazon Chime SDK concatenation pipelines
<a name="concat-folder-structure"></a>

The Amazon S3 buckets for media concatenation pipelines use this folder structure:

```
S3 bucket path/
  audio
  video
  composited-video
  data-channel
  meeting-events
  transcription-messages
```

**Note**  
If you specify a prefix when you create a media pipeline, the path to the folders becomes *bucket name*/*prefix*. Without a prefix, the path becomes *bucket name*/*media pipeline ID*. You specify a prefix in the `Destination` field of the `S3BucketSinkConfiguration` object. The concatenated file names consist of *media pipeline ID*.mp4 for media files and *media pipeline ID*.txt for text files.

# Creating media live connector pipelines for Amazon Chime SDK meetings
<a name="connector-pipe-config"></a>

The following sections list and describe the Real-Time Messaging Protocol (RTMP), audio, and video settings for a media live connector pipeline.

**RTMP settings**  
Media live connector pipelines support RTMP over a TLS/SSL connection. The sink URL consists of the stream URL and stream key. The URLs follow this format:

`rtmp(s)://stream-server/stream-key`

The following examples show how to connect to common streaming platforms.
+ **Amazon Interactive Video Service (IVS)** – rtmps://a1b2c3d4e5f6.global-contribute.live-video.net:443/app/*IVS-stream-key*
+ **YouTube** – rtmps://a.youtube.com/live2/*stream-key*
+ **Twitch** – rtmps://live.twitch.tv/app/*primary-stream-key*

**Important**  
RTMPS uses encryption to help ensure that a stream is not intercepted by an unauthorized entity. As a best practice, use RTMPS when you need additional data security.

**Audio settings**  
Media live connector pipelines support the following audio settings:
+ **Codec** – AAC
+ **Sample rate** – 44100 Hz or 48000 Hz. The default is 44100Hz.
+ **Channels** – Mono or stereo. The default is mono.

**Video settings**  
Media live connector pipelines use the H264 encoder. You can use HD at 1280x720 or FHD at 1920x1080. Both resolutions use 30 frames per second, with a keyframe every two seconds.

**Stopping media live connector pipelines**  
As a best practice for stopping media live connector pipelines, call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html) API. Ending a stream on a streaming platform such as IVS does not stop a media live connector pipeline.

# Creating media stream pipelines using the Amazon Chime SDK
<a name="create-media-stream-pipeline"></a>

Media stream pipelines capture individual audio for all the attendees in a meeting, plus the mixed audio generated by a media concatenation pipeline. All media stream pipelines save their data to [ Amazon Kinesis Video Streams](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/what-is-kinesis-video.html) (KVS).

You create the video stream by calling the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html) API. You can create one media stream pipeline per Amazon Chime SDK meeting.

**Note**  
If a meeting uses an opt-in Region as its [MediaRegion](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html#chimesdk-meeting-chime_CreateMeeting-request-MediaRegion), the KVS stream must be in that same Region. For example, if a meeting uses the `af-south-1` Region, the KVS stream must also be in `af-south-1`. However, if the meeting uses a Region that AWS turns on by default, the KVS stream can be in any available Region, including an opt-in Region. For example, if the meeting uses `ca-central-1`, the KVS stream can be in `eu-west-2`, `us-east-1`, `af-south-1`, or any other Region that the Amazon Chime SDK supports.  
To learn which AWS Region a meeting uses, call the [GetMeeting](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_GetMeeting.html) API and use the [MediaRegion](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html#chimesdk-meeting-chime_CreateMeeting-request-MediaRegion) parameter from the response.  
For more information about opt-in Regions, refer to [Available AWS Regions for the Amazon Chime SDK](sdk-available-regions.md) in this guide, and [Specify which AWS Regions your account can use](https://docs.aws.amazon.com/accounts/latest/reference/manage-acct-regions.html#rande-manage-enable.html), in the *AWS Account Management Reference Guide*.

The following sections explain how to create a media stream pipeline. Follow them in the order listed.

**Topics**
+ [Creating a Kinesis Video Streams pool for Amazon Chime SDK media stream pipelines](create-kvs-pool.md)
+ [Example code for Kinesis Video Streams pools for Amazon Chime SDK media stream pipelines](pool-creation-code.md)
+ [Creating Amazon Chime SDK media stream pipelines](create-stream-pipeline.md)
+ [Example code for Amazon Chime SDK media stream pipelines](pipeline-creation-code.md)
+ [Using Event Bridge notifications for Amazon Chime SDK media stream pipelines](media-stream-event-bridge.md)
+ [Using Amazon Chime SDK media stream pipelines data](media-stream-tips-tricks.md)

# Creating a Kinesis Video Streams pool for Amazon Chime SDK media stream pipelines
<a name="create-kvs-pool"></a>

The Kinesis Video Streams (KVS) pool for your media stream pipeline must belong to the same AWS account as the Amazon Chime SDK meeting. You create a Kinesis Video Streams pool by calling the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html) API.

The following diagram shows the architecture of a media pipeline Kinesis Video Streams pool. Numbers in the image correspond to the numbered text below:

![\[Diagram showing an API call that creates a Kinesis Video Streams pool.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/media-stream-pool-architecture.png)


In the diagram:

1. You call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html) API.

1. The media pipeline control plane creates and manages the Kinesis Video Streams (KVS) and the pool on your behalf in your account.

KVS pool operation, the process of creating, updating, and deleting streams in the pool, is asynchronous. As a result, Event Bridge notifications use the `Chime Media Pipeline Kinesis Video Pool State Change` detail type to communicate the status of the streams in a pool.

You can create a pool once and reuse it across different meetings. You can also create different pools as needed, and delete pools when you don't need them.

Pools scale up automatically, based on your concurrent call burst. You can delete any unneeded pools.

**Note**  
When you delete a pool, you must wait for pool to be completely deleted before you delete the KVS streams in the pool. An Event Bridge notification will indicate when the pool has been completely deleted. That happens after all the meetings that use the pool have ended. You can also call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipelineKinesisVideoStreamPool.html) API to view the `PoolId` for a given KVS pool.  
When you invoke the Kinesis Video Streams [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_DeleteStream.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_DeleteStream.html) API, you can use that naming string to search for and delete the streams in a pool. You can also call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipelineKinesisVideoStreamPool.html) API to view the `PoolId` for a given KVS pool. The examples in the next section explain how.

# Example code for Kinesis Video Streams pools for Amazon Chime SDK media stream pipelines
<a name="pool-creation-code"></a>

The following examples show how to create, update, get, list, and delete Kinesis Video Streams (KVS) pools. Expand each section to learn more.

## Imports and common variables
<a name="imports-variables"></a>

```
'''
Define imports and common variables
'''

import boto3
from uuid import uuid4
import json

client = boto3.client("chime-sdk-media-pipelines", region_name='us-east-1')
pool_name = 'MyDemoKvsPool'

def pretty_print_json(obj):
    print(json.dumps(obj, default=str, indent=4))
```

## CreateMediaPipelineKinesisVideoStreamPool
<a name="create-stream-sample"></a>

```
response = client.create_media_pipeline_kinesis_video_stream_pool(
        StreamConfiguration={
            'Region': 'us-east-1',
            'DataRetentionInHours': 24
        },
        PoolName=pool_name,
        ClientRequestToken=str(uuid4()),
        Tags=[
            {
                'Key': 'MyTagForAccessControl',
                'Value': 'SomeTagValue'
            },
        ]
)

pretty_print_json(response['KinesisVideoStreamPoolConfiguration'])
```

**Output**:

```
{
    "PoolArn": "arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/MyDemoKvsPool",
    "PoolName": "MyDemoKvsPool",
    "PoolId": "ChimeMediaPipelines-MyDemoKvsPool-1f4e1a69-e718-4884-bf92-8a393ac0405b",
    "PoolStatus": "CREATING",
    "StreamConfiguration": {
        "Region": "us-east-1",
        "DataRetentionInHours": 24
    },
    "CreatedTimestamp": "2023-10-13 01:26:09.979000+00:00",
    "UpdatedTimestamp": "2023-10-13 01:26:09.979000+00:00"
}
```

## GetMediaPipelineKinesisVideoStream
<a name="get-stream-sample"></a>

```
response = client.get_media_pipeline_kinesis_video_stream_pool(
        Identifier=pool_name
)

pretty_print_json(response['KinesisVideoStreamPoolConfiguration'])
```

**Output**:

```
{
    "PoolArn": "arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/MyDemoKvsPool",
    "PoolName": "MyDemoKvsPool",
    "PoolId": "ChimeMediaPipelines-MyDemoKvsPool-1f4e1a69-e718-4884-bf92-8a393ac0405b",
    "PoolStatus": "ACTIVE",
    "StreamConfiguration": {
        "Region": "us-east-1",
        "DataRetentionInHours": 24
    },
    "CreatedTimestamp": "2023-10-13 01:26:09.979000+00:00",
    "UpdatedTimestamp": "2023-10-13 01:26:09.979000+00:00"
}
```

## UpdateMediaPipelineKinesisVideoStream
<a name="update-stream-sample"></a>

```
response = client.update_media_pipeline_kinesis_video_stream_pool(
    Identifier=pool_name,
    StreamConfiguration={
        'DataRetentionInHours': 48
    }
)
pretty_print_json(response['KinesisVideoStreamPoolConfiguration'])
```

**Output**:

```
{
    "PoolArn": "arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/MyDemoKvsPool",
    "PoolName": "MyDemoKvsPool",
    "PoolId": "ChimeMediaPipelines-MyDemoKvsPool-d08c26ae-0336-4e2e-acdf-805a7d71b891",
    "PoolStatus": "UPDATING",
    "PoolSize": 40,
    "StreamConfiguration": {
        "Region": "us-east-1",
        "DataRetentionInHours": 48
    },
    "CreatedTimestamp": "2023-10-13 01:44:23.010000+00:00",
    "UpdatedTimestamp": "2023-10-13 01:44:28.486000+00:00"
}
```

## ListMediaPipelineKinesisVideoStream
<a name="list-stream-sample"></a>

```
list_of_pools = []
max_results = 100
next_token = None
while(True):
    if next_token:
        response = client.list_media_pipeline_kinesis_video_stream_pools(
            NextToken=next_token,
            MaxResults=max_results
        )
    else:
        response = client.list_media_pipeline_kinesis_video_stream_pools(
            MaxResults=max_results
        )

    list_of_pools.extend(response['KinesisVideoStreamPools'])
    next_token = response.get('NextToken')
    if not next_token:
        break
pretty_print_json(list_of_pools)
```

**Output**:

```
[
    {
        "PoolName": "MyDemoKvsPool",
        "PoolId": "ChimeMediaPipelines-MyDemoKvsPool-6588e703-f046-4288-ba7f-0c03de76a6bb",
        "PoolArn": "arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/MyDemoKvsPool"
    }
]
```

## DeleteMediaPipelineKinesisVideoStream
<a name="delete-stream-sample"></a>

```
client.delete_media_pipeline_kinesis_video_stream_pool(
    Identifier=pool_name
)
```

**Output**: A successful `delete_media_pipeline_kinesis_video_stream_pool` request has no body.

# Creating Amazon Chime SDK media stream pipelines
<a name="create-stream-pipeline"></a>

The chime media stream pipeline must belong to the same AWS account as the Amazon Chime SDK meeting. You create the Amazon Chime SDK media stream pipeline by calling the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaStreamPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaStreamPipeline.html) API and specifying a source and a sink.

The following diagram shows the architecture of an Amazon Chime SDK media stream pipeline. Numbers in the diagram correspond to the numbered text below.

![\[Diagram showing an API call that creates a media stream pool.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/media-stream-pipe-architecture.png)


In the diagram:

1. You call the `CreateMediaStreamPipeline` API. In the request, specify the sources and sinks for the streams. whether you want to capture individual audio, mixed audio, or both. Include the ARN of your KVS pool in the request.
   + The sources array consists of the `SourceType` and `SourceArn`. You must use the `ChimeSdkMeeting SourceType`. The `SourceArn` is the ARN of the `ChimeSdkMeeting`.
   + The sinks array consists of the `SinkType`, `SinkArn`, `ReservedStreamCapacity`, and `MediaStreamType`. We only support the `KinesisVideoStreamPoolSinkType`. The `SinkArn` is the ARN of the `KinesisVideoStreamPool`. The `MediaStreamType` controls the type of media streamed to the sink, either `MixedAudio` or `IndividualAudio`. `ReservedStreamCapacity` sets the number of streams allocated for the `MediaStreamType` from the `KinesisVideoStreamPool`.
     + If you want to stream both `IndividualAudio` and `MixedAudio`, create two sink objects in the `Sinks` array, one for `IndividualAudio`, another for `MixedAudio`. The `SinkArn` (the ARN of the `KinesisVideoStreamPool`) can vary for each sink.
     + To stream just individual audio or mixed audio, create one sink object with the desired `MediaStreamType`.
   + Note the following:
     + When invoking the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaStreamPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaStreamPipeline.html) API with `KinesisVideoStreamPool` as the `SinkType`, the `SinkARN` must belong to the control plane region in which `CreateMediaStreamPipeline` is being invoked.

       For example, if you create a media stream pipeline in `us-east-1`, you must use a `KinesisVideoStreamPool` in `us-east-1`.
     + `ReservedStreamCapacity` should be **1** when you specify the `MixedAudio` `MediaStreamType`, and between **1-10** when you specify the `IndividualAudio` `MediaStreamType`.

1. The media pipeline data plane calls the KVS [ PutMedia ](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_PutMedia.html) API to store individual audio in a KVS stream that belongs to the KVS pool that you specify.

1. The media pipeline data plane calls the KVS `PutMedia` API to store mixed audio in a stream that belongs to the KVS pool that you specify.

**Note**  
After calling the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaStreamPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaStreamPipeline.html) API, builders can use [media pipeline events](media-pipe-events.md) or call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_GetMediaPipeline.html) API to determine if the pipeline state is `InProgress`.  
Once the pipeline state reaches `InProgress`, the media—any combination of `IndividualAudio` and `MixedAudio`—streams to KVS.   
For the `IndividualAudio` stream type, a 1:1 mapping exists between attendee IDs and the KVS stream allocated from the `KinesisVideoStreamPool`. The mapping applies for the life of the media pipeline.  
To know which KVS stream maps to an attendee ID, or is assigned for MixedAudio, use one of the following techniques:  
Use [Event Bridge Notifications](media-stream-event-bridge.md). Each notification provides information such as attendee IDs and the KVS ARN that streams the attendee’s audio. When a `IndividualAudio` or `MixedAudio` streaming session starts, we send a `chime:MediaPipelineKinesisVideoStreamStart` event. Streaming sessions end when an attendee leaves the call (for `IndividualAudio`), or when the meeting ends.
Use the persistent metadata that the Kinesis Video Streams send with each fragment. The metadata contains information similar to what Event Bridge sends. Builders need to parse all the streams of the `KinesisVideoStreamPool` by specifying the pool name as the prefix in the [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_ListStreams.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_ListStreams.html) Kinesis Video Streams API using this solution.
Media Stream pipeline termination happens when the meeting is deleted, or the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html) API is invoked for that media stream pipeline. An [Event Bridge notification](media-pipe-events.md) is also sent to indicate the media pipeline termination.

# Example code for Amazon Chime SDK media stream pipelines
<a name="pipeline-creation-code"></a>

The following examples show how to create media stream pipelines for mixed audio, individual audio, and both. Expand each section to learn more.

## CreateMediaStreamPipeline for mixed audio
<a name="create-mixed-sample"></a>

```
response = client.create_media_stream_pipeline(
    Sources=[
        {
            'SourceType': 'ChimeSdkMeeting',
            'SourceArn': 'arn:aws:chime:us-east-1:account-ID:meeting/bed804cf-8cf0-4991-9b8d-d1acc2987433'
        },
    ],
    Sinks=[
        {
            'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
            'SinkType': 'KinesisVideoStreamPool',
            'ReservedStreamCapacity': 1,
            'MediaStreamType': 'MixedAudio'
        },
    ],
    ClientRequestToken='sample token',
    Tags=[
        {
            'Key': 'sample key',
            'Value': 'sample value'
        },
    ]
)
```

**Response**:

```
{
    'MediaStreamPipeline': {
        'MediaPipelineId': '45bc79a0-4591-4ebe-a642-d42c4e279f2d',
        'MediaPipelineArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline/45bc79a0-4591-4ebe-a642-d42c4e279f2d',
        'CreatedTimestamp': '2023-07-25T21:48:48.265Z',
        'UpdatedTimestamp': '2023-07-25T21:48:48.376Z',
        'Status': 'Initializing',
        'Sources': [
            {
                'SourceType': 'ChimeSdkMeeting',
                'SourceArn': 'arn:aws:chime:us-east-1:account-ID:meeting/bed804cf-8cf0-4991-9b8d-d1acc2987433'
            },
        ],
        'Sinks': [
            {
                'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
                'SinkType': 'KinesisVideoStreamPool',
                'ReservedStreamCapacity': 1,
                'MediaStreamType': 'MixedAudio'
            },
        ]
    }
}
```

## CreateMediaStreamPipeline for individual audio
<a name="create-individual-sample"></a>

```
response = client.create_media_stream_pipeline(
    Sources=[
        {
            'SourceType': 'ChimeSdkMeeting',
            'SourceArn': 'arn:aws:chime:us-east-1:account-ID:meeting/bed804cf-8cf0-4991-9b8d-d1acc2987433'
        },
    ],
    Sinks=[
        {
            'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
            'SinkType': 'KinesisVideoStreamPool',
            'ReservedStreamCapacity': 5,
            'MediaStreamType': 'IndividualAudio'
        },
    ],
    ClientRequestToken='sample token',
    Tags=[
        {
            'Key': 'sample key',
            'Value': 'sample value'
        },
    ]
)
```

**Response**:

```
{
    'MediaStreamPipeline': {
        'MediaPipelineId': '45bc79a0-4591-4ebe-a642-d42c4e279f2d',
        'MediaPipelineArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline/45bc79a0-4591-4ebe-a642-d42c4e279f2d',
        'CreatedTimestamp': '2023-07-25T21:48:48.265Z',
        'UpdatedTimestamp': '2023-07-25T21:48:48.376Z',
        'Status': 'Initializing',
        'Sources': [
            {
                'SourceType': 'ChimeSdkMeeting',
                'SourceArn': 'arn:aws:chime:us-east-1:account-ID:meeting/bed804cf-8cf0-4991-9b8d-d1acc2987433'
            },
        ],
        'Sinks': [
            {
                'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
                'SinkType': 'KinesisVideoStreamPool',
                'ReservedStreamCapacity': 5,
                'MediaStreamType': 'IndividualAudio'
            },
        ]
    }
}
```

## CreateMediaStreamPipeline for mixed and individual audio
<a name="create-both-sample"></a>

```
response = client.create_media_stream_pipeline(
    Sources=[
        {
            'SourceType': 'ChimeSdkMeeting',
            'SourceArn': 'arn:aws:chime:us-east-1:account-ID:meeting/bed804cf-8cf0-4991-9b8d-d1acc2987433'
        },
    ],
    Sinks=[
        {
            'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
            'SinkType': 'KinesisVideoStreamPool',
            'ReservedStreamCapacity': 1,
            'MediaStreamType': 'MixedAudio'
        },
        {
            'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
            'SinkType': 'KinesisVideoStreamPool',
            'ReservedStreamCapacity': 5,
            'MediaStreamType': 'IndividualAudio'
        },
    ],
    ClientRequestToken='sample token',
    Tags=[
        {
            'Key': 'sample key',
            'Value': 'sample value'
        },
    ]
)
```

**Response**:

```
{
    'MediaStreamPipeline': {
        'MediaPipelineId': '45bc79a0-4591-4ebe-a642-d42c4e279f2d',
        'MediaPipelineArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline/45bc79a0-4591-4ebe-a642-d42c4e279f2d',
        'CreatedTimestamp': '2023-07-25T21:48:48.265Z',
        'UpdatedTimestamp': '2023-07-25T21:48:48.376Z',
        'Status': 'Initializing',
        'Sources': [
            {
                'SourceType': 'ChimeSdkMeeting',
                'SourceArn': 'arn:aws:chime:us-east-1:account-ID:meeting/bed804cf-8cf0-4991-9b8d-d1acc2987433'
            },
        ],
        'Sinks': [
            {
                'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
                'SinkType': 'KinesisVideoStreamPool',
                'ReservedStreamCapacity': 1,
                'MediaStreamType': 'MixedAudio'
            },
            {
                'SinkArn': 'arn:aws:chime:us-east-1:account-ID:media-pipeline-kinesis-video-stream-pool/foo',
                'SinkType': 'KinesisVideoStreamPool',
                'ReservedStreamCapacity': 5,
                'MediaStreamType': 'IndividualAudio'
            },
        ]
    }
}
```

# Using Event Bridge notifications for Amazon Chime SDK media stream pipelines
<a name="media-stream-event-bridge"></a>

In addition to the [Using Amazon Chime SDK media pipeline events](media-pipe-events.md), media stream pipelines send Event Bridge notifications when they start and stop streaming to KVS, and when video pool states change.

**Topics**
+ [Understanding Amazon Chime SDK media stream pipeline events](stream-pipe-events.md)
+ [Understanding Kinesis Video Streams pool events for Amazon Chime SDK media stream pipelines](media-stream-pool-events.md)

# Understanding Amazon Chime SDK media stream pipeline events
<a name="stream-pipe-events"></a>

Media stream pipelines send the following events. Expand each section to learn more.

## Amazon Chime Media Stream Pipeline Kinesis Video Stream Start
<a name="stream-pipe-kvs-start"></a>

The Amazon Chime SDK media pipeline sends this event when the media stream pipeline starts receiving audio from the meeting and streaming that audio to KVS. Empty `AttendeeId` and `ExternalUserId` fields indicate that the media pipeline sent mixed audio to the KVS stream.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamStart", 
        "timestamp": 1627503649251, 
        "meetingId": "1e6bf4f5-f4b5-4917-b8c9-bda45c340706", 
        "externalMeetingId": "Meeting_Id", 
        "mediaPipelineId": "e40ee45e-2ed1-408e-9156-f52b8208a491", 
        "mediaRegion": "ap-southeast-1",
        
        "attendeeId": "Attendee_Id", 
        "externalUserId": "External_User_Id",
                
        "kinesisVideoStreamArn": "arn:aws:kinesisvideo:us-east-1:123456:stream/Chime*",
        "startFragmentNumber": "1234567899444",
        "startTime": "yyyy-mm-ddThh:mm:ssZ"
                
    }
}
```

## Amazon Chime Media Stream Pipeline Kinesis Video Stream End
<a name="stream-pipe-kvs-stop"></a>

The media pipeline sends this event to Event Bridge when streaming to KVS ends.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamEnd", 
        "timestamp": 1627503649251, 
        "meetingId": "1e6bf4f5-f4b5-4917-b8c9-bda45c340706", 
        "externalMeetingId": "Meeting_Id", 
        "mediaPipelineId": "e40ee45e-2ed1-408e-9156-f52b8208a491", 
        "mediaRegion": "ap-southeast-1",
        
        "attendeeId": "Attendee_Id", 
        "externalUserId": "External_User_Id",
                
        "kinesisVideoStreamArn": "arn:aws:kinesisvideo:us-east-1:123456:stream/Chime*",
        "startFragmentNumber": "1234567899444",
        "startTime": "yyyy-mm-ddThh:mm:ssZ",
        "endTime": "yyyy-mm-ddThh:mm:ssZ",
        "endFragmentNumber": "1234567899555"
    }
}
```

# Understanding Kinesis Video Streams pool events for Amazon Chime SDK media stream pipelines
<a name="media-stream-pool-events"></a>

Media pipelines send the following events to Event Bridge when the pools' states change. Expand each section to learn more.

## Amazon Chime Media Pipeline Kinesis Video Pool Active
<a name="kvs-pool-active"></a>

The media pipeline sends this event is sent after the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_CreateMediaPipelineKinesisVideoStreamPool.html) API creates a pool.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline Kinesis Video Pool State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamPoolActive", 
        "timestamp": 1627503649251,
        "mediaRegion": "ap-southeast-1",
        "poolArn" : "ARN of the KVS Pool"
    }
}
```

## Amazon Chime Chime Media Pipeline Kinesis Video Pool Updated
<a name="kvs-pool-updated"></a>

The media pipeline sends this event after the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_UpdateMediaPipelineKinesisVideoStreamPool.html) API updates a pool.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline Kinesis Video Pool State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamPoolUpdated", 
        "timestamp": 1627503649251,
        "mediaRegion": "ap-southeast-1",
        "poolArn" : "ARN of the KVS Pool"
    }
}
```

## Amazon Chime Media Pipeline Kinesis Video Pool Deleted
<a name="kvs-pool-deleted"></a>

The media pipeline sends this event to Event Bridge when the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipelineKinesisVideoStreamPool.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipelineKinesisVideoStreamPool.html) deletes a pool.

For more information about deleting pools, refer to [Creating a Kinesis Video Streams pool for Amazon Chime SDK media stream pipelines](create-kvs-pool.md), in this section.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline Kinesis Video Pool State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamPoolDeleted", 
        "timestamp": 1627503649251,
        "mediaRegion": "ap-southeast-1",
        "poolArn" : "ARN of the KVS Pool"
    }
 }
```

## Amazon Chime Media Pipeline Kinesis Video Pool Temporary Failure
<a name="kvs-pool-temp-failure"></a>

The media pipeline sends the following event to Event Bridge when a video pool fails temporarily.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline Kinesis Video Pool State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamPoolTemporaryFailure", 
        "timestamp": 1627503649251,
        "mediaRegion": "ap-southeast-1",
        "poolArn" : "ARN of the KVS Pool"
    }
 }
```

## Amazon Chime Media Pipeline Kinesis Video Pool Permanent Failure
<a name="kvs-pool-perm-failure"></a>

The media pipeline sends the following event to Event Bridge when a video pool fails permanently.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline Kinesis Video Pool State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamPoolPermanentFailure", 
        "timestamp": 1627503649251,
        "mediaRegion": "ap-southeast-1",
        "poolArn" : "ARN of the KVS Pool"
    }
}
```

You will receive the following additional media pipeline event if your AWS account has exceeded its Amazon Kinesis video stream limit.

```
{
    "version": "0",
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483",
    "detail-type": "Chime Media Pipeline Kinesis Video Pool State Change",
    "source": "aws.chime",
    "account": "111122223333",
    "time": "2021-07-28T20:20:49Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "eventType": "chime:MediaPipelineKinesisVideoStreamPoolStreamLimitExceeded",
        "timestamp": 1627503649251,
        "mediaRegion": "ap-southeast-1",
        "poolArn" : "ARN of the KVS Pool"
    }
}
```

# Using Amazon Chime SDK media stream pipelines data
<a name="media-stream-tips-tricks"></a>

You can use the metadata in the notifications to get KVS ARNs, fragment numbers, and fragment timestamps. That information can help you to process the audio data in a KVS stream.

Also, you can use KVS ARNs with the KVS APIs to read data from a stream. Depending on the use case, you call the [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_GetMedia.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_GetMedia.html) and [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_GetMediaForFragmentList.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_GetMediaForFragmentList.html) APIs. Typically, a `GetMediaForFragmentList` call is preceded by a call to the [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_ListFragments.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_reader_ListFragments.html) API. For more information, refer [Reading data from streams](https://aws.amazon.com/kinesis/video-streams/faqs/), in the *Amazon Kinesis Video Streams FAQs*.

Depending on the use case, builders can use the Kinesis Video Streams parser library, which in turn uses the KVS [https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_GetMedia.html](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_GetMedia.html) API.

Media stream pipelines add the following meeting and attendee metadata to each fragment.

```
"meetingId"
"externalMeetingId"
"attendeeId"
"externalUserId"
"sampleRate"
"channels"
```

Media data is stored in MKV format. All MKV audio data is AAC encoded. For more information, see [Kinesis Video Streams data model](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/how-data.html), in the *Kinesis Video Streams Developer Guide*.

# Compositing audio and video into a single view in Amazon Chime SDK meetings
<a name="pipeline-compositing"></a>

The Amazon Chime SDK media pipelines support compositing of audio, webcam videos, and content-share video streams into a single view. You can then use live connector to send that single view to streaming services such as Amazon Interactive Video Service, Twitch, or YouTube Live. Composited video can also be captured to Amazon Simple Storage Service for storage or further consumption.

Compositing uses a default screen layout called `GridView`, which has the following behaviors. 
+ When only webcam videos are active, `GridView` organizes the streams in the following grid pattern:  
![\[A four-column, four-row grid showing the outlines of people.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/grid-no-content-share.png)

  The grid displays a maximum of 25 webcam streams, and it orders the tiles by when users turn on their cameras.
+ `GridView` provides two canvas orientations, `Landscape` and `Portrait`. Landscape, the default orientation, supports video resolutions of 1280x720 and 1920x1080 for FHD. Portrait supports resolutions of 720x1280 and 1080x1920 for FHD.
+ You can configure the order, position, total number, tile aspect ratio, corner radius, border color, border thickness and highlight color of the video tiles.
+ During a meeting, when someone shares their screen, the webcam video tiles transition dynamically to make room for the content share. You control those transitions, and the locations of the video tiles, by using one of the layout configurations described in the next section.

**About the layout configurations**  
When someone starts a content share, you can choose how to composite the content share and webcam video streams by using one of the following layout configurations.
+ `ActiveSpeakerOnlyConfiguration` composites the content video full screen, with the active speaker’s webcam video overlaid in a corner. You can specify the corner.
+ `PresenterOnlyConfiguration` composites the content video full screen, with the presenter's webcam video overlaid in a corner. You can specify the corner.
+ `VerticalLayoutConfiguration` composites the content video with the webcam video in an adjacent vertical column. You can display the column to the right or left of the content share.
+ `HorizontalLayoutConfiguration` composites the content video with the webcam video in an adjacent horizontal row. You can display the row above or below the content share.

Composited layouts automatically transition between `GridView` and your chosen layout, based on whether content share is active or not.

The following topics explain how to use the global `GridView` settings and each configuration layout.

**Topics**
+ [Setting canvas orientation for compositing in Amazon Chime SDK meetings](canvas-orientation.md)
+ [Setting border and corner attributes for compositing in Amazon Chime SDK meetings](video-attribute.md)
+ [Using the layout configurations for compositing in Amazon Chime SDK meetings](compositing-layouts.md)

# Setting canvas orientation for compositing in Amazon Chime SDK meetings
<a name="canvas-orientation"></a>

In compositing, the *canvas* contains all your video streams. You can specify a `Landscape` or `Portrait` orientation for the canvas. Landscape provides a 16:9 aspect ratio. Portrait provides a 9:16 aspect ratio.

The following image shows the portrait orientation.

![\[Image showing two video tiles in a portrait (vertical) window.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/compositing-portrait-with-tile.png)


The following example shows how to implement a portrait canvas with the video tile in the upper-right corner. In this example, the active speaker appears in the tile. For more information, see [ActiveSpeakerOnlyConfiguration](compositing-layouts.md#active-speaker-only)

```
{
   "CompositedVideo":{
      "Layout":"GridView",
      "Resolution":"FHD",
      "GridViewConfiguration":{
         "ContentShareLayout":"ActiveSpeakerOnly",
         "ActiveSpeakerOnlyConfiguration":{
            "ActiveSpeakerPosition":"TopRight"
         }
      },
      "CanvasOrientation": "Portrait"       
   }
}
```

The following image shows the landscape orientation.

![\[Image showing two video tiles in a landscape (horizontal) window.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/compositing-landscape-with-tile.png)


**CanvasOrientation**  
*Description* – The orientation setting, Landscape or Portrait.  
*Allowed values* – `Landscape` \$1 `Portrait`  
*Required* – No  
*Default* – Landscape

# Setting border and corner attributes for compositing in Amazon Chime SDK meetings
<a name="video-attribute"></a>

As desired, you can use the `VideoAttribute` parameter to specify border and corner settings for your video tiles. You can specify colors, widths, and rounded corners. You can also specify a highlight color, and the border changes to that color when someone speaks. 

Your attribute settings apply to all layouts, regardless of content sharing.

The following image shows a video tile with a border color and corner radius applied.

![\[Image of a screen share and video tile with a red border and rounded corners.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/compositing-speaker-border.png)


The following example shows how to use each attribute. In this case, video tiles have rounded corners with a five-pixel radius. The tiles have a green border, also five pixels wide. When the speaker talks, the `HighlightColor` attribute changes the border color to red.

```
{
   "CompositedVideo":{
      "Layout":"GridView",
      "Resolution":"FHD",
      "GridViewConfiguration":{
         "ContentShareLayout":"ActiveSpeakerOnly",
         "ActiveSpeakerOnlyConfiguration":{
            "ActiveSpeakerPosition":"TopRight"
         }
         "VideoAttribute": {
            "CornerRadius"   : 10,                               
            "BorderColor"    : "Green", 
            "HighlightColor" : "Red",  
            "BorderThickness": 5 
          },      
       }
   }
}
```

**VideoAttribute**  
*Description* – Specifies the settings for video tile borders and rounded corners  
*Allowed values* – `BorderColor` \$1 `BorderThickness` \$1 `CornerRadius` \$1 `HighlightColor`  
*Required* – No

**VideoAttribute.BorderColor**  
*Description* – Defines the border color for all video tiles  
*Allowed values* – Color names, such as Red, Green, or Blue  
*Required* – No

**VideoAttribute.BorderThickness**  
*Description* – Defines the border thickness in pixels for all video tiles  
*Type* – Integer  
*Allowed values* – 1–20  
*Required* – No

**VideoAttribute.CornerRadius**  
*Description* – Defines the corner radius in pixels for all video tiles.   
*Type* – Integer  
*Allowed values* – 1–20  
*Required* – No

**VideoAttribute.HighlightColor**  
*Description* – Defines a border color that appears when a presenter or speaker talks  
*Allowed values* – Color names, such as Red, Green, or Blue  
*Required* – No

# Using the layout configurations for compositing in Amazon Chime SDK meetings
<a name="compositing-layouts"></a>

The following topics explain how to use the different configuration layouts. The layouts only take effect when someone starts a content share. Expand each section to learn more.

## ActiveSpeakerOnlyConfiguration
<a name="active-speaker-only"></a>

`ActiveSpeakerOnlyConfiguration` displays the content share and the active speaker’s video, meaning the person talking appears in the small video tile that overlays the content share stream.

The following image shows the configuration and the available locations for the speaker tile.

![\[Image showing a large video tile in the center of a window and a small tile in the upper-left.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/compositing-active-speaker-4x.png)


The following example shows how to implement the `ActiveSpeakerOnly` layout programmatically. In this case, the presenter tile appears in the upper-left corner.

```
{
   "CompositedVideo":{
      "Layout":"GridView",
      "Resolution":"FHD",
      "GridViewConfiguration":{
         "ContentShareLayout":"ActiveSpeakerOnly",
         "ActiveSpeakerOnlyConfiguration":{
            "ActiveSpeakerPosition":"TopLeft"
         }
      }
   }
}
```

**ActiveSpeakerOnlyConfiguration**  
*Description* – The configuration settings for an `ActiveSpeakerOnly` video tile  
*Type* – ActiveSpeakerOnlyConfiguration object  
*Required* – No

**ActiveSpeakerOnlyConfiguration.ActiveSpeakerPosition**  
*Description* – The position of the active speaker video tile  
*Type* – String  
*Valid values* – `TopLeft` \$1 `TopRight` \$1 `BottomLeft` \$1 `BottomRight`  
*Required* – No  
*Default* – `TopRight`

## PresenterOnlyConfiguration
<a name="presenter-only"></a>

`PresenterOnlyConfiguration` displays the content share and only the presenter’s video regardless of who talks. The following image shows the configuration.

![\[Image of four screens. Each screen has a share window in the middle and a video tile in each corner.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/compositing-presenter-only-4x.png)


The following example shows how to implement the layout programmatically with the presenter at top-right.

```
{
    "CompositedVideo": {
    "Layout": "GridView",
    "Resolution": "FHD",
     "GridViewConfiguration": {
         "ContentShareLayout": "PresenterOnly",
         "PresenterOnlyConfiguration": { 
             "PresenterPosition": "TopRight"
             }
         }           
     }
}
```

**PresenterOnlyConfiguration**  
*Description* – The configuration settings for a `PresenterOnly` layout  
*Type* – `PresenterOnlyConfiguration` object  
*Required* – No

**PresenterOnlyConfiguration.PresenterPosition**  
*Description* – The position of the presenter video tile  
*Type* – String  
*Valid values* – `TopLeft` \$1 `TopRight` \$1 `BottomLeft` \$1 `BottomRight`  
*Required* – No  
*Default* – `TopRight`

## HorizontalLayoutConfiguration
<a name="horizontal-layout"></a>

`HorizontalLayoutConfiguration` displays the content sharing and video streams horizontally. You can use the `TilePosition` setting to display the tiles above or below the content share stream. Presenters always appear on the left. Additional tiles appear in the order dictated by `JoinSequence`. 

The following image shows the tiles below the content share stream.

![\[Image showing a large central tile and 4 smaller tiles in a line below.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/compositing-horizontal-bottom.png)


The following example shows how to implement a horizontal layout programmatically. In this case, the layout orders the tiles by `SpeakerSequence` and places them below the screen share. The layout allows a maximum of four tiles and applies a 16/9 aspect ratio.

```
{
   "CompositedVideo":{
      "Layout":"GridView",
      "Resolution":"FHD",
      "GridViewConfiguration":{
         "ContentShareLayout":"Horizontal",
         "HorizontalLayoutConfiguration":{
            "TileOrder":"SpeakerSequence",
            "TilePosition":"Bottom",
            "TileCount":4,
            "TileAspectRatio":"16/9"
         }
      }
   }
}
```

**HorizontalLayoutConfiguration**  
*Description* – The configuration settings for a horizontal layout  
*Type* – HorizontalLayoutConfiguration object  
*Required* – No

**HorizontalLayoutConfiguration.TilePosition**  
*Description* – Places tiles above or below a content share.  
*Type* - String  
*Valid values* – `Bottom` \$1 `Top`  
*Required* – No  
*Default* – Bottom

**HorizontalLayoutConfiguration.TileOrder**  
*Description* – Orders tiles by when users join or when they speak  
*Type* – String  
*Valid values* – `JoinSequence` \$1 `SpeakerSequence`  
*Required* – No  
*Default* – JoinSequence

**HorizontalLayoutConfiguration.TileCount**  
*Description* – Specifies the number of tiles that remain visible during a screen share  
*Type* – Integer  
*Valid values* – 1–10  
*Required* – No  
*Default* – 4

**HorizontalLayoutConfiguration.TileAspectRatio**  
*Description* – Specifies the tiles' aspect ratio  
*Type* – Integer  
*Valid values* – *n***/***n*  
*Required* – No  
*Default* – 16/9, value applies to all tiles

## VerticalLayoutConfiguration
<a name="vertical-layout"></a>

`VerticalLayoutConfiguration` displays the content share and the four most recent videos stacked on the right. Presenters always appear on top. Other attendees appear in the order dictated by `TileOrder`.

![\[Image showing a large video tile in the center of a window and 4 smaller tiles stacked on the right.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/grid-vertical.png)


The following example shows how to implement the vertical layout programmatically. In this case, the layout orders tiles by JoinSequence and places them to the right of the screen share. The layout allows a maximum of four tiles and applies a 16/9 aspect ratio.

```
{
   "CompositedVideo":{
      "Layout": "GridView",
      "Resolution": "FHD",
      "GridViewConfiguration":{
         "ContentShareLayout": "Vertical",
         "VerticalLayoutConfiguration":{
            "TileOrder": "JoinSequence",
            "TilePosition": "Right",
            "TileCount": 4,
            "TileAspectRatio": "16/9"
         }
      }
   }
}
```

**VerticalLayoutConfiguration**  
*Description* – The configuration settings for a vertical layout  
*Type* – VerticalLayoutConfiguration object  
*Required* – No

**VerticalLayoutConfiguration.TilePosition**  
*Description* – Places tiles to the right or left of a content share.  
*Type* – String  
*Valid values* – `Bottom` \$1 `Top`  
*Required* – No  
*Default* – Bottom

**VerticalLayoutConfiguration.TileOrder**  
*Description* – Orders tiles by when users join or when they speak  
*Type* – String  
*Valid values* – `JoinSequence` \$1 `SpeakerSequence`  
*Required* – No  
*Default* – JoinSequence

**VerticalLayoutConfiguration.TileCount**  
*Description* – Specifies the number of tiles  
*Type* – Integer  
*Valid values* – 1–10  
*Required* – No  
*Default* – 4

**VerticalLayoutConfiguration.TileAspectRatio**  
*Description* – Specifies the tiles' aspect ratio  
*Type* – Integer  
*Valid values* – *n***/***n*  
*Required* – No  
*Default* – 9/16, value applies to all tiles

# Creating a service-linked role for Amazon Chime SDK media pipelines
<a name="create-pipeline-role"></a>

The information in the following sections explains how to create a service-linked role that grants media pipelines access to your Amazon Chime SDK meetings.

**Topics**
+ [Setting role permissions](#pipeline-role-permissions)
+ [Creating the service-linked role](#create-sl-role)
+ [Editing the service-linked role](#edit-pipeline-role)
+ [Deleting the service-linked role](#delete-pipeline-role)
+ [Regions that support service-linked roles](#role-supported-regions)

## Setting role permissions
<a name="pipeline-role-permissions"></a>

media pipelines use a service-linked role named *AWSServiceRoleForAmazonChimeSDKMediaPipelines*. The role allows the capture pipelines to access Amazon Chime SDK meetings and publish metrics to Amazon CloudWatch on your behalf. The role trusts the `mediapipelines.chime.amazonaws.com` service.

The role permissions policy allows the Amazon Chime SDK to complete the following actions on all AWS resources:
+ Action: `cloudwatch:PutMetricData` on `all AWS resources`
+ Action: `chime:CreateAttendee` on `all AWS resources`
+ Action: `chime:DeleteAttendee` on `all AWS resources`
+ Action: `chime:GetMeeting` on `all AWS resources`
+ Action: `kinesisvideo:CreateStream` on `arn:aws:kinesisvideo:*:111122223333:stream/ChimeMediaPipelines-*`
+ Action: `kinesisvideo:PutMedia` on `arn:aws:kinesisvideo:*:111122223333:stream/ChimeMediaPipelines-*`
+ Action: `kinesisvideo:UpdateDataRetention` on `arn:aws:kinesisvideo:*:111122223333:stream/ChimeMediaPipelines-*`
+ Action: `kinesisvideo:DescribeStream` on `arn:aws:kinesisvideo:*:111122223333:stream/ChimeMediaPipelines-*`
+ Action: `kinesisvideo:GetDataEndpoint` on `arn:aws:kinesisvideo:*:111122223333:stream/ChimeMediaPipelines-*`
+ Action: `kinesisvideo:ListStreams` on `arn:aws:kinesisvideo:*:111122223333:stream/*`

You must configure permissions to allow an IAM entity, such as a user, group, or role, to create, edit, or delete a service-linked role. For more information about permissions, see [ Service linked role permissions](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#service-linked-role-permissions) in the *IAM User Guide*. 

## Creating the service-linked role
<a name="create-sl-role"></a>

You use the IAM console to create a service-linked role for use with Amazon Chime SDK media pipelines. You must have IAM administrative permissions to complete these steps. If you don't, contact a system administrator.

**To create the role**

1. Sign in to the AWS Management Console, and then open the IAM console at [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam).

1. In the navigation pane of the IAM console, choose **Roles**, and then choose **Create role**.

1. Choose the **AWS Service** role type, and then choose **Chime SDK Media Pipelines**.

   The IAM policy appears.

1. Select the check box next to the policy, then choose **Next: Tags**.

1. Choose **Next: Review**.

1. Edit the description as needed, then choose **Create role**.

You can also use the AWS CLI or the AWS API to create a service-linked role named *mediapipelines.chime.amazonaws.com*. In the AWS CLI, run this command:

```
aws iam create-service-linked-role --aws-service-name mediapipelines.chime.amazonaws.com
```

For more information creating the role, see [Creating a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#create-service-linked-role) in the *IAM User Guide*. If you delete this role, you can use this same process to create it again.

## Editing the service-linked role
<a name="edit-pipeline-role"></a>

You can't to edit the *AWSServiceRoleForAmazonChimeSDKMediaPipelines* service-linked role. After you create the role, you can't change its name because other entities may reference the role. However, you can use IAM to edit the role's description. For more information, see [Editing a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#edit-service-linked-role) in the *IAM User Guide*.

## Deleting the service-linked role
<a name="delete-pipeline-role"></a>

If don't need a service-linked role, we recommend that you delete it. To do that, you first delete the media pipelines that use the role. You can use the AWS CLI or the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaCapturePipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaCapturePipeline.html) API to delete the pipelines. 

**Using the CLI to delete pipelines**  
Use this command in the AWS CLI to delete media pipelines in your account.

```
aws chime-sdk-media-pipelines delete-media-capture-pipeline --media-pipeline-id Pipeline_Id
```

**Using an API to delete pipelines**  
Use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaCapturePipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaCapturePipeline.html) API to delete media pipelines in your account.

**Deleting the role**  
Once you delete the pipelines, you can use the IAM console, the AWS CLI, or the AWS API to delete the role. For more information about deleting roles, see [Deleting a Service-Linked Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html#delete-service-linked-role) in the *IAM User Guide*.

## Regions that support service-linked roles
<a name="role-supported-regions"></a>

Amazon Chime SDK supports using service-linked roles in all of the AWS Regions where the service is available. For more information, see [Amazon Chime SDK endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html) in the *Amazon Web Services General Reference*.

# Using Amazon Chime SDK media pipeline events
<a name="media-pipe-events"></a>

Each type of media pipeline sends lifecycle events, which you can use to trigger notifications and initiate downstream workflows. Some examples of using media pipeline events include:
+ Processing captured media after a media pipeline has completed.
+ Notifying meeting participants if a media pipeline has a temporary failure.
+ Stopping a meeting if a media pipeline fails permanently.

You can send events to Amazon EventBridge, Amazon Simple Notification Service (SNS), and Amazon Simple Queue Service (SQS). For more information, refer to [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) in the *Amazon EventBridge User Guide*.

## Amazon Chime SDK media pipeline created
<a name="media-pipeline-create"></a>

The Amazon Chime SDK sends this event when the media pipeline is created.

**Example: Event data**  
 The following is example data for this event.

```
{
    "version": "0", 
    "id": "5ee6265a-0a40-104e-d8fd-a3b4bdd78483", 
    "detail-type": "Chime Media Pipeline State Change", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "time": "2021-07-28T20:20:49Z", 
    "region": "us-east-1", 
    "resources": [], 
    "detail": {
        "version": "0", 
        "eventType": "chime:MediaPipelineInProgress", 
        "timestamp": 1627503649251, 
        "meetingId": "1e6bf4f5-f4b5-4917-b8c9-bda45c340706", 
        "externalMeetingId": "Meeting_Id",
        "mediaPipelineId": "e40ee45e-2ed1-408e-9156-f52b8208a491", 
        "mediaRegion": "ap-southeast-1"
    }
}
```

## Amazon Chime SDK media pipeline deleted
<a name="media-pipeline-delete"></a>

The Amazon Chime SDK sends this event after the media pipeline stops successfully. 

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0",
    "id": "9e11e429-97fd-9532-5670-fac3f7abc05f",
    "detail-type": "Chime Media Pipeline State Change",
    "source": "aws.chime",
    "account": "365135496707",
    "time": "2021-07-28T20:21:50Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "version": "0",
        "eventType": "chime:MediaPipelineDeleted",
        "timestamp": 1627503710485,
        "meetingId": "1e6bf4f5-f4b5-4917-b8c9-bda45c340706",
        "externalMeetingId": "Meeting_Id",
        "mediaPipelineId": "e40ee45e-2ed1-408e-9156-f52b8208a491",
        "mediaRegion": "ap-southeast-1"
    }
}
```

## Amazon Chime SDK media pipeline has a temporary failure
<a name="pipeline-temp-failure"></a>

The Amazon Chime SDK sends this event when the media pipeline has a temporary failure.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0",
    "id": "abc141e1-fc2e-65e8-5f18-ab5130f1035a",
    "detail-type": "Chime Media Pipeline State Change",
    "source": "aws.chime",
    "account": "365135496707",
    "time": "2021-07-28T21:16:42Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "version": "0",
        "eventType": "chime:MediaPipelineTemporaryFailure",
        "timestamp": 1627507002882,
        "meetingId": "7a5434e3-724a-4bbb-9eb6-2fb209dc0706",
        "externalMeetingId": "Meeting_Id",
        "mediaPipelineId": "ebd62f4e-04a9-426d-bcb0-974c0f266400",
        "mediaRegion": "eu-south-1"
    }
}
```

## Amazon Chime SDK media pipeline in progress
<a name="pipeline-in-progress"></a>

The Amazon Chime SDK sends this event when the media pipeline begins capturing artifacts.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0",
    "id": "9e11e429-97fd-9532-5670-fac3f7abc05f",
    "detail-type": "Chime Media Pipeline State Change",
    "source": "aws.chime",
    "account": "365135496707",
    "time": "2021-07-28T20:21:50Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "version": "0",
        "eventType": "chime:MediaPipelineInProgress",
        "timestamp": 1627503710485?,
        "meetingId": "1e6bf4f5-f4b5-4917-b8c9-bda45c340706",
        "externalMeetingId": "Meeting_Id",
        "mediaPipelineId": "e40ee45e-2ed1-408e-9156-f52b8208a491",
        "mediaRegion": "ap-southeast-1"
    }
}
```

## Amazon Chime SDK media pipeline permanent failure
<a name="pipeline-perm-failure"></a>

The Amazon Chime SDK sends this event when a media pipeline fails permanently.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0",
    "id": "9e11e429-97fd-9532-5670-fac3f7abc05f",
    "detail-type": "Chime Media Pipeline State Change",
    "source": "aws.chime",
    "account": "365135496707",
    "time": "2021-07-28T20:21:50Z",
    "region": "us-east-1",
    "resources": [],
    "detail": {
        "version": "0",
        "eventType": "chime:MediaPipelinePermanentFailure",
        "timestamp": 1627503710485,
        "meetingId": "1e6bf4f5-f4b5-4917-b8c9-bda45c340706",
        "externalMeetingId": "Meeting_Id",
        "mediaPipelineId": "e40ee45e-2ed1-408e-9156-f52b8208a491",
        "mediaRegion": "ap-southeast-1"
    }
}
```

# Setting Amazon S3 bucket permissions for Amazon Chime SDK media pipelines
<a name="s3-permissions"></a>

If you haven't created an Amazon S3 bucket, make sure you create yours in the account and Region where you host meetings. Also, make sure you grant adequate permissions to the service. For more information about creating an Amazon S3 bucket, see [Creating an Amazon S3 bucket for Amazon Chime SDK media capture pipelines](create-s3-bucket.md).

# Sending Amazon Chime SDK media pipeline events to CloudTrail
<a name="pipeline-cloudtrail"></a>

AWS enables CloudTrail for you when you create your AWS account. When a user calls a supported API in the media pipeline SDK, CloudTrail logs that activity for that API in **Event history**, along with other AWS events. You can view, search, and download the media pipeline events in your AWS account. For more information, see [Viewing Events with CloudTrail Event History](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) in the *CloudTrail User Guide*.

For an ongoing record of media pipeline events, you can create a *trail*. A trail enables CloudTrail to deliver log files to your Amazon S3 bucket. The following example shows a media pipeline trail. The data includes the user that called the API, the IAM role used to call the API, and timestamps. For more information about using CloudTrail see [Logging and monitoring](https://docs.aws.amazon.com/chime-sdk/latest/ag/monitoring-overview.html) in the *Amazon Chime SDK Administrator Guide*.

```
{
   "Records": [    
   {
      "eventVersion": "1.08",
      "userIdentity": {
          "type": "AssumedRole",
          "principalId": "ABCDEFGHIJKLMNOPQRSTUV:user-name",
          "arn": "arn:aws:sts::123456789101:assumed-role/role-name/user-name",
          "accountId": "109876543210",
          "accessKeyId": "ABCDEFGHIJKLMNOPQRSTUV",
          "sessionContext": {
              "sessionIssuer": {
                  "type": "Role",
                  "principalId": "ABCDEFGHIJKLMNOPQRSTUV",
                  "arn": "arn:aws:iam::109876543210:role/role-name",
                  "accountId": "012345678910",
                  "userName": "user-name"
                  },
          "webIdFederationData": {},
          "attributes": {
              "mfaAuthenticated": "false",
              "creationDate": "2022-03-08T19:34:55Z"
              }
          }
      },
      "eventTime": "2022-03-08T20:28:41Z",
     "eventSource": "chime-sdk-media-pipelines.amazonaws.com",
     "eventName": "CreateMediaCapturePipeline",
     "awsRegion": "us-east-1",
     "sourceIPAddress": "127.0.0.1",
     "userAgent": "[]/[]",
     "requestParameters": {
         "sourceType": "ChimeSdkMeeting",
         "sourceArn": "Hidden_For_Security_Reasons",
         "sinkType": "S3Bucket",
         "sinkArn": "Hidden_For_Security_Reasons",
         "chimeSdkMeetingConfiguration": {
             "artifactsConfiguration": {
                 "audio": {
                    "muxType": "AudioOnly"
                 },
            "video": {
                "state": "Enabled",
                "muxType": "VideoOnly"
                },
            "content": {
                "state": "Enabled",
                "muxType": "ContentOnly"
                }
            }
        }
      },
     "responseElements": {
        "mediaCapturePipeline": {
        "mediaPipelineId": "pipeline-uuid",
        "sourceType": "ChimeSdkMeeting",
        "sourceArn": "Hidden_For_Security_Reasons",
        "status": "Initializing",
        "sinkType": "S3Bucket",
        "sinkArn": "Hidden_For_Security_Reasons",
        "createdTimestamp": "2022-03-08T20:28:41.336Z",
        "updatedTimestamp": "2022-03-08T20:28:41.463Z",
        "chimeSdkMeetingConfiguration": {
            "artifactsConfiguration": {
                "audio": {
                    "muxType": "AudioOnly"
                },
            "video": {
                "state": "Enabled",
                 "muxType": "VideoOnly"
                 },
             "content": {
                 "state": "Enabled",
                 "muxType": "ContentOnly"
                 }
              }
            }
          }
      },
      "requestID": "request-id",
      "eventID": "event-id",
     "readOnly": false,
      "eventType": "AwsApiCall",
      "managementEvent": true,
      "eventCategory": "Management",
      "recipientAccountId": "112233445566",
      "tlsDetails": {
          "tlsVersion": "TLSv1.2",
          "clientProvidedHostHeader": "example.com"
       }
    },  
  ]
}
```

# Best practices for stopping Amazon Chime SDK media pipelines
<a name="stop-pipe-best-practices"></a>

As a best practice for stopping media pipelines, call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaPipeline.html) API. The API allows you to delete media capture and media live connector pipelines. You can also call the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaCapturePipeline.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_media-pipelines-chime_DeleteMediaCapturePipeline.html) API to delete media capture pipelines. All media pipelines stop when the meeting ends.

# Using Amazon Chime SDK live transcription
<a name="meeting-transcription"></a>

You use Amazon Chime SDK live transcription to generate live, user-attributed transcripts of your meetings. Amazon Chime SDK live transcription integrates with the Amazon Transcribe and Amazon Transcribe Medical services to generate transcripts of Amazon Chime SDK meetings while they're in progress.

Amazon Chime SDK live transcription processes each user’s audio separately for improved accuracy in multi-speaker scenarios. The Amazon Chime SDK uses its active talker algorithm to select the top two active talkers, and then sends their audio to Amazon Transcribe, in separate channels, via a single stream. Meeting participants receive user-attributed transcriptions via Amazon Chime SDK data messages. You can use transcriptions in a variety of ways, such as displaying subtitles, creating meeting transcripts, or using the transcriptions for content analysis.

Live transcription uses one stream to Amazon Transcribe for the duration of the meeting transcription. Standard Amazon Transcribe and Amazon Transcribe Medical costs apply. For more information, refer to [Amazon Transcribe Pricing](https://aws.amazon.com/transcribe/pricing/). For questions about usage or billing, contact your AWS account manager.

**Important**  
By default, Amazon Transcribe may use and store audio content processed by the service to develop and improve AWS AI/ML services as further described in section 50 of the [AWS Service Terms](https://aws.amazon.com/service-terms/). Using Amazon Transcribe may be subject to federal and state laws or regulations regarding the recording or interception of electronic communications. It is your and your end users’ responsibility to comply with all applicable laws regarding the recording, including properly notifying all participants in a recorded session or communication that the session or communication is being recorded, and obtaining all necessary consents. You can opt out from AWS using audio content to develop and improve AWS AI/ML services by configuring an AI services opt out policy using AWS Organizations.

**Topics**
+ [System architecture](#sys-architecture)
+ [Billing and usage](#billing-and-usage)
+ [Configuring your account for Amazon Chime SDK live transcription](configure-transcribe.md)
+ [Choosing Amazon Chime SDK live transcription options](transcription-options.md)
+ [Starting and stopping Amazon Chime SDK live transcription](initiate-transcription.md)
+ [Amazon Chime SDK live transcription parameters](#transcription-parameters)
+ [Understanding Amazon Chime SDK live transcription events](transcription-events.md)
+ [Understanding Amazon Chime SDK live transcription messages](process-msgs.md)
+ [Processing a received Amazon Chime SDK live transcript event](delivery-examples.md)
+ [Parsing Amazon Chime SDK transcripts](parse-transcripts.md)

## System architecture
<a name="sys-architecture"></a>

The Amazon Chime SDK creates real-time meeting transcriptions, without audio leaving the AWS network, via a service-side integration with your Amazon Transcribe or Amazon Transcribe Medical account. For improved accuracy, users’ audio is processed separately, then mixed into the meeting. The Amazon Chime SDK uses its active talker algorithm to select the top two active talkers, and then sends their audio to Amazon Transcribe or Amazon Transcribe Medical in separate channels via a single stream. For reduced latency, user-attributed transcriptions are sent directly to every meeting participant via data messages. When using a media pipeline to capture meeting audio, the meeting’s transcription information is also captured.

![\[A diagram showing the data flow of meeting transcription.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/transcription-architecture.png)


## Billing and usage
<a name="billing-and-usage"></a>

Live transcription uses one stream to Amazon Transcribe or Amazon Transcribe Medical for the duration of the meeting transcription. Standard Amazon Transcribe and Amazon Transcribe Medical costs apply. For more information, see [Amazon Transcribe Pricing](https://aws.amazon.com/transcribe/pricing/).. For questions about usage or billing, contact your AWS account manager.

# Configuring your account for Amazon Chime SDK live transcription
<a name="configure-transcribe"></a>

Before you can use Amazon Chime SDK live transcription, you must grant Amazon Chime SDK permission to call Amazon Transcribe and Amazon Transcribe Medical in your AWS account. You do that by adding the Chime Transcription service-linked role to your account. For information about creating the service-linked role for live transcription, refer to [Using roles with live transcription](https://docs.aws.amazon.com/chime-sdk/latest/ag/using-service-linked-roles-transcription.html) in the *Amazon Chime SDK Administration Guide*. For more information about IAM service-linked roles, refer to [Service Linked Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/using-service-linked-roles.html) in the *IAM User Guide*.

# Choosing Amazon Chime SDK live transcription options
<a name="transcription-options"></a>

When you use Amazon Chime SDK live transcription, you use [Amazon Transcribe](https://aws.amazon.com/transcribe/) or [Amazon Transcribe Medical](https://aws.amazon.com/transcribe/medical/) in your AWS account. You have access to all the [streaming languages supported by Amazon Transcribe](https://docs.aws.amazon.com/transcribe/latest/dg/what-is-transcribe.html), plus features such as [custom vocabularies](https://docs.aws.amazon.com/transcribe/latest/dg/how-vocabulary.html) and [vocabulary filters](https://docs.aws.amazon.com/transcribe/latest/dg/filter-unwanted-words.html). When using Amazon Transcribe Medical, you can choose a medical specialty, conversation type, and optionally provide any custom vocabulary. Standard Amazon Transcribe and Amazon Transcribe Medical costs apply.

The process of choosing transcription options follows these steps. 

## Step 1: Choosing a transcription service
<a name="choose-service"></a>

You need to decide which transcription service to use, [Amazon Transcribe](https://aws.amazon.com/transcribe/) or [Amazon Transcribe Medical](https://aws.amazon.com/transcribe/medical/). 

If your use case requires medical speech to text capabilities, you probably want to use Amazon Transcribe Medical. For all other use cases, you probably want to use Amazon Transcribe.

You specify which transcription service to use when you call the `StartMeetingTranscription` API:
+ To use Amazon Transcribe, specify a `TranscriptionConfiguration` with `EngineTranscribeSettings`. 
+ To use Amazon Transcribe Medical, specify a `TranscriptionConfiguration` with `EngineTranscribeMedicalSettings`.

## Step 2: Choosing a transcription Region
<a name="choose-region"></a>

You need to choose an AWS Region for the transcription service. For information about the available AWS Regions for Amazon Transcribe and Amazon Transcribe Medical, refer to the [AWS Regional Services](https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/) table.

 In general, the lowest latency between a meeting’s media Region and transcription Region provides the best user experience. For the lowest latency, use the same Region for media and transcription whenever possible. However, you may have other factors to consider in selecting a Region, such as regulatory requirements or the Regions where you have configured Amazon Transcribe or Amazon Transcribe Medical.

Amazon Transcribe and Amazon Transcribe Medical features, such as custom vocabularies or vocabulary filters, are Region specific. If you configure any of those features, you should do so identically in all of the AWS Regions in which you intend to use live transcription. Alternately, you can use the same Amazon Transcribe Region for all meetings.

You can specify the Region that the transcription service uses. You do that by adding the region name to the `Region` field of the transcription engine settings when you call the `StartMeetingTranscription` API. If you do not specify a Region, the Amazon Chime SDK attempts to use the transcription service in the meeting’s media region. To have the Amazon Chime SDK select the Region for the transcription service for you, specify `auto` in the `Region` field. When you do that, Amazon Chime selects the transcription service Region based the meeting’s media Region as described in the tables below. For more information about the `StartMeetingTranscription` API, refer to [Starting and stopping Amazon Chime SDK live transcription](initiate-transcription.md) in this guide.

**Note**  
The transcription region selected by the Amazon Chime SDK is subject to change as AWS, Amazon Chime SDK, Amazon Transcribe and Amazon Transcribe Medical make more regions available.

**Automatic region selection for Amazon Transcribe**  



|  Amazon Chime SDK Media Region  |  Region code  |  Transcription Region  | 
| --- | --- | --- | 
|  US East (Ohio)  |  us-east-2  | us-east-2  | 
|  US East (N. Virginia)  |  us-east-1  | us-east-1  | 
|  US West (N. California)  |  us-west-1  | us-west-2 | 
|  US West (Oregon)  |  us-west-2  | us-west-2  | 
|  Africa (Cape Town)**\$1**  |  af-south-1  | eu-west-2  | 
|  Asia Pacific (Mumbai)  |  ap-south-1  | eu-west-2 | 
|  Asia Pacific (Seoul)  |  ap-northeast-2  | ap-northeast-2 | 
|  Asia Pacific (Singapore)  |  ap-southeast-1  | ap-northeast-1 | 
|  Asia Pacific (Sydney)  |  ap-southeast-2  | ap-southeast-2 | 
|  Asia Pacific (Tokyo)  |  ap-northeast-1  | ap-northeast-1 | 
|  Canada (Central)  |  ca-central-1  | ca-central-1 | 
|  Europe (Frankfurt)   |  eu-central-1  | eu-central-1  | 
|  Europe (Ireland)  |  eu-west-1  | eu-west-1 | 
|  Europe (London)  |  eu-west-2  | eu-west-2  | 
|  Europe (Milan)**\$1**  |  eu-south-1  | eu-central-1  | 
|  Europe (Paris)  |  eu-west-3  | eu-central-1  | 
|  Europe (Stockholm)  |  eu-north-1  | eu-central-1 | 
|  South America (São Paulo)  |  sa-east-1  | sa-east-1 | 
|  GovCloud (US-East)  |  us-gov-east-1  |  us-gov-west-1  | 
|  GovCloud (US-West)  |  us-gov-west-1  |  us-gov-west-1  | 

**Automatic region selection for Amazon Transcribe Medical**  



|  Amazon Chime SDK Media Region  |  Region code  |  Transcription Region  | 
| --- | --- | --- | 
|  US East (Ohio)  |  us-east-2  | us-east-2 | 
|  US East (N. Virginia)  |  us-east-1  | us-east-1 | 
|  US West (N. California)  |  us-west-1  | us-west-2 | 
|  US West (Oregon)  |  us-west-2  | us-west-2 | 
|  Africa (Cape Town)**\$1**  |  af-south-1  |  eu-west-1  | 
|  Asia Pacific (Mumbai)  |  ap-south-1  | eu-west-1  | 
|  Asia Pacific (Seoul)  |  ap-northeast-2  | us-west-2 | 
|  Asia Pacific (Singapore)  |  ap-southeast-1  | ap-southeast-2 | 
|  Asia Pacific (Sydney)  |  ap-southeast-2  | ap-southeast-2 | 
|  Asia Pacific (Tokyo)  |  ap-northeast-1  | us-west-2 | 
|  Canada (Central)  |  ca-central-1  | ca-central-1 | 
|  Europe (Frankfurt)   |  eu-central-1  | eu-west-1 | 
|  Europe (Ireland)  |  eu-west-1  | eu-west-1 | 
|  Europe (London)  |  eu-west-2  | us-east-1 | 
|  Europe (Milan)**\$1**  |  eu-south-1  | eu-west-1 | 
|  Europe (Paris)  |  eu-west-3  | eu-west-1 | 
|  Europe (Stockholm)  |  eu-north-1  | eu-west-1 | 
|  South America (São Paulo)  |  sa-east-1  | us-east-1 | 

**Note**  
To use live transcription in Regions marked with an asterisk (**\$1**), you must first enable the Region in your AWS account. For more information, refer to [Enabling a Region](https://docs.aws.amazon.com/general/latest/gr/rande-manage.html) in the AWS General Reference.

For more information about the regions and endpoints for each service, refer to:
+ [Amazon Chime SDK media Regions](https://docs.aws.amazon.com/chime-sdk/latest/dg/chime-sdk-meetings-regions.html)
+ [Amazon Transcribe endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/transcribe.html#transcribe_region)
+ [Amazon Transcribe Medical endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/transcribe-medical.html)

## Step 3: Review service quotas
<a name="transcribe-quotas"></a>

Each Amazon Chime SDK meeting with live transcription requires exactly one HTTP/2 stream to Amazon Transcribe or Amazon Transcribe Medical. Both services have regional service quotas for the number of concurrent HTTP/2 streams, and for start-stream transactions per second. For more information about the quotas, refer to [Guidelines and quotas](https://docs.aws.amazon.com/transcribe/latest/dg/limits-guidelines.html) in the *Amazon Transcribe Developer Guide*. For information about quota increases, refer to Service Quotas in the AWS console.

# Starting and stopping Amazon Chime SDK live transcription
<a name="initiate-transcription"></a>

You use the Amazon Chime SDK [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_StartMeetingTranscription.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_StartMeetingTranscription.html) API to initiate meeting transcription by applying a `TranscriptionConfiguration` to the meeting. The Amazon Chime SDK controller forwards the configuration to the meeting asynchronously. The success or failure of initiating meeting transcription is signaled through a message via Amazon Simple Notification Service (Amazon SNS) and Amazon EventBridge.

**Starting transcription**  
This example shows how to start live transcription with Amazon Transcribe.

```
POST /meetings/meetingId/transcription?operation=start HTTP/1.1 
Content-type: application/json
{
    "TranscriptionConfiguration": {
        "EngineTranscribeSettings": {
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_ResponseSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_ResponseSyntax)": "en-US",  
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_ResponseSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_ResponseSyntax)": "tag",
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "profanity",
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "lingo",
            "Region": "us-east-1"
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": true,  
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "high",  
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "PII",  
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "PII",  
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "ALL",  
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestSyntax)": "language-model"
        }
    }
}
```

This example shows how to start live transcription with Amazon Transcribe Medical.

```
POST /meetings/meetingId/transcription?operation=start HTTP/1.1 
Content-type: application/json
{  
    "TranscriptionConfiguration": {
        "EngineTranscribeMedicalSettings": {
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html)": "en-US",
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html)": "PRIMARYCARE",
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html)": "CONVERSATION",
            "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html)": "lingo",
            "Region": "us-east-1",
           "[https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html)": "PHI", 
        }
   }
}
```

`StartMeetingTranscription` – Starts transcription for the meeting.  
`meetingId` – The ID of the meeting, returned by the [CreateMeeting API](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_CreateMeeting.html#API_CreateMeeting_ResponseSyntax).  
`TranscriptionConfiguration` – Encapsulates the parameters for live transcription. You must specify exactly one configuration, `EngineTranscribeSettings` or `EngineTranscribeMedicalSettings`.

`EngineTranscribeSettings` – Specifies the use of Amazon Transcribe and passes its settings through to [https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestParameters](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html#API_streaming_StartStreamTranscription_RequestParameters).  
`LanguageCode` – Required.  
`VocabularyFilterMethod` – Optional.  
`VocabularyFilterName` – Optional.  
`VocabularyName` – Optional.  
`Region` – Optional.  
`EnablePartialResultsStabilization` – Optional.  
`PartialResultsStability` – Optional.  
` ContentIdentificationType` – Optional.  
`ContentRedactionType` – Optional.  
`PiiEntityTypes ` – Optional.  
`LanguageModelName` – Optional.

`EngineTranscribeMedicalSettings` – Specifies the use of Amazon Transcribe Medical and passes its settings through to [https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html#API_streaming_StartMedicalStreamTranscription_RequestParameters](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html#API_streaming_StartMedicalStreamTranscription_RequestParameters).   
`LanguageCode` – Required.  
`Speciality` – Required.  
`Type` – Required.  
`VocabularyName` – Optional.  
`Region` – Optional.  
` ContentIdentificationType` – Optional.

**Responses**  
Amazon Transcribe and Amazon Transcribe Medical take the following responses:
+ `OK` (200) with empty body, if you successfully apply the `TranscriptionConfiguration` to the meeting.

**Error messages**  
Amazon Transcribe and Amazon Transcribe Medical display the following error messages:
+ **BadRequestException (400):** The input parameters don't match the service's restrictions.
+ **ForbiddenException (403):** The client is permanently forbidden from making the request.
+ **NotFoundException (404):** The `meetingId` does not exist.
+ **ResourceLimitExceededException (400):** The request exceeds the resource limit. For example, too many meetings have live transcription enabled.
+ **ServiceFailureException (500):** The service encountered an unexpected error.
+ **ServiceUnavailableException (503):** The service is currently unavailable.
+ **ThrottledClientException (429):** The client exceeded its request rate limit.
+ **UnauthorizedClientException (401):** The client is not currently authorized to make the request.

Calling `StartMeetingTranscription` a second time updates the `TranscriptionConfiguration` applied to the meeting.

**Stopping transcription**  
You use the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_StopMeetingTranscription.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_StopMeetingTranscription.html) API to remove the `TranscriptionConfiguration` for a given `meetingID` and end meeting transcription. Ending a meeting stops transcription automatically.

This example shows the request syntax that invokes `StopMeetingTranscription`.

```
POST/meetings/meetingId/transcription?operation=stop HTTP/1.1
```

**Responses**  
Amazon Transcribe and Amazon Transcribe Medical take the following responses:
+ `OK` (200) with empty body, if you successfully remove the `TranscriptionConfiguration` from the meeting.

**Error messages**  
Amazon Transcribe and Amazon Transcribe Medical display the following error messages:
+ **BadRequestException (400):** The input parameters don't match the service's restrictions.
+ **ForbiddenException (403):** The client is permanently forbidden from making the request.
+ **NotFoundException (404):** The `meetingId` does not exist.
+ **ServiceFailureException (500):** The service encountered an unexpected error.
+ **ServiceUnavailableException (503):** The service is currently unavailable.
+ **ThrottledClientException (429):** The client exceeded its request rate limit.
+ **UnauthorizedClientException (401):** The client is not currently authorized to make the request.

## Amazon Chime SDK live transcription parameters
<a name="transcription-parameters"></a>

The Amazon Transcribe and Amazon Transcribe Medical APIs offer a number of parameters when initiating streaming transcription, such as [https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartStreamTranscription.html) and [https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html](https://docs.aws.amazon.com/transcribe/latest/dg/API_streaming_StartMedicalStreamTranscription.html). You can use t hose parameters in the `StartMeetingTranscription` API unless the Amazon Chime SDK predetermines the parameter’s value. For example, the `MediaEncoding` and `MediaSampleRateHertz` parameters are not available because the Amazon Chime SDK sets them automatically.

Amazon Transcribe and Amazon Transcribe Medical validate the parameters, and that allows you to use new parameter values as soon as they become available. For example, if Amazon Transcribe Medical launches support for a new language, you only need to specify the new language value in the `LanguageCode` parameter. 

# Understanding Amazon Chime SDK live transcription events
<a name="transcription-events"></a>

The Amazon Chime SDK sends transcription lifecycle events, which you can use to trigger notifications and initiate downstream work flows. Some examples of using transcription events include:
+ Measuring the adoption of live transcription in Amazon Chime SDK meetings
+ Tracking language preferences

You can send events to Amazon EventBridge, Amazon Simple Notification Service, and Amazon Simple Queue Service. For more information, refer to [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) in the *Amazon EventBridge User Guide*.

## Amazon Chime SDK meeting transcription started
<a name="transcript-start"></a>

The Amazon Chime SDK sends this event when meeting transcription is started or the [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html) is updated. 

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "id": "12345678-1234-1234-1234-111122223333", 
    "region": "us-east-1", 
    "detail-type": "Chime Meeting State Change", 
    "time": "yyyy-mm-ddThh:mm:ssZ", 
    "resources": []
    "detail": {
        "version": "0", 
        "eventType": "chime:TranscriptionStarted",
        "timestamp": 12344566754,
        "meetingId": "87654321-4321-4321-1234-111122223333",
        "externalMeetingId": "mymeeting",
        "mediaRegion": "us-west-1",
        "transcriptionRegion": "us-west-2",
        "[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_StartMeetingTranscription.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_StartMeetingTranscription.html)": "{...}"
    }
}
```

## Amazon Chime SDK meeting transcription stopped
<a name="transcript-stop"></a>

The Amazon Chime SDK sends this event when meeting transcription is stopped.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "id": "12345678-1234-1234-1234-111122223333", 
    "region": "us-east-1", 
    "detail-type": "Chime Meeting State Change", 
    "time": "yyyy-mm-ddThh:mm:ssZ", 
    "resources": []
    "detail": {
        "version": "0", 
        "eventType": "chime:TranscriptionStopped",
        "timestamp": 12344566754,
        "meetingId": "87654321-4321-4321-1234-111122223333",
        "externalMeetingId": "mymeeting",
        "mediaRegion": "us-west-1",
        "transcriptionRegion": "us-west-2",
        "[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_StopMeetingTranscription.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_StopMeetingTranscription.html)": "{...}"
    }
}
```

## Amazon Chime SDK meeting transcription interrupted
<a name="transcript-interrupted"></a>

The Amazon Chime SDK sends this event if meeting transcription is interrupted.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "id": "12345678-1234-1234-1234-111122223333", 
    "region": "us-east-1", 
    "detail-type": "Chime Meeting State Change", 
    "time": "yyyy-mm-ddThh:mm:ssZ", 
    "resources": []
    "detail": {
        "version": "0", 
        "eventType": "chime:TranscriptionInterrupted",
        "timestamp": 12344566754,
        "meetingId": "87654321-4321-4321-1234-111122223333",
        "externalMeetingId": "mymeeting",
        "message": "Internal server error",
        "mediaRegion": "us-west-1",
        "transcriptionRegion": "us-west-2",
        "[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html)": "{...}"
    }
}
```

## Amazon Chime SDK meeting transcription resumed
<a name="transcript-resumed"></a>

The Amazon Chime SDK sends this event if meeting transcription is resumed after an interruption.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "id": "12345678-1234-1234-1234-111122223333", 
    "region": "us-east-1", 
    "detail-type": "Chime Meeting State Change", 
    "time": "yyyy-mm-ddThh:mm:ssZ", 
    "resources": []
    "detail": {
        "version": "0", 
        "eventType": "chime:TranscriptionResumed",
        "timestamp": 12344566754,
        "meetingId": "87654321-4321-4321-1234-111122223333",
        "externalMeetingId": "mymeeting",
        "mediaRegion": "us-west-1",
        "transcriptionRegion": "us-west-2",
        "[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html)": "{...}"
    }
}
```

## Amazon Chime SDK meeting transcription failed
<a name="transcript-failed"></a>

The Amazon Chime SDK sends this event if meeting transcription failed to start, or failed to resume after an interruption.

**Example: Event data**  
The following is example data for this event.

```
{
    "version": "0", 
    "source": "aws.chime", 
    "account": "111122223333", 
    "id": "12345678-1234-1234-1234-111122223333", 
    "region": "us-east-1", 
    "detail-type": "Chime Meeting State Change", 
    "time": "yyyy-mm-ddThh:mm:ssZ", 
    "resources": []
    "detail": {
        "version": "0", 
        "eventType": "chime:TranscriptionFailed",
        "timestamp": 12344566754,
        "meetingId": "87654321-4321-4321-1234-111122223333",
        "externalMeetingId": "mymeeting",
        "message": "Internal server error",
        "mediaRegion": "us-west-1",
        "transcriptionRegion": "us-west-2",
        "[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_TranscriptionConfiguration.html)": "{...}"
    }
}
```

# Understanding Amazon Chime SDK live transcription messages
<a name="process-msgs"></a>

The Amazon Chime SDK service shares transcription information with attendees by sending `TranscriptEvent` objects in data messages. A `TranscriptEvent` delivers a `Transcript` or a `TranscriptionStatus`. 

A `Transcript` includes results with timestamped, user-attributed words and punctuation. A result may be “partial”, in which case the system usually updates it in a subsequent `TranscriptEvent`. This allows you to see transcriptions quickly and apply inline updates later as necessary.

A `TranscriptStatus` may deliver one of the `TranscriptionStatusType` events, listed in the example in the next section.

Newer versions of the Amazon Chime SDKs include additional data types and helper functions for common processing a `TranscriptEvent`.

## TranscriptEvent
<a name="transcript-event"></a>

This example shows a typical transcription event.

```
type TranscriptEvent = Transcript | TranscriptionStatus;

export class TranscriptEventConverter {
  static from(dataMessage: DataMessage): TranscriptEvent[] {
    // convert DataMessage to TranscriptEvents
    return ...
  }
}

export default class TranscriptionStatus {
    type: TranscriptionStatusType;
    eventTimeMs:                   number;
    transcriptionRegion:           string;
    transcriptionConfiguration:    string;
    message?:                      string;
}

enum TranscriptionStatusType {
    STARTED        =    'started',
    INTERRUPTED    =    'interrupted',
    RESUMED        =    'resumed',
    STOPPED        =    'stopped',
    FAILED         =    'failed',
}

export default class Transcript {
    results: TranscriptResult[];    // at least one
}

export class TranscriptResult {
    resultId:        string;
    isPartial:       boolean;
    startTimeMs:     number;
    endTimeMs:       number;
    alternatives:    TranscriptAlternative[];    // most confident first
    }

export default class TranscriptAlternative {
    items: TranscriptItem[];    // in start time order
    transcript: string; //concatenated transcript items
    entities?: TranscriptEntity[];
}

export default class TranscriptItem {
    type:                      TranscriptItemType;
    startTimeMs:               number;
    endTimeMs:                 number;
    attendee:                  Attendee;
    content:                   string;
    vocabularyFilterMatch?:    boolean;
    confidence?:               number;  
    stable?:                   boolean;
}

enum TranscriptItemType {
    PRONUNCIATION    =    'pronunciation',// content is a word
    PUNCTUATION      =    'punctuation',// content is punctuation
}

export default class TranscriptEntity {  
    category:       string;  
    confidence:     number;  
    content:        string;  
    endTimeMs:      number;  
    startTimeMs:    number;  
    type?:          string;
}

// This is an existing SDK model
export default class Attendee {
    attendeeId:        string;
    externalUserId:    string;
}
```

## Data guidelines
<a name="data-guidelines"></a>

Keep these guidelines in mind as you go.

1. `transcription.results` may have more than one result.

1. If `transcription.results[i].isPartial = true`, then there may be an update for the entire result. The update is likely, but not guaranteed. The update has the same `transcript.result[i].resultId`. If you want to avoid low-confidence transcriptions, you can skip partial results completely. If you want low-latency results, you can display partial results, then overwrite completely when the update arrives.

1. `transcription.results[i].alternatives` always contains at least one entry. If it contains more than one entry, the most confident entry is first in the list. In most cases, you can take the first entry in `transcription.results[i].alternatives` and ignore the others.

1. `transcription.results[i].alternatives[j].items` includes an entry for each word or punctuation mark.

1. `transcription.results[i].alternatives[j].items[k].` content is what was spoken.

1. `transcription.results[i].alternatives[j].items[k].attendee` is the user attribution (who) of the content.

1. `transcription.results[i].alternatives[j].items[k].startTimeMs` is the "when" of the content. This enables word-by-word rendering of user-attributed transcription across different users in the order that the words were spoken.

1. The `transcription.results[i].alternatives[j].items[k].endTimeMs` field can generally be ignored, but is supplied for completeness of who said what when.

1. `transcription.results[i].alternatives[j].items[k].vocabularyFilterMatch` is true if the content matched a word in the filter, otherwise it is false.

1. `transcription.results[i].alternatives[j].items[k].confidence` is a value between 0 and 1. It indicates the engine's confidence that the item content correctly matches the spoken word, with 0 being the lowest confidence and 1 being the highest confidence.

1. `transcription.results[i].alternatives[j].items[k].stable` indicates whether the current word will change in future partial result updates. This value can only be true if you enable the partial results stabilization feature by setting `EnablePartialResultsStabilization` to `true` in your request.

1. `transcription.results[i].alternatives[j].entities` includes an entry for each entity that the Content Identification or Redaction features detect. The list is only populated if you enable Content Identification or Redaction. An entity can be data such as personally identifiable information or personal health information. You can use entities to highlight, or take action on, words of interest during transcription.

1. `transcription.results[i].alternatives[j].entities[k].category` is the entity's category. It equals the Content Identification or Redaction type, such as "PII" or "PHI", which is provided in the request.

1. `transcription.results[i].alternatives[j].entities[k].confidence` measures how strong the engine is that the particular content is truly an entity. Note that this is different than the item-level confidence, which measures how confident the engine is in the correctness of the words themselves.

1. `transcription.results[i].alternatives[j].entities[k].content` is the actual text that makes up the entity. This can be multiple items, such as an address.

1. `transcription.results[i].alternatives[j].entities[k].startTimeMs` captures the time at which the entity started being spoken.

1. `transcription.results[i].alternatives[j].entities[k].endTimeMs` captures the time at which the entity finished being spoken.

1. `transcription.results[i].alternatives[j].entities[k].type` is only supported for the Transcribe engine and provides the sub-type of the entity. These are values such as `ADDRESS`, `CREDIT\$1DEBIT\$1NUMBER`, and so on.

## Registering event handlers for TranscriptEvents
<a name="register-handler"></a>

The following examples use the Amazon Chime SDK client library for JavaScript. However, the pattern is consistent across all Amazon Chime SDKs.

The `TranscriptionController` in the `RealtimeController` and `RealtimeControllerFacade` includes specific functions for adding a handler that processes `TranscriptionEvents`:

```
/** 
 * Returns the [[TranscriptionController]] for this real-time controller. 
 */
readonly transcriptionController?: TranscriptionController;
```

The `TranscriptionController` has two functions to manage subscribing and unsubscribing to `TranscriptionEvent` callbacks:

```
import TranscriptEvent from './TranscriptEvent';

export default interface TranscriptionController {
  /**
   * Subscribe a callback to handle received transcript event
   */
  subscribeToTranscriptEvent(callback: (transcriptEvent: TranscriptEvent) => void): void;

  /** 
   * Unsubscribe a callback from receiving transcript event 
   */
  unsubscribeFromTranscriptEvent(callback: (transcriptEvent: TranscriptEvent) => void): void;
}
```

**Using the optional `TranscriptionController`**  
We provide a default implementation of `TranscriptionController` interface named `DefaultTranscriptionController`. The default implementation in `DefaultRealtimeController` and `DefaultAudioVideoFacade` returns a `DefaultTranscriptionController` object:

```
/** 
get transcriptionController(): TranscriptionController {
   return this.realtimeController.transcriptionController;
}
```

`DefaultRealtimeController` also takes an optional `TranscriptionController` object in its constructor. That allows you to override the `DefaultTranscriptionController` behavior. Developer applications subscribe and unsubscribe to one or more callbacks through the `TranscriptionController` object of the `AudioVideoFacade` object:

```
// Subscribe
this.audioVideo.transcriptionController?.subscribeToTranscriptEvent(this.transcriptEventHandler);

// Unsubscribe
this.audioVideo.transcriptionController?.unsubscribeFromTranscriptEvent(this.transcriptEventHandler););
```

# Processing a received Amazon Chime SDK live transcript event
<a name="delivery-examples"></a>

The following examples show how to process a received `TranscriptEvent`.

**Note**  
The exact output depends on several factors, including how quickly individuals talk and when they pause.

## Example 1: StartMeetingTranscription
<a name="example-1"></a>

This example shows a typical `StartMeetingTranscription` operation.

```
meeting.StartMeetingTranscription(
    { EngineTranscribeSettings: { Languagecode: ‘en-US’ } } );
```

The operation generates a `TranscriptEvent`.

```
{   
    status: {        
        type: 'started',        
        eventTimeMs: 1620118800000,        
        transcriptionConfig: {                    
            LanguageCode: 'en-US'        
        }    
    }
}
```

## Example 2: A partial transcript result
<a name="example-2"></a>

In this example, an attendee says, "The quick brown fox jumps over the lazy dog." Note that in this example, the `isPartial` value is `true`. If you look deeper into the message, you can see that the system processed the word "fox" as "facts." The system uses the same `resultId` to update the transcript. 

```
{
    transcript: {
        results: [{
            resultId:"1",                               isPartial: true,
            startTimeMs: 1620118800000,                 endTimeMs: 1620118801000,
            alternatives: [{
                items:[{
                    type:        'pronunciation',
                    startTimeMs: 1620118800000,         endTimeMs: 1620118800200,
                    attendee: { attendeeId: "1",        externalUserId: "A"},
                    content: "the",                     vocabularyFilterMatch: false
                },
                {
                    type:        'pronunciation',
                    startTimeMs: 1620118800200,          endTimeMs: 1620118800400,
                    attendee: { attendeeId: "1",         externalUserId: "A" },
                    content:"quick",                     vocabularyFilterMatch: false
                },
                {
                    type:'pronunciation',
                    startTimeMs: 1620118800400,          endTimeMs: 1620118800750,
                    attendee: { attendeeId: "1",         externalUserId: "A" },
                    content:"brown",                     vocabularyFilterMatch: false
                },
                {
                    type:'pronunciation',
                    startTimeMs: 1620118800750,          endTimeMs: 1620118801000,
                    attendee:{ attendeeId: "1",          externalUserId: "A" },
                    content:"facts",                     vocabularyFilterMatch: false
                },
                {
                    type:'punctuation',
                    startTimeMs: 1620118801000,          endTimeMs: 1620118801500,
                    attendee:{ attendeeId: "1",          externalUserId: "A" },
                    content:    ",",                     vocabularyFilterMatch: false
                }]
            }]
        }]
    }
}
```

## Example 3: A final transcript result
<a name="example-3"></a>

In the event of a partial transcript, the system processes the phrase again. This example has an `isPartial` value of `false`, and the message contains "fox" instead of "facts." The system re-issues the message using the same ID.

```
{
    transcript: {
        results: [{
            resultId:"1",                                isPartial: false,
            startTimeMs: 1620118800000,                  endTimeMs: 1620118801000,
            alternatives: [{
                items:[{
                    type:        'pronunciation',
                    startTimeMs: 1620118800000,          endTimeMs: 1620118800200,
                    attendee: { attendeeId: "1",         externalUserId: "A"},
                    content: "the",                      vocabularyFilterMatch: false
                },
                {
                    type:        'pronunciation',
                    startTimeMs: 1620118800200,          endTimeMs: 1620118800400,
                    attendee: { attendeeId: "1",         externalUserId: "A" },
                    content:"quick",                     vocabularyFilterMatch: false
                },
                {
                    type:'pronunciation',
                    startTimeMs: 1620118800400,          endTimeMs: 1620118800750,
                    attendee: { attendeeId: "1",         externalUserId: "A" },
                    content:"brown",                     vocabularyFilterMatch: false
                },
                {
                    type:'pronunciation',
                    startTimeMs: 1620118800750,          endTimeMs: 1620118801000,
                    attendee: { attendeeId: "1",          externalUserId: "A" },
                    content:"fox",                       vocabularyFilterMatch: false
                },
                {
                    type:'punctuation',
                    startTimeMs: 1620118801000,          endTimeMs: 1620118801500,
                    attendee: { attendeeId: "1",          externalUserId: "A" },
                    content:    ",",                     vocabularyFilterMatch: false
                }]
            }]
        }]
    }
}
```

# Parsing Amazon Chime SDK transcripts
<a name="parse-transcripts"></a>

Use the following command to parse transcription content from a transcription message. The command parses complete sentences from the transcript-message.txt files.

```
with open('transcript-message.txt') as f:
        for line in f:
            result_json = json.loads(line)["transcript"]["results"][0]
            if result_json['isPartial'] == False:
                print(result_json["alternatives"][0]["transcript"])
```

# Using media replication for Amazon Chime SDK meetings
<a name="media-replication"></a>

You can use media replication to link a primary WebRTC session with multiple replica sessions to reach larger audiences. Each WebRTC media session supports 250 connections, and you can replicate a primary session to multiple replica sessions. Participants connected to a replica session receive only the audio and video of the presenters connected to the primary session. They have no knowledge of the participants connected to the replicated session, which makes media replication ideal for webinars and other use cases where privacy is desired.

The following image shows media replication between a primary session with presenters sharing audio and video, and a replica session with participants consuming the media.

![\[Presenters sharing in a primary session.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/replication-1.png)


**Note**  
The service quota *Chime SDK Meetings - replica meetings per primary meeting* has a default value of 4, and you can increase that limit on request. For more information about quotas, refer to [AWS service quotas](https://docs.aws.amazon.com/general/latest/gr/aws_service_limits.html) in the *AWS General Reference*.

**Topics**
+ [Interactive participants](#interactive-participants)
+ [Global participants](#global-participants)
+ [Session lifecycle](#session-lifecycle)

## Interactive participants
<a name="interactive-participants"></a>

Participants connected to a replica session can be granted access to join the primary session. Because everyone uses a WebRTC connection, presenters and participants don't experience transcoding delays. When participants switch between primary and replicated sessions, they reuse their WebRTC connections, so switching is extremely fast. That allows participants to contribute to the live conversation without missing any content.

The following image shows a participant in a replica session using their WebRTC connection to switch to the primary session.

![\[Diagram showing two participants switching from a replica meeting to the primary meeting.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/replication-2.png)


## Global participants
<a name="global-participants"></a>

You can choose the AWS Region for each WebRTC media session. That allows you to create replica sessions in Regions closer to your participants than the primary session's Region. When you do this, media flows from the primary session to the replica sessions across the AWS network, then from the replica session to the participant across the Internet. When presenting to a global audience, having replica sessions near your participants can help ensure that media travels around the world on the AWS network, instead of the internet, for a better meeting experience.

The following image shows a primary session and replicated sessions in different Regions.

![\[Diagram showing participants in 3 Regions watching a presentation.\]](http://docs.aws.amazon.com/chime-sdk/latest/dg/images/replication-3.png)


## Session lifecycle
<a name="session-lifecycle"></a>

Creating sessions  
You use the [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateMeeting.html) or [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html) APIs to create WebRTC media sessions. By default, the APIs create a primary session unless you specifically create a replica session.  
You create a replica session by specifying the `MeetingId` of the primary session as the `PrimaryMeetingId` in the `CreateMeeting` or `CreateMeetingWithAttendees` API call.  
If you specify the `MeetingId` of a replica session as the `PrimaryMeetingId`, the API call will fail.

Creating attendees  
 To create the attendee credentials needed to join a WebRTC media session, you can use the [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html), [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html), or [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateAttendee.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_CreateAttendee.html) APIs.   
When creating sessions for a large number of attendees, use `CreateMeetingWithAttendees` or `BatchCreateAttendee` to minimize the number of API calls required.

Deleting attendees  
You use the [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteAttendee.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteAttendee.html) API to revoke a attendee's credentials for a WebRTC media session. If the attendee is connected to the session, they will disconnected and cannot rejoin.  
When you use the [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteMeeting.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteMeeting.html) API to delete a WebRTC media session, the API automatically deletes all attendees and you don't need to call `DeleteAttendee`.

Switching sessions  
To allow a participant to switch from a replica session to a primary session, you must create credentials for them in the primary meeting. Refer to *Creating attendees* earlier in this list. Use the credentials with the `promoteToPrimaryMeeting` method in the Amazon Chime SDK client library to switch to the primary session.  
To switch participants back to a replica session, use the `demoteFromPrimaryMeeting` method in the Amazon Chime SDK client library, or use the [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteAttendee.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteAttendee.html) API to invalidate their primary session credentials.  
A presenter who connects directly to a primary session can't switch to a replica session.
For more information on switching between sessions, refer to the client library documentation:  
+ [Amazon Chime SDK for Android](https://github.com/aws/amazon-chime-sdk-android) on GitHub.
+ [Amazon Chime SDK for iOS](https://github.com/aws/amazon-chime-sdk-ios) on GitHub.
+ [Amazon Chime SDK client library for JavaScript](https://github.com/aws/amazon-chime-sdk-js) on GitHub.

Deleting sessions  
You use the [https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteMeeting.html](https://docs.aws.amazon.com/chime/latest/APIReference/API_meeting-chime_DeleteMeeting.html) API to delete WebRTC media sessions.  
If you delete a primary session, the `DeleteMeeting` API automatically deletes all attached replica sessions. So to delete all sessions, just delete the primary.  
The service automatically deletes a primary session if no attendees connect for 5 contiguous minutes. The service only deletes replica sessions automatically when it deletes a primary session. That means you can create replica sessions when you create a primary session, and the replicas will be available for the duration of the primary session.

# Troubleshooting and debugging Amazon Chime SDK meetings
<a name="troubleshoot-sdk-meetings"></a>

Use the following topics to help diagnose and troubleshoot issues that you encounter when working with the Amazon Chime SDK. 

**Topics**
+ [Understanding the system requirements for Amazon Chime SDK meetings](ts-supported-browsers.md)
+ [Setting up logging and monitoring for Amazon Chime SDK meetings](ts-log-monitor.md)
+ [Troubleshooting Amazon Chime SDK meetings](self-troubleshooting.md)
+ [Understanding common issues with Amazon Chime SDK meetings](common-issues.md)

# Understanding the system requirements for Amazon Chime SDK meetings
<a name="ts-supported-browsers"></a>

As part of troubleshooting, make sure you code for supported browsers. For a current list of supported browsers, versions, and operating systems, see [Amazon Chime SDK system requirements](meetings-sdk.md#mtg-browsers). The [developer guide and FAQs on Github](https://github.com/aws/amazon-chime-sdk-js/issues/1059) address browser and other compatibility issues. Also, familiarize yourself with the [known browser issues](https://aws.github.io/amazon-chime-sdk-js/modules/faqs.html#known-browser-issues) on GitHub and any workarounds.

If you just started with Amazon Chime SDK Meetings, the [Amazon Chime SDK’s Builder Journey](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/20_Builders_Journey.md) provides a step-by-step guide for building with the Amazon Chime SDK, plus the tools needed for troubleshooting.

# Setting up logging and monitoring for Amazon Chime SDK meetings
<a name="ts-log-monitor"></a>

Logging helps you collect information such as server-side meeting events and client-side browser console logs.

The Amazon Chime SDK provides server-side meeting events that you can send to Amazon EventBridge and Amazon CloudWatch Events logs. You can create CloudWatch metrics and insights, and use them in your dashboard for monitoring. The [Server-side Logging and Monitoring of Amazon Chime SDK events](https://aws.amazon.com/blogs/business-productivity/server-side-logging-and-monitoring-of-amazon-chime-sdk-events/) blog post explains how to enable the CloudWatch Metrics, Insights and Dashboard.

The Amazon Chime SDK provides client-side events for audio and video quality, network bandwidth, and connectivity issues. The [Monitoring and troubleshooting with Amazon Chime SDK Meeting events](https://aws.amazon.com/blogs/business-productivity/monitoring-and-troubleshooting-with-amazon-chime-sdk-meeting-events/) blog post explains how to enable CloudWatch Metrics, Insights and Dashboard for join failures, audio quality issues, and microphone and camera setup failures. For additional information about meeting events, see [Meeting Events](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/06_Meeting_Events.md) on Github. 



## Options for troubleshooting metrics
<a name="ts-cloudwatch-options"></a>

You have the following options for collecting troubleshooting events.
+ Send metrics at every event 
+ Batch events every N seconds 
+ Send metrics at end of the meeting 
+ Logging level for browser console logs

## Recommended metrics
<a name="ts-cloudwatch-metrics"></a>

At a minimum, you should collect and log the following metrics.
+ SDK platform and version
+ Browser and version
+ Operating system
+ Logical cores
+ Meeting started
+ Meeting ended
+ Attendee joined
+ Attendee left
+ Attendees dropped

Additionally, depending on the issues you face, the following metrics can provide information about connectivity, bandwidth, and quality issues. You can log every occurrence of these metrics, or just count them. Counting can provide a summarized view of the underlying issues:
+ connectionDidSuggestStopVideo
+ connectionDidBecomeGood
+ connectionDidBecomePoor
+ Attendee join time > t seconds
+ MeetingStartFailed
+ MeetingFailed

## Enabling client-side logging
<a name="client-side-logging"></a>

You can enable `INFO`-level browser logs by passing `LogLevel.INFO` to the `ConsoleLogger` object.

```
const logger = new ConsoleLogger('MyLogger', LogLevel.INFO);const meetingSession = new DefaultMeetingSession(configuration,logger,deviceController); 
```

You can also use the `POSTLogger` component in the Amazon Chime SDK for JavaScript to capture browser logs in your back end, such as Amazon CloudWatch Logs. `POSTLogger` makes `HTTP POST` requests to upload browser logs to the given URL in the [POSTLogger constructor](https://aws.github.io/amazon-chime-sdk-js/classes/postlogger.html). For example, the [Amazon Chime SDK serverless demo on GitHub](https://github.com/aws/amazon-chime-sdk-js/blob/main/demos/browser/app/meetingV2/meetingV2.ts#L1773) uses the `POSTLogger` to send browser logs to Amazon CloudWatch Logs for future investigation.

## Enabling server-side logging
<a name="server-side-logging"></a>

The Amazon Chime SDK for JavaScript also calls the `eventDidReceive` observer method with key meeting events, such as `MeetingStartFailed` and `MeetingFailed`. Meeting events often includes specific reasons for failures. For example, say that a large group of customers experience failures. Your web application can collect those meeting events, and then share them with us to troubleshoot the root cause. For more information about meeting events, see the [meeting event guide on GitHub](https://aws.github.io/amazon-chime-sdk-js/modules/meetingevents.html), and the [ Monitoring and troubleshooting with Amazon Chime SDK meeting events](https://aws.amazon.com/blogs/business-productivity/monitoring-and-troubleshooting-with-amazon-chime-sdk-meeting-events/) blog post.

# Troubleshooting Amazon Chime SDK meetings
<a name="self-troubleshooting"></a>

The sections in this topic explain several ways to self-troubleshoot Amazon Chime SDK meetings.

**Topics**
+ [Checking FAQs and known issues](#check-faqs)
+ [Verifying network access](#net-acess)

## Checking FAQs and known issues
<a name="check-faqs"></a>

Check these FAQs and lists of known issues on GitHub for troubleshooting and debugging advice.
+ [Amazon Chime SDK – JavaScript - Meetings](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#meetings)
+ [Amazon Chime SDK – JavaScript - Media](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#media)
+ [Amazon Chime SDK – JavaScript - Networking](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#networking)
+ [Amazon Chime SDK – - Audio and Video](https://github.com/aws/amazon-chime-sdk-js/blob/main/guides/07_FAQs.md#audio-and-video)

## Verifying network access
<a name="net-acess"></a>

Enterprises often have network firewalls that restrict access to specific ports, or connections to IP address ranges out of their network. The following sections explain some of the ways you can verify network access.

**Topics**
+ [Validating AWS SDK and Amazon Chime SDK subnets and ports](#subnets-ports)
+ [Using demo apps to reproduce issues](#repro-on-demo-apps)
+ [Using the Meeting Readiness Checker](#ready-checker)

### Validating AWS SDK and Amazon Chime SDK subnets and ports
<a name="subnets-ports"></a>

Applications that use the Amazon Chime SDK utilize two tiers, server and client. The server tier uses the AWS SDK and has server-side meeting handlers. The client tier uses client SDKs.

The AWS SDK is used to call server APIs such as [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html). Such APIs connect to the AWS global service endpoints in the `us-east-1`, `us-west-2`, `ap-southeast-1`, `eu-central-1`, `us-gov-east-1`, and `us-gov-west-1` Regions. The [AWS IP address ranges](https://docs.aws.amazon.com/general/latest/gr/aws-ip-ranges.html) page in the *AWS General Reference* lists the IP address ranges for each Region. For information about service endpoints and quotas, see the [Amazon Chime SDK endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html).

Client SDKs, such as the Amazon Chime SDK for JavaScript, connect to service endpoints in the `*.chime.aws` domain. 

Use the following validations to ensure that you have network permissions:
+ Run the [Amazon Chime SDK Meeting Readiness Checker](https://github.com/aws/amazon-chime-sdk-js#meeting-readiness-checker) on GitHub to verify that you can reach your network and ports.
+ Verify you can resolve \$1.chime.aws domain from your network or your end user’s network. 
+ Ensure that your firewall allows connections to the AWS IP range via TCP Port 443 for control commands and UDP Port 3478 for media. 

### Using demo apps to reproduce issues
<a name="repro-on-demo-apps"></a>

As a best practice, start the debugging process by trying to reproduce your issue in one of demo apps. That enables the service team to locate where the issue might be. If you can't reproduce the issue with a demo app, you can review the app's code to see how it implemented the relevant use case.




| Amazon Chime SDK | Feature | Demo app resources | 
| --- | --- | --- | 
| JavaScript SDK | Meetings | [Demo instructions](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/serverless), [Source code](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/browser) | 
| React components | Meetings |   [Demo instructions](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/meeting) [Source code](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/meeting/src)   | 
| Meeting chat | Messaging |   [Blog post](https://aws.amazon.com/blogs/business-productivity/build-meeting-features-into-your-amazon-chime-sdk-messaging-application/), [Demo instructions](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat), [Source code](https://github.com/aws-samples/amazon-chime-sdk/tree/main/apps/chat/src)   | 
| iOS/Android | Meetings |  (Blog post) [ Building a Meeting Application on Android using the Amazon Chime SDK](https://aws.amazon.com/blogs/business-productivity//building-a-meeting-application-on-android-using-the-amazon-chime-sdk/) (Blog post) [ Building a Meeting Application on iOS using the Amazon Chime SDK](https://aws.amazon.com/blogs/business-productivity/building-a-meeting-application-on-ios-using-the-amazon-chime-sdk/)   | 
| PSTN audio | Inbound calling |   [Blog post](https://github.com/aws-samples/amazon-chime-sma-update-call) [Source code](https://github.com/aws-samples/amazon-chime-sma-update-call)   | 

### Using the Meeting Readiness Checker
<a name="ready-checker"></a>

Use the [Amazon Chime SDK Meeting Readiness Checker](https://github.com/aws/amazon-chime-sdk-js#meeting-readiness-checker) on GitHub. The checker helps verify audio and video devices, and user connections. You can present the results to your end users with by using pass/fail statues that expose the root cause of any issues.

# Understanding common issues with Amazon Chime SDK meetings
<a name="common-issues"></a>

The following sections provide troubleshooting methods for common meeting issues.

**Topics**
+ [Connectivity issues](#connectivity-issues)
+ [Audio and video quality issues](#a-v-quality)
+ [Verifying SDK quotas and API throttling for Amazon Chime SDK meetings](quotas-throttling.md)
+ [Opening support cases for Amazon Chime SDK meetings](open-support-cases.md)

## Connectivity issues
<a name="connectivity-issues"></a>

For connectivity issues, see [Verifying network access](self-troubleshooting.md#net-acess).

## Audio and video quality issues
<a name="a-v-quality"></a>

Audio and video quality issues can have several causes. Two main reasons for sub optimal audio/video quality are network bandwidth, and device performance. For detailed information on different challenges and how these impact audio/video quality, see [Quality, Bandwidth, and Connectivity](https://aws.github.io/amazon-chime-sdk-js/modules/qualitybandwidth_connectivity.html) on *GitHub*. This article describes different events and metrics that can be monitored to detect bandwidth issues and potential mitigations.

You can choose a Media Region that is closer to the audience of the target meeting session. To understand how to choose an optimal media region, see Using meeting Regions (https://docs.aws.amazon.com/chime-sdk/latest/dg/chime-sdk-meetings-regions.html).

Depending on the bandwidth available for a meeting attendee, the Amazon Chime SDK adjusts the video quality of the video being received/uploaded. To understand how you can control the video quality for different video layouts, visit Managing Video Quality for different Video Layouts (https://aws.github.io/amazon-chime-sdk-js/modules/videolayout.html). This article describes video lifecycle management and uplink/downlink policies. 

**Video resolution considerations**
+ Default resolution for uploading video is 540p and 15fps at 1400 kbps. Depending on bandwidth, you can reduce that resolution and frame rate.
+ Based on receiver bandwidth available, determine how many video tiles to show. Don’t overshoot 6Mbps for all video tiles and content sharing. End users see black video tiles when they don't have enough bandwidth.

**Using video uplink and downlink bandwidth policies**  
The Amazon Chime SDK provides the following bandwidth policies.
+ NScaleVideoUplinkBandwidthPolicy – Implements capture and encoding parameters that nearly equal those used by the desktop, web, and mobile clients.
+ AllHighestVideoBandwidthPolicy – Always subscribes to the highest quality video stream.
+ NoVideoDownlinkBandwidthPolicy – Disables video when bandwidth drops below a given threshold.
+ VideoPriorityBasedPolicy – Prioritizes audio over video in cases of low bandwidth.
+ VideoAdaptiveProbePolicy

# Verifying SDK quotas and API throttling for Amazon Chime SDK meetings
<a name="quotas-throttling"></a>

The [Amazon Chime SDK endpoints and quotas](https://docs.aws.amazon.com/general/latest/gr/chime-sdk.html) page lists the service quotas, API rates, and whether you can adjust them. Use the [AWS Console Service Quota](https://console.aws.amazon.com/servicequotas/home/services/chime/quotas) page to request quota adjustments.

**Fine tuning your API rates**  
Applications that exceed their API rates receive HTTP Status Code 429 and `ThrottledClientException` messages. You can adjust your API rates, but before you do, check your application for bugs that may exhaust those rates. For example, you may create meetings in a loop, or create meetings and not clean up.

Depending on how you create meetings, you might need to modify your code. For example, you can replace `CreateMeeting` and `CreateAttendee` with: 
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeetingWithAttendees.html) – Creates up to 10 attendees per meeting.
+ [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_BatchCreateAttendee.html) – Creates up to 100 attendees per meeting.

You can store created attendees in a database, pull attendee information as invitees join the meeting, and then associate them with the pre-created attendees.

# Opening support cases for Amazon Chime SDK meetings
<a name="open-support-cases"></a>

If you have more questions, or require support for your business, you can reach out to [AWS Customer support](https://pages.awscloud.com/GLOBAL-aware-GC-Amazon-Chime-SDK-2020-reg.html). For more information about our support plans, see the [Compare support plans](https://aws.amazon.com/premiumsupport/plans/?nc=sn) page. When creating a support case, always open it under the account that has the problem. Include console browser logs, meeting and attendee IDs, and any related support cases or GitHub issues.