This documentation is for Version 1 of the Amazon CLI only. For documentation related to Version 2 of the Amazon CLI, see the Version 2 User Guide.
Amazon IVS Real-Time Streaming examples using Amazon CLI
The following code examples show you how to perform actions and implement common scenarios by using the Amazon Command Line Interface with Amazon IVS Real-Time Streaming.
Actions are code excerpts from larger programs and must be run in context. While actions show you how to call individual service functions, you can see actions in context in their related scenarios.
Each example includes a link to the complete source code, where you can find instructions on how to set up and run the code in context.
Topics
Actions
The following code example shows how to use create-encoder-configuration
.
- Amazon CLI
-
To create a composition encoder configuration
The following
create-encoder-configuration
example creates a composition encoder configuration with the specified properties.aws ivs-realtime create-encoder-configuration \ --name
test-ec
--videobitrate=3500000,framerate=30.0,height=1080,width=1920
Output:
{ "encoderConfiguration": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef", "name": "test-ec", "tags": {}, "video": { "bitrate": 3500000, "framerate": 30, "height": 1080, "width": 1920 } } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see CreateEncoderConfiguration
in Amazon CLI Command Reference.
-
The following code example shows how to use create-participant-token
.
- Amazon CLI
-
To create a stage participant token
The following
create-participant-token
example creates a participant toke for the specified stage.aws ivs-realtime create-participant-token \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --user-idbob
Output:
{ "participantToken": { "expirationTime": "2023-03-07T09:47:43+00:00", "participantId": "ABCDEfghij01234KLMN6789", "token": "abcd1234defg5678" } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see CreateParticipantToken
in Amazon CLI Command Reference.
-
The following code example shows how to use create-stage
.
- Amazon CLI
-
Example 1: To create a stage
The following
create-stage
example creates a stage and stage participant token for a specified user.aws ivs-realtime create-stage \ --name
stage1
\ --participant-token-configurationsuserId=alice
Output:
{ "participantTokens": [ { "participantId": "ABCDEfghij01234KLMN5678", "token": "a1b2c3d4567890ab", "userId": "alice" } ], "stage": { "activeSessionId": "st-a1b2c3d4e5f6g", "arn": "arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh", "endpoints": { "events": "wss://global.events.live-video.net", "whip": "https://1a2b3c4d5e6f.global-bm.whip.live-video.net" }, "name": "stage1", "tags": {} } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. Example 2: To create a stage and configure individial participant recording
The following
create-stage
example creates a stage and configures individual participant recording.aws ivs-realtime create-stage \ --name
stage1
\ --auto-participant-recording-configuration '{"mediaTypes": ["AUDIO_VIDEO"],"storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/abcdABCDefgh"}
'Output:
{ "stage": { "activeSessionId": "st-a1b2c3d4e5f6g", "arn": "arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh", "autoParticipantRecordingConfiguration": { "mediaTypes": [ "AUDIO_VIDEO" ], "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/abcdABCDefgh", }, "endpoints": { "events": "wss://global.events.live-video.net", "whip": "https://1a2b3c4d5e6f.global-bm.whip.live-video.net" }, "name": "stage1", "tags": {} } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see CreateStage
in Amazon CLI Command Reference.
-
The following code example shows how to use create-storage-configuration
.
- Amazon CLI
-
To create a composition storage configuration
The following
create-storage-configuration
example creates a composition storage configuration with the specified properties.aws ivs-realtime create-storage-configuration \ --name
"test-sc"
--s3"bucketName=test-bucket-name"
Output:
{ "storageConfiguration": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/ABabCDcdEFef", "name": "test-sc", "s3": { "bucketName": "test-bucket-name" }, "tags": {} } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see CreateStorageConfiguration
in Amazon CLI Command Reference.
-
The following code example shows how to use delete-encoder-configuration
.
- Amazon CLI
-
To delete a composition encoder configuration
The following
delete-encoder-configuration
deletes the composition encoder configuration specified by the given ARN (Amazon Resource Name).aws ivs-realtime delete-encoder-configuration \ --arn
"arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef"
This command produces no output.
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see DeleteEncoderConfiguration
in Amazon CLI Command Reference.
-
The following code example shows how to use delete-public-key
.
- Amazon CLI
-
To delete a public key
The following
delete-public-key
deletes the specified public key.aws ivs-realtime delete-public-key \ --arn
arn:aws:ivs:us-west-2:123456789012:public-key/abcdABC1efg2
This command produces no output.
For more information, see Distribute Participant Tokens
in the Amazon IVS Real-Time Streaming User Guide. -
For API details, see DeletePublicKey
in Amazon CLI Command Reference.
-
The following code example shows how to use delete-stage
.
- Amazon CLI
-
To delete a stage
The following
delete-stage
example deletes the specified stage.aws ivs-realtime delete-stage \ --arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
This command produces no output.
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see DeleteStage
in Amazon CLI Command Reference.
-
The following code example shows how to use delete-storage-configuration
.
- Amazon CLI
-
To delete a composition storage configuration
The following
delete-storage-configuration
deletes the composition storage configuration specified by the given ARN (Amazon Resource Name).aws ivs-realtime delete-storage-configuration \ --arn
"arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/ABabCDcdEFef"
This command produces no output.
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see DeleteStorageConfiguration
in Amazon CLI Command Reference.
-
The following code example shows how to use disconnect-participant
.
- Amazon CLI
-
To disconnect a stage participant
The following
disconnect-participant
example disconnects the specified participant from the specified stage.aws ivs-realtime disconnect-participant \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --participant-idABCDEfghij01234KLMN5678
This command produces no output.
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see DisconnectParticipant
in Amazon CLI Command Reference.
-
The following code example shows how to use get-composition
.
- Amazon CLI
-
Example 1: To get a composition with default layout settings
The following
get-composition
example gets the composition for the ARN (Amazon Resource Name) specified.aws ivs-realtime get-composition \ --arn
"arn:aws:ivs:ap-northeast-1:123456789012:composition/abcdABCDefgh"
Output:
{ "composition": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:composition/abcdABCDefgh", "destinations": [ { "configuration": { "channel": { "channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/abcABCdefDEg", "encoderConfigurationArn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" }, "name": "" }, "id": "AabBCcdDEefF", "startTime": "2023-10-16T23:26:00+00:00", "state": "ACTIVE" }, { "configuration": { "name": "", "s3": { "encoderConfigurationArns": [ "arn:aws:ivs:arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" ], "recordingConfiguration": { "format": "HLS" }, "storageConfigurationArn": "arn:arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/FefABabCDcdE" } }, "detail": { "s3": { "recordingPrefix": "aBcDeFgHhGfE/AbCdEfGhHgFe/GHFabcgefABC/composite" } }, "id": "GHFabcgefABC", "startTime": "2023-10-16T23:26:00+00:00", "state": "STARTING" } ], "layout": { "grid": { "featuredParticipantAttribute": "" "gridGap": 2, "omitStoppedVideo": false, "videoAspectRatio": "VIDEO", "videoFillMode": "" } }, "stageArn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd", "startTime": "2023-10-16T23:24:00+00:00", "state": "ACTIVE", "tags": {} } }
For more information, see Composite Recording (Real-Time Streaming)
in the Amazon Interactive Video Service User Guide. Example 2: To get a composition with PiP layout
The following
get-composition
example gets the composition for the ARN (Amazon Resource Name) specified, which uses PiP layout.aws ivs-realtime get-composition \ --arn
"arn:aws:ivs:ap-northeast-1:123456789012:composition/wxyzWXYZpqrs"
Output:
{ "composition": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:composition/wxyzWXYZpqrs", "destinations": [ { "configuration": { "channel": { "channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/abcABCdefDEg", "encoderConfigurationArn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" }, "name": "" }, "id": "AabBCcdDEefF", "startTime": "2023-10-16T23:26:00+00:00", "state": "ACTIVE" }, { "configuration": { "name": "", "s3": { "encoderConfigurationArns": [ "arn:aws:ivs:arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" ], "recordingConfiguration": { "format": "HLS" }, "storageConfigurationArn": "arn:arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/FefABabCDcdE" } }, "detail": { "s3": { "recordingPrefix": "aBcDeFgHhGfE/AbCdEfGhHgFe/GHFabcgefABC/composite" } }, "id": "GHFabcgefABC", "startTime": "2023-10-16T23:26:00+00:00", "state": "STARTING" } ], "layout": { "pip": { "featuredParticipantAttribute": "abcdefg", "gridGap": 0, "omitStoppedVideo": false, "pipBehavior": "STATIC", "pipOffset": 0, "pipParticipantAttribute": "", "pipPosition": "BOTTOM_RIGHT", "videoFillMode": "COVER" } }, "stageArn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd", "startTime": "2023-10-16T23:24:00+00:00", "state": "ACTIVE", "tags": {} } }
For more information, see Composite Recording (Real-Time Streaming)
in the Amazon Interactive Video Service User Guide. -
For API details, see GetComposition
in Amazon CLI Command Reference.
-
The following code example shows how to use get-encoder-configuration
.
- Amazon CLI
-
To get a composition encoder configuration
The following
get-encoder-configuration
example gets the composition encoder configuration specified by the given ARN (Amazon Resource Name).aws ivs-realtime get-encoder-configuration \ --arn
"arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/abcdABCDefgh"
Output:
{ "encoderConfiguration": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/abcdABCDefgh", "name": "test-ec", "tags": {}, "video": { "bitrate": 3500000, "framerate": 30, "height": 1080, "width": 1920 } } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see GetEncoderConfiguration
in Amazon CLI Command Reference.
-
The following code example shows how to use get-participant
.
- Amazon CLI
-
To get a stage participant
The following
get-participant
example gets the stage participant for a specified participant ID and session ID in the specified stage ARN (Amazon Resource Name).aws ivs-realtime get-participant \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --session-idst-a1b2c3d4e5f6g
\ --participant-idabCDEf12GHIj
Output:
{ "participant": { "browserName", "Google Chrome", "browserVersion", "116", "firstJoinTime": "2023-04-26T20:30:34+00:00", "ispName", "Comcast", "osName", "Microsoft Windows 10 Pro", "osVersion", "10.0.19044" "participantId": "abCDEf12GHIj", "published": true, "recordingS3BucketName": "bucket-name", "recordingS3Prefix": "abcdABCDefgh/st-a1b2c3d4e5f6g/abCDEf12GHIj/1234567890", "recordingState": "ACTIVE", "sdkVersion", "", "state": "CONNECTED", "userId": "", } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see GetParticipant
in Amazon CLI Command Reference.
-
The following code example shows how to use get-public-key
.
- Amazon CLI
-
To get an existing public key used to sign stage participant tokens
The following
get-public-key
example gets a public key specified by the provided ARN, for sigining stage participant tokens.aws ivs-realtime get-public-key \ --arn
arn:aws:ivs:us-west-2:123456789012:public-key/abcdABC1efg2
Output:
{ "publicKey": { "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/abcdABC1efg2", "name": "", "publicKeyMaterial": "-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEqVWUtqs6EktQMR1sCYmEzGvRwtaycI16\n9pmzcpiWu/uhNStGlteJ5odRfRwVkoQUMnSZXTCcbn9bBTTmiWo4mJcFOOAzsthH\n0UAb8NdD4tUE0At4a9hYP9IETEXAMPLE\n-----END PUBLIC KEY-----", "fingerprint": "12:a3:44:56:bc:7d:e8:9f:10:2g:34:hi:56:78:90:12", "tags": {} } }
For more information, see Distribute Participant Tokens
in the Amazon IVS Real-Time Streaming User Guide. -
For API details, see GetPublicKey
in Amazon CLI Command Reference.
-
The following code example shows how to use get-stage-session
.
- Amazon CLI
-
To get a stage session
The following
get-stage-session
example gets the stage session for a specified session ID of a specified stage ARN (Amazon Resource Name).aws ivs-realtime get-stage-session \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --session-idst-a1b2c3d4e5f6g
Output:
{ "stageSession": { "endTime": "2023-04-26T20:36:29+00:00", "sessionId": "st-a1b2c3d4e5f6g", "startTime": "2023-04-26T20:30:29.602000+00:00" } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see GetStageSession
in Amazon CLI Command Reference.
-
The following code example shows how to use get-stage
.
- Amazon CLI
-
To get a stage's configuration information
The following
get-stage
example gets the stage configuration for a specified stage ARN (Amazon Resource Name).aws ivs-realtime get-stage \ --arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
Output:
{ "stage": { "activeSessionId": "st-a1b2c3d4e5f6g", "arn": "arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh", "autoParticipantRecordingConfiguration": { "mediaTypes": [ "AUDIO_VIDEO" ], "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/abcdABCDefgh", }, "endpoints": { "events": "wss://global.events.live-video.net", "whip": "https://1a2b3c4d5e6f.global-bm.whip.live-video.net" }, "name": "test", "tags": {} } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see GetStage
in Amazon CLI Command Reference.
-
The following code example shows how to use get-storage-configuration
.
- Amazon CLI
-
To get a composition storage configuration
The following
get-storage-configuration
example gets the composition storage configuration specified by the given ARN (Amazon Resource Name).aws ivs-realtime get-storage-configuration \ --name
arn
"arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/abcdABCDefgh"
Output:
{ "storageConfiguration": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/abcdABCDefgh", "name": "test-sc", "s3": { "bucketName": "test-bucket-name" }, "tags": {} } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see GetStorageConfiguration
in Amazon CLI Command Reference.
-
The following code example shows how to use import-public-key
.
- Amazon CLI
-
To import an existing public key to be used to sign stage participant tokens
The following
import-public-key
example imports a public key from a material file, to be used for sigining stage participant tokens.aws ivs-realtime import-public-key \ --public-key-material="`cat public.pem`"
Output:
{ "publicKey": { "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/abcdABC1efg2", "name": "", "publicKeyMaterial": "-----BEGIN PUBLIC KEY-----\nMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEqVWUtqs6EktQMR1sCYmEzGvRwtaycI16\n9pmzcpiWu/uhNStGlteJ5odRfRwVkoQUMnSZXTCcbn9bBTTmiWo4mJcFOOAzsthH\n0UAb8NdD4tUE0At4a9hYP9IETEXAMPLE\n-----END PUBLIC KEY-----", "fingerprint": "12:a3:44:56:bc:7d:e8:9f:10:2g:34:hi:56:78:90:12", "tags": {} } }
For more information, see Distribute Participant Tokens
in the Amazon IVS Real-Time Streaming User Guide. -
For API details, see ImportPublicKey
in Amazon CLI Command Reference.
-
The following code example shows how to use list-compositions
.
- Amazon CLI
-
To get a list of compositions
The following
list-compositions
lists all compositions for your Amazon account, in the Amazon region where the API request is processed.aws ivs-realtime list-compositions
Output:
{ "compositions": [ { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:composition/abcdABCDefgh", "destinations": [ { "id": "AabBCcdDEefF", "startTime": "2023-10-16T23:25:23+00:00", "state": "ACTIVE" } ], "stageArn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd", "startTime": "2023-10-16T23:25:21+00:00", "state": "ACTIVE", "tags": {} }, { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:composition/ABcdabCDefgh", "destinations": [ { "endTime": "2023-10-16T23:25:00.786512+00:00", "id": "aABbcCDdeEFf", "startTime": "2023-10-16T23:24:01+00:00", "state": "STOPPED" }, { "endTime": "2023-10-16T23:25:00.786512+00:00", "id": "deEFfaABbcCD", "startTime": "2023-10-16T23:24:01+00:00", "state": "STOPPED" } ], "endTime": "2023-10-16T23:25:00+00:00", "stageArn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/efghabcdABCD", "startTime": "2023-10-16T23:24:00+00:00", "state": "STOPPED", "tags": {} } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListCompositions
in Amazon CLI Command Reference.
-
The following code example shows how to use list-encoder-configurations
.
- Amazon CLI
-
To list composition encoder configurations
The following
list-encoder-configurations
lists all composition encoder configurations for your Amazon account, in the Amazon region where the API request is processed.aws ivs-realtime list-encoder-configurations
Output:
{ "encoderConfigurations": [ { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/abcdABCDefgh", "name": "test-ec-1", "tags": {} }, { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABCefgEFGabc", "name": "test-ec-2", "tags": {} } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListEncoderConfigurations
in Amazon CLI Command Reference.
-
The following code example shows how to use list-participant-events
.
- Amazon CLI
-
To get a list of stage participant events
The following
list-participant-events
example lists all participant events for a specified participant ID and session ID of a specified stage ARN (Amazon Resource Name).aws ivs-realtime list-participant-events \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --session-idst-a1b2c3d4e5f6g
\ --participant-idabCDEf12GHIj
Output:
{ "events": [ { "eventTime": "2023-04-26T20:36:28+00:00", "name": "LEFT", "participantId": "abCDEf12GHIj" }, { "eventTime": "2023-04-26T20:36:28+00:00", "name": "PUBLISH_STOPPED", "participantId": "abCDEf12GHIj" }, { "eventTime": "2023-04-26T20:30:34+00:00", "name": "JOINED", "participantId": "abCDEf12GHIj" }, { "eventTime": "2023-04-26T20:30:34+00:00", "name": "PUBLISH_STARTED", "participantId": "abCDEf12GHIj" } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListParticipantEvents
in Amazon CLI Command Reference.
-
The following code example shows how to use list-participants
.
- Amazon CLI
-
To get a list of stage participants
The following
list-participants
example lists all participants for a specified session ID of a specified stage ARN (Amazon Resource Name).aws ivs-realtime list-participants \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --session-idst-a1b2c3d4e5f6g
Output:
{ "participants": [ { "firstJoinTime": "2023-04-26T20:30:34+00:00", "participantId": "abCDEf12GHIj" "published": true, "recordingState": "STOPPED", "state": "DISCONNECTED", "userId": "" } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListParticipants
in Amazon CLI Command Reference.
-
The following code example shows how to use list-public-keys
.
- Amazon CLI
-
To list existing public keys available to sign stage participant tokens
The following
list-public-keys
example lists all public keys available for sigining stage participant tokens, in the Amazon region where the API request is processed.aws ivs-realtime list-public-keys
Output:
{ "publicKeys": [ { "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/abcdABC1efg2", "name": "", "tags": {} }, { "arn": "arn:aws:ivs:us-west-2:123456789012:public-key/3bcdABCDefg4", "name": "", "tags": {} } ] }
For more information, see Distribute Participant Tokens
in the Amazon IVS Real-Time Streaming User Guide. -
For API details, see ListPublicKeys
in Amazon CLI Command Reference.
-
The following code example shows how to use list-stage-sessions
.
- Amazon CLI
-
To get a list of stage sessions
The following
list-stage-sessions
example lists all sessions for a specified stage ARN (Amazon Resource Name).aws ivs-realtime list-stage-sessions \ --stage-arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
Output:
{ "stageSessions": [ { "endTime": "2023-04-26T20:36:29+00:00", "sessionId": "st-a1b2c3d4e5f6g", "startTime": "2023-04-26T20:30:29.602000+00:00" } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListStageSessions
in Amazon CLI Command Reference.
-
The following code example shows how to use list-stages
.
- Amazon CLI
-
To get summary information about all stages
The following
list-stages
example lists all stages for your Amazon account, in the Amazon region where the API request is processed.aws ivs-realtime list-stages
Output:
{ "stages": [ { "activeSessionId": "st-a1b2c3d4e5f6g", "arn": "arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh", "name": "stage1", "tags": {} }, { "activeSessionId": "st-a123bcd456efg", "arn": "arn:aws:ivs:us-west-2:123456789012:stage/abcd1234ABCD", "name": "stage2", "tags": {} }, { "activeSessionId": "st-abcDEF1234ghi", "arn": "arn:aws:ivs:us-west-2:123456789012:stage/ABCD1234efgh", "name": "stage3", "tags": {} } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListStages
in Amazon CLI Command Reference.
-
The following code example shows how to use list-storage-configurations
.
- Amazon CLI
-
To list composition storage configurations
The following
list-storage-configurations
lists all composition storage configurations for your Amazon account, in the Amazon region where the API request is processed.aws ivs-realtime list-storage-configurations
Output:
{ "storageConfigurations": [ { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/abcdABCDefgh", "name": "test-sc-1", "s3": { "bucketName": "test-bucket-1-name" }, "tags": {} }, { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/ABCefgEFGabc", "name": "test-sc-2", "s3": { "bucketName": "test-bucket-2-name" }, "tags": {} } ] }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see ListStorageConfigurations
in Amazon CLI Command Reference.
-
The following code example shows how to use start-composition
.
- Amazon CLI
-
Example 1: To start a composition with default layout settings
The following
start-composition
example starts a composition for the specified stage to be streamed to the specified locations.aws ivs-realtime start-composition \ --stage-arn
arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd
\ --destinations '[{"channel": {"channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/abcABCdefDEg", \ "encoderConfigurationArn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef"}}, \ {"s3":{"encoderConfigurationArns":["arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef"], \ "storageConfigurationArn":"arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/FefABabCDcdE"}}]
'Output:
{ "composition": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:composition/abcdABCDefgh", "destinations": [ { "configuration": { "channel": { "channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/abcABCdefDEg", "encoderConfigurationArn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" }, "name": "" }, "id": "AabBCcdDEefF", "state": "STARTING" }, { "configuration": { "name": "", "s3": { "encoderConfigurationArns": [ "arn:aws:ivs:arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" ], "recordingConfiguration": { "format": "HLS" }, "storageConfigurationArn": "arn:arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/FefABabCDcdE" } }, "detail": { "s3": { "recordingPrefix": "aBcDeFgHhGfE/AbCdEfGhHgFe/GHFabcgefABC/composite" } }, "id": "GHFabcgefABC", "state": "STARTING" } ], "layout": { "grid": { "featuredParticipantAttribute": "" "gridGap": 2, "omitStoppedVideo": false, "videoAspectRatio": "VIDEO", "videoFillMode": "" } }, "stageArn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd", "startTime": "2023-10-16T23:24:00+00:00", "state": "STARTING", "tags": {} } }
For more information, see Composite Recording (Real-Time Streaming)
in the Amazon Interactive Video Service User Guide. Example 2: To start a composition with PiP layout
The following
start-composition
example starts a composition for the specified stage to be streamed to the specified locations using PiP layout.aws ivs-realtime start-composition \ --stage-arn
arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd
\ --destinations '[{"channel": {"channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/abcABCdefDEg", \ "encoderConfigurationArn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef"}}, \ {"s3":{"encoderConfigurationArns":["arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef"], \ "storageConfigurationArn":"arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/FefABabCDcdE"}}]
' \ --layout pip='{featuredParticipantAttribute="abcdefg"}'Output:
{ "composition": { "arn": "arn:aws:ivs:ap-northeast-1:123456789012:composition/wxyzWXYZpqrs", "destinations": [ { "configuration": { "channel": { "channelArn": "arn:aws:ivs:ap-northeast-1:123456789012:channel/abcABCdefDEg", "encoderConfigurationArn": "arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" }, "name": "" }, "id": "AabBCcdDEefF", "state": "STARTING" }, { "configuration": { "name": "", "s3": { "encoderConfigurationArns": [ "arn:aws:ivs:arn:aws:ivs:ap-northeast-1:123456789012:encoder-configuration/ABabCDcdEFef" ], "recordingConfiguration": { "format": "HLS" }, "storageConfigurationArn": "arn:arn:aws:ivs:ap-northeast-1:123456789012:storage-configuration/FefABabCDcdE" } }, "detail": { "s3": { "recordingPrefix": "aBcDeFgHhGfE/AbCdEfGhHgFe/GHFabcgefABC/composite" } }, "id": "GHFabcgefABC", "state": "STARTING" } ], "layout": { "pip": { "featuredParticipantAttribute": "abcdefg", "gridGap": 0, "omitStoppedVideo": false, "pipBehavior": "STATIC", "pipOffset": 0, "pipParticipantAttribute": "", "pipPosition": "BOTTOM_RIGHT", "videoFillMode": "COVER" } }, "stageArn": "arn:aws:ivs:ap-northeast-1:123456789012:stage/defgABCDabcd", "startTime": "2023-10-16T23:24:00+00:00", "state": "STARTING", "tags": {} } }
For more information, see Composite Recording (Real-Time Streaming)
in the Amazon Interactive Video Service User Guide. -
For API details, see StartComposition
in Amazon CLI Command Reference.
-
The following code example shows how to use stop-composition
.
- Amazon CLI
-
To stop a composition
The following
stop-composition
stops the composition specified by the given ARN (Amazon Resource Name).aws ivs-realtime stop-composition \ --arn
"arn:aws:ivs:ap-northeast-1:123456789012:composition/abcdABCDefgh"
This command produces no output.
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see StopComposition
in Amazon CLI Command Reference.
-
The following code example shows how to use update-stage
.
- Amazon CLI
-
To update a stage's configuration
The following
update-stage
example updates a stage for a specified stage ARN to update the stage name and configure individual participant recording.aws ivs-realtime update-stage \ --arn
arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh
\ --auto-participant-recording-configuration '{"mediaTypes": ["AUDIO_VIDEO"],"storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/abcdABCDefgh"}
' \ --namestage1a
Output:
{ "stage": { "arn": "arn:aws:ivs:us-west-2:123456789012:stage/abcdABCDefgh", "autoParticipantRecordingConfiguration": { "mediaTypes": [ "AUDIO_VIDEO" ], "storageConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:storage-configuration/abcdABCDefgh", }, "endpoints": { "events": "wss://global.events.live-video.net", "whip": "https://1a2b3c4d5e6f.global-bm.whip.live-video.net" }, "name": "stage1a", "tags": {} } }
For more information, see Enabling Multiple Hosts on an Amazon IVS Stream
in the Amazon Interactive Video Service User Guide. -
For API details, see UpdateStage
in Amazon CLI Command Reference.
-