Updated on 2025-01-24 GMT+08:00

Querying Channel Information

Function

Queries channel information. Batch query is supported.

URI

GET /v1/{project_id}/ott/channels

Table 1 Path Parameters

Parameter

Mandatory

Type

Description

project_id

Yes

String

Project ID. For details about how to obtain the project ID, see Obtaining a Project ID.

Table 2 Query Parameters

Parameter

Mandatory

Type

Description

domain

No

String

Ingest domain name.

app_name

No

String

Group name or application name.

id

No

String

Channel ID.

limit

No

Integer

Number of records on each page. The value ranges from 1 to 100. The default value is 10.

offset

No

Integer

Offset, which is the position where the query starts. The value must be greater than or equal to 0.

Request Parameters

Table 3 Request header parameters

Parameter

Mandatory

Type

Description

X-Auth-Token

Yes

String

User token. This parameter is mandatory when token authentication is used. It can be obtained by calling the IAM API used to obtain a user token. The value of X-Subject-Token in the response header is the user token.

Access-Control-Allow-Internal

No

String

Service authentication token. If authentication is enabled for a service, Access-Control-Allow-Internal must be carried to access the service.

Access-Control-Allow-External

No

String

Service authentication token. If authentication is enabled for a service, Access-Control-Allow-External must be carried to access the service.

Response Parameters

Status code: 200

Table 4 Response body parameters

Parameter

Type

Description

total

Integer

Total number of channels.

channels

Array of CreateOttChannelInfoReq objects

Channel information.

Table 5 CreateOttChannelInfoReq

Parameter

Type

Description

domain

String

Ingest domain name of a channel.

app_name

String

Group name or application name.

id

String

(Mandatory) Unique ID of a channel.

name

String

Channel name. This parameter is optional.

state

String

Channel status.

  • ON: After a channel is delivered, functions such as stream pull, transcoding, and recording are automatically enabled.

  • OFF: Only the channel information is saved but the channel is not started.

input

InputStreamInfo object

Channel input stream information.

encoder_settings

Array of encoder_settings objects

Transcoding template configuration.

record_settings

record_settings object

Catch-up TV configuration.

endpoints

Array of EndpointItem objects

Channel output stream information.

encoder_settings_expand

EncoderSettingsExpand object

Audio output configuration

Table 6 InputStreamInfo

Parameter

Type

Description

input_protocol

String

Channel input protocol

  • FLV_PULL

  • RTMP_PUSH

  • HLS_PULL

  • SRT_PULL

  • SRT_PUSH

sources

Array of SourcesInfo objects

Information about the primary source stream of a channel. This parameter is optional when the stream input protocol is RTMP_PUSH or SRT_PUSH. In other cases, this parameter is mandatory.

secondary_sources

Array of SecondarySourcesInfo objects

Standby input stream array. This parameter is optional. If there is a standby input stream, ensure that the number of channels, codec, and resolution of the primary and standby input streams are the same. If the stream input protocol is RTMP_PUSH, you do not need to specify this parameter.

failover_conditions

FailoverConditions object

(Optional) Configuration provided by the channel supplier to switch between the primary and standby media stream URLs.

max_bandwidth_limit

Integer

Maximum bandwidth required when the input protocol is HLS_PULL.

A streaming URL provided by the user includes the parameter BANDWIDTH for audios/videos with different bitrates.

  • If the maximum bandwidth is specified, Media Live will pull the media stream that has the highest bitrate and a bandwidth lower than the maximum bandwidth from the URL, and push the stream to the origin server.

  • If the maximum bandwidth is not specified, Media Live will pull the media stream with the largest BANDWIDTH value from the URL, and push the stream to the origin server.

ip_port_mode

Boolean

When the stream push protocol is SRT_PUSH and streams are pushed to the origin server, the encoder does not support the input of streamid. In this case, set this parameter to true.

ip_whitelist

String

IP address whitelist of the customer for SRT_PUSH

scte35_source

String

SCTE-35 signal source of an advertisement.

Only HLS_PULL channels support this configuration. Currently, this field can only be set to SEGMENTS.

ad_triggers

Array of strings

Configures an ad trigger.

Options:

  • Splice insert

  • Provider advertisement

  • Distributor advertisement

  • Provider placement opportunity

  • Distributor placement opportunity

audio_selectors

Array of InputAudioSelector objects

Configures an audio selector (a maximum of 8).

Table 7 SourcesInfo

Parameter

Type

Description

url

String

Channel source stream URL, which is used for external stream pull.

bitrate

Integer

Bitrate. This parameter is mandatory when live transcoding is not required.

Unit: bit/s. Value range: (0, 104,857,600] (100 Mbit/s)

width

Integer

Width corresponding to the resolution. This parameter is optional.

Value range: 0–4096 (4K)

height

Integer

Height corresponding to the resolution. This parameter is optional.

Value range: 0–2160 (4K)

enable_snapshot

Boolean

Whether to use the stream for snapshot capturing.

bitrate_for3u8

Boolean

Whether to use bitrate to fix the bitrate. Default value: false

passphrase

String

Encryption information when the protocol is SRT_PUSH.

backup_urls

Array of strings

Standby streaming URL list

stream_id

String

Stream ID of the streaming URL in an SRT_PULL channel.

latency

Integer

Stream pull latency of an SRT_PULL channel.

Table 8 SecondarySourcesInfo

Parameter

Type

Description

url

String

Channel source stream URL, which is used for external stream pull.

bitrate

Integer

Bitrate. This parameter is mandatory when live transcoding is not required.

Unit: bit/s. Value range: (0, 104,857,600] (100 Mbit/s)

width

Integer

Width corresponding to the resolution. This parameter is optional.

Value range: 0–4096 (4K)

height

Integer

Height corresponding to the resolution. This parameter is optional.

Value range: 0–2160 (4K)

bitrate_for3u8

Boolean

Whether to use bitrate to fix the bitrate. Default value: false

passphrase

String

Encryption information when the protocol is SRT_PUSH

backup_urls

Array of strings

Standby streaming URL list

stream_id

String

Stream ID of the streaming URL in an SRT_PULL channel.

latency

Integer

Stream pull latency of an SRT_PULL channel.

Table 9 FailoverConditions

Parameter

Type

Description

input_loss_threshold_msec

Integer

Duration threshold for stopping input streams. When the threshold is reached, the primary/standby switchover is automatically triggered.

Unit: millisecond. Value range: 0–3,600,000

(Optional) The default value is 2,000 ms.

input_preference

String

Whether the primary ingest URL has the highest priority (PRIMARY) or the primary and standby URLs are switched equally (EQUAL).

In the equal switchover mode, the standby URL is used and will not be automatically switched to the primary URL.

(Optional) The default value is EQUAL.

Table 10 InputAudioSelector

Parameter

Type

Description

name

String

Name of an audio selector. Enter only letters, digits, hyphens (-), and underscores (_).

The name of each selector must be unique within the same channel.

selector_settings

AudioSelectorSettings object

Configures an audio selector.

Table 11 AudioSelectorSettings

Parameter

Type

Description

audio_language_selection

AudioSelectorLangSelection object

Configures a language selector.

audio_pid_selection

AudioSelectorPidSelection object

Configures a PID selector.

audio_hls_selection

AudioSelectorHlsSelection object

Configures an HLS selector.

Table 12 AudioSelectorLangSelection

Parameter

Type

Description

language_code

String

Enter a language code of 2 or 3 lowercase letters.

language_selection_policy

String

Language output policy.

Options:

  • LOOSE: loose match. For example, if the language code eng is selected, an audio stream in English will be preferentially selected. If there is no audio stream in English, the audio stream with the lowest PID will be selected.

  • STRICT: strict match. For example, if the language code eng is selected, only an audio stream in English will be selected. If there is no audio stream in English, a muted segment will be automatically added. When this audio selector is used to play the video, the video is muted.

Table 13 AudioSelectorPidSelection

Parameter

Type

Description

pid

Integer

Sets the PID value.

Table 14 AudioSelectorHlsSelection

Parameter

Type

Description

name

String

HLS audio selector name

group_id

String

HLS audio selector GID

Table 15 encoder_settings

Parameter

Type

Description

template_id

String

Transcoding template ID.

Table 16 record_settings

Parameter

Type

Description

rollingbuffer_duration

Integer

Maximum replay recording duration. The recording is continuous in this period. This parameter is mandatory.

Unit: second. The value 0 indicates that recording is not supported. The maximum recording duration is 14 days.

Table 17 EndpointItem

Parameter

Type

Description

hls_package

Array of HlsPackageItem objects

HLS packaging information.

dash_package

Array of DashPackageItem objects

DASH packaging information.

mss_package

Array of MssPackageItem objects

MSS packaging information.

Table 18 HlsPackageItem

Parameter

Type

Description

url

String

A customized streaming URL, including the method, domain name, and path.

stream_selection

Array of StreamSelectionItem objects

Filters out a stream whose bitrate is in the range of [min, max] from all streams. If bitrate filtering is not required, you do not need to specify this parameter.

hls_version

String

HLS version number.

segment_duration_seconds

Integer

Output segment duration of a channel. This parameter is mandatory.

Unit: second. Value range: 1 to 10

NOTE:

Changing the segment duration will affect time-shifted viewing and catch-up TV of the recorded content. Exercise caution when performing this operation.

playlist_window_seconds

Integer

Total output segment duration of a channel. The value is the output segment duration multiplied by the number of segments. There are at least three returned segments.

Unit: second. Value range: 0–86,400 (value of converting 24 hours to seconds)

encryption

Encryption object

Encryption information.

ads

Object

Advertising configuration

ext_args

Object

Other additional parameters

request_args

PackageRequestArgs object

Playback configuration

ad_marker

Array of strings

Advertisement ID.

For HLS, the value is ["ENHANCED_SCTE35"].

Table 19 DashPackageItem

Parameter

Type

Description

url

String

A customized streaming URL, including the method, domain name, and path.

stream_selection

Array of StreamSelectionItem objects

Filters out a stream whose bitrate is in the range of [min, max] from all streams. If bitrate filtering is not required, you do not need to specify this parameter.

segment_duration_seconds

Integer

Output segment duration of a channel. This parameter is mandatory.

Unit: second. Value range: 1 to 10

NOTE:

Changing the segment duration will affect time-shifted viewing and catch-up TV of the recorded content. Exercise caution when performing this operation.

playlist_window_seconds

Integer

Total output segment duration of a channel. The value is the output segment duration multiplied by the number of segments. There are at least three returned segments.

Unit: second. Value range: 0–86,400 (value of converting 24 hours to seconds)

encryption

Encryption object

Encryption information.

ads

Object

Advertising configuration

ext_args

Object

Other additional parameters

request_args

PackageRequestArgs object

Playback configuration

ad_marker

String

Advertisement ID.

For DASH, the value is xml+bin.

suggested_presentation_delay

Integer

Recommended stream delay

Unit: second. Value range: 1 to 120

minimum_update_period

Integer

Shortest index update period

Unit: second. Value range: 1 to 120

min_buffer_time

Integer

Minimum buffer time

Unit: second. Value range: 1 to 120

Table 20 MssPackageItem

Parameter

Type

Description

url

String

A customized streaming URL, including the method, domain name, and path.

stream_selection

Array of StreamSelectionItem objects

Filters out a stream whose bitrate is in the range of [min, max] from all streams. If bitrate filtering is not required, you do not need to specify this parameter.

segment_duration_seconds

Integer

Output segment duration of a channel. This parameter is mandatory.

Unit: second. Value range: 1 to 10

NOTE:

Changing the segment duration will affect time-shifted viewing and catch-up TV of the recorded content. Exercise caution when performing this operation.

playlist_window_seconds

Integer

Total output segment duration of a channel. The value is the output segment duration multiplied by the number of segments. There are at least three returned segments.

Unit: second. Value range: 0–86,400 (value of converting 24 hours to seconds)

encryption

Encryption object

Encryption information.

ext_args

Object

Other additional parameters

delay_segment

Integer

Playback delay, in seconds.

request_args

PackageRequestArgs object

Playback configuration

Table 21 StreamSelectionItem

Parameter

Type

Description

key

String

Parameter used for bitrate filtering in a streaming URL.

max_bandwidth

Integer

Maximum bitrate, in bit/s.

Value range: 0-104,857,600 (100 Mbit/s)

min_bandwidth

Integer

Minimum bitrate, in bit/s.

Value range: 0-104,857,600 (100 Mbit/s)

Table 22 Encryption

Parameter

Type

Description

key_rotation_interval_seconds

Integer

Key cache time. If the key remains unchanged, the data is cached for seven days by default.

This field is reserved and cannot be configured.

encryption_method

String

Encryption mode.

This field is reserved and cannot be configured.

level

String

The options are as follows:

  • content: One channel corresponds to one key.

  • profile: One bitrate corresponds to one key.

Default value: content

resource_id

String

DRM content ID generated by the customer

system_ids

Array of strings

Enumerated value of system_id.

Options:

HLS: FairPlay

DASH: Widevine, PlayReady

MSS: PlayReady

url

String

DRM address for obtaining a key

speke_version

String

DRM SPEKE version. Currently, only version 1.0 is supported.

request_mode

String

Request mode.

Options:

direct_http: accessing the DRM using HTTP(S)

functiongraph_proxy: accessing the DRM using a FunctionGraph proxy

http_headers

Array of HttpHeader objects

Authentication information to be added to the DRM request header. A maximum of five items can be added.

Only the direct_http request mode allows configuring http_headers.

urn

String

The functiongraph_proxy request mode requires the URN of FunctionGraph.

Table 23 HttpHeader

Parameter

Type

Description

key

String

key field name in the request header

value

String

value corresponding to the key in the request header

Table 24 PackageRequestArgs

Parameter

Type

Description

record

Array of RecordRequestArgs objects

Recording configuration

timeshift

Array of TimeshiftRequestArgs objects

Time shifting configuration

live

Array of LiveRequestArgs objects

Livestreaming configuration

Table 25 RecordRequestArgs

Parameter

Type

Description

start_time

String

Start time

end_time

String

End time

format

String

Format

unit

String

Unit

Table 26 TimeshiftRequestArgs

Parameter

Type

Description

back_time

String

Time shifting duration field name

unit

String

Unit

Table 27 LiveRequestArgs

Parameter

Type

Description

delay

String

Delay field

unit

String

Unit

Table 28 EncoderSettingsExpand

Parameter

Type

Description

audio_descriptions

Array of audio_descriptions objects

Description of an audio output setting

Table 29 audio_descriptions

Parameter

Type

Description

name

String

Name of an audio output setting. Enter only letters, digits, hyphens (-), and underscores (_).

Names of audio output settings in the same channel must be different.

audio_selector_name

String

Audio selector name

language_code_control

String

Language code control. The setting will change only the audio's language displayed externally, not its actual language.

Options:

  • FOLLOW_INPUT: If the output audio of the selected audio selector has a language, this language will be used. Otherwise, the language code and stream name specified here will be used. The default value is recommended.

  • USE_CONFIGURED: The language and stream name of the output audio can be customized.

language_code

String

Language code, which consists of 2 or 3 lowercase letters.

stream_name

String

Stream name

Status code: 400

Table 30 Response body parameters

Parameter

Type

Description

result_code

String

Error code.

result_msg

String

Error description.

domain

String

Ingest domain name.

app_name

String

Group name or application name. This parameter is mandatory.

id

String

Unique ID of a channel. This parameter is mandatory.

Example Requests

GET https://{endpoint}/v1/{project_id}/ott/channels?app_name=ott&domain=push.testott.hls.com&id=test

Example Responses

Status code: 200

Demo Information

{
  "total" : 1,
  "channels" : [ {
    "domain" : "push.testott.hls.com",
    "app_name" : "ott",
    "id" : "test",
    "name" : "testname",
    "input" : {
      "input_protocol" : "RTMP_PUSH",
      "sources" : [ {
        "url" : "rtmp://push.testott.hls.com/ott/test_1024?request_source=ott&channel_id=test",
        "bitrate" : 1024,
        "width" : 100,
        "height" : 100
      } ],
      "failover_conditions" : {
        "input_loss_threshold_msec" : 100,
        "input_preference" : "EQUAL"
      }
    },
    "record_settings" : {
      "rollingbuffer_duration" : 86400
    },
    "endpoints" : [ {
      "hls_package" : [ {
        "url" : "pull.testott.hls.com/ott/test/index.m3u8",
        "stream_selection" : [ {
          "key" : "sss",
          "max_bandwidth" : 0,
          "min_bandwidth" : 0
        } ],
        "segment_duration_seconds" : 4,
        "playlist_window_seconds" : 3600,
        "request_args" : {
          "record" : [ {
            "start_time" : "begin",
            "end_time" : "end",
            "format" : "timestamp",
            "unit" : "second"
          } ],
          "timeshift" : [ {
            "back_time" : "begin",
            "unit" : "second"
          } ],
          "live" : null
        },
        "hls_version" : "1"
      } ],
      "dash_package" : [ {
        "url" : "pull.testott.hls.com/ott/test/index.mpd",
        "stream_selection" : [ {
          "key" : "bitrate=900000-1800000",
          "max_bandwidth" : 1800000,
          "min_bandwidth" : 900000
        } ],
        "segment_duration_seconds" : 4,
        "playlist_window_seconds" : 3600,
        "request_args" : {
          "record" : [ {
            "start_time" : "begin",
            "end_time" : "end",
            "format" : "timestamp",
            "unit" : "second"
          } ],
          "timeshift" : [ {
            "back_time" : "begin",
            "unit" : "second"
          } ],
          "live" : null
        }
      } ],
      "mss_package" : [ {
        "url" : "pull.testott.hls.com/ott/channel/manifest",
        "stream_selection" : [ {
          "key" : "bitrate=900000-1800000",
          "max_bandwidth" : 1800000,
          "min_bandwidth" : 900000
        } ],
        "segment_duration_seconds" : 4,
        "playlist_window_seconds" : 3600,
        "request_args" : {
          "record" : [ {
            "start_time" : "begin",
            "end_time" : "end",
            "format" : "timestamp",
            "unit" : "second"
          } ],
          "timeshift" : [ {
            "back_time" : "begin",
            "unit" : "second"
          } ],
          "live" : null
        }
      } ]
    } ],
    "state" : "OFF"
  } ]
}

Status code: 400

Error response

{
  "result_code" : "LIVE.103011019",
  "result_msg" : "The resource to access is not exists",
  "domain" : "push.testott.hls.com",
  "app_name" : "ott",
  "id" : "agbc"
}

Status Codes

Status Code

Description

200

Demo Information

400

Error response

Error Codes

See Error Codes.