2023/11/16 - Amazon Interactive Video Service RealTime - 12 new api methods
Changes This release introduces server side composition and recording for stages.
Deletes an EncoderConfiguration resource. Ensures that no Compositions are using this template; otherwise, returns an error.
See also: AWS API Documentation
Request Syntax
client.delete_encoder_configuration(
arn='string'
)
string
[REQUIRED]
ARN of the EncoderConfiguration.
dict
Response Syntax
{}
Response Structure
(dict) --
Stops and deletes a Composition resource. Any broadcast from the Composition resource is stopped.
See also: AWS API Documentation
Request Syntax
client.stop_composition(
arn='string'
)
string
[REQUIRED]
ARN of the Composition.
dict
Response Syntax
{}
Response Structure
(dict) --
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.
See also: AWS API Documentation
Request Syntax
client.delete_storage_configuration(
arn='string'
)
string
[REQUIRED]
ARN of the storage configuration to be deleted.
dict
Response Syntax
{}
Response Structure
(dict) --
Gets summary information about all storage configurations in your account, in the AWS region where the API request is processed.
See also: AWS API Documentation
Request Syntax
client.list_storage_configurations(
maxResults=123,
nextToken='string'
)
integer
Maximum number of storage configurations to return. Default: your service quota or 100, whichever is smaller.
string
The first storage configuration to retrieve. This is used for pagination; see the nextToken response field.
dict
Response Syntax
{
'nextToken': 'string',
'storageConfigurations': [
{
'arn': 'string',
'name': 'string',
's3': {
'bucketName': 'string'
},
'tags': {
'string': 'string'
}
},
]
}
Response Structure
(dict) --
nextToken (string) --
If there are more storage configurations than maxResults, use nextToken in the request to get the next set.
storageConfigurations (list) --
List of the matching storage configurations.
(dict) --
Summary information about a storage configuration.
arn (string) --
ARN of the storage configuration.
name (string) --
Name of the storage configuration.
s3 (dict) --
An S3 destination configuration where recorded videos will be stored.
bucketName (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.
tags (dict) --
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.
(string) --
(string) --
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.
See also: AWS API Documentation
Request Syntax
client.start_composition(
destinations=[
{
'channel': {
'channelArn': 'string',
'encoderConfigurationArn': 'string'
},
'name': 'string',
's3': {
'encoderConfigurationArns': [
'string',
],
'recordingConfiguration': {
'format': 'HLS'
},
'storageConfigurationArn': 'string'
}
},
],
idempotencyToken='string',
layout={
'grid': {
'featuredParticipantAttribute': 'string'
}
},
stageArn='string',
tags={
'string': 'string'
}
)
list
[REQUIRED]
Array of destination configuration.
(dict) --
Complex data type that defines destination-configuration objects.
channel (dict) --
An IVS channel to be used for broadcasting, for server-side composition. Either a channel or an s3 must be specified.
channelArn (string) -- [REQUIRED]
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 (string) --
ARN of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.
name (string) --
Name that can be specified to help identify the destination.
s3 (dict) --
An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.
encoderConfigurationArns (list) -- [REQUIRED]
ARNs of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.
(string) --
recordingConfiguration (dict) --
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.
format (string) --
The recording format for storing a recording in Amazon S3.
storageConfigurationArn (string) -- [REQUIRED]
ARN of the StorageConfiguration where recorded videos will be stored.
string
Idempotency token.
This field is autopopulated if not provided.
dict
Layout object to configure composition parameters.
grid (dict) --
Configuration related to grid layout. Default: Grid layout.
featuredParticipantAttribute (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.
string
[REQUIRED]
ARN of the stage to be used for compositing.
dict
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.
(string) --
(string) --
dict
Response 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(2015, 1, 1),
'id': 'string',
'startTime': datetime(2015, 1, 1),
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'RECONNECTING'|'FAILED'|'STOPPED'
},
],
'endTime': datetime(2015, 1, 1),
'layout': {
'grid': {
'featuredParticipantAttribute': 'string'
}
},
'stageArn': 'string',
'startTime': datetime(2015, 1, 1),
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'FAILED'|'STOPPED',
'tags': {
'string': 'string'
}
}
}
Response Structure
(dict) --
composition (dict) --
The Composition that was created.
arn (string) --
ARN of the Composition resource.
destinations (list) --
Array of Destination objects. A Composition can contain either one destination ( channel or s3) or two (one channel and one s3).
(dict) --
Object specifying the status of a Destination.
configuration (dict) --
Configuration used to create this destination.
channel (dict) --
An IVS channel to be used for broadcasting, for server-side composition. Either a channel or an s3 must be specified.
channelArn (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 (string) --
ARN of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.
name (string) --
Name that can be specified to help identify the destination.
s3 (dict) --
An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.
encoderConfigurationArns (list) --
ARNs of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.
(string) --
recordingConfiguration (dict) --
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.
format (string) --
The recording format for storing a recording in Amazon S3.
storageConfigurationArn (string) --
ARN of the StorageConfiguration where recorded videos will be stored.
detail (dict) --
Optional details regarding the status of the destination.
s3 (dict) --
An S3 detail object to return information about the S3 destination.
recordingPrefix (string) --
The S3 bucket prefix under which the recording is stored.
endTime (datetime) --
UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.
id (string) --
Unique identifier for this destination, assigned by IVS.
startTime (datetime) --
UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.
state (string) --
State of the Composition Destination.
endTime (datetime) --
UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.
layout (dict) --
Layout object to configure composition parameters.
grid (dict) --
Configuration related to grid layout. Default: Grid layout.
featuredParticipantAttribute (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.
stageArn (string) --
ARN of the stage used as input
startTime (datetime) --
UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.
state (string) --
State of the Composition.
tags (dict) --
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.
(string) --
(string) --
Get information about the specified Composition resource.
See also: AWS API Documentation
Request Syntax
client.get_composition(
arn='string'
)
string
[REQUIRED]
ARN of the Composition resource.
dict
Response 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(2015, 1, 1),
'id': 'string',
'startTime': datetime(2015, 1, 1),
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'RECONNECTING'|'FAILED'|'STOPPED'
},
],
'endTime': datetime(2015, 1, 1),
'layout': {
'grid': {
'featuredParticipantAttribute': 'string'
}
},
'stageArn': 'string',
'startTime': datetime(2015, 1, 1),
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'FAILED'|'STOPPED',
'tags': {
'string': 'string'
}
}
}
Response Structure
(dict) --
composition (dict) --
The Composition that was returned.
arn (string) --
ARN of the Composition resource.
destinations (list) --
Array of Destination objects. A Composition can contain either one destination ( channel or s3) or two (one channel and one s3).
(dict) --
Object specifying the status of a Destination.
configuration (dict) --
Configuration used to create this destination.
channel (dict) --
An IVS channel to be used for broadcasting, for server-side composition. Either a channel or an s3 must be specified.
channelArn (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 (string) --
ARN of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.
name (string) --
Name that can be specified to help identify the destination.
s3 (dict) --
An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.
encoderConfigurationArns (list) --
ARNs of the EncoderConfiguration resource. The encoder configuration and stage resources must be in the same AWS account and region.
(string) --
recordingConfiguration (dict) --
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.
format (string) --
The recording format for storing a recording in Amazon S3.
storageConfigurationArn (string) --
ARN of the StorageConfiguration where recorded videos will be stored.
detail (dict) --
Optional details regarding the status of the destination.
s3 (dict) --
An S3 detail object to return information about the S3 destination.
recordingPrefix (string) --
The S3 bucket prefix under which the recording is stored.
endTime (datetime) --
UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.
id (string) --
Unique identifier for this destination, assigned by IVS.
startTime (datetime) --
UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.
state (string) --
State of the Composition Destination.
endTime (datetime) --
UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.
layout (dict) --
Layout object to configure composition parameters.
grid (dict) --
Configuration related to grid layout. Default: Grid layout.
featuredParticipantAttribute (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.
stageArn (string) --
ARN of the stage used as input
startTime (datetime) --
UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.
state (string) --
State of the Composition.
tags (dict) --
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.
(string) --
(string) --
Gets summary information about all Compositions in your account, in the AWS region where the API request is processed.
See also: AWS API Documentation
Request Syntax
client.list_compositions(
filterByEncoderConfigurationArn='string',
filterByStageArn='string',
maxResults=123,
nextToken='string'
)
string
Filters the Composition list to match the specified EncoderConfiguration attached to at least one of its output.
string
Filters the Composition list to match the specified Stage ARN.
integer
Maximum number of results to return. Default: 100.
string
The first Composition to retrieve. This is used for pagination; see the nextToken response field.
dict
Response Syntax
{
'compositions': [
{
'arn': 'string',
'destinations': [
{
'endTime': datetime(2015, 1, 1),
'id': 'string',
'startTime': datetime(2015, 1, 1),
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'RECONNECTING'|'FAILED'|'STOPPED'
},
],
'endTime': datetime(2015, 1, 1),
'stageArn': 'string',
'startTime': datetime(2015, 1, 1),
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'FAILED'|'STOPPED',
'tags': {
'string': 'string'
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
compositions (list) --
List of the matching Compositions (summary information only).
(dict) --
Summary information about a Composition.
arn (string) --
ARN of the Composition resource.
destinations (list) --
Array of Destination objects.
(dict) --
Summary information about a Destination.
endTime (datetime) --
UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.
id (string) --
Unique identifier for this destination, assigned by IVS.
startTime (datetime) --
UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.
state (string) --
State of the Composition Destination.
endTime (datetime) --
UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.
stageArn (string) --
ARN of the attached stage.
startTime (datetime) --
UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.
state (string) --
State of the Composition resource.
tags (dict) --
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.
(string) --
(string) --
nextToken (string) --
If there are more compositions than maxResults, use nextToken in the request to get the next set.
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.
See also: AWS API Documentation
Request Syntax
client.create_storage_configuration(
name='string',
s3={
'bucketName': 'string'
},
tags={
'string': 'string'
}
)
string
Storage configuration name. The value does not need to be unique.
dict
[REQUIRED]
A complex type that contains a storage configuration for where recorded video will be stored.
bucketName (string) -- [REQUIRED]
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.
dict
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.
(string) --
(string) --
dict
Response Syntax
{
'storageConfiguration': {
'arn': 'string',
'name': 'string',
's3': {
'bucketName': 'string'
},
'tags': {
'string': 'string'
}
}
}
Response Structure
(dict) --
storageConfiguration (dict) --
The StorageConfiguration that was created.
arn (string) --
ARN of the storage configuration.
name (string) --
Name of the storage configuration.
s3 (dict) --
An S3 destination configuration where recorded videos will be stored.
bucketName (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.
tags (dict) --
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.
(string) --
(string) --
Gets information about the specified EncoderConfiguration resource.
See also: AWS API Documentation
Request Syntax
client.get_encoder_configuration(
arn='string'
)
string
[REQUIRED]
ARN of the EncoderConfiguration resource.
dict
Response Syntax
{
'encoderConfiguration': {
'arn': 'string',
'name': 'string',
'tags': {
'string': 'string'
},
'video': {
'bitrate': 123,
'framerate': ...,
'height': 123,
'width': 123
}
}
}
Response Structure
(dict) --
encoderConfiguration (dict) --
The EncoderConfiguration that was returned.
arn (string) --
ARN of the EncoderConfiguration resource.
name (string) --
Optional name to identify the resource.
tags (dict) --
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.
(string) --
(string) --
video (dict) --
Video configuration. Default: video resolution 1280x720, bitrate 2500 kbps, 30 fps
bitrate (integer) --
Bitrate for generated output, in bps. Default: 2500000.
framerate (float) --
Video frame rate, in fps. Default: 30.
height (integer) --
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 (integer) --
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.
Gets the storage configuration for the specified ARN.
See also: AWS API Documentation
Request Syntax
client.get_storage_configuration(
arn='string'
)
string
[REQUIRED]
ARN of the storage configuration to be retrieved.
dict
Response Syntax
{
'storageConfiguration': {
'arn': 'string',
'name': 'string',
's3': {
'bucketName': 'string'
},
'tags': {
'string': 'string'
}
}
}
Response Structure
(dict) --
storageConfiguration (dict) --
The StorageConfiguration that was returned.
arn (string) --
ARN of the storage configuration.
name (string) --
Name of the storage configuration.
s3 (dict) --
An S3 destination configuration where recorded videos will be stored.
bucketName (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.
tags (dict) --
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.
(string) --
(string) --
Gets summary information about all EncoderConfigurations in your account, in the AWS region where the API request is processed.
See also: AWS API Documentation
Request Syntax
client.list_encoder_configurations(
maxResults=123,
nextToken='string'
)
integer
Maximum number of results to return. Default: 100.
string
The first encoder configuration to retrieve. This is used for pagination; see the nextToken response field.
dict
Response Syntax
{
'encoderConfigurations': [
{
'arn': 'string',
'name': 'string',
'tags': {
'string': 'string'
}
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
encoderConfigurations (list) --
List of the matching EncoderConfigurations (summary information only).
(dict) --
Summary information about an EncoderConfiguration.
arn (string) --
ARN of the EncoderConfiguration resource.
name (string) --
Optional name to identify the resource.
tags (dict) --
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.
(string) --
(string) --
nextToken (string) --
If there are more encoder configurations than maxResults, use nextToken in the request to get the next set.
Creates an EncoderConfiguration object.
See also: AWS API Documentation
Request Syntax
client.create_encoder_configuration(
name='string',
tags={
'string': 'string'
},
video={
'bitrate': 123,
'framerate': ...,
'height': 123,
'width': 123
}
)
string
Optional name to identify the resource.
dict
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.
(string) --
(string) --
dict
Video configuration. Default: video resolution 1280x720, bitrate 2500 kbps, 30 fps.
bitrate (integer) --
Bitrate for generated output, in bps. Default: 2500000.
framerate (float) --
Video frame rate, in fps. Default: 30.
height (integer) --
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 (integer) --
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.
dict
Response Syntax
{
'encoderConfiguration': {
'arn': 'string',
'name': 'string',
'tags': {
'string': 'string'
},
'video': {
'bitrate': 123,
'framerate': ...,
'height': 123,
'width': 123
}
}
}
Response Structure
(dict) --
encoderConfiguration (dict) --
The EncoderConfiguration that was created.
arn (string) --
ARN of the EncoderConfiguration resource.
name (string) --
Optional name to identify the resource.
tags (dict) --
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.
(string) --
(string) --
video (dict) --
Video configuration. Default: video resolution 1280x720, bitrate 2500 kbps, 30 fps
bitrate (integer) --
Bitrate for generated output, in bps. Default: 2500000.
framerate (float) --
Video frame rate, in fps. Default: 30.
height (integer) --
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 (integer) --
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.