SDK for PHP 3.x

Client: Aws\IVSRealTime\IVSRealTimeClient
Service ID: ivs-realtime
Version: 2020-07-14

This page describes the parameters and results for the operations of the Amazon Interactive Video Service RealTime (2020-07-14), and shows how to use the Aws\IVSRealTime\IVSRealTimeClient object to call the described operations. This documentation is specific to the 2020-07-14 API version of the service.

Operation Summary

Each of the following operations can be created from a client using $client->getCommand('CommandName'), where "CommandName" is the name of one of the following operations. Note: a command is a value that encapsulates an operation and the parameters used to create an HTTP request.

You can also create and send a command immediately using the magic methods available on a client object: $client->commandName(/* parameters */). You can send the command asynchronously (returning a promise) by appending the word "Async" to the operation name: $client->commandNameAsync(/* parameters */).

CreateEncoderConfiguration ( array $params = [] )
Creates an EncoderConfiguration object.
CreateParticipantToken ( array $params = [] )
Creates an additional token for a specified stage.
CreateStage ( array $params = [] )
Creates a new stage (and optionally participant tokens).
CreateStorageConfiguration ( array $params = [] )
Creates a new storage configuration, used to enable recording to Amazon S3.
DeleteEncoderConfiguration ( array $params = [] )
Deletes an EncoderConfiguration resource.
DeleteStage ( array $params = [] )
Shuts down and deletes the specified stage (disconnecting all participants).
DeleteStorageConfiguration ( array $params = [] )
Deletes the storage configuration for the specified ARN.
DisconnectParticipant ( array $params = [] )
Disconnects a specified participant and revokes the participant permanently from a specified stage.
GetComposition ( array $params = [] )
Get information about the specified Composition resource.
GetEncoderConfiguration ( array $params = [] )
Gets information about the specified EncoderConfiguration resource.
GetParticipant ( array $params = [] )
Gets information about the specified participant token.
GetStage ( array $params = [] )
Gets information for the specified stage.
GetStageSession ( array $params = [] )
Gets information for the specified stage session.
GetStorageConfiguration ( array $params = [] )
Gets the storage configuration for the specified ARN.
ListCompositions ( array $params = [] )
Gets summary information about all Compositions in your account, in the AWS region where the API request is processed.
ListEncoderConfigurations ( array $params = [] )
Gets summary information about all EncoderConfigurations in your account, in the AWS region where the API request is processed.
ListParticipantEvents ( array $params = [] )
Lists events for a specified participant that occurred during a specified stage session.
ListParticipants ( array $params = [] )
Lists all participants in a specified stage session.
ListStageSessions ( array $params = [] )
Gets all sessions for a specified stage.
ListStages ( array $params = [] )
Gets summary information about all stages in your account, in the AWS region where the API request is processed.
ListStorageConfigurations ( array $params = [] )
Gets summary information about all storage configurations in your account, in the AWS region where the API request is processed.
ListTagsForResource ( array $params = [] )
Gets information about AWS tags for the specified ARN.
StartComposition ( array $params = [] )
Starts a Composition from a stage based on the configuration provided in the request.
StopComposition ( array $params = [] )
Stops and deletes a Composition resource.
TagResource ( array $params = [] )
Adds or updates tags for the AWS resource with the specified ARN.
UntagResource ( array $params = [] )
Removes tags from the resource with the specified ARN.
UpdateStage ( array $params = [] )
Updates a stage’s configuration.

Paginators

Paginators handle automatically iterating over paginated API results. Paginators are associated with specific API operations, and they accept the parameters that the corresponding API operation accepts. You can get a paginator from a client class using getPaginator($paginatorName, $operationParameters). This client supports the following paginators:

ListCompositions
ListEncoderConfigurations
ListParticipantEvents
ListParticipants
ListStageSessions
ListStages
ListStorageConfigurations

Operations

CreateEncoderConfiguration

$result = $client->createEncoderConfiguration([/* ... */]);
$promise = $client->createEncoderConfigurationAsync([/* ... */]);

Creates an EncoderConfiguration object.

Parameter Syntax

$result = $client->createEncoderConfiguration([
    'name' => '<string>',
    'tags' => ['<string>', ...],
    'video' => [
        'bitrate' => <integer>,
        'framerate' => <float>,
        'height' => <integer>,
        'width' => <integer>,
    ],
]);

Parameter Details

Members
name
Type: string

Optional name to identify the resource.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

video
Type: Video structure

Video configuration. Default: video resolution 1280x720, bitrate 2500 kbps, 30 fps.

Result Syntax

[
    'encoderConfiguration' => [
        'arn' => '<string>',
        'name' => '<string>',
        'tags' => ['<string>', ...],
        'video' => [
            'bitrate' => <integer>,
            'framerate' => <float>,
            'height' => <integer>,
            'width' => <integer>,
        ],
    ],
]

Result Details

Members
encoderConfiguration
Type: EncoderConfiguration structure

The EncoderConfiguration that was created.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

PendingVerification:

CreateParticipantToken

$result = $client->createParticipantToken([/* ... */]);
$promise = $client->createParticipantTokenAsync([/* ... */]);

Creates an additional token for a specified stage. This can be done after stage creation or when tokens expire. Tokens always are scoped to the stage for which they are created.

Encryption keys are owned by Amazon IVS and never used directly by your application.

Parameter Syntax

$result = $client->createParticipantToken([
    'attributes' => ['<string>', ...],
    'capabilities' => ['<string>', ...],
    'duration' => <integer>,
    'stageArn' => '<string>', // REQUIRED
    'userId' => '<string>',
]);

Parameter Details

Members
attributes
Type: Associative array of custom strings keys (String) to strings

Application-provided attributes to encode into the token and attach to a stage. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

capabilities
Type: Array of strings

Set of capabilities that the user is allowed to perform in the stage. Default: PUBLISH, SUBSCRIBE.

duration
Type: int

Duration (in minutes), after which the token expires. Default: 720 (12 hours).

stageArn
Required: Yes
Type: string

ARN of the stage to which this token is scoped.

userId
Type: string

Name that can be specified to help identify the token. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

Result Syntax

[
    'participantToken' => [
        'attributes' => ['<string>', ...],
        'capabilities' => ['<string>', ...],
        'duration' => <integer>,
        'expirationTime' => <DateTime>,
        'participantId' => '<string>',
        'token' => '<string>',
        'userId' => '<string>',
    ],
]

Result Details

Members
participantToken
Type: ParticipantToken structure

The participant token that was created.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

ServiceQuotaExceededException:

PendingVerification:

CreateStage

$result = $client->createStage([/* ... */]);
$promise = $client->createStageAsync([/* ... */]);

Creates a new stage (and optionally participant tokens).

Parameter Syntax

$result = $client->createStage([
    'name' => '<string>',
    'participantTokenConfigurations' => [
        [
            'attributes' => ['<string>', ...],
            'capabilities' => ['<string>', ...],
            'duration' => <integer>,
            'userId' => '<string>',
        ],
        // ...
    ],
    'tags' => ['<string>', ...],
]);

Parameter Details

Members
name
Type: string

Optional name that can be specified for the stage being created.

participantTokenConfigurations
Type: Array of ParticipantTokenConfiguration structures

Array of participant token configuration objects to attach to the new stage.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

Result Syntax

[
    'participantTokens' => [
        [
            'attributes' => ['<string>', ...],
            'capabilities' => ['<string>', ...],
            'duration' => <integer>,
            'expirationTime' => <DateTime>,
            'participantId' => '<string>',
            'token' => '<string>',
            'userId' => '<string>',
        ],
        // ...
    ],
    'stage' => [
        'activeSessionId' => '<string>',
        'arn' => '<string>',
        'name' => '<string>',
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
participantTokens
Type: Array of ParticipantToken structures

Participant tokens attached to the stage. These correspond to the participants in the request.

stage
Type: Stage structure

The stage that was created.

Errors

ValidationException:

AccessDeniedException:

ServiceQuotaExceededException:

PendingVerification:

CreateStorageConfiguration

$result = $client->createStorageConfiguration([/* ... */]);
$promise = $client->createStorageConfigurationAsync([/* ... */]);

Creates a new storage configuration, used to enable recording to Amazon S3. When a StorageConfiguration is created, IVS will modify the S3 bucketPolicy of the provided bucket. This will ensure that IVS has sufficient permissions to write content to the provided bucket.

Parameter Syntax

$result = $client->createStorageConfiguration([
    'name' => '<string>',
    's3' => [ // REQUIRED
        'bucketName' => '<string>', // REQUIRED
    ],
    'tags' => ['<string>', ...],
]);

Parameter Details

Members
name
Type: string

Storage configuration name. The value does not need to be unique.

s3
Required: Yes
Type: S3StorageConfiguration structure

A complex type that contains a storage configuration for where recorded video will be stored.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

Result Syntax

[
    'storageConfiguration' => [
        'arn' => '<string>',
        'name' => '<string>',
        's3' => [
            'bucketName' => '<string>',
        ],
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
storageConfiguration
Type: StorageConfiguration structure

The StorageConfiguration that was created.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

PendingVerification:

DeleteEncoderConfiguration

$result = $client->deleteEncoderConfiguration([/* ... */]);
$promise = $client->deleteEncoderConfigurationAsync([/* ... */]);

Deletes an EncoderConfiguration resource. Ensures that no Compositions are using this template; otherwise, returns an error.

Parameter Syntax

$result = $client->deleteEncoderConfiguration([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the EncoderConfiguration.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

DeleteStage

$result = $client->deleteStage([/* ... */]);
$promise = $client->deleteStageAsync([/* ... */]);

Shuts down and deletes the specified stage (disconnecting all participants).

Parameter Syntax

$result = $client->deleteStage([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the stage to be deleted.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

ConflictException:

PendingVerification:

DeleteStorageConfiguration

$result = $client->deleteStorageConfiguration([/* ... */]);
$promise = $client->deleteStorageConfigurationAsync([/* ... */]);

Deletes the storage configuration for the specified ARN.

If you try to delete a storage configuration that is used by a Composition, you will get an error (409 ConflictException). To avoid this, for all Compositions that reference the storage configuration, first use StopComposition and wait for it to complete, then use DeleteStorageConfiguration.

Parameter Syntax

$result = $client->deleteStorageConfiguration([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the storage configuration to be deleted.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

DisconnectParticipant

$result = $client->disconnectParticipant([/* ... */]);
$promise = $client->disconnectParticipantAsync([/* ... */]);

Disconnects a specified participant and revokes the participant permanently from a specified stage.

Parameter Syntax

$result = $client->disconnectParticipant([
    'participantId' => '<string>', // REQUIRED
    'reason' => '<string>',
    'stageArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
participantId
Required: Yes
Type: string

Identifier of the participant to be disconnected. This is assigned by IVS and returned by CreateParticipantToken.

reason
Type: string

Description of why this participant is being disconnected.

stageArn
Required: Yes
Type: string

ARN of the stage to which the participant is attached.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

PendingVerification:

GetComposition

$result = $client->getComposition([/* ... */]);
$promise = $client->getCompositionAsync([/* ... */]);

Get information about the specified Composition resource.

Parameter Syntax

$result = $client->getComposition([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the Composition resource.

Result Syntax

[
    'composition' => [
        'arn' => '<string>',
        'destinations' => [
            [
                'configuration' => [
                    'channel' => [
                        'channelArn' => '<string>',
                        'encoderConfigurationArn' => '<string>',
                    ],
                    'name' => '<string>',
                    's3' => [
                        'encoderConfigurationArns' => ['<string>', ...],
                        'recordingConfiguration' => [
                            'format' => 'HLS',
                        ],
                        'storageConfigurationArn' => '<string>',
                    ],
                ],
                'detail' => [
                    's3' => [
                        'recordingPrefix' => '<string>',
                    ],
                ],
                'endTime' => <DateTime>,
                'id' => '<string>',
                'startTime' => <DateTime>,
                'state' => 'STARTING|ACTIVE|STOPPING|RECONNECTING|FAILED|STOPPED',
            ],
            // ...
        ],
        'endTime' => <DateTime>,
        'layout' => [
            'grid' => [
                'featuredParticipantAttribute' => '<string>',
                'gridGap' => <integer>,
                'omitStoppedVideo' => true || false,
                'videoAspectRatio' => 'AUTO|VIDEO|SQUARE|PORTRAIT',
                'videoFillMode' => 'FILL|COVER|CONTAIN',
            ],
            'pip' => [
                'featuredParticipantAttribute' => '<string>',
                'gridGap' => <integer>,
                'omitStoppedVideo' => true || false,
                'pipBehavior' => 'STATIC|DYNAMIC',
                'pipHeight' => <integer>,
                'pipOffset' => <integer>,
                'pipParticipantAttribute' => '<string>',
                'pipPosition' => 'TOP_LEFT|TOP_RIGHT|BOTTOM_LEFT|BOTTOM_RIGHT',
                'pipWidth' => <integer>,
                'videoFillMode' => 'FILL|COVER|CONTAIN',
            ],
        ],
        'stageArn' => '<string>',
        'startTime' => <DateTime>,
        'state' => 'STARTING|ACTIVE|STOPPING|FAILED|STOPPED',
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
composition
Type: Composition structure

The Composition that was returned.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

GetEncoderConfiguration

$result = $client->getEncoderConfiguration([/* ... */]);
$promise = $client->getEncoderConfigurationAsync([/* ... */]);

Gets information about the specified EncoderConfiguration resource.

Parameter Syntax

$result = $client->getEncoderConfiguration([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the EncoderConfiguration resource.

Result Syntax

[
    'encoderConfiguration' => [
        'arn' => '<string>',
        'name' => '<string>',
        'tags' => ['<string>', ...],
        'video' => [
            'bitrate' => <integer>,
            'framerate' => <float>,
            'height' => <integer>,
            'width' => <integer>,
        ],
    ],
]

Result Details

Members
encoderConfiguration
Type: EncoderConfiguration structure

The EncoderConfiguration that was returned.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

GetParticipant

$result = $client->getParticipant([/* ... */]);
$promise = $client->getParticipantAsync([/* ... */]);

Gets information about the specified participant token.

Parameter Syntax

$result = $client->getParticipant([
    'participantId' => '<string>', // REQUIRED
    'sessionId' => '<string>', // REQUIRED
    'stageArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
participantId
Required: Yes
Type: string

Unique identifier for the participant. This is assigned by IVS and returned by CreateParticipantToken.

sessionId
Required: Yes
Type: string

ID of a session within the stage.

stageArn
Required: Yes
Type: string

Stage ARN.

Result Syntax

[
    'participant' => [
        'attributes' => ['<string>', ...],
        'browserName' => '<string>',
        'browserVersion' => '<string>',
        'firstJoinTime' => <DateTime>,
        'ispName' => '<string>',
        'osName' => '<string>',
        'osVersion' => '<string>',
        'participantId' => '<string>',
        'published' => true || false,
        'sdkVersion' => '<string>',
        'state' => 'CONNECTED|DISCONNECTED',
        'userId' => '<string>',
    ],
]

Result Details

Members
participant
Type: Participant structure

The participant that is returned.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

GetStage

$result = $client->getStage([/* ... */]);
$promise = $client->getStageAsync([/* ... */]);

Gets information for the specified stage.

Parameter Syntax

$result = $client->getStage([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the stage for which the information is to be retrieved.

Result Syntax

[
    'stage' => [
        'activeSessionId' => '<string>',
        'arn' => '<string>',
        'name' => '<string>',
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
stage
Type: Stage structure

The stage that is returned.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

GetStageSession

$result = $client->getStageSession([/* ... */]);
$promise = $client->getStageSessionAsync([/* ... */]);

Gets information for the specified stage session.

Parameter Syntax

$result = $client->getStageSession([
    'sessionId' => '<string>', // REQUIRED
    'stageArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
sessionId
Required: Yes
Type: string

ID of a session within the stage.

stageArn
Required: Yes
Type: string

ARN of the stage for which the information is to be retrieved.

Result Syntax

[
    'stageSession' => [
        'endTime' => <DateTime>,
        'sessionId' => '<string>',
        'startTime' => <DateTime>,
    ],
]

Result Details

Members
stageSession
Type: StageSession structure

The stage session that is returned.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

GetStorageConfiguration

$result = $client->getStorageConfiguration([/* ... */]);
$promise = $client->getStorageConfigurationAsync([/* ... */]);

Gets the storage configuration for the specified ARN.

Parameter Syntax

$result = $client->getStorageConfiguration([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the storage configuration to be retrieved.

Result Syntax

[
    'storageConfiguration' => [
        'arn' => '<string>',
        'name' => '<string>',
        's3' => [
            'bucketName' => '<string>',
        ],
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
storageConfiguration
Type: StorageConfiguration structure

The StorageConfiguration that was returned.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

ListCompositions

$result = $client->listCompositions([/* ... */]);
$promise = $client->listCompositionsAsync([/* ... */]);

Gets summary information about all Compositions in your account, in the AWS region where the API request is processed.

Parameter Syntax

$result = $client->listCompositions([
    'filterByEncoderConfigurationArn' => '<string>',
    'filterByStageArn' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
filterByEncoderConfigurationArn
Type: string

Filters the Composition list to match the specified EncoderConfiguration attached to at least one of its output.

filterByStageArn
Type: string

Filters the Composition list to match the specified Stage ARN.

maxResults
Type: int

Maximum number of results to return. Default: 100.

nextToken
Type: string

The first Composition to retrieve. This is used for pagination; see the nextToken response field.

Result Syntax

[
    'compositions' => [
        [
            'arn' => '<string>',
            'destinations' => [
                [
                    'endTime' => <DateTime>,
                    'id' => '<string>',
                    'startTime' => <DateTime>,
                    'state' => 'STARTING|ACTIVE|STOPPING|RECONNECTING|FAILED|STOPPED',
                ],
                // ...
            ],
            'endTime' => <DateTime>,
            'stageArn' => '<string>',
            'startTime' => <DateTime>,
            'state' => 'STARTING|ACTIVE|STOPPING|FAILED|STOPPED',
            'tags' => ['<string>', ...],
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
compositions
Required: Yes
Type: Array of CompositionSummary structures

List of the matching Compositions (summary information only).

nextToken
Type: string

If there are more compositions than maxResults, use nextToken in the request to get the next set.

Errors

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

ListEncoderConfigurations

$result = $client->listEncoderConfigurations([/* ... */]);
$promise = $client->listEncoderConfigurationsAsync([/* ... */]);

Gets summary information about all EncoderConfigurations in your account, in the AWS region where the API request is processed.

Parameter Syntax

$result = $client->listEncoderConfigurations([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

Maximum number of results to return. Default: 100.

nextToken
Type: string

The first encoder configuration to retrieve. This is used for pagination; see the nextToken response field.

Result Syntax

[
    'encoderConfigurations' => [
        [
            'arn' => '<string>',
            'name' => '<string>',
            'tags' => ['<string>', ...],
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
encoderConfigurations
Required: Yes
Type: Array of EncoderConfigurationSummary structures

List of the matching EncoderConfigurations (summary information only).

nextToken
Type: string

If there are more encoder configurations than maxResults, use nextToken in the request to get the next set.

Errors

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

ListParticipantEvents

$result = $client->listParticipantEvents([/* ... */]);
$promise = $client->listParticipantEventsAsync([/* ... */]);

Lists events for a specified participant that occurred during a specified stage session.

Parameter Syntax

$result = $client->listParticipantEvents([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'participantId' => '<string>', // REQUIRED
    'sessionId' => '<string>', // REQUIRED
    'stageArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
maxResults
Type: int

Maximum number of results to return. Default: 50.

nextToken
Type: string

The first participant event to retrieve. This is used for pagination; see the nextToken response field.

participantId
Required: Yes
Type: string

Unique identifier for this participant. This is assigned by IVS and returned by CreateParticipantToken.

sessionId
Required: Yes
Type: string

ID of a session within the stage.

stageArn
Required: Yes
Type: string

Stage ARN.

Result Syntax

[
    'events' => [
        [
            'errorCode' => 'INSUFFICIENT_CAPABILITIES|QUOTA_EXCEEDED|PUBLISHER_NOT_FOUND',
            'eventTime' => <DateTime>,
            'name' => 'JOINED|LEFT|PUBLISH_STARTED|PUBLISH_STOPPED|SUBSCRIBE_STARTED|SUBSCRIBE_STOPPED|PUBLISH_ERROR|SUBSCRIBE_ERROR|JOIN_ERROR',
            'participantId' => '<string>',
            'remoteParticipantId' => '<string>',
        ],
        // ...
    ],
    'nextToken' => '<string>',
]

Result Details

Members
events
Required: Yes
Type: Array of Event structures

List of the matching events.

nextToken
Type: string

If there are more events than maxResults, use nextToken in the request to get the next set.

Errors

ValidationException:

AccessDeniedException:

ListParticipants

$result = $client->listParticipants([/* ... */]);
$promise = $client->listParticipantsAsync([/* ... */]);

Lists all participants in a specified stage session.

Parameter Syntax

$result = $client->listParticipants([
    'filterByPublished' => true || false,
    'filterByState' => 'CONNECTED|DISCONNECTED',
    'filterByUserId' => '<string>',
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'sessionId' => '<string>', // REQUIRED
    'stageArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
filterByPublished
Type: boolean

Filters the response list to only show participants who published during the stage session. Only one of filterByUserId, filterByPublished, or filterByState can be provided per request.

filterByState
Type: string

Filters the response list to only show participants in the specified state. Only one of filterByUserId, filterByPublished, or filterByState can be provided per request.

filterByUserId
Type: string

Filters the response list to match the specified user ID. Only one of filterByUserId, filterByPublished, or filterByState can be provided per request. A userId is a customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems.

maxResults
Type: int

Maximum number of results to return. Default: 50.

nextToken
Type: string

The first participant to retrieve. This is used for pagination; see the nextToken response field.

sessionId
Required: Yes
Type: string

ID of the session within the stage.

stageArn
Required: Yes
Type: string

Stage ARN.

Result Syntax

[
    'nextToken' => '<string>',
    'participants' => [
        [
            'firstJoinTime' => <DateTime>,
            'participantId' => '<string>',
            'published' => true || false,
            'state' => 'CONNECTED|DISCONNECTED',
            'userId' => '<string>',
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If there are more participants than maxResults, use nextToken in the request to get the next set.

participants
Required: Yes
Type: Array of ParticipantSummary structures

List of the matching participants (summary information only).

Errors

ValidationException:

AccessDeniedException:

ListStageSessions

$result = $client->listStageSessions([/* ... */]);
$promise = $client->listStageSessionsAsync([/* ... */]);

Gets all sessions for a specified stage.

Parameter Syntax

$result = $client->listStageSessions([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
    'stageArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
maxResults
Type: int

Maximum number of results to return. Default: 50.

nextToken
Type: string

The first stage session to retrieve. This is used for pagination; see the nextToken response field.

stageArn
Required: Yes
Type: string

Stage ARN.

Result Syntax

[
    'nextToken' => '<string>',
    'stageSessions' => [
        [
            'endTime' => <DateTime>,
            'sessionId' => '<string>',
            'startTime' => <DateTime>,
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If there are more stage sessions than maxResults, use nextToken in the request to get the next set.

stageSessions
Required: Yes
Type: Array of StageSessionSummary structures

List of matching stage sessions.

Errors

ValidationException:

AccessDeniedException:

ListStages

$result = $client->listStages([/* ... */]);
$promise = $client->listStagesAsync([/* ... */]);

Gets summary information about all stages in your account, in the AWS region where the API request is processed.

Parameter Syntax

$result = $client->listStages([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

Maximum number of results to return. Default: 50.

nextToken
Type: string

The first stage to retrieve. This is used for pagination; see the nextToken response field.

Result Syntax

[
    'nextToken' => '<string>',
    'stages' => [
        [
            'activeSessionId' => '<string>',
            'arn' => '<string>',
            'name' => '<string>',
            'tags' => ['<string>', ...],
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If there are more stages than maxResults, use nextToken in the request to get the next set.

stages
Required: Yes
Type: Array of StageSummary structures

List of the matching stages (summary information only).

Errors

ValidationException:

AccessDeniedException:

ConflictException:

ListStorageConfigurations

$result = $client->listStorageConfigurations([/* ... */]);
$promise = $client->listStorageConfigurationsAsync([/* ... */]);

Gets summary information about all storage configurations in your account, in the AWS region where the API request is processed.

Parameter Syntax

$result = $client->listStorageConfigurations([
    'maxResults' => <integer>,
    'nextToken' => '<string>',
]);

Parameter Details

Members
maxResults
Type: int

Maximum number of storage configurations to return. Default: your service quota or 100, whichever is smaller.

nextToken
Type: string

The first storage configuration to retrieve. This is used for pagination; see the nextToken response field.

Result Syntax

[
    'nextToken' => '<string>',
    'storageConfigurations' => [
        [
            'arn' => '<string>',
            'name' => '<string>',
            's3' => [
                'bucketName' => '<string>',
            ],
            'tags' => ['<string>', ...],
        ],
        // ...
    ],
]

Result Details

Members
nextToken
Type: string

If there are more storage configurations than maxResults, use nextToken in the request to get the next set.

storageConfigurations
Required: Yes
Type: Array of StorageConfigurationSummary structures

List of the matching storage configurations.

Errors

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Gets information about AWS tags for the specified ARN.

Parameter Syntax

$result = $client->listTagsForResource([
    'resourceArn' => '<string>', // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The ARN of the resource to be retrieved. The ARN must be URL-encoded.

Result Syntax

[
    'tags' => ['<string>', ...],
]

Result Details

Members
tags
Required: Yes
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value).

Errors

ResourceNotFoundException:

ValidationException:

InternalServerException:

StartComposition

$result = $client->startComposition([/* ... */]);
$promise = $client->startCompositionAsync([/* ... */]);

Starts a Composition from a stage based on the configuration provided in the request.

A Composition is an ephemeral resource that exists after this endpoint returns successfully. Composition stops and the resource is deleted:

  • When StopComposition is called.

  • After a 1-minute timeout, when all participants are disconnected from the stage.

  • After a 1-minute timeout, if there are no participants in the stage when StartComposition is called.

  • When broadcasting to the IVS channel fails and all retries are exhausted.

  • When broadcasting is disconnected and all attempts to reconnect are exhausted.

Parameter Syntax

$result = $client->startComposition([
    'destinations' => [ // REQUIRED
        [
            'channel' => [
                'channelArn' => '<string>', // REQUIRED
                'encoderConfigurationArn' => '<string>',
            ],
            'name' => '<string>',
            's3' => [
                'encoderConfigurationArns' => ['<string>', ...], // REQUIRED
                'recordingConfiguration' => [
                    'format' => 'HLS',
                ],
                'storageConfigurationArn' => '<string>', // REQUIRED
            ],
        ],
        // ...
    ],
    'idempotencyToken' => '<string>',
    'layout' => [
        'grid' => [
            'featuredParticipantAttribute' => '<string>',
            'gridGap' => <integer>,
            'omitStoppedVideo' => true || false,
            'videoAspectRatio' => 'AUTO|VIDEO|SQUARE|PORTRAIT',
            'videoFillMode' => 'FILL|COVER|CONTAIN',
        ],
        'pip' => [
            'featuredParticipantAttribute' => '<string>',
            'gridGap' => <integer>,
            'omitStoppedVideo' => true || false,
            'pipBehavior' => 'STATIC|DYNAMIC',
            'pipHeight' => <integer>,
            'pipOffset' => <integer>,
            'pipParticipantAttribute' => '<string>',
            'pipPosition' => 'TOP_LEFT|TOP_RIGHT|BOTTOM_LEFT|BOTTOM_RIGHT',
            'pipWidth' => <integer>,
            'videoFillMode' => 'FILL|COVER|CONTAIN',
        ],
    ],
    'stageArn' => '<string>', // REQUIRED
    'tags' => ['<string>', ...],
]);

Parameter Details

Members
destinations
Required: Yes
Type: Array of DestinationConfiguration structures

Array of destination configuration.

idempotencyToken
Type: string

Idempotency token.

layout
Type: LayoutConfiguration structure

Layout object to configure composition parameters.

stageArn
Required: Yes
Type: string

ARN of the stage to be used for compositing.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

Result Syntax

[
    'composition' => [
        'arn' => '<string>',
        'destinations' => [
            [
                'configuration' => [
                    'channel' => [
                        'channelArn' => '<string>',
                        'encoderConfigurationArn' => '<string>',
                    ],
                    'name' => '<string>',
                    's3' => [
                        'encoderConfigurationArns' => ['<string>', ...],
                        'recordingConfiguration' => [
                            'format' => 'HLS',
                        ],
                        'storageConfigurationArn' => '<string>',
                    ],
                ],
                'detail' => [
                    's3' => [
                        'recordingPrefix' => '<string>',
                    ],
                ],
                'endTime' => <DateTime>,
                'id' => '<string>',
                'startTime' => <DateTime>,
                'state' => 'STARTING|ACTIVE|STOPPING|RECONNECTING|FAILED|STOPPED',
            ],
            // ...
        ],
        'endTime' => <DateTime>,
        'layout' => [
            'grid' => [
                'featuredParticipantAttribute' => '<string>',
                'gridGap' => <integer>,
                'omitStoppedVideo' => true || false,
                'videoAspectRatio' => 'AUTO|VIDEO|SQUARE|PORTRAIT',
                'videoFillMode' => 'FILL|COVER|CONTAIN',
            ],
            'pip' => [
                'featuredParticipantAttribute' => '<string>',
                'gridGap' => <integer>,
                'omitStoppedVideo' => true || false,
                'pipBehavior' => 'STATIC|DYNAMIC',
                'pipHeight' => <integer>,
                'pipOffset' => <integer>,
                'pipParticipantAttribute' => '<string>',
                'pipPosition' => 'TOP_LEFT|TOP_RIGHT|BOTTOM_LEFT|BOTTOM_RIGHT',
                'pipWidth' => <integer>,
                'videoFillMode' => 'FILL|COVER|CONTAIN',
            ],
        ],
        'stageArn' => '<string>',
        'startTime' => <DateTime>,
        'state' => 'STARTING|ACTIVE|STOPPING|FAILED|STOPPED',
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
composition
Type: Composition structure

The Composition that was created.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

PendingVerification:

StopComposition

$result = $client->stopComposition([/* ... */]);
$promise = $client->stopCompositionAsync([/* ... */]);

Stops and deletes a Composition resource. Any broadcast from the Composition resource is stopped.

Parameter Syntax

$result = $client->stopComposition([
    'arn' => '<string>', // REQUIRED
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the Composition.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

InternalServerException:

ServiceQuotaExceededException:

ConflictException:

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Adds or updates tags for the AWS resource with the specified ARN.

Parameter Syntax

$result = $client->tagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tags' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The ARN of the resource to be tagged. The ARN must be URL-encoded.

tags
Required: Yes
Type: Associative array of custom strings keys (TagKey) to strings

Array of tags to be added or updated. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints beyond what is documented there.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

InternalServerException:

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes tags from the resource with the specified ARN.

Parameter Syntax

$result = $client->untagResource([
    'resourceArn' => '<string>', // REQUIRED
    'tagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Members
resourceArn
Required: Yes
Type: string

The ARN of the resource to be untagged. The ARN must be URL-encoded.

tagKeys
Required: Yes
Type: Array of strings

Array of tags to be removed. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints beyond what is documented there.

Result Syntax

[]

Result Details

The results for this operation are always empty.

Errors

ResourceNotFoundException:

ValidationException:

InternalServerException:

UpdateStage

$result = $client->updateStage([/* ... */]);
$promise = $client->updateStageAsync([/* ... */]);

Updates a stage’s configuration.

Parameter Syntax

$result = $client->updateStage([
    'arn' => '<string>', // REQUIRED
    'name' => '<string>',
]);

Parameter Details

Members
arn
Required: Yes
Type: string

ARN of the stage to be updated.

name
Type: string

Name of the stage to be updated.

Result Syntax

[
    'stage' => [
        'activeSessionId' => '<string>',
        'arn' => '<string>',
        'name' => '<string>',
        'tags' => ['<string>', ...],
    ],
]

Result Details

Members
stage
Type: Stage structure

The updated stage.

Errors

ResourceNotFoundException:

ValidationException:

AccessDeniedException:

ServiceQuotaExceededException:

ConflictException:

PendingVerification:

Shapes

AccessDeniedException

Description

Members
exceptionMessage
Type: string

User does not have sufficient access to perform this action.

ChannelDestinationConfiguration

Description

Object specifying a channel as a destination.

Members
channelArn
Required: Yes
Type: string

ARN of the channel to use for broadcasting. The channel and stage resources must be in the same AWS account and region. The channel must be offline (not broadcasting).

encoderConfigurationArn
Type: string

ARN of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.

Composition

Description

Object specifying a Composition resource.

Members
arn
Required: Yes
Type: string

ARN of the Composition resource.

destinations
Required: Yes
Type: Array of Destination structures

Array of Destination objects. A Composition can contain either one destination (channel or s3) or two (one channel and one s3).

endTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.

layout
Required: Yes
Type: LayoutConfiguration structure

Layout object to configure composition parameters.

stageArn
Required: Yes
Type: string

ARN of the stage used as input

startTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.

state
Required: Yes
Type: string

State of the Composition.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

CompositionSummary

Description

Summary information about a Composition.

Members
arn
Required: Yes
Type: string

ARN of the Composition resource.

destinations
Required: Yes
Type: Array of DestinationSummary structures

Array of Destination objects.

endTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.

stageArn
Required: Yes
Type: string

ARN of the attached stage.

startTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.

state
Required: Yes
Type: string

State of the Composition resource.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

ConflictException

Description

Members
exceptionMessage
Type: string

Updating or deleting a resource can cause an inconsistent state.

Destination

Description

Object specifying the status of a Destination.

Members
configuration
Required: Yes
Type: DestinationConfiguration structure

Configuration used to create this destination.

detail
Type: DestinationDetail structure

Optional details regarding the status of the destination.

endTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.

id
Required: Yes
Type: string

Unique identifier for this destination, assigned by IVS.

startTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.

state
Required: Yes
Type: string

State of the Composition Destination.

DestinationConfiguration

Description

Complex data type that defines destination-configuration objects.

Members
channel

An IVS channel to be used for broadcasting, for server-side composition. Either a channel or an s3 must be specified.

name
Type: string

Name that can be specified to help identify the destination.

s3
Type: S3DestinationConfiguration structure

An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.

DestinationDetail

Description

Complex data type that defines destination-detail objects.

Members
s3
Type: S3Detail structure

An S3 detail object to return information about the S3 destination.

DestinationSummary

Description

Summary information about a Destination.

Members
endTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.

id
Required: Yes
Type: string

Unique identifier for this destination, assigned by IVS.

startTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.

state
Required: Yes
Type: string

State of the Composition Destination.

EncoderConfiguration

Description

Settings for transcoding.

Members
arn
Required: Yes
Type: string

ARN of the EncoderConfiguration resource.

name
Type: string

Optional name to identify the resource.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

video
Type: Video structure

Video configuration. Default: video resolution 1280x720, bitrate 2500 kbps, 30 fps

EncoderConfigurationSummary

Description

Summary information about an EncoderConfiguration.

Members
arn
Required: Yes
Type: string

ARN of the EncoderConfiguration resource.

name
Type: string

Optional name to identify the resource.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

Event

Description

An occurrence during a stage session.

Members
errorCode
Type: string

If the event is an error event, the error code is provided to give insight into the specific error that occurred. If the event is not an error event, this field is null. INSUFFICIENT_CAPABILITIES indicates that the participant tried to take an action that the participant’s token is not allowed to do. For more information about participant capabilities, see the capabilities field in CreateParticipantToken. QUOTA_EXCEEDED indicates that the number of participants who want to publish/subscribe to a stage exceeds the quota; for more information, see Service Quotas. PUBLISHER_NOT_FOUND indicates that the participant tried to subscribe to a publisher that doesn’t exist.

eventTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) for when the event occurred.

name
Type: string

The name of the event.

participantId
Type: string

Unique identifier for the participant who triggered the event. This is assigned by IVS.

remoteParticipantId
Type: string

Unique identifier for the remote participant. For a subscribe event, this is the publisher. For a publish or join event, this is null. This is assigned by IVS.

GridConfiguration

Description

Configuration information specific to Grid layout, for server-side composition. See "Layouts" in Server-Side Composition.

Members
featuredParticipantAttribute
Type: string

This attribute name identifies the featured slot. A participant with this attribute set to "true" (as a string value) in ParticipantTokenConfiguration is placed in the featured slot.

gridGap
Type: int

Specifies the spacing between participant tiles in pixels. Default: 2.

omitStoppedVideo
Type: boolean

Determines whether to omit participants with stopped video in the composition. Default: false.

videoAspectRatio
Type: string

Sets the non-featured participant display mode. Default: VIDEO.

videoFillMode
Type: string

Defines how video fits within the participant tile. When not set, videoFillMode defaults to COVER fill mode for participants in the grid and to CONTAIN fill mode for featured participants.

InternalServerException

Description

Members
exceptionMessage
Type: string

Unexpected error during processing of request.

LayoutConfiguration

Description

Configuration information of supported layouts for server-side composition.

Members
grid
Type: GridConfiguration structure

Configuration related to grid layout. Default: Grid layout.

pip
Type: PipConfiguration structure

Configuration related to PiP layout.

Participant

Description

Object describing a participant that has joined a stage.

Members
attributes
Type: Associative array of custom strings keys (String) to strings

Application-provided attributes to encode into the token and attach to a stage. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

browserName
Type: string

The participant’s browser.

browserVersion
Type: string

The participant’s browser version.

firstJoinTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.

ispName
Type: string

The participant’s Internet Service Provider.

osName
Type: string

The participant’s operating system.

osVersion
Type: string

The participant’s operating system version.

participantId
Type: string

Unique identifier for this participant, assigned by IVS.

published
Type: boolean

Whether the participant ever published to the stage session.

sdkVersion
Type: string

The participant’s SDK version.

state
Type: string

Whether the participant is connected to or disconnected from the stage.

userId
Type: string

Customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

ParticipantSummary

Description

Summary object describing a participant that has joined a stage.

Members
firstJoinTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.

participantId
Type: string

Unique identifier for this participant, assigned by IVS.

published
Type: boolean

Whether the participant ever published to the stage session.

state
Type: string

Whether the participant is connected to or disconnected from the stage.

userId
Type: string

Customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

ParticipantToken

Description

Object specifying a participant token in a stage.

Important: Treat tokens as opaque; i.e., do not build functionality based on token contents. The format of tokens could change in the future.

Members
attributes
Type: Associative array of custom strings keys (String) to strings

Application-provided attributes to encode into the token and attach to a stage. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

capabilities
Type: Array of strings

Set of capabilities that the user is allowed to perform in the stage.

duration
Type: int

Duration (in minutes), after which the participant token expires. Default: 720 (12 hours).

expirationTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) for when this token expires.

participantId
Type: string

Unique identifier for this participant token, assigned by IVS.

token
Type: string

The issued client token, encrypted.

userId
Type: string

Customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

ParticipantTokenConfiguration

Description

Object specifying a participant token configuration in a stage.

Members
attributes
Type: Associative array of custom strings keys (String) to strings

Application-provided attributes to encode into the corresponding participant token and attach to a stage. Map keys and values can contain UTF-8 encoded text. The maximum length of this field is 1 KB total. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

capabilities
Type: Array of strings

Set of capabilities that the user is allowed to perform in the stage.

duration
Type: int

Duration (in minutes), after which the corresponding participant token expires. Default: 720 (12 hours).

userId
Type: string

Customer-assigned name to help identify the token; this can be used to link a participant to a user in the customer’s own systems. This can be any UTF-8 encoded text. This field is exposed to all stage participants and should not be used for personally identifying, confidential, or sensitive information.

PendingVerification

Description

Members
exceptionMessage
Type: string

Your account is pending verification.

PipConfiguration

Description

Configuration information specific to Picture-in-Picture (PiP) layout, for server-side composition.

Members
featuredParticipantAttribute
Type: string

This attribute name identifies the featured slot. A participant with this attribute set to "true" (as a string value) in ParticipantTokenConfiguration is placed in the featured slot.

gridGap
Type: int

Specifies the spacing between participant tiles in pixels. Default: 0.

omitStoppedVideo
Type: boolean

Determines whether to omit participants with stopped video in the composition. Default: false.

pipBehavior
Type: string

Defines PiP behavior when all participants have left. Default: STATIC.

pipHeight
Type: int

Specifies the height of the PiP window in pixels. When this is not set explicitly, pipHeight’s value will be based on the size of the composition and the aspect ratio of the participant’s video.

pipOffset
Type: int

Sets the PiP window’s offset position in pixels from the closest edges determined by PipPosition. Default: 0.

pipParticipantAttribute
Type: string

Identifies the PiP slot. A participant with this attribute set to "true" (as a string value) in ParticipantTokenConfiguration is placed in the PiP slot.

pipPosition
Type: string

Determines the corner position of the PiP window. Default: BOTTOM_RIGHT.

pipWidth
Type: int

Specifies the width of the PiP window in pixels. When this is not set explicitly, pipWidth’s value will be based on the size of the composition and the aspect ratio of the participant’s video.

videoFillMode
Type: string

Defines how video fits within the participant tile. Default: COVER.

RecordingConfiguration

Description

An object representing a configuration to record a stage stream.

Members
format
Type: string

The recording format for storing a recording in Amazon S3.

ResourceNotFoundException

Description

Members
exceptionMessage
Type: string

Request references a resource which does not exist.

S3DestinationConfiguration

Description

A complex type that describes an S3 location where recorded videos will be stored.

Members
encoderConfigurationArns
Required: Yes
Type: Array of strings

ARNs of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.

recordingConfiguration
Type: RecordingConfiguration structure

Array of maps, each of the form string:string (key:value). This is an optional customer specification, currently used only to specify the recording format for storing a recording in Amazon S3.

storageConfigurationArn
Required: Yes
Type: string

ARN of the StorageConfiguration where recorded videos will be stored.

S3Detail

Description

Complex data type that defines S3Detail objects.

Members
recordingPrefix
Required: Yes
Type: string

The S3 bucket prefix under which the recording is stored.

S3StorageConfiguration

Description

A complex type that describes an S3 location where recorded videos will be stored.

Members
bucketName
Required: Yes
Type: string

Location (S3 bucket name) where recorded videos will be stored. Note that the StorageConfiguration and S3 bucket must be in the same region as the Composition.

ServiceQuotaExceededException

Description

Members
exceptionMessage
Type: string

Request would cause a service quota to be exceeded.

Stage

Description

Object specifying a stage.

Members
activeSessionId
Type: string

ID of the active session within the stage.

arn
Required: Yes
Type: string

Stage ARN.

name
Type: string

Stage name.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

StageSession

Description

A stage session begins when the first participant joins a stage and ends after the last participant leaves the stage. A stage session helps with debugging stages by grouping events and participants into shorter periods of time (i.e., a session), which is helpful when stages are used over long periods of time.

Members
endTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) when the stage session ended. This is null if the stage is active.

sessionId
Type: string

ID of the session within the stage.

startTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) when this stage session began.

StageSessionSummary

Description

Summary information about a stage session.

Members
endTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) when the stage session ended. This is null if the stage is active.

sessionId
Type: string

ID of the session within the stage.

startTime
Type: timestamp (string|DateTime or anything parsable by strtotime)

ISO 8601 timestamp (returned as a string) when this stage session began.

StageSummary

Description

Summary information about a stage.

Members
activeSessionId
Type: string

ID of the active session within the stage.

arn
Required: Yes
Type: string

Stage ARN.

name
Type: string

Stage name.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

StorageConfiguration

Description

A complex type that describes a location where recorded videos will be stored.

Members
arn
Required: Yes
Type: string

ARN of the storage configuration.

name
Type: string

Name of the storage configuration.

s3
Type: S3StorageConfiguration structure

An S3 destination configuration where recorded videos will be stored.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

StorageConfigurationSummary

Description

Summary information about a storage configuration.

Members
arn
Required: Yes
Type: string

ARN of the storage configuration.

name
Type: string

Name of the storage configuration.

s3
Type: S3StorageConfiguration structure

An S3 destination configuration where recorded videos will be stored.

tags
Type: Associative array of custom strings keys (TagKey) to strings

Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Tagging AWS Resources for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no constraints on tags beyond what is documented there.

ValidationException

Description

Members
exceptionMessage
Type: string

The input fails to satisfy the constraints specified by an Amazon Web Services service.

Video

Description

Settings for video.

Members
bitrate
Type: int

Bitrate for generated output, in bps. Default: 2500000.

framerate
Type: float

Video frame rate, in fps. Default: 30.

height
Type: int

Video-resolution height. Note that the maximum value is determined by width times height, such that the maximum total pixels is 2073600 (1920x1080 or 1080x1920). Default: 720.

width
Type: int

Video-resolution width. Note that the maximum value is determined by width times height, such that the maximum total pixels is 2073600 (1920x1080 or 1080x1920). Default: 1280.