CLI Instructions for Creating an IVS Channel
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
-
Run the
create-channel
command and pass in an optional name:aws ivs create-channel --name test-channel
-
This returns a new channel:
{ "channel": { "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh", "authorized": false, "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net", "insecureIngest": false, "latencyMode": "LOW", "name": "channel-live", "playbackRestrictionPolicyArn": "arn:aws:ivs:us-west-2:123456789012:playback-restriction-policy/abcdABCDefgh", "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8", "recordingConfigurationArn": "none", "srt": { "endpoint": "a1b2c3d4e5f6.srt.live-video.net", "passphrase: "ZU5A3yrjGAkghUNDr0c5NXBhsPrjlmtcKMNBluh7oImwJQ3ijeyClvMKxlpPcGAMziICJ", }, "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" } }
-
Important: Note the
ingestEndpoint
,streamKey value
, andplaybackUrl
. 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:
-
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 isCREATE_FAILED
(instead ofACTIVE
). (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.
-
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 } } }
-
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"
-
This returns a response indicating that the recording configuration was created (
state
isACTIVE
):{ "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 } } }
-
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"
-
This returns a channel object with a non-"none" value for
recordingConfigurationArn
, indicating that recording is enabled. (The response below is fromcreate-channel
. Theupdate-channel
response does not include thestreamKey
object.){ "channel": { "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh", "authorized": false, "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net", "insecureIngest": false, "latencyMode": "LOW", "name": "channel-live", "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8", "recordingConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:recording-configuration/mhndauNaO1te", "srt": { "endpoint": "a1b2c3d4e5f6.srt.live-video.net", "passphrase: "ZU5A3yrjGAkghUNDr0c5NXBhsPrjlmtcKMNBluh7oImwJQ3ijeyClvMKxlpPcGAMziICJ", }, "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" } }
-
Important: Note the
ingestEndpoint
,streamKey value
, andplaybackUrl
. You will use these to set up streaming and playback.