Step 4: Create a Channel with Optional Recording - Amazon Interactive Video Service

Step 4: Create a Channel with Optional Recording

An Amazon IVS channel stores configuration information related to your live stream. You first create a channel and then contribute video to it using the channel’s stream key to start your live stream.

As part of channel creation, the following items are assigned:

  • An ingest server identifies a specific Amazon IVS component that receives the stream, along with an ingestion protocol (RTMPS).

  • Amazon IVS assigns a stream key when you create a channel and uses it to authorize streaming. Treat the stream key like a secret, since it allows anyone to stream to the channel.

  • A playback URL identifies the endpoint to start playback for a specific channel. This endpoint can be used globally. It automatically selects the best location from the Amazon IVS global content delivery network for a viewer to stream the video. (Note that Amazon IVS does not support custom domains for playback. Do not proxy the playback URL with your own domain; that does not work and will cause issues.)

You can create a channel — with or without recording — through the Amazon IVS console or the AWS CLI. Channel creation and recording are discussed below.

Auto-Record to Amazon S3

You have the option of enabling recording for a channel. If the auto-record to S3 feature is enabled, all streams on the channel are recorded and saved to an Amazon S3 storage bucket that you own. Subsequently, the recording is available for on-demand playback.

Setting this up is an advanced option. By default, recording is disabled when a channel is created.

Before you can set up a channel for recording, you must create a recording-configuration. This is a resource which specifies an Amazon S3 location where the recorded streams for the channel are stored. You can create and manage recording configurations using the console or CLI; both procedures are given below. After you create the recording configuration, you associate it with a channel either when you create the channel (as described below) or later, by updating an existing channel. (In the API, see CreateChannel and UpdateChannel.) You can associate multiple channels with the same recording configuration. You can delete a recording configuration that is no longer associated with any channels.

Keep in mind the following constraints:

  • You must own the S3 bucket. That is, the account that sets up a channel to be recorded must own the S3 bucket where recordings will be stored.

  • The channel, recording configuration, and S3 location must be in the same AWS region. If you create channels in other regions and want to record them, you must also set up recording configurations and S3 buckets in those regions.

Recording to your S3 bucket requires authorization with your AWS credentials. To give IVS the required access, an AWS IAM Service-Linked Role (SLR) is created automatically when the recording configuration is created: the SLR is limited to give IVS write permission only on the specific bucket.

To disable recording after you have enabled it, see How to Disable Recording.

Note that network issues between the streaming location and AWS or within AWS could result in some data loss while recording your stream. In these cases, Amazon IVS prioritizes the live stream over the recording. For redundancy, record locally via your streaming tool.

For more information (including how to set up post-processing or VOD playback on your recorded files), see Auto-Record to Amazon S3.

Console Instructions

These steps are divided into three phases: initial channel setup, set up to auto-record to Amazon S3 (optional), and final channel creation.

Initial Channel Setup

  1. Open the Amazon IVS console.

    (You can also access the Amazon IVS console through the AWS Management Console.)

  2. From the navigation bar, use the Select a Region drop-down to choose a region. Your new channel will be created in this region.

  3. In the Get started box (top right), choose Create Channel.

  4. Under Channel configuration, accept the Default configuration. Optionally, specify a Channel name. Channel names are not unique, but they provide a way for you to distinguish channels other than the channel ARN (Amazon Resource Name).

                                Create a channel using the IVS Console: Specify channel
                                    configuration in the Create Channel window.
  5. If you want to auto-record to Amazon S3, continue with Set Up to Auto-Record to Amazon S3 (Optional) below. Otherwise, skip that and proceed directly to Final Channel Creation.

Set Up to Auto-Record to Amazon S3 (Optional)

Follow these steps to enable recording while creating a new channel:

  1. On the Create channel page, under Record and store streams, choose Auto-record to Amazon S3. Additional fields display, to choose an existing Recording configuration or create a new one.

                                Create a channel using the IVS Console: Select Auto-record
                                    to Amazon S3.
  2. Choose Create recording configuration. A new window opens, with options for creating an Amazon S3 bucket and attaching it to the new recording configuration.

                                Create a channel using the IVS Console: Specify storage
                                    options for the recording configuration.
  3. Fill out the fields:

    1. Optionally enter a Recording configuration name.

    2. Enter a Bucket Name.

    3. Leave the default selections as is.

    4. Optionally enable Merge fragmented streams by selecting Reconnect in a window. In the Reconnect window field which appears, accept the default or specify a number of seconds. If a broadcast disconnects and then reconnects within the specified reconnect interval, the multiple streams are considered a single broadcast and merged together.

  4. Choose Create recording configuration, to create a new recording-configuration resource with a unique ARN. Typically, creation of the recording configuration takes a few seconds, but it can be up to 20 seconds. When the recording configuration is created, you are returned to the Create channel window. There, the Record and store streams area shows your new Recording configuration, with its State as Active and the S3 Bucket that you created.

                                Create a channel using the IVS Console: New recording
                                    configuration created.

Final Channel Creation

  1. Choose Create channel, to create a new channel with a unique ARN. A channel details page is displayed for the new channel; keep this open. (Note: if you did not enable recording, Auto-record to S3 is set to Disabled and there is no Recording configuration section on the screen.)

                            Create a channel using the IVS Console: View channel stream,
                                playback and recording configuration, and stream sessions in the
                                Channel Details window.
  2. Important:

    • In the Stream configuration area, note the Ingest server and Stream key. You will use these in the next step, to set up streaming.

    • In the Playback configuration area, note the Playback URL. You will use it later, to play back your stream.

CLI Instructions

Creating a channel with the AWS CLI is an advanced option and requires that you first download and configure the CLI on your machine. For details, see the AWS Command Line Interface User Guide.

Follow one of the two procedures below, depending on whether you want to create a channel with or without recording enabled.

Create a Channel without Recording

  1. Run the create-channel command and pass in an optional name:

    aws ivs create-channel --name test-channel
  2. This returns a new channel:

    { "channel": { "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh", "authorized": false, "ingestEndpoint": "", "latencyMode": "LOW", "name": "channel-live", "playbackUrl": "", "recordingConfigurationArn": "none", "tags": {}, "type": "STANDARD" }, "streamKey": { "arn": "arn:aws:ivs:us-west-2:123456789012:stream-key/g1H2I3j4k5L6", "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh", "tags": {}, "value": "sk_us-west-2_abcdABCDefgh_567890abcdef" } }

    Note: The latencyMode values in the API are LOW and NORMAL. In the Amazon IVS console, these correspond to Ultra-low and Standard, respectively.

  3. Important: Note the ingestEndpoint, streamKey value, and playbackUrl. You will use these to set up streaming and playback.

Create a Channel with Recording

Prerequisite: Before starting this procedure, create an Amazon S3 bucket and note its ARN. See Getting Started with Amazon S3. The S3 bucket must be in the same region where you will create a recording configuration; see the known issue in Step 1 below.

Then follow these steps to create the channel:

  1. Run the create-recording-configuration command and pass in the ARN of an existing Amazon S3 bucket:

    aws ivs create-recording-configuration --name configuration-1 --destination-configuration s3={bucketName=test-bucket}

    Optionally, pass the thumbnail-configuration parameter to manually set the thumbnail-recording mode and thumbnail interval:

    aws ivs create-recording-configuration --name configuration-1 --destination-configuration s3={bucketName=s3_bucket_name} --thumbnail-configuration recordingMode="INTERVAL",targetIntervalSeconds=60

    Optionally, pass the recording-reconnect-window-seconds parameter to enable merge fragmented streams functionality:

    aws ivs create-recording-configuration --name configuration-1 --destination-configuration s3={bucketName=test-bucket} --recording-reconnect-window-seconds 60

    Known issue: In the us-east-1 region, if you use the AWS CLI to create a recording configuration, it returns success even if the S3 bucket is in a different region. In this case, the state of the recording configuration is CREATE_FAILED (instead of ACTIVE). (In other regions, the CLI correctly returns failure if the bucket is in a different region.)

    Workaround: Ensure that your S3 bucket is in the same region as the recording configuration. If you create a recording configuration in a different region as your S3 bucket, delete that recording configuration and create a new one with an S3 bucket from the correct region.

  2. This returns a new recording configuration with a unique ARN. The state of the recording configuration is CREATING, indicating that it is in the process of being created.

    { "recordingConfiguration": { "arn": "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te", "name": "configuration-1", "destinationConfiguration": { "s3": { "bucketName": "s3_bucket_name" } }, "recordingReconnectWindowSeconds": 60, "state": "CREATING", "tags": {}, "thumbnailConfiguration": { "recordingMode": "INTERVAL", "targetIntervalSeconds": 60 } } }
  3. Typically, creation of the recording configuration takes a few seconds, but it can be up to 20 seconds. To check that the recording configuration has been created,run the get-recording-configuration command:

    aws ivs get-recording-configuration --arn "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te"
  4. This returns a response indicating that the recording configuration was created (state is ACTIVE):

    { "recordingConfiguration": { "arn": "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te", "name": "configuration-1", "destinationConfiguration": { "s3": { "bucketName": "s3_bucket_name" } }, "recordingReconnectWindowSeconds": 60, "state": "ACTIVE", "tags": {}, "thumbnailConfiguration": { "recordingMode": "INTERVAL", "targetIntervalSeconds": 60 } } }
  5. To create a channel and enable recording on it, run the create-channel command and pass in the recording-configuration ARN:

    aws ivs create-channel --name channel-live --recording-configuration-arn "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te"

    Alternately, to enable recording on an existing channel, run the update-channel command and pass in the recording-configuration ARN:

    aws ivs update-channel --arn "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh" --recording-configuration-arn "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te"
  6. This returns a channel object with a non-”none” value for recordingConfigurationArn, indicating that recording is enabled. (The response below is from create-channel. The update-channel response does not include the streamKey object.)

    { "channel": { "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh", "authorized": false, "ingestEndpoint": "", "latencyMode": "LOW", "name": "channel-live", "playbackUrl": "", "recordingConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te", "tags": {}, "type": "STANDARD" }, "streamKey": { "arn": "arn:aws:ivs:us-west-2:123456789012:stream-key/g1H2I3j4k5L6", "channelArn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh", "tags": {}, "value": "sk_us-west-2_abcdABCDefgh_567890abcdef" } }
  7. Important: Note the ingestEndpoint, streamKey value, and playbackUrl. You will use these to set up streaming and playback.