2025/05/29 - Amazon Interactive Video Service RealTime - 3 new 6 updated api methods
Changes IVS Real-Time now offers customers the participant replication that allow customers to copy a participant from one stage to another.
Lists all the replicas for a participant from a source stage.
See also: AWS API Documentation
Request Syntax
client.list_participant_replicas(
sourceStageArn='string',
participantId='string',
nextToken='string',
maxResults=123
)
string
[REQUIRED]
ARN of the stage where the participant is publishing.
string
[REQUIRED]
Participant ID of the publisher that has been replicated. This is assigned by IVS and returned by CreateParticipantToken or the jti (JWT ID) used to create a self signed token.
string
The first participant to retrieve. This is used for pagination; see the nextToken response field.
integer
Maximum number of results to return. Default: 50.
dict
Response Syntax
{
'replicas': [
{
'sourceStageArn': 'string',
'participantId': 'string',
'sourceSessionId': 'string',
'destinationStageArn': 'string',
'destinationSessionId': 'string',
'replicationState': 'ACTIVE'|'STOPPED'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
replicas (list) --
List of all participant replicas.
(dict) --
Information about the replicated destination stage for a participant.
sourceStageArn (string) --
ARN of the stage from which this participant is replicated.
participantId (string) --
Participant ID of the publisher that will be replicated. This is assigned by IVS and returned by CreateParticipantToken or the jti (JWT ID) used to create a self signed token.
sourceSessionId (string) --
ID of the session within the source stage.
destinationStageArn (string) --
ARN of the stage where the participant is replicated.
destinationSessionId (string) --
ID of the session within the destination stage.
replicationState (string) --
Replica’s current replication state.
nextToken (string) --
If there are more participants than maxResults, use nextToken in the request to get the next set.
Stops a replicated participant session.
See also: AWS API Documentation
Request Syntax
client.stop_participant_replication(
sourceStageArn='string',
destinationStageArn='string',
participantId='string'
)
string
[REQUIRED]
ARN of the stage where the participant is publishing.
string
[REQUIRED]
ARN of the stage where the participant has been replicated.
string
[REQUIRED]
Participant ID of the publisher that has been replicated. This is assigned by IVS and returned by CreateParticipantToken or the jti (JWT ID) used to create a self signed token.
dict
Response Syntax
{
'accessControlAllowOrigin': 'string',
'accessControlExposeHeaders': 'string',
'cacheControl': 'string',
'contentSecurityPolicy': 'string',
'strictTransportSecurity': 'string',
'xContentTypeOptions': 'string',
'xFrameOptions': 'string'
}
Response Structure
(dict) --
accessControlAllowOrigin (string) --
accessControlExposeHeaders (string) --
cacheControl (string) --
contentSecurityPolicy (string) --
strictTransportSecurity (string) --
xContentTypeOptions (string) --
xFrameOptions (string) --
Starts replicating a publishing participant from a source stage to a destination stage.
See also: AWS API Documentation
Request Syntax
client.start_participant_replication(
sourceStageArn='string',
destinationStageArn='string',
participantId='string',
reconnectWindowSeconds=123,
attributes={
'string': 'string'
}
)
string
[REQUIRED]
ARN of the stage where the participant is publishing.
string
[REQUIRED]
ARN of the stage to which the participant will be replicated.
string
[REQUIRED]
Participant ID of the publisher that will be replicated. This is assigned by IVS and returned by CreateParticipantToken or the jti (JWT ID) used to create a self signed token.
integer
If the participant disconnects and then reconnects within the specified interval, replication will continue to be ACTIVE. Default: 0.
dict
Application-provided attributes to set on the replicated participant in the destination 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.
These attributes are merged with any attributes set for this participant when creating the token. If there is overlap in keys, the values in these attributes are replaced.
(string) --
(string) --
dict
Response Syntax
{
'accessControlAllowOrigin': 'string',
'accessControlExposeHeaders': 'string',
'cacheControl': 'string',
'contentSecurityPolicy': 'string',
'strictTransportSecurity': 'string',
'xContentTypeOptions': 'string',
'xFrameOptions': 'string'
}
Response Structure
(dict) --
accessControlAllowOrigin (string) --
accessControlExposeHeaders (string) --
cacheControl (string) --
contentSecurityPolicy (string) --
strictTransportSecurity (string) --
xContentTypeOptions (string) --
xFrameOptions (string) --
{'autoParticipantRecordingConfiguration': {'recordParticipantReplicas': 'boolean'}}
Response {'stage': {'autoParticipantRecordingConfiguration': {'recordParticipantReplicas': 'boolean'}}}
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'
},
'recordingReconnectWindowSeconds': 123,
'hlsConfiguration': {
'targetSegmentDurationSeconds': 123
},
'recordParticipantReplicas': True|False
}
)
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. To disable individual participant recording, set this to ""; other fields in this object will get reset to their defaults when sending "".
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.
recordingReconnectWindowSeconds (integer) --
If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.
The default value is 0, which disables merging.
hlsConfiguration (dict) --
HLS configuration object for individual participant recording.
targetSegmentDurationSeconds (integer) --
Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
recordParticipantReplicas (boolean) --
Optional field to disable replica participant recording. If this is set to false when a participant is a replica, replica participants are not recorded. Default: true.
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'
},
'recordingReconnectWindowSeconds': 123,
'hlsConfiguration': {
'targetSegmentDurationSeconds': 123
},
'recordParticipantReplicas': True|False
},
'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. To disable individual participant recording, set this to ""; other fields in this object will get reset to their defaults when sending "".
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.
recordingReconnectWindowSeconds (integer) --
If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.
The default value is 0, which disables merging.
hlsConfiguration (dict) --
HLS configuration object for individual participant recording.
targetSegmentDurationSeconds (integer) --
Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
recordParticipantReplicas (boolean) --
Optional field to disable replica participant recording. If this is set to false when a participant is a replica, replica participants are not recorded. Default: true.
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.
{'participant': {'replicationState': 'ACTIVE | STOPPED',
'replicationType': 'SOURCE | REPLICA | NONE',
'sourceSessionId': 'string',
'sourceStageArn': 'string'}}
Gets information about the specified participant token.
See also: AWS API Documentation
Request Syntax
client.get_participant(
stageArn='string',
sessionId='string',
participantId='string'
)
string
[REQUIRED]
Stage ARN.
string
[REQUIRED]
ID of a session within the stage.
string
[REQUIRED]
Unique identifier for the participant. This is assigned by IVS and returned by CreateParticipantToken.
dict
Response Syntax
{
'participant': {
'participantId': 'string',
'userId': 'string',
'state': 'CONNECTED'|'DISCONNECTED',
'firstJoinTime': datetime(2015, 1, 1),
'attributes': {
'string': 'string'
},
'published': True|False,
'ispName': 'string',
'osName': 'string',
'osVersion': 'string',
'browserName': 'string',
'browserVersion': 'string',
'sdkVersion': 'string',
'recordingS3BucketName': 'string',
'recordingS3Prefix': 'string',
'recordingState': 'STARTING'|'ACTIVE'|'STOPPING'|'STOPPED'|'FAILED'|'DISABLED',
'protocol': 'UNKNOWN'|'WHIP'|'RTMP'|'RTMPS',
'replicationType': 'SOURCE'|'REPLICA'|'NONE',
'replicationState': 'ACTIVE'|'STOPPED',
'sourceStageArn': 'string',
'sourceSessionId': 'string'
}
}
Response Structure
(dict) --
participant (dict) --
The participant that is returned.
participantId (string) --
Unique identifier for this participant, assigned by IVS.
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.
state (string) --
Whether the participant is connected to or disconnected from the stage.
firstJoinTime (datetime) --
ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.
attributes (dict) --
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.
(string) --
(string) --
published (boolean) --
Whether the participant ever published to the stage session.
ispName (string) --
The participant’s Internet Service Provider.
osName (string) --
The participant’s operating system.
osVersion (string) --
The participant’s operating system version.
browserName (string) --
The participant’s browser.
browserVersion (string) --
The participant’s browser version.
sdkVersion (string) --
The participant’s SDK version.
recordingS3BucketName (string) --
Name of the S3 bucket to where the participant is being recorded, if individual participant recording is enabled, or "" (empty string), if recording is not enabled.
recordingS3Prefix (string) --
S3 prefix of the S3 bucket where the participant is being recorded, if individual participant recording is enabled, or "" (empty string), if recording is not enabled. If individual participant recording merge is enabled, and if a stage publisher disconnects from a stage and then reconnects, IVS tries to record to the same S3 prefix as the previous session. See Merge Fragmented Individual Participant Recordings.
recordingState (string) --
The participant’s recording state.
protocol (string) --
Type of ingest protocol that the participant employs for broadcasting.
replicationType (string) --
Indicates if the participant has been replicated to another stage or is a replica from another stage. Default: NONE.
replicationState (string) --
The participant's replication state.
sourceStageArn (string) --
Source stage ARN from which this participant is replicated, if replicationType is REPLICA.
sourceSessionId (string) --
ID of the session within the source stage, if replicationType is REPLICA.
{'stage': {'autoParticipantRecordingConfiguration': {'recordParticipantReplicas': 'boolean'}}}
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'
},
'recordingReconnectWindowSeconds': 123,
'hlsConfiguration': {
'targetSegmentDurationSeconds': 123
},
'recordParticipantReplicas': True|False
},
'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. To disable individual participant recording, set this to ""; other fields in this object will get reset to their defaults when sending "".
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.
recordingReconnectWindowSeconds (integer) --
If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.
The default value is 0, which disables merging.
hlsConfiguration (dict) --
HLS configuration object for individual participant recording.
targetSegmentDurationSeconds (integer) --
Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
recordParticipantReplicas (boolean) --
Optional field to disable replica participant recording. If this is set to false when a participant is a replica, replica participants are not recorded. Default: true.
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.
{'events': {'destinationSessionId': 'string',
'destinationStageArn': 'string',
'name': ['REPLICATION_STARTED', 'REPLICATION_STOPPED'],
'replica': 'boolean'}}
Lists events for a specified participant that occurred during a specified stage session.
See also: AWS API Documentation
Request Syntax
client.list_participant_events(
stageArn='string',
sessionId='string',
participantId='string',
nextToken='string',
maxResults=123
)
string
[REQUIRED]
Stage ARN.
string
[REQUIRED]
ID of a session within the stage.
string
[REQUIRED]
Unique identifier for this participant. This is assigned by IVS and returned by CreateParticipantToken.
string
The first participant event to retrieve. This is used for pagination; see the nextToken response field.
integer
Maximum number of results to return. Default: 50.
dict
Response Syntax
{
'events': [
{
'name': 'JOINED'|'LEFT'|'PUBLISH_STARTED'|'PUBLISH_STOPPED'|'SUBSCRIBE_STARTED'|'SUBSCRIBE_STOPPED'|'PUBLISH_ERROR'|'SUBSCRIBE_ERROR'|'JOIN_ERROR'|'REPLICATION_STARTED'|'REPLICATION_STOPPED',
'participantId': 'string',
'eventTime': datetime(2015, 1, 1),
'remoteParticipantId': 'string',
'errorCode': 'INSUFFICIENT_CAPABILITIES'|'QUOTA_EXCEEDED'|'PUBLISHER_NOT_FOUND'|'BITRATE_EXCEEDED'|'RESOLUTION_EXCEEDED'|'STREAM_DURATION_EXCEEDED'|'INVALID_AUDIO_CODEC'|'INVALID_VIDEO_CODEC'|'INVALID_PROTOCOL'|'INVALID_STREAM_KEY'|'REUSE_OF_STREAM_KEY'|'B_FRAME_PRESENT'|'INVALID_INPUT'|'INTERNAL_SERVER_EXCEPTION',
'destinationStageArn': 'string',
'destinationSessionId': 'string',
'replica': True|False
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
events (list) --
List of the matching events.
(dict) --
An occurrence during a stage session.
name (string) --
The name of the event.
participantId (string) --
Unique identifier for the participant who triggered the event. This is assigned by IVS.
eventTime (datetime) --
ISO 8601 timestamp (returned as a string) for when the event occurred.
remoteParticipantId (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.
errorCode (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.
B_FRAME_PRESENT — The participant's stream includes B-frames. For details, see IVS RTMP Publishing.
BITRATE_EXCEEDED — The participant exceeded the maximum supported bitrate. For details, see Service Quotas.
INSUFFICIENT_CAPABILITIES — The participant tried to take an action that the participant’s token is not allowed to do. For details on participant capabilities, see the capabilities field in CreateParticipantToken.
INTERNAL_SERVER_EXCEPTION — The participant failed to publish to the stage due to an internal server error.
INVALID_AUDIO_CODEC — The participant is using an invalid audio codec. For details, see Stream Ingest.
INVALID_INPUT — The participant is using an invalid input stream.
INVALID_PROTOCOL — The participant's IngestConfiguration resource is configured for RTMPS but they tried streaming with RTMP. For details, see IVS RTMP Publishing.
INVALID_STREAM_KEY — The participant is using an invalid stream key. For details, see IVS RTMP Publishing.
INVALID_VIDEO_CODEC — The participant is using an invalid video codec. For details, see Stream Ingest.
PUBLISHER_NOT_FOUND — The participant tried to subscribe to a publisher that doesn’t exist.
QUOTA_EXCEEDED — The number of participants who want to publish/subscribe to a stage exceeds the quota. For details, see Service Quotas.
RESOLUTION_EXCEEDED — The participant exceeded the maximum supported resolution. For details, see Service Quotas.
REUSE_OF_STREAM_KEY — The participant tried to use a stream key that is associated with another active stage session.
STREAM_DURATION_EXCEEDED — The participant exceeded the maximum allowed stream duration. For details, see Service Quotas.
destinationStageArn (string) --
ARN of the stage where the participant is replicated. Applicable only if the event name is REPLICATION_STARTED or REPLICATION_STOPPED.
destinationSessionId (string) --
ID of the session within the destination stage. Applicable only if the event name is REPLICATION_STARTED or REPLICATION_STOPPED.
replica (boolean) --
If true, this indicates the participantId is a replicated participant. If this is a subscribe event, then this flag refers to remoteParticipantId.
nextToken (string) --
If there are more events than maxResults, use nextToken in the request to get the next set.
{'participants': {'replicationState': 'ACTIVE | STOPPED',
'replicationType': 'SOURCE | REPLICA | NONE',
'sourceSessionId': 'string',
'sourceStageArn': 'string'}}
Lists all participants in a specified stage session.
See also: AWS API Documentation
Request Syntax
client.list_participants(
stageArn='string',
sessionId='string',
filterByUserId='string',
filterByPublished=True|False,
filterByState='CONNECTED'|'DISCONNECTED',
nextToken='string',
maxResults=123,
filterByRecordingState='STARTING'|'ACTIVE'|'STOPPING'|'STOPPED'|'FAILED'
)
string
[REQUIRED]
Stage ARN.
string
[REQUIRED]
ID of the session within the stage.
string
Filters the response list to match the specified user ID. Only one of filterByUserId, filterByPublished, filterByState, or filterByRecordingState 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.
boolean
Filters the response list to only show participants who published during the stage session. Only one of filterByUserId, filterByPublished, filterByState, or filterByRecordingState can be provided per request.
string
Filters the response list to only show participants in the specified state. Only one of filterByUserId, filterByPublished, filterByState, or filterByRecordingState can be provided per request.
string
The first participant to retrieve. This is used for pagination; see the nextToken response field.
integer
Maximum number of results to return. Default: 50.
string
Filters the response list to only show participants with the specified recording state. Only one of filterByUserId, filterByPublished, filterByState, or filterByRecordingState can be provided per request.
dict
Response Syntax
{
'participants': [
{
'participantId': 'string',
'userId': 'string',
'state': 'CONNECTED'|'DISCONNECTED',
'firstJoinTime': datetime(2015, 1, 1),
'published': True|False,
'recordingState': 'STARTING'|'ACTIVE'|'STOPPING'|'STOPPED'|'FAILED'|'DISABLED',
'replicationType': 'SOURCE'|'REPLICA'|'NONE',
'replicationState': 'ACTIVE'|'STOPPED',
'sourceStageArn': 'string',
'sourceSessionId': 'string'
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
participants (list) --
List of the matching participants (summary information only).
(dict) --
Summary object describing a participant that has joined a stage.
participantId (string) --
Unique identifier for this participant, assigned by IVS.
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.
state (string) --
Whether the participant is connected to or disconnected from the stage.
firstJoinTime (datetime) --
ISO 8601 timestamp (returned as a string) when the participant first joined the stage session.
published (boolean) --
Whether the participant ever published to the stage session.
recordingState (string) --
The participant’s recording state.
replicationType (string) --
Indicates if the participant has been replicated to another stage or is a replica from another stage. Default: NONE.
replicationState (string) --
The participant's replication state.
sourceStageArn (string) --
ARN of the stage from which this participant is replicated.
sourceSessionId (string) --
ID of the session within the source stage, if replicationType is REPLICA.
nextToken (string) --
If there are more participants than maxResults, use nextToken in the request to get the next set.
{'autoParticipantRecordingConfiguration': {'recordParticipantReplicas': 'boolean'}}
Response {'stage': {'autoParticipantRecordingConfiguration': {'recordParticipantReplicas': 'boolean'}}}
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'
},
'recordingReconnectWindowSeconds': 123,
'hlsConfiguration': {
'targetSegmentDurationSeconds': 123
},
'recordParticipantReplicas': True|False
}
)
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. To disable individual participant recording, set this to ""; other fields in this object will get reset to their defaults when sending "".
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.
recordingReconnectWindowSeconds (integer) --
If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.
The default value is 0, which disables merging.
hlsConfiguration (dict) --
HLS configuration object for individual participant recording.
targetSegmentDurationSeconds (integer) --
Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
recordParticipantReplicas (boolean) --
Optional field to disable replica participant recording. If this is set to false when a participant is a replica, replica participants are not recorded. Default: true.
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'
},
'recordingReconnectWindowSeconds': 123,
'hlsConfiguration': {
'targetSegmentDurationSeconds': 123
},
'recordParticipantReplicas': True|False
},
'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. To disable individual participant recording, set this to ""; other fields in this object will get reset to their defaults when sending "".
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.
recordingReconnectWindowSeconds (integer) --
If a stage publisher disconnects and then reconnects within the specified interval, the multiple recordings will be considered a single recording and merged together.
The default value is 0, which disables merging.
hlsConfiguration (dict) --
HLS configuration object for individual participant recording.
targetSegmentDurationSeconds (integer) --
Defines the target duration for recorded segments generated when recording a stage participant. Segments may have durations longer than the specified value when needed to ensure each segment begins with a keyframe. Default: 6.
recordParticipantReplicas (boolean) --
Optional field to disable replica participant recording. If this is set to false when a participant is a replica, replica participants are not recorded. Default: true.
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.