channels

Creates, updates, deletes, gets or lists a channels resource.

Overview

Name	channels
Type	Resource
Id	aws.ivs.channels

Fields

The following fields are returned by SELECT queries:

batch_get_channel

Name	Datatype	Description
access_control_allow_origin	string	See Access-Control-Allow-Origin in the MDN Web Docs.
access_control_expose_headers	string	See Access-Control-Expose-Headers in the MDN Web Docs.
cache_control	string	See Cache-Control in the MDN Web Docs.
channels	array
content_security_policy	string	See Content-Security-Policy in the MDN Web Docs.
errors	array	Each error object is related to a specific ARN in the request.
strict_transport_security	string	See Strict-Transport-Security in the MDN Web Docs.
x_content_type_options	string	See X-Content-Type-Options in the MDN Web Docs.
x_frame_options	string	See X-Frame-Options in the MDN Web Docs.

get_channel

Name	Datatype	Description
name	string	Channel name. (pattern: <code>[a-zA-Z0-9-_]*</code>)
ad_configuration_arn	string	ARN of the ad configuration associated with the channel. (pattern: <code>^$|^arn:aws:ivs:[a-z0-9-]+:[0-9]+:ad-configuration/[a-zA-Z0-9-]+$</code>)
arn	string	Channel ARN. (pattern: <code>arn:aws:ivs:[a-z0-9-]+:[0-9]+:channel/[a-zA-Z0-9-]+</code>)
authorized	boolean	Whether the channel is private (enabled for playback authorization). Default: false.
container_format	string	Indicates which content-packaging format is used (MPEG-TS or fMP4). If multitrackInputConfiguration is specified and enabled is true, then containerFormat is required and must be set to FRAGMENTED_MP4. Otherwise, containerFormat may be set to TS or FRAGMENTED_MP4. Default: TS. (TS, FRAGMENTED_MP4)
ingest_endpoint	string	Channel ingest endpoint, part of the definition of an ingest server, used when you set up streaming software.
insecure_ingest	boolean	Whether the channel allows insecure RTMP ingest. Default: false.
latency_mode	string	Channel latency mode. Use NORMAL to broadcast and deliver live video up to Full HD. Use LOW for near-real-time interaction with viewers. Default: LOW. (NORMAL, LOW)
multitrack_input_configuration	object	Object specifying multitrack input configuration. Default: no multitrack input configuration is specified.
playback_restriction_policy_arn	string	Playback-restriction-policy ARN. A valid ARN value here both specifies the ARN and enables playback restriction. Default: "" (empty string, no playback restriction policy is applied). (pattern: <code>^$|^arn:aws:ivs:[a-z0-9-]+:[0-9]+:playback-restriction-policy/[a-zA-Z0-9-]+$</code>)
playback_url	string	Channel playback URL.
preset	string	Optional transcode preset for the channel. This is selectable only for ADVANCED_HD and ADVANCED_SD channel types. For those channel types, the default preset is HIGHER_BANDWIDTH_DELIVERY. For other channel types (BASIC and STANDARD), preset is the empty string (""). (HIGHER_BANDWIDTH_DELIVERY, CONSTRAINED_BANDWIDTH_DELIVERY)
recording_configuration_arn	string	Recording-configuration ARN. A valid ARN value here both specifies the ARN and enables recording. Default: "" (empty string, recording is disabled). (pattern: <code>^$|^arn:aws:ivs:[a-z0-9-]+:[0-9]+:recording-configuration/[a-zA-Z0-9-]+$</code>)
srt	object	Specifies the endpoint and optional passphrase for streaming with the SRT protocol.
tags	object	Tags attached to the resource. Array of 1-50 maps, each of the form string:string (key:value). See Best practices and strategies in Tagging Amazon Web Services Resources and Tag Editor for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no service-specific constraints beyond what is documented there.
type_	string	Channel type, which determines the allowable resolution and bitrate. If you exceed the allowable input resolution or bitrate, the stream probably will disconnect immediately. Default: STANDARD. For details, see Channel Types. (BASIC, STANDARD, ADVANCED_SD, ADVANCED_HD)

list_channels

Name	Datatype	Description
name	string	Channel name. (pattern: <code>[a-zA-Z0-9-_]*</code>)
ad_configuration_arn	string	ARN of the ad configuration associated with the channel. (pattern: <code>^$|^arn:aws:ivs:[a-z0-9-]+:[0-9]+:ad-configuration/[a-zA-Z0-9-]+$</code>)
arn	string	Channel ARN. (pattern: <code>arn:aws:ivs:[a-z0-9-]+:[0-9]+:channel/[a-zA-Z0-9-]+</code>)
authorized	boolean	Whether the channel is private (enabled for playback authorization). Default: false.
insecure_ingest	boolean	Whether the channel allows insecure RTMP ingest. Default: false.
latency_mode	string	Channel latency mode. Use NORMAL to broadcast and deliver live video up to Full HD. Use LOW for near-real-time interaction with viewers. Default: LOW. (NORMAL, LOW)
playback_restriction_policy_arn	string	Playback-restriction-policy ARN. A valid ARN value here both specifies the ARN and enables playback restriction. Default: "" (empty string, no playback restriction policy is applied). (pattern: <code>^$|^arn:aws:ivs:[a-z0-9-]+:[0-9]+:playback-restriction-policy/[a-zA-Z0-9-]+$</code>)
preset	string	Optional transcode preset for the channel. This is selectable only for ADVANCED_HD and ADVANCED_SD channel types. For those channel types, the default preset is HIGHER_BANDWIDTH_DELIVERY. For other channel types (BASIC and STANDARD), preset is the empty string (""). (HIGHER_BANDWIDTH_DELIVERY, CONSTRAINED_BANDWIDTH_DELIVERY)
recording_configuration_arn	string	Recording-configuration ARN. A valid ARN value here both specifies the ARN and enables recording. Default: "" (empty string, recording is disabled). (pattern: <code>^$|^arn:aws:ivs:[a-z0-9-]+:[0-9]+:recording-configuration/[a-zA-Z0-9-]+$</code>)
tags	object	Tags attached to the resource. Array of 1-50 maps, each of the form string:string (key:value). See Best practices and strategies in Tagging Amazon Web Services Resources and Tag Editor for details, including restrictions that apply to tags and "Tag naming limits and requirements"; Amazon IVS has no service-specific constraints beyond what is documented there.
type_	string	Channel type, which determines the allowable resolution and bitrate. If you exceed the allowable input resolution or bitrate, the stream probably will disconnect immediately. Default: STANDARD. For details, see Channel Types. (BASIC, STANDARD, ADVANCED_SD, ADVANCED_HD)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
batch_get_channel	select	region		Performs GetChannel on multiple ARNs simultaneously.
get_channel	select	region		Gets the channel configuration for the specified channel ARN. See also BatchGetChannel.
list_channels	select	region		Gets summary information about all channels in your account, in the Amazon Web Services region where the API request is processed. This list can be filtered to match a specified name or recording-configuration ARN. Filters are mutually exclusive and cannot be used together. If you try to use both filters, you will get an error (409 ConflictException).
create_channel	insert	region		Creates a new channel and an associated stream key to start streaming.
update_channel	update	region, arn		Updates a channel's configuration. Live channels cannot be updated. You must stop the ongoing stream, update the channel, and restart the stream for the changes to take effect.
put_metadata	replace	region, channelArn, metadata		Inserts metadata into the active stream of the specified channel. At most 5 requests per second per channel are allowed, each with a maximum 1 KB payload. (If 5 TPS is not sufficient for your needs, we recommend batching your data into a single PutMetadata call.) At most 155 requests per second per account are allowed. Also see Embedding Metadata within a Video Stream in the Amazon IVS User Guide.
delete_channel	delete	region		Deletes the specified channel and its associated stream keys. If you try to delete a live channel, you will get an error (409 ConflictException). To delete a channel that is live, call StopStream, wait for the Amazon EventBridge "Stream End" event (to verify that the stream's state is no longer Live), then call DeleteChannel. (See Using EventBridge with Amazon IVS.)
insert_ad_break	exec	region, channelArn, durationSeconds		Inserts an ad marker in the playlist for the specified channel and duration using the ad configuration associated with the channel. Note: AWS Elemental MediaTailor (EMT), the service that handles ad requests, provides CloudWatch metrics to help you monitor the success or failure of each InsertAdBreak operation. See Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics in the AWS Elemental MediaTailor User Guide for details on available metrics.
start_viewer_session_revocation	exec	region, channelArn, viewerId		Starts the process of revoking the viewer session associated with a specified channel ARN and viewer ID. Optionally, you can provide a version to revoke viewer sessions less than and including that version. For instructions on associating a viewer ID with a viewer session, see Setting Up Private Channels.
stop_stream	exec	region, channelArn		Disconnects the incoming RTMPS stream for the specified channel. Can be used in conjunction with DeleteStreamKey to prevent further streaming to a channel. Many streaming client-software libraries automatically reconnect a dropped RTMPS session, so to stop the stream permanently, you may want to first revoke the streamKey attached to the channel.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
region	string	AWS region (default: us-east-1)

SELECT examples

batch_get_channel

Performs GetChannel on multiple ARNs simultaneously.

SELECT
access_control_allow_origin,
access_control_expose_headers,
cache_control,
channels,
content_security_policy,
errors,
strict_transport_security,
x_content_type_options,
x_frame_options
FROM aws.ivs.channels
WHERE region = '{{ region }}' -- required
;

get_channel

Gets the channel configuration for the specified channel ARN. See also BatchGetChannel.

SELECT
name,
ad_configuration_arn,
arn,
authorized,
container_format,
ingest_endpoint,
insecure_ingest,
latency_mode,
multitrack_input_configuration,
playback_restriction_policy_arn,
playback_url,
preset,
recording_configuration_arn,
srt,
tags,
type_
FROM aws.ivs.channels
WHERE region = '{{ region }}' -- required
;

list_channels

Gets summary information about all channels in your account, in the Amazon Web Services region where the API request is processed. This list can be filtered to match a specified name or recording-configuration ARN. Filters are mutually exclusive and cannot be used together. If you try to use both filters, you will get an error (409 ConflictException).

SELECT
name,
ad_configuration_arn,
arn,
authorized,
insecure_ingest,
latency_mode,
playback_restriction_policy_arn,
preset,
recording_configuration_arn,
tags,
type_
FROM aws.ivs.channels
WHERE region = '{{ region }}' -- required
;

INSERT examples

create_channel

Creates a new channel and an associated stream key to start streaming.

INSERT INTO aws.ivs.channels (
name,
latencyMode,
type,
authorized,
recordingConfigurationArn,
tags,
insecureIngest,
preset,
playbackRestrictionPolicyArn,
multitrackInputConfiguration,
containerFormat,
adConfigurationArn,
region
)
SELECT 
'{{ name }}',
'{{ latencyMode }}',
'{{ type }}',
{{ authorized }},
'{{ recordingConfigurationArn }}',
'{{ tags }}',
{{ insecureIngest }},
'{{ preset }}',
'{{ playbackRestrictionPolicyArn }}',
'{{ multitrackInputConfiguration }}',
'{{ containerFormat }}',
'{{ adConfigurationArn }}',
'{{ region }}'
RETURNING
channel,
stream_key
;

Manifest

# Description fields are for documentation purposes
- name: channels
props:
  - name: region
    value: "{{ region }}"
    description: Required parameter for the channels resource.
  - name: name
    value: "{{ name }}"
  - name: latencyMode
    value: "{{ latencyMode }}"
    valid_values: ['NORMAL', 'LOW']
  - name: type
    value: "{{ type }}"
    valid_values: ['BASIC', 'STANDARD', 'ADVANCED_SD', 'ADVANCED_HD']
  - name: authorized
    value: {{ authorized }}
  - name: recordingConfigurationArn
    value: "{{ recordingConfigurationArn }}"
  - name: tags
    value: "{{ tags }}"
  - name: insecureIngest
    value: {{ insecureIngest }}
  - name: preset
    value: "{{ preset }}"
    valid_values: ['HIGHER_BANDWIDTH_DELIVERY', 'CONSTRAINED_BANDWIDTH_DELIVERY']
  - name: playbackRestrictionPolicyArn
    value: "{{ playbackRestrictionPolicyArn }}"
  - name: multitrackInputConfiguration
    description: |
      A complex type that specifies multitrack input configuration.
    value:
      enabled: {{ enabled }}
      policy: "{{ policy }}"
      maximumResolution: "{{ maximumResolution }}"
  - name: containerFormat
    value: "{{ containerFormat }}"
    valid_values: ['TS', 'FRAGMENTED_MP4']
  - name: adConfigurationArn
    value: "{{ adConfigurationArn }}"

UPDATE examples

update_channel

Updates a channel's configuration. Live channels cannot be updated. You must stop the ongoing stream, update the channel, and restart the stream for the changes to take effect.

UPDATE aws.ivs.channels
SET 
arn = '{{ arn }}',
name = '{{ name }}',
latencyMode = '{{ latencyMode }}',
type = '{{ type }}',
authorized = {{ authorized }},
recordingConfigurationArn = '{{ recordingConfigurationArn }}',
insecureIngest = {{ insecureIngest }},
preset = '{{ preset }}',
playbackRestrictionPolicyArn = '{{ playbackRestrictionPolicyArn }}',
multitrackInputConfiguration = '{{ multitrackInputConfiguration }}',
containerFormat = '{{ containerFormat }}',
adConfigurationArn = '{{ adConfigurationArn }}'
WHERE 
region = '{{ region }}' --required
AND arn = '{{ arn }}' --required
RETURNING
channel;

REPLACE examples

put_metadata

Inserts metadata into the active stream of the specified channel. At most 5 requests per second per channel are allowed, each with a maximum 1 KB payload. (If 5 TPS is not sufficient for your needs, we recommend batching your data into a single PutMetadata call.) At most 155 requests per second per account are allowed. Also see Embedding Metadata within a Video Stream in the Amazon IVS User Guide.

REPLACE aws.ivs.channels
SET 
channelArn = '{{ channelArn }}',
metadata = '{{ metadata }}'
WHERE 
region = '{{ region }}' --required
AND channelArn = '{{ channelArn }}' --required
AND metadata = '{{ metadata }}' --required;

DELETE examples

delete_channel

Deletes the specified channel and its associated stream keys. If you try to delete a live channel, you will get an error (409 ConflictException). To delete a channel that is live, call StopStream, wait for the Amazon EventBridge "Stream End" event (to verify that the stream's state is no longer Live), then call DeleteChannel. (See Using EventBridge with Amazon IVS.)

DELETE FROM aws.ivs.channels
WHERE region = '{{ region }}' --required
;

Lifecycle Methods

insert_ad_break

Inserts an ad marker in the playlist for the specified channel and duration using the ad configuration associated with the channel. Note: AWS Elemental MediaTailor (EMT), the service that handles ad requests, provides CloudWatch metrics to help you monitor the success or failure of each InsertAdBreak operation. See Monitoring AWS Elemental MediaTailor with Amazon CloudWatch metrics in the AWS Elemental MediaTailor User Guide for details on available metrics.

EXEC aws.ivs.channels.insert_ad_break 
@region='{{ region }}' --required 
@@json=
'{
"channelArn": "{{ channelArn }}", 
"durationSeconds": {{ durationSeconds }}
}'
;

start_viewer_session_revocation

Starts the process of revoking the viewer session associated with a specified channel ARN and viewer ID. Optionally, you can provide a version to revoke viewer sessions less than and including that version. For instructions on associating a viewer ID with a viewer session, see Setting Up Private Channels.

EXEC aws.ivs.channels.start_viewer_session_revocation 
@region='{{ region }}' --required 
@@json=
'{
"channelArn": "{{ channelArn }}", 
"viewerId": "{{ viewerId }}", 
"viewerSessionVersionsLessThanOrEqualTo": {{ viewerSessionVersionsLessThanOrEqualTo }}
}'
;

stop_stream

Disconnects the incoming RTMPS stream for the specified channel. Can be used in conjunction with DeleteStreamKey to prevent further streaming to a channel. Many streaming client-software libraries automatically reconnect a dropped RTMPS session, so to stop the stream permanently, you may want to first revoke the streamKey attached to the channel.

EXEC aws.ivs.channels.stop_stream 
@region='{{ region }}' --required 
@@json=
'{
"channelArn": "{{ channelArn }}"
}'
;