Note:

You are viewing the documentation for an older major version of the AWS CLI (version 1).

AWS CLI version 2, the latest major version of AWS CLI, is now stable and recommended for general use. To view this page for the AWS CLI version 2, click here. For more information see the AWS CLI version 2 installation instructions and migration guide.

[ aws . ivs ]

update-channel

Description

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.

See also: AWS API Documentation

Synopsis

  update-channel
--arn <value>
[--authorized | --no-authorized]
[--container-format <value>]
[--insecure-ingest | --no-insecure-ingest]
[--latency-mode <value>]
[--multitrack-input-configuration <value>]
[--name <value>]
[--playback-restriction-policy-arn <value>]
[--preset <value>]
[--recording-configuration-arn <value>]
[--type <value>]
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]
[--debug]
[--endpoint-url <value>]
[--no-verify-ssl]
[--no-paginate]
[--output <value>]
[--query <value>]
[--profile <value>]
[--region <value>]
[--version <value>]
[--color <value>]
[--no-sign-request]
[--ca-bundle <value>]
[--cli-read-timeout <value>]
[--cli-connect-timeout <value>]

Options

--arn (string)

ARN of the channel to be updated.

--authorized | --no-authorized (boolean)

Whether the channel is private (enabled for playback authorization).

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

Possible values:

  • TS
  • FRAGMENTED_MP4

--insecure-ingest | --no-insecure-ingest (boolean)

Whether the channel allows insecure RTMP and SRT 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.

Possible values:

  • NORMAL
  • LOW

--multitrack-input-configuration (structure)

Object specifying multitrack input configuration. Default: no multitrack input configuration is specified.

enabled -> (boolean)

Indicates whether multitrack input is enabled. Can be set to true only if channel type is STANDARD . Setting enabled to true with any other channel type will cause an exception. If true , then policy , maximumResolution , and containerFormat are required, and containerFormat must be set to FRAGMENTED_MP4 . Default: false .

maximumResolution -> (string)

Maximum resolution for multitrack input. Required if enabled is true .

policy -> (string)

Indicates whether multitrack input is allowed or required. Required if enabled is true .

Shorthand Syntax:

enabled=boolean,maximumResolution=string,policy=string

JSON Syntax:

{
  "enabled": true|false,
  "maximumResolution": "SD"|"HD"|"FULL_HD",
  "policy": "ALLOW"|"REQUIRE"
}

--name (string)

Channel name.

--playback-restriction-policy-arn (string)

Playback-restriction-policy ARN. A valid ARN value here both specifies the ARN and enables playback restriction. If this is set to an empty string, playback restriction policy is disabled.

--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 ("" ).

Possible values:

  • 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. If this is set to an empty string, recording is disabled.

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

Possible values:

  • BASIC
  • STANDARD
  • ADVANCED_SD
  • ADVANCED_HD

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

Global Options

--debug (boolean)

Turn on debug logging.

--endpoint-url (string)

Override command's default URL with the given URL.

--no-verify-ssl (boolean)

By default, the AWS CLI uses SSL when communicating with AWS services. For each SSL connection, the AWS CLI will verify SSL certificates. This option overrides the default behavior of verifying SSL certificates.

--no-paginate (boolean)

Disable automatic pagination. If automatic pagination is disabled, the AWS CLI will only make one call, for the first page of results.

--output (string)

The formatting style for command output.

  • json
  • text
  • table

--query (string)

A JMESPath query to use in filtering the response data.

--profile (string)

Use a specific profile from your credential file.

--region (string)

The region to use. Overrides config/env settings.

--version (string)

Display the version of this tool.

--color (string)

Turn on/off color output.

  • on
  • off
  • auto

--no-sign-request (boolean)

Do not sign requests. Credentials will not be loaded if this argument is provided.

--ca-bundle (string)

The CA certificate bundle to use when verifying SSL certificates. Overrides config/env settings.

--cli-read-timeout (int)

The maximum socket read time in seconds. If the value is set to 0, the socket read will be blocking and not timeout. The default value is 60 seconds.

--cli-connect-timeout (int)

The maximum socket connect time in seconds. If the value is set to 0, the socket connect will be blocking and not timeout. The default value is 60 seconds.

Examples

Note

To use the following examples, you must have the AWS CLI installed and configured. See the Getting started guide in the AWS CLI User Guide for more information.

Unless otherwise stated, all examples have unix-like quotation rules. These examples will need to be adapted to your terminal's quoting rules. See Using quotation marks with strings in the AWS CLI User Guide .

Example 1: To update a channel's configuration information

The following update-channel example updates the channel configuration for a specified channel ARN to change the channel name. This does not affect an ongoing stream of this channel; you must stop and restart the stream for the changes to take effect.

aws ivs update-channel \
    --arn arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh \
    --name "channel-1" \
    --insecure-ingest

Output:

{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh",
        "name": "channel-1",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "playbackRestrictionPolicyArn": "",
        "recordingConfigurationArn": "",
        "srt": {
            "endpoint": "a1b2c3d4e5f6.srt.live-video.net",
            "passphrase": "AB1C2defGHijkLMNo3PqQRstUvwxyzaBCDEfghh4ijklMN5opqrStuVWxyzAbCDEfghIJ"
        },
        "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net",
        "insecureIngest": true,
        "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8",
        "preset": "",
        "authorized": false,
        "tags": {}
}

For more information, see Create a Channel in the IVS Low-Latency User Guide.

Example 2: To update a channel's configuration to enable recording

The following update-channel example updates the channel configuration for a specified channel ARN to enable recording. This does not affect an ongoing stream of this channel; you must stop and restart the stream for the changes to take effect.

aws ivs update-channel \
    --arn "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh" \
    --no-insecure-ingest \
    --recording-configuration-arn "arn:aws:ivs:us-west-2:123456789012:recording-configuration/ABCD12cdEFgh"

Output:

{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh",
        "name": "test-channel-with-recording",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "playbackRestrictionPolicyArn": "",
        "recordingConfigurationArn": "arn:aws:ivs:us-west-2:123456789012:recording-configuration/ABCD12cdEFgh",
        "srt": {
            "endpoint": "a1b2c3d4e5f6.srt.live-video.net",
            "passphrase": "BA1C2defGHijkLMNo3PqQRstUvwxyzaBCDEfghh4ijklMN5opqrStuVWxyzAbCDEfghIJ"
        },
        "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net",
        "insecureIngest": false,
        "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8",
        "preset": "",
        "authorized": false,
        "tags": {}
    }
}

For more information, see Record to Amazon S3 in the IVS Low-Latency User Guide.

Example 3: To update a channel's configuration to disable recording

The following update-channel example updates the channel configuration for a specified channel ARN to disable recording. This does not affect an ongoing stream of this channel; you must stop and restart the stream for the changes to take effect.

aws ivs update-channel \
    --arn "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh" \
    --recording-configuration-arn ""

Output:

{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh",
        "name": "test-channel-with-recording",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "playbackRestrictionPolicyArn": "",
        "recordingConfigurationArn": "",
        "srt": {
            "endpoint": "a1b2c3d4e5f6.srt.live-video.net",
            "passphrase": "AB1C2edfGHijkLMNo3PqQRstUvwxyzaBCDEfghh4ijklMN5opqrStuVWxyzAbCDEfghIJ"
        },
        "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net",
        "insecureIngest": false,
        "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8",
        "preset": "",
        "authorized": false,
        "tags": {}
    }
}

For more information, see Record to Amazon S3 in the IVS Low-Latency User Guide.

Example 4: To update a channel's configuration to enable playback restriction

The following update-channel example updates the channel configuration for a specified channel ARN to apply a playback restriction policy. This does not affect an ongoing stream of this channel; you must stop and restart the stream for the changes to take effect.

aws ivs update-channel \
    --arn "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh" \
    --no-insecure-ingest \
    --playback-restriction-policy-arn "arn:aws:ivs:us-west-2:123456789012:playback-restriction-policy/ABcdef34ghIJ"

Output:

{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh",
        "name": "test-channel-with-playback-restriction-policy",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "playbackRestrictionPolicyArn": "arn:aws:ivs:us-west-2:123456789012:playback-restriction-policy/ABcdef34ghIJ",
        "recordingConfigurationArn": "",
        "srt": {
            "endpoint": "a1b2c3d4e5f6.srt.live-video.net",
            "passphrase": "AB1C2defGHijkLMNo3PqQRstUvwxyzaCBDEfghh4ijklMN5opqrStuVWxyzAbCDEfghIJ"
        },
        "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net",
        "insecureIngest": false,
        "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8",
        "preset": "",
        "authorized": false,
        "tags": {}
    }
}

For more information, see Undesired Content and Viewers in the IVS Low-Latency User Guide.

Example 5: To update a channel's configuration to disable playback restriction

The following update-channel example updates the channel configuration for a specified channel ARN to disable playback restriction. This does not affect an ongoing stream of this channel; you must stop and restart the stream for the changes to take effect.

aws ivs update-channel \
    --arn "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh" \
    --playback-restriction-policy-arn ""

Output:

{
    "channel": {
        "arn": "arn:aws:ivs:us-west-2:123456789012:channel/abcdABCDefgh",
        "name": "test-channel-with-playback-restriction-policy",
        "latencyMode": "LOW",
        "type": "STANDARD",
        "playbackRestrictionPolicyArn": "",
        "recordingConfigurationArn": "",
        "srt": {
            "endpoint": "a1b2c3d4e5f6.srt.live-video.net",
            "passphrase": "AB1C2defGHijkLMNo3PqQRstUvwxyzaBCDeFghh4ijklMN5opqrStuVWxyzAbCDEfghIJ"
        },
        "ingestEndpoint": "a1b2c3d4e5f6.global-contribute.live-video.net",
        "insecureIngest": false,
        "playbackUrl": "https://a1b2c3d4e5f6.us-west-2.playback.live-video.net/api/video/v1/us-west-2.123456789012.channel.abcdEFGH.m3u8",
        "preset": "",
        "authorized": false,
        "tags": {}
    }
}

For more information, see Undesired Content and Viewers in the IVS Low-Latency User Guide.

Output

channel -> (structure)

Object specifying the updated channel.

arn -> (string)

Channel ARN.

authorized -> (boolean)

Whether the channel is private (enabled for playback authorization). Default: false .

containerFormat -> (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 .

ingestEndpoint -> (string)

Channel ingest endpoint, part of the definition of an ingest server, used when you set up streaming software.

insecureIngest -> (boolean)

Whether the channel allows insecure RTMP ingest. Default: false .

latencyMode -> (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 .

multitrackInputConfiguration -> (structure)

Object specifying multitrack input configuration. Default: no multitrack input configuration is specified.

enabled -> (boolean)

Indicates whether multitrack input is enabled. Can be set to true only if channel type is STANDARD . Setting enabled to true with any other channel type will cause an exception. If true , then policy , maximumResolution , and containerFormat are required, and containerFormat must be set to FRAGMENTED_MP4 . Default: false .

maximumResolution -> (string)

Maximum resolution for multitrack input. Required if enabled is true .

policy -> (string)

Indicates whether multitrack input is allowed or required. Required if enabled is true .

name -> (string)

Channel name.

playbackRestrictionPolicyArn -> (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).

playbackUrl -> (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 ("" ).

recordingConfigurationArn -> (string)

Recording-configuration ARN. A valid ARN value here both specifies the ARN and enables recording. Default: "" (empty string, recording is disabled).

srt -> (structure)

Specifies the endpoint and optional passphrase for streaming with the SRT protocol.

endpoint -> (string)

The endpoint to be used when streaming with IVS using the SRT protocol.

passphrase -> (string)

Auto-generated passphrase to enable encryption. This field is applicable only if the end user has not enabled the insecureIngest option for the channel.

tags -> (map)

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.

key -> (string)

value -> (string)

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 .