ivsrealtime / Client / start_composition

start_composition

ivsrealtime.Client.start_composition(**kwargs)

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

response = 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'
    }
)

Parameters:

• destinations (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.

• idempotencyToken (string) –

  Idempotency token.

  This field is autopopulated if not provided.

• 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) –

  [REQUIRED]

  ARN of the stage to be used for compositing.

• 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) –

Return type:

dict

Returns:

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) –

Exceptions

• ivsrealtime.Client.exceptions.ResourceNotFoundException

• ivsrealtime.Client.exceptions.ValidationException

• ivsrealtime.Client.exceptions.AccessDeniedException

• ivsrealtime.Client.exceptions.InternalServerException

• ivsrealtime.Client.exceptions.ServiceQuotaExceededException

• ivsrealtime.Client.exceptions.ConflictException

• ivsrealtime.Client.exceptions.PendingVerification