:doc:`ivsrealtime <../../ivs-realtime>` / Client / get_composition

***************
get_composition
***************



.. py:method:: ivsrealtime.Client.get_composition(**kwargs)

  

  Get information about the specified Composition resource.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/ivs-realtime-2020-07-14/GetComposition>`_  


  **Request Syntax**
  ::

    response = client.get_composition(
        arn='string'
    )
    
  :type arn: string
  :param arn: **[REQUIRED]** 

    ARN of the Composition resource.

    

  
  
  :rtype: dict
  :returns: 
    
    **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,
                      'participantOrderAttribute': 'string'
                  },
                  '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,
                      'participantOrderAttribute': 'string'
                  }
              },
              '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': {
                                  'hlsConfiguration': {
                                      'targetSegmentDurationSeconds': 123
                                  },
                                  '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``.

              
            

            - **participantOrderAttribute** *(string) --* 

              Attribute name in  ParticipantTokenConfiguration identifying the participant ordering key. Participants with ``participantOrderAttribute`` set to ``""`` or not specified are ordered based on their arrival time into the stage.

              
        
          

          - **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.

              
            

            - **participantOrderAttribute** *(string) --* 

              Attribute name in  ParticipantTokenConfiguration identifying the participant ordering key. Participants with ``participantOrderAttribute`` set to ``""`` or not specified are ordered based on their arrival time into the stage.

              
        
      
        

        - **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.

                  
                  

                  - **hlsConfiguration** *(dict) --* 

                    An HLS configuration object to return information about how the recording will be configured.

                    
                    

                    - **targetSegmentDurationSeconds** *(integer) --* 

                      Defines the target duration for recorded segments generated when using composite recording. Default: 2.

                      
                
                  

                  - **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 <https://docs.aws.amazon.com/tag-editor/latest/userguide/best-practices-and-strats.html>`__ 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*.

          
    
  
  **Exceptions**
  
  *   :py:class:`ivsrealtime.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`ivsrealtime.Client.exceptions.ValidationException`

  
  *   :py:class:`ivsrealtime.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`ivsrealtime.Client.exceptions.InternalServerException`

  
  *   :py:class:`ivsrealtime.Client.exceptions.ServiceQuotaExceededException`

  
  *   :py:class:`ivsrealtime.Client.exceptions.ConflictException`

  