2024/12/10 - Amazon Interactive Video Service RealTime - 5 updated api methods
Changes IVS Real-Time now offers customers the ability to customize thumbnails recording mode and interval for both Individual Participant Recording (IPR) and Server-Side Compositions (SSC).
{'autoParticipantRecordingConfiguration': {'mediaTypes': {'NONE'},
'thumbnailConfiguration': {'recordingMode': 'INTERVAL '
'| '
'DISABLED',
'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}}}
Response {'stage': {'autoParticipantRecordingConfiguration': {'mediaTypes': {'NONE'},
'thumbnailConfiguration': {'recordingMode': 'INTERVAL '
'| '
'DISABLED',
'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}}}}
Creates a new stage (and optionally participant tokens).
See also: AWS API Documentation
Request Syntax
client.create_stage(
name='string',
participantTokenConfigurations=[
{
'duration': 123,
'userId': 'string',
'attributes': {
'string': 'string'
},
'capabilities': [
'PUBLISH'|'SUBSCRIBE',
]
},
],
tags={
'string': 'string'
},
autoParticipantRecordingConfiguration={
'storageConfigurationArn': 'string',
'mediaTypes': [
'AUDIO_VIDEO'|'AUDIO_ONLY'|'NONE',
],
'thumbnailConfiguration': {
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
],
'recordingMode': 'INTERVAL'|'DISABLED'
}
}
)
string
Optional name that can be specified for the stage being created.
list
Array of participant token configuration objects to attach to the new stage.
(dict) --
Object specifying a participant token configuration in a stage.
duration (integer) --
Duration (in minutes), after which the corresponding participant token expires. Default: 720 (12 hours).
userId (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.
attributes (dict) --
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.
(string) --
(string) --
capabilities (list) --
Set of capabilities that the user is allowed to perform in the stage.
(string) --
dict
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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
Configuration object for individual participant recording, to attach to the new stage.
storageConfigurationArn (string) -- [REQUIRED]
ARN of the StorageConfiguration resource to use for individual participant recording. Default: "" (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a Stage is created or updated.
mediaTypes (list) --
Types of media to be recorded. Default: AUDIO_VIDEO.
(string) --
thumbnailConfiguration (dict) --
A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. This is configurable only if recordingMode is INTERVAL. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. LATEST saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
recordingMode (string) --
Thumbnail recording mode. Default: DISABLED.
dict
Response Syntax
{
'stage': {
'arn': 'string',
'name': 'string',
'activeSessionId': 'string',
'tags': {
'string': 'string'
},
'autoParticipantRecordingConfiguration': {
'storageConfigurationArn': 'string',
'mediaTypes': [
'AUDIO_VIDEO'|'AUDIO_ONLY'|'NONE',
],
'thumbnailConfiguration': {
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
],
'recordingMode': 'INTERVAL'|'DISABLED'
}
},
'endpoints': {
'events': 'string',
'whip': 'string',
'rtmp': 'string',
'rtmps': 'string'
}
},
'participantTokens': [
{
'participantId': 'string',
'token': 'string',
'userId': 'string',
'attributes': {
'string': 'string'
},
'duration': 123,
'capabilities': [
'PUBLISH'|'SUBSCRIBE',
],
'expirationTime': datetime(2015, 1, 1)
},
]
}
Response Structure
(dict) --
stage (dict) --
The stage that was created.
arn (string) --
Stage ARN.
name (string) --
Stage name.
activeSessionId (string) --
ID of the active session within the stage.
tags (dict) --
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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) --
autoParticipantRecordingConfiguration (dict) --
Configuration object for individual participant recording, attached to the stage.
storageConfigurationArn (string) --
ARN of the StorageConfiguration resource to use for individual participant recording. Default: "" (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a Stage is created or updated.
mediaTypes (list) --
Types of media to be recorded. Default: AUDIO_VIDEO.
(string) --
thumbnailConfiguration (dict) --
A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. This is configurable only if recordingMode is INTERVAL. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. LATEST saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
recordingMode (string) --
Thumbnail recording mode. Default: DISABLED.
endpoints (dict) --
Summary information about various endpoints for a stage.
events (string) --
Events endpoint.
whip (string) --
The endpoint to be used for IVS real-time streaming using the WHIP protocol.
rtmp (string) --
The endpoint to be used for IVS real-time streaming using the RTMP protocol.
rtmps (string) --
The endpoint to be used for IVS real-time streaming using the RTMPS protocol.
participantTokens (list) --
Participant tokens attached to the stage. These correspond to the participants in the request.
(dict) --
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.
participantId (string) --
Unique identifier for this participant token, assigned by IVS.
token (string) --
The issued client token, encrypted.
userId (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.
attributes (dict) --
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.
(string) --
(string) --
duration (integer) --
Duration (in minutes), after which the participant token expires. Default: 720 (12 hours).
capabilities (list) --
Set of capabilities that the user is allowed to perform in the stage.
(string) --
expirationTime (datetime) --
ISO 8601 timestamp (returned as a string) for when this token expires.
{'composition': {'destinations': {'configuration': {'s3': {'thumbnailConfigurations': [{'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}]}}}}}
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',
'stageArn': 'string',
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'FAILED'|'STOPPED',
'layout': {
'grid': {
'featuredParticipantAttribute': 'string',
'omitStoppedVideo': True|False,
'videoAspectRatio': 'AUTO'|'VIDEO'|'SQUARE'|'PORTRAIT',
'videoFillMode': 'FILL'|'COVER'|'CONTAIN',
'gridGap': 123
},
'pip': {
'featuredParticipantAttribute': 'string',
'omitStoppedVideo': True|False,
'videoFillMode': 'FILL'|'COVER'|'CONTAIN',
'gridGap': 123,
'pipParticipantAttribute': 'string',
'pipBehavior': 'STATIC'|'DYNAMIC',
'pipOffset': 123,
'pipPosition': 'TOP_LEFT'|'TOP_RIGHT'|'BOTTOM_LEFT'|'BOTTOM_RIGHT',
'pipWidth': 123,
'pipHeight': 123
}
},
'destinations': [
{
'id': 'string',
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'RECONNECTING'|'FAILED'|'STOPPED',
'startTime': datetime(2015, 1, 1),
'endTime': datetime(2015, 1, 1),
'configuration': {
'name': 'string',
'channel': {
'channelArn': 'string',
'encoderConfigurationArn': 'string'
},
's3': {
'storageConfigurationArn': 'string',
'encoderConfigurationArns': [
'string',
],
'recordingConfiguration': {
'format': 'HLS'
},
'thumbnailConfigurations': [
{
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
]
},
]
}
},
'detail': {
's3': {
'recordingPrefix': 'string'
}
}
},
],
'tags': {
'string': 'string'
},
'startTime': datetime(2015, 1, 1),
'endTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
composition (dict) --
The Composition that was returned.
arn (string) --
ARN of the Composition resource.
stageArn (string) --
ARN of the stage used as input
state (string) --
State of the Composition.
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. Default: "" (no featured participant).
omitStoppedVideo (boolean) --
Determines whether to omit participants with stopped video in the composition. Default: false.
videoAspectRatio (string) --
Sets the non-featured participant display mode, to control the aspect ratio of video tiles. VIDEO is 16:9, SQUARE is 1:1, and PORTRAIT is 3:4. Default: VIDEO.
videoFillMode (string) --
Defines how video content fits within the participant tile: FILL (stretched), COVER (cropped), or CONTAIN (letterboxed). When not set, videoFillMode defaults to COVER fill mode for participants in the grid and to CONTAIN fill mode for featured participants.
gridGap (integer) --
Specifies the spacing between participant tiles in pixels. Default: 2.
pip (dict) --
Configuration related to PiP 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. Default: "" (no featured participant).
omitStoppedVideo (boolean) --
Determines whether to omit participants with stopped video in the composition. Default: false.
videoFillMode (string) --
Defines how video content fits within the participant tile: FILL (stretched), COVER (cropped), or CONTAIN (letterboxed). Default: COVER.
gridGap (integer) --
Specifies the spacing between participant tiles in pixels. Default: 0.
pipParticipantAttribute (string) --
Specifies the participant for the PiP window. A participant with this attribute set to "true" (as a string value) in ParticipantTokenConfiguration is placed in the PiP slot. Default: "" (no PiP participant).
pipBehavior (string) --
Defines PiP behavior when all participants have left: STATIC (maintains original position/size) or DYNAMIC (expands to full composition). Default: STATIC.
pipOffset (integer) --
Sets the PiP window’s offset position in pixels from the closest edges determined by PipPosition. Default: 0.
pipPosition (string) --
Determines the corner position of the PiP window. Default: BOTTOM_RIGHT.
pipWidth (integer) --
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.
pipHeight (integer) --
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.
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.
id (string) --
Unique identifier for this destination, assigned by IVS.
state (string) --
State of the Composition Destination.
startTime (datetime) --
UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.
endTime (datetime) --
UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.
configuration (dict) --
Configuration used to create this destination.
name (string) --
Name that can be specified to help identify the 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.
s3 (dict) --
An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.
storageConfigurationArn (string) --
ARN of the StorageConfiguration where recorded videos will be stored.
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.
thumbnailConfigurations (list) --
A complex type that allows you to enable/disable the recording of thumbnails for a Composition and modify the interval at which thumbnails are generated for the live session.
(dict) --
An object representing a configuration of thumbnails for recorded video for a Composition.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/(width)x(height) directory, where (width) and (height) are the width and height of the thumbnail. LATEST saves the latest thumbnail in media/latest_thumbnail/(width)x(height)/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
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.
tags (dict) --
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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) --
startTime (datetime) --
UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.
endTime (datetime) --
UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.
{'stage': {'autoParticipantRecordingConfiguration': {'mediaTypes': {'NONE'},
'thumbnailConfiguration': {'recordingMode': 'INTERVAL '
'| '
'DISABLED',
'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}}}}
Gets information for the specified stage.
See also: AWS API Documentation
Request Syntax
client.get_stage(
arn='string'
)
string
[REQUIRED]
ARN of the stage for which the information is to be retrieved.
dict
Response Syntax
{
'stage': {
'arn': 'string',
'name': 'string',
'activeSessionId': 'string',
'tags': {
'string': 'string'
},
'autoParticipantRecordingConfiguration': {
'storageConfigurationArn': 'string',
'mediaTypes': [
'AUDIO_VIDEO'|'AUDIO_ONLY'|'NONE',
],
'thumbnailConfiguration': {
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
],
'recordingMode': 'INTERVAL'|'DISABLED'
}
},
'endpoints': {
'events': 'string',
'whip': 'string',
'rtmp': 'string',
'rtmps': 'string'
}
}
}
Response Structure
(dict) --
stage (dict) --
The stage that is returned.
arn (string) --
Stage ARN.
name (string) --
Stage name.
activeSessionId (string) --
ID of the active session within the stage.
tags (dict) --
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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) --
autoParticipantRecordingConfiguration (dict) --
Configuration object for individual participant recording, attached to the stage.
storageConfigurationArn (string) --
ARN of the StorageConfiguration resource to use for individual participant recording. Default: "" (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a Stage is created or updated.
mediaTypes (list) --
Types of media to be recorded. Default: AUDIO_VIDEO.
(string) --
thumbnailConfiguration (dict) --
A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. This is configurable only if recordingMode is INTERVAL. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. LATEST saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
recordingMode (string) --
Thumbnail recording mode. Default: DISABLED.
endpoints (dict) --
Summary information about various endpoints for a stage.
events (string) --
Events endpoint.
whip (string) --
The endpoint to be used for IVS real-time streaming using the WHIP protocol.
rtmp (string) --
The endpoint to be used for IVS real-time streaming using the RTMP protocol.
rtmps (string) --
The endpoint to be used for IVS real-time streaming using the RTMPS protocol.
{'destinations': {'s3': {'thumbnailConfigurations': [{'storage': ['SEQUENTIAL '
'| LATEST'],
'targetIntervalSeconds': 'integer'}]}}}
Response {'composition': {'destinations': {'configuration': {'s3': {'thumbnailConfigurations': [{'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}]}}}}}
Starts a Composition from a stage based on the configuration provided in the request.
A Composition is an ephemeral resource that exists after this operation 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(
stageArn='string',
idempotencyToken='string',
layout={
'grid': {
'featuredParticipantAttribute': 'string',
'omitStoppedVideo': True|False,
'videoAspectRatio': 'AUTO'|'VIDEO'|'SQUARE'|'PORTRAIT',
'videoFillMode': 'FILL'|'COVER'|'CONTAIN',
'gridGap': 123
},
'pip': {
'featuredParticipantAttribute': 'string',
'omitStoppedVideo': True|False,
'videoFillMode': 'FILL'|'COVER'|'CONTAIN',
'gridGap': 123,
'pipParticipantAttribute': 'string',
'pipBehavior': 'STATIC'|'DYNAMIC',
'pipOffset': 123,
'pipPosition': 'TOP_LEFT'|'TOP_RIGHT'|'BOTTOM_LEFT'|'BOTTOM_RIGHT',
'pipWidth': 123,
'pipHeight': 123
}
},
destinations=[
{
'name': 'string',
'channel': {
'channelArn': 'string',
'encoderConfigurationArn': 'string'
},
's3': {
'storageConfigurationArn': 'string',
'encoderConfigurationArns': [
'string',
],
'recordingConfiguration': {
'format': 'HLS'
},
'thumbnailConfigurations': [
{
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
]
},
]
}
},
],
tags={
'string': 'string'
}
)
string
[REQUIRED]
ARN of the stage to be used for compositing.
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. Default: "" (no featured participant).
omitStoppedVideo (boolean) --
Determines whether to omit participants with stopped video in the composition. Default: false.
videoAspectRatio (string) --
Sets the non-featured participant display mode, to control the aspect ratio of video tiles. VIDEO is 16:9, SQUARE is 1:1, and PORTRAIT is 3:4. Default: VIDEO.
videoFillMode (string) --
Defines how video content fits within the participant tile: FILL (stretched), COVER (cropped), or CONTAIN (letterboxed). When not set, videoFillMode defaults to COVER fill mode for participants in the grid and to CONTAIN fill mode for featured participants.
gridGap (integer) --
Specifies the spacing between participant tiles in pixels. Default: 2.
pip (dict) --
Configuration related to PiP 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. Default: "" (no featured participant).
omitStoppedVideo (boolean) --
Determines whether to omit participants with stopped video in the composition. Default: false.
videoFillMode (string) --
Defines how video content fits within the participant tile: FILL (stretched), COVER (cropped), or CONTAIN (letterboxed). Default: COVER.
gridGap (integer) --
Specifies the spacing between participant tiles in pixels. Default: 0.
pipParticipantAttribute (string) --
Specifies the participant for the PiP window. A participant with this attribute set to "true" (as a string value) in ParticipantTokenConfiguration is placed in the PiP slot. Default: "" (no PiP participant).
pipBehavior (string) --
Defines PiP behavior when all participants have left: STATIC (maintains original position/size) or DYNAMIC (expands to full composition). Default: STATIC.
pipOffset (integer) --
Sets the PiP window’s offset position in pixels from the closest edges determined by PipPosition. Default: 0.
pipPosition (string) --
Determines the corner position of the PiP window. Default: BOTTOM_RIGHT.
pipWidth (integer) --
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.
pipHeight (integer) --
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.
list
[REQUIRED]
Array of destination configuration.
(dict) --
Complex data type that defines destination-configuration objects.
name (string) --
Name that can be specified to help identify the 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) -- [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.
s3 (dict) --
An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.
storageConfigurationArn (string) -- [REQUIRED]
ARN of the StorageConfiguration where recorded videos will be stored.
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.
thumbnailConfigurations (list) --
A complex type that allows you to enable/disable the recording of thumbnails for a Composition and modify the interval at which thumbnails are generated for the live session.
(dict) --
An object representing a configuration of thumbnails for recorded video for a Composition.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/(width)x(height) directory, where (width) and (height) are the width and height of the thumbnail. LATEST saves the latest thumbnail in media/latest_thumbnail/(width)x(height)/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
dict
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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',
'stageArn': 'string',
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'FAILED'|'STOPPED',
'layout': {
'grid': {
'featuredParticipantAttribute': 'string',
'omitStoppedVideo': True|False,
'videoAspectRatio': 'AUTO'|'VIDEO'|'SQUARE'|'PORTRAIT',
'videoFillMode': 'FILL'|'COVER'|'CONTAIN',
'gridGap': 123
},
'pip': {
'featuredParticipantAttribute': 'string',
'omitStoppedVideo': True|False,
'videoFillMode': 'FILL'|'COVER'|'CONTAIN',
'gridGap': 123,
'pipParticipantAttribute': 'string',
'pipBehavior': 'STATIC'|'DYNAMIC',
'pipOffset': 123,
'pipPosition': 'TOP_LEFT'|'TOP_RIGHT'|'BOTTOM_LEFT'|'BOTTOM_RIGHT',
'pipWidth': 123,
'pipHeight': 123
}
},
'destinations': [
{
'id': 'string',
'state': 'STARTING'|'ACTIVE'|'STOPPING'|'RECONNECTING'|'FAILED'|'STOPPED',
'startTime': datetime(2015, 1, 1),
'endTime': datetime(2015, 1, 1),
'configuration': {
'name': 'string',
'channel': {
'channelArn': 'string',
'encoderConfigurationArn': 'string'
},
's3': {
'storageConfigurationArn': 'string',
'encoderConfigurationArns': [
'string',
],
'recordingConfiguration': {
'format': 'HLS'
},
'thumbnailConfigurations': [
{
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
]
},
]
}
},
'detail': {
's3': {
'recordingPrefix': 'string'
}
}
},
],
'tags': {
'string': 'string'
},
'startTime': datetime(2015, 1, 1),
'endTime': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
composition (dict) --
The Composition that was created.
arn (string) --
ARN of the Composition resource.
stageArn (string) --
ARN of the stage used as input
state (string) --
State of the Composition.
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. Default: "" (no featured participant).
omitStoppedVideo (boolean) --
Determines whether to omit participants with stopped video in the composition. Default: false.
videoAspectRatio (string) --
Sets the non-featured participant display mode, to control the aspect ratio of video tiles. VIDEO is 16:9, SQUARE is 1:1, and PORTRAIT is 3:4. Default: VIDEO.
videoFillMode (string) --
Defines how video content fits within the participant tile: FILL (stretched), COVER (cropped), or CONTAIN (letterboxed). When not set, videoFillMode defaults to COVER fill mode for participants in the grid and to CONTAIN fill mode for featured participants.
gridGap (integer) --
Specifies the spacing between participant tiles in pixels. Default: 2.
pip (dict) --
Configuration related to PiP 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. Default: "" (no featured participant).
omitStoppedVideo (boolean) --
Determines whether to omit participants with stopped video in the composition. Default: false.
videoFillMode (string) --
Defines how video content fits within the participant tile: FILL (stretched), COVER (cropped), or CONTAIN (letterboxed). Default: COVER.
gridGap (integer) --
Specifies the spacing between participant tiles in pixels. Default: 0.
pipParticipantAttribute (string) --
Specifies the participant for the PiP window. A participant with this attribute set to "true" (as a string value) in ParticipantTokenConfiguration is placed in the PiP slot. Default: "" (no PiP participant).
pipBehavior (string) --
Defines PiP behavior when all participants have left: STATIC (maintains original position/size) or DYNAMIC (expands to full composition). Default: STATIC.
pipOffset (integer) --
Sets the PiP window’s offset position in pixels from the closest edges determined by PipPosition. Default: 0.
pipPosition (string) --
Determines the corner position of the PiP window. Default: BOTTOM_RIGHT.
pipWidth (integer) --
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.
pipHeight (integer) --
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.
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.
id (string) --
Unique identifier for this destination, assigned by IVS.
state (string) --
State of the Composition Destination.
startTime (datetime) --
UTC time of the destination start. This is an ISO 8601 timestamp; note that this is returned as a string.
endTime (datetime) --
UTC time of the destination end. This is an ISO 8601 timestamp; note that this is returned as a string.
configuration (dict) --
Configuration used to create this destination.
name (string) --
Name that can be specified to help identify the 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.
s3 (dict) --
An S3 storage configuration to be used for recording video data. Either a channel or an s3 must be specified.
storageConfigurationArn (string) --
ARN of the StorageConfiguration where recorded videos will be stored.
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.
thumbnailConfigurations (list) --
A complex type that allows you to enable/disable the recording of thumbnails for a Composition and modify the interval at which thumbnails are generated for the live session.
(dict) --
An object representing a configuration of thumbnails for recorded video for a Composition.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/(width)x(height) directory, where (width) and (height) are the width and height of the thumbnail. LATEST saves the latest thumbnail in media/latest_thumbnail/(width)x(height)/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
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.
tags (dict) --
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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) --
startTime (datetime) --
UTC time of the Composition start. This is an ISO 8601 timestamp; note that this is returned as a string.
endTime (datetime) --
UTC time of the Composition end. This is an ISO 8601 timestamp; note that this is returned as a string.
{'autoParticipantRecordingConfiguration': {'mediaTypes': {'NONE'},
'thumbnailConfiguration': {'recordingMode': 'INTERVAL '
'| '
'DISABLED',
'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}}}
Response {'stage': {'autoParticipantRecordingConfiguration': {'mediaTypes': {'NONE'},
'thumbnailConfiguration': {'recordingMode': 'INTERVAL '
'| '
'DISABLED',
'storage': ['SEQUENTIAL '
'| '
'LATEST'],
'targetIntervalSeconds': 'integer'}}}}
Updates a stage’s configuration.
See also: AWS API Documentation
Request Syntax
client.update_stage(
arn='string',
name='string',
autoParticipantRecordingConfiguration={
'storageConfigurationArn': 'string',
'mediaTypes': [
'AUDIO_VIDEO'|'AUDIO_ONLY'|'NONE',
],
'thumbnailConfiguration': {
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
],
'recordingMode': 'INTERVAL'|'DISABLED'
}
}
)
string
[REQUIRED]
ARN of the stage to be updated.
string
Name of the stage to be updated.
dict
Configuration object for individual participant recording, to attach to the stage. Note that this cannot be updated while recording is active.
storageConfigurationArn (string) -- [REQUIRED]
ARN of the StorageConfiguration resource to use for individual participant recording. Default: "" (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a Stage is created or updated.
mediaTypes (list) --
Types of media to be recorded. Default: AUDIO_VIDEO.
(string) --
thumbnailConfiguration (dict) --
A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. This is configurable only if recordingMode is INTERVAL. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. LATEST saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
recordingMode (string) --
Thumbnail recording mode. Default: DISABLED.
dict
Response Syntax
{
'stage': {
'arn': 'string',
'name': 'string',
'activeSessionId': 'string',
'tags': {
'string': 'string'
},
'autoParticipantRecordingConfiguration': {
'storageConfigurationArn': 'string',
'mediaTypes': [
'AUDIO_VIDEO'|'AUDIO_ONLY'|'NONE',
],
'thumbnailConfiguration': {
'targetIntervalSeconds': 123,
'storage': [
'SEQUENTIAL'|'LATEST',
],
'recordingMode': 'INTERVAL'|'DISABLED'
}
},
'endpoints': {
'events': 'string',
'whip': 'string',
'rtmp': 'string',
'rtmps': 'string'
}
}
}
Response Structure
(dict) --
stage (dict) --
The updated stage.
arn (string) --
Stage ARN.
name (string) --
Stage name.
activeSessionId (string) --
ID of the active session within the stage.
tags (dict) --
Tags attached to the resource. Array of maps, each of the form string:string (key:value). See Best practices and strategies in Tagging AWS Resources and Tag Editor 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) --
autoParticipantRecordingConfiguration (dict) --
Configuration object for individual participant recording, attached to the stage.
storageConfigurationArn (string) --
ARN of the StorageConfiguration resource to use for individual participant recording. Default: "" (empty string, no storage configuration is specified). Individual participant recording cannot be started unless a storage configuration is specified, when a Stage is created or updated.
mediaTypes (list) --
Types of media to be recorded. Default: AUDIO_VIDEO.
(string) --
thumbnailConfiguration (dict) --
A complex type that allows you to enable/disable the recording of thumbnails for individual participant recording and modify the interval at which thumbnails are generated for the live session.
targetIntervalSeconds (integer) --
The targeted thumbnail-generation interval in seconds. This is configurable only if recordingMode is INTERVAL. Default: 60.
storage (list) --
Indicates the format in which thumbnails are recorded. SEQUENTIAL records all generated thumbnails in a serial manner, to the media/thumbnails/high directory. LATEST saves the latest thumbnail in media/latest_thumbnail/high/thumb.jpg and overwrites it at the interval specified by targetIntervalSeconds. You can enable both SEQUENTIAL and LATEST. Default: SEQUENTIAL.
(string) --
recordingMode (string) --
Thumbnail recording mode. Default: DISABLED.
endpoints (dict) --
Summary information about various endpoints for a stage.
events (string) --
Events endpoint.
whip (string) --
The endpoint to be used for IVS real-time streaming using the WHIP protocol.
rtmp (string) --
The endpoint to be used for IVS real-time streaming using the RTMP protocol.
rtmps (string) --
The endpoint to be used for IVS real-time streaming using the RTMPS protocol.