StartCompositionCommand

Suggest an Edit

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.

Example Syntax

Use a bare-bones client and the command you need to make an API call.

import { IVSRealTimeClient, StartCompositionCommand } from "@aws-sdk/client-ivs-realtime"; // ES Modules import
// const { IVSRealTimeClient, StartCompositionCommand } = require("@aws-sdk/client-ivs-realtime"); // CommonJS import
const client = new IVSRealTimeClient(config);
const input = { // StartCompositionRequest
  stageArn: "STRING_VALUE", // required
  idempotencyToken: "STRING_VALUE",
  layout: { // LayoutConfiguration
    grid: { // GridConfiguration
      featuredParticipantAttribute: "STRING_VALUE",
      omitStoppedVideo: true || false,
      videoAspectRatio: "AUTO" || "VIDEO" || "SQUARE" || "PORTRAIT",
      videoFillMode: "FILL" || "COVER" || "CONTAIN",
      gridGap: Number("int"),
    },
    pip: { // PipConfiguration
      featuredParticipantAttribute: "STRING_VALUE",
      omitStoppedVideo: true || false,
      videoFillMode: "FILL" || "COVER" || "CONTAIN",
      gridGap: Number("int"),
      pipParticipantAttribute: "STRING_VALUE",
      pipBehavior: "STATIC" || "DYNAMIC",
      pipOffset: Number("int"),
      pipPosition: "TOP_LEFT" || "TOP_RIGHT" || "BOTTOM_LEFT" || "BOTTOM_RIGHT",
      pipWidth: Number("int"),
      pipHeight: Number("int"),
    },
  },
  destinations: [ // DestinationConfigurationList // required
    { // DestinationConfiguration
      name: "STRING_VALUE",
      channel: { // ChannelDestinationConfiguration
        channelArn: "STRING_VALUE", // required
        encoderConfigurationArn: "STRING_VALUE",
      },
      s3: { // S3DestinationConfiguration
        storageConfigurationArn: "STRING_VALUE", // required
        encoderConfigurationArns: [ // EncoderConfigurationArnList // required
          "STRING_VALUE",
        ],
        recordingConfiguration: { // RecordingConfiguration
          hlsConfiguration: { // CompositionRecordingHlsConfiguration
            targetSegmentDurationSeconds: Number("int"),
          },
          format: "STRING_VALUE",
        },
        thumbnailConfigurations: [ // CompositionThumbnailConfigurationList
          { // CompositionThumbnailConfiguration
            targetIntervalSeconds: Number("int"),
            storage: [ // ThumbnailStorageTypeList
              "SEQUENTIAL" || "LATEST",
            ],
          },
        ],
      },
    },
  ],
  tags: { // Tags
    "<keys>": "STRING_VALUE",
  },
};
const command = new StartCompositionCommand(input);
const response = await client.send(command);
// { // StartCompositionResponse
//   composition: { // Composition
//     arn: "STRING_VALUE", // required
//     stageArn: "STRING_VALUE", // required
//     state: "STRING_VALUE", // required
//     layout: { // LayoutConfiguration
//       grid: { // GridConfiguration
//         featuredParticipantAttribute: "STRING_VALUE",
//         omitStoppedVideo: true || false,
//         videoAspectRatio: "AUTO" || "VIDEO" || "SQUARE" || "PORTRAIT",
//         videoFillMode: "FILL" || "COVER" || "CONTAIN",
//         gridGap: Number("int"),
//       },
//       pip: { // PipConfiguration
//         featuredParticipantAttribute: "STRING_VALUE",
//         omitStoppedVideo: true || false,
//         videoFillMode: "FILL" || "COVER" || "CONTAIN",
//         gridGap: Number("int"),
//         pipParticipantAttribute: "STRING_VALUE",
//         pipBehavior: "STATIC" || "DYNAMIC",
//         pipOffset: Number("int"),
//         pipPosition: "TOP_LEFT" || "TOP_RIGHT" || "BOTTOM_LEFT" || "BOTTOM_RIGHT",
//         pipWidth: Number("int"),
//         pipHeight: Number("int"),
//       },
//     },
//     destinations: [ // DestinationList // required
//       { // Destination
//         id: "STRING_VALUE", // required
//         state: "STRING_VALUE", // required
//         startTime: new Date("TIMESTAMP"),
//         endTime: new Date("TIMESTAMP"),
//         configuration: { // DestinationConfiguration
//           name: "STRING_VALUE",
//           channel: { // ChannelDestinationConfiguration
//             channelArn: "STRING_VALUE", // required
//             encoderConfigurationArn: "STRING_VALUE",
//           },
//           s3: { // S3DestinationConfiguration
//             storageConfigurationArn: "STRING_VALUE", // required
//             encoderConfigurationArns: [ // EncoderConfigurationArnList // required
//               "STRING_VALUE",
//             ],
//             recordingConfiguration: { // RecordingConfiguration
//               hlsConfiguration: { // CompositionRecordingHlsConfiguration
//                 targetSegmentDurationSeconds: Number("int"),
//               },
//               format: "STRING_VALUE",
//             },
//             thumbnailConfigurations: [ // CompositionThumbnailConfigurationList
//               { // CompositionThumbnailConfiguration
//                 targetIntervalSeconds: Number("int"),
//                 storage: [ // ThumbnailStorageTypeList
//                   "SEQUENTIAL" || "LATEST",
//                 ],
//               },
//             ],
//           },
//         },
//         detail: { // DestinationDetail
//           s3: { // S3Detail
//             recordingPrefix: "STRING_VALUE", // required
//           },
//         },
//       },
//     ],
//     tags: { // Tags
//       "<keys>": "STRING_VALUE",
//     },
//     startTime: new Date("TIMESTAMP"),
//     endTime: new Date("TIMESTAMP"),
//   },
// };

StartCompositionCommand Input

See StartCompositionCommandInput for more details

Parameter
Type
Description
destinations
Required
DestinationConfiguration[] | undefined

Array of destination configuration.

stageArn
Required
string | undefined

ARN of the stage to be used for compositing.

idempotencyToken
string | undefined

Idempotency token.

layout
LayoutConfiguration | undefined

Layout object to configure composition parameters.

tags
Record<string, string> | undefined

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.

StartCompositionCommand Output

See StartCompositionCommandOutput for details

Parameter
Type
Description
$metadata
Required
ResponseMetadata
Metadata pertaining to this request.
composition
Composition | undefined

The Composition that was created.

Throws

Name
Fault
Details
AccessDeniedException
client
<p/>
ConflictException
client
<p/>
InternalServerException
server
<p/>
PendingVerification
client
<p/>
ResourceNotFoundException
client
<p/>
ServiceQuotaExceededException
client
<p/>
ValidationException
client
<p/>
IVSRealTimeServiceException
Base exception class for all service exceptions from IVSRealTime service.