Channel

In Azure Media Services (AMS), the Channel entity represents a pipeline for processing live streaming content. A Channel receives live input streams in one of two ways:

• An on-premises live encoder sends multi-bitrate RTMP or Smooth Streaming (Fragmented MP4) to the Channel. You can use the following live encoders that output multi-bitrate Smooth Streaming: MediaExcel, Imagine Communications, Ateme, Envivio, Cisco and Elemental. The following live encoders output RTMP: Adobe Flash Live Encoder, Haivision, Telestream Wirecast, Teradek and Tricaster encoders. The ingested streams pass through Channels without any further processing. When requested, Media Services delivers the stream to customers.

• A single bitrate stream (in one of the following formats: RTP (MPEG-TS), RTMP, or Smooth Streaming (Fragmented MP4)) is sent to the Channel that is enabled to perform live encoding with Media Services. The Channel then performs live encoding of the incoming single bitrate stream to a multi-bitrate (adaptive) video stream. When requested, Media Services delivers the stream to customers.

Starting with the Media Services 2.10 release, when you create a Channel, you can specify in which way you want for your channel to receive the input stream and whether or not you want for the channel to perform live encoding of your stream. You have two options:

• None – Specify this value, if you plan to use an on-premises live encoder which will output multi-bitrate stream. In this case, the incoming stream passed through to the output without any encoding. This is the behavior of a Channel prior to 2.10 release. For more detailed information about working with channels of this type, see Working with Channels that Receive Multi-bitrate Live Stream from On-premises Encoders.

• Standard – If you plan to use Media Services to encode your single bitrate live stream to multi-bitrate stream, choose this value.

  Note

  Be aware that there is a billing impact for live encoding and you should remember that leaving a live encoding channel in the "Running" state will incur billing charges. It is recommended that you immediately stop your running channels after your live streaming event is complete to avoid extra hourly charges. For more information, see Working with Channels that are Enabled to Perform Live Encoding with Azure Media Services.

For more information on Live Streaming and managing channels, see Delivering Live Streaming with Azure Media Services.

Important

When accessing entities in Media Services, you must set specific header fields and values in your HTTP requests.
For more information, see Setup for Media Services REST API Development and Connecting to Media Services with the Media Services REST API.

This topic gives an overview of the Channel entity and also demonstrates how to execute various operations with the Media Services REST API.

• Create Channels

• Start Channels

• Stop Channels

• List Channels

• Reset Channels

• Update Channels

• Start Advertisement

• End Advertisement

• Show Slate

• Hide Slate

• Delete Channels

Channel Entity

The Channel entity contains the following properties.

Property	Type	Description
Id Read-only. Set by Media Services.	Edm.String	The Channel ID, assigned upon creation. The format is: nb:chid:UUID:<GUID>.
Name	Edm.String	The Channel name. 1. Must be unique within your Media Services account. 2. Maximum length = 32 characters. 3. Cannot contain spaces. 4. Hyphens and alphanumeric characters only. 5. Cannot begin or end with a hyphen.
Created Read-only. Set by Media Services.	Edm.DateTime	A UTC date/time value that indicates the time of creation.
Description	Edm.String	User provided description. The maximum length is 256 characters.
LastModified Read-only. Set by Media Services.	Edm.DateTime	The date and time of the last update to the channel.
State Read-only. Set by Media Services.	Edm.String	The current state of channel. Possible values include: - Stopped. This is the initial state of the Channel after its creation. In this state, the Channel properties can be updated but streaming is not allowed. - Starting. Channel is being started. No updates or streaming is allowed during this state. If an error occurs, the Channel returns to the Stopped state. - Running. The Channel is capable of processing live streams. - Stopping. The channel is being stopped. No updates or streaming is allowed during this state. - Deleting. The Channel is being deleted. No updates or streaming is allowed during this state.
Input	ChannelInput ComplexType	Channel input (ingest) settings.
Output	ChannelOutput ComplexType	Channel output settings.
Preview	ChannelPreview ComplexType	Channel preview settings.
CrossSiteAccessPolicies	CrossSiteAccessPolicies	Cross site access policies.
Programs Read-only. Set by Media Services.	A collection of Programs.	A reference to the collection of programs associated with the channel.
EncodingType	Edm.String	Optional. Describes the configuration of the Channel. Allowed values are: - None – This is the default value. When you select this value, the incoming stream passed through to the output without any encoding (this is the behavior of a Channel prior to 2.10 release). - Standard – The incoming single bitrate stream is sent to the Channel and transcoded into a multi-bitrate stream using System presets
Encoding	Encoding ComplexType	Azure live encoder settings.
Slate	Slate	This setting is supported only when the Encoding Type of the Channel is set to Standard. The live encoder within the Channel can be signaled to switch to a slate image. It can also be signaled to end an on-going slate. The live encoder can be configured to switch to a slate image and mask the incoming video signal in certain situations – for example, during an ad break. If such a slate is not configured, input video is not masked during that ad break.

ChannelInput ComplexType

Name	Type	Description
KeyFrameInterval	Edm.Time	This value is ignored if EncoderType is set to Standard. When using an on-premises live encoder to generate multi-bitrate stream, the key frame interval specifies GOP duration (as used by that external encoder). Once this incoming stream is received by the Channel, you can then deliver your live stream to client playback applications in any of the following formats: Smooth Streaming, DASH and HLS. When doing live streaming, HLS is always packaged dynamically. By default, Media Services automatically calculates HLS segment packaging ratio (fragments per segment) based on the key frame interval, also referred to as Group of Pictures – GOP, that is received from the live encoder.
StreamingProtocol Read-only.	Edm.String	After you set the encoder type, you can set an ingest protocol. If the Encoder Type is set to None, valid options are: - Multi-bitrate Fragmented MP4 (Smooth Streaming) - Multi-bitrate RTMP When your Encoder Type is set to None, it is valid, but undesirable, for a single bitrate RTMP or Smooth Streaming live stream to be sent. The channel does not do any processing with the stream, so it will pass through, but the client applications will get a single bitrate stream. If the Encoder Type is set to Standard, valid options are: 1. Single bitrate Fragmented MP4 (Smooth Streaming) 2. Single bitrate RTMP 3. RTP (MPEG-TS): MPEG-2 Transport Stream over RTP.
AccessControl	ChannelInputAccessControl ComplexType	Channel input access control settings.
Endpoints Read-only.	ChannelEndpoint ComplexType	Channel input endpoints. A Channel provides input endpoints (ingest URLs) that you then use to ingest your live stream. The channel receives live input streams and makes the output streams available for streaming through one or more streaming endpoints.

ChannelPreview ComplexType

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
AccessControl	ChannelPreviewAccessControl ComplexType	Channel preview access control settings.
Endpoints Read-only.	ChannelEndpoint ComplexType	Channel preview endpoints.

ChannelInputAccessControl ComplexType

Name	Type	Description
IP	IPAccessControl	IP addresses that are allowed to connect to channel input endpoints. IP addresses have to be in one of the following formats: IpV4 address with 4 numbers, CIDR address range.

ChannelPreviewAccessControl ComplexType

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
IP	IPAccessControl	IP addresses that are allowed to connect to channel input endpoints. IP addresses have to be in one of the following formats: IpV4 address with 4 numbers, CIDR address range

IPAccessControl

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
Allow	IPRange ComplexType	IP addresses that are allowed to connect to channel input endpoints. Note: Setting this value to null allows all IP source addresses to connect. Setting it to an empty string (“”) allows no one to connect.

IPRange ComplexType

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
Name	Edm.String	A friendly name for this IP Range.
Address	Edm.String	The base IP address for the subnet representation (for example:192.168.0.1).
SubnetPrefixLength	Edm.Int32	The number of significant bits for the subnet mask (for example, in the following IP address 192.168.0.1/24, 24 represents the number of significant bits).

ChannelEndpoint ComplexType

Name	Type	Description
Protocol	Edm.String	The channel streaming endpoint protocol.
Url	Edm.String	The channel streaming endpoint URL.

ChannelOutput ComplexType

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding

Name	Type	Description
Hls	ChannelOutputHls ComplexType	The HLS specific settings.

ChannelOutputHls ComplexType

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
FragmentsPerSegment	Edm.Int16	The amount of fragments per HTTP Live Streaming (HLS) segment.

Encoding ComplexType

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
AdMarkerSource	Edm.String	You can specify the source for ad markers signals. Default value is Api, which indicates that the live encoder within the Channel should listen to an asynchronous Ad Marker API.The other valid option is Scte35 (allowed only if the ingest streaming protocol is set to RTP (MPEG-TS). When Scte35 is specified, the encoder will parse SCTE-35 signals from the input RTP (MPEG-TS) stream.
IgnoreCea708ClosedCaptions	Edm.bool	Optional. An optional flag which tells the live encoder to ignore any CEA 708 captions data embedded in the incoming video. When the flag is set to false (default), the encoder will detect and re-insert CEA 708 data into the output video streams.
VideoStream	VideoStream	Optional. Describes the input video stream. If this field is not specified, the default value is used. This setting is allowed only if the input streaming protocol is set to RTP (MPEG-TS).
AudioStreams	AudioStreams	Optional. Describes the input audio streams. If this field is not specified, the default values specified apply. This setting is allowed only if the input streaming protocol is set to RTP (MPEG-TS).
SystemPreset	Edm.String	Specifies the encoder preset to be used for this Channel. Currently, the only allowed value is Default720p (default). For more details see SystemPreset

SystemPreset

Default720p specifies to encode the video to the following 6 layers.

BitRate	Width	Height	MaxFPS	Profile	Output Stream Name
3500	1280	720	30	High	Video_1280x720_3500kbps
2200	960	540	30	High	Video_960x540_2200kbps
1350	704	396	30	High	Video_704x396_1350kbps
850	512	288	30	High	Video_512x288_850kbps
550	384	216	30	High	Video_384x216_550kbps
200	340	192	30	High	Video_340x192_200kbps

Audio is encoded to stereo AAC-LC at 64 kbps, sampling rate of 44.1 kHz.

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

VideoStream

Describes the input video stream. If this field is not specified, the default value is used. This setting is allowed only if the input streaming protocol is set to RTP (MPEG-TS).

Name	Type	Description
Index	Edm.Int1	A zero-based index that specifies which input video stream should be processed by the live encoder within the Channel. This setting applies only if ingest streaming protocol is RTP (MPEG-TS). Default value is zero. It is recommended to send in a single program transport stream (SPTS). If the input stream contains multiple programs, the live encoder parses the Program Map Table (PMT) in the input, identifies the inputs that have a stream type name of MPEG-2 Video or H.264, and arranges them in the order specified in the PMT. The zero-based index is then used to pick up the n-th entry in that arrangement.
Name	Edm.String	Optional. Descriptive tag for this input video stream.

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

AudioStreams

Describes the input audio streams. If this field is not specified, the default values specified apply. This setting is allowed only if the input streaming protocol is set to RTP (MPEG-TS).

Name	Type	Description
Index	Edm.Int16	It is recommended to send in a single program transport stream (SPTS). If the input stream contains multiple programs, the live encoder within the Channel parses the Program Map Table (PMT) in the input, identifies the inputs that have a stream type name of MPEG-2 AAC ADTS or AC-3 System-A or AC-3 System-B or MPEG-2 Private PES or MPEG-1 Audio or MPEG-2 Audio, and arranges them in the order specified in the PMT. The zero-based index is then used to pick up the n-th entry in that arrangement.
Name	Edm.String	Optional. Descriptive tag for this input audio stream.
Language	Edm.String	Optional. The language identifier of the audio stream, conforming to ISO 639-2, such as ENG. If not present, the default is UND (undefined). There can be up to 8 audio stream sets specified if the input to the Channel is MPEG-2 TS over RTP. However, there can be no two entries with the same value of Index.

There can be up to 8 {Index, Name, Language} sets specified if the input to the encoder is MPEG-2 TS over RTP. However, there can be no two entries with the same value of Index. If the input to the encoder is RTMP or HTTP (Smooth Streaming), then there can only be one audio stream in the input.

Slate

This setting is supported only when the Encoding Type of the Channel is set to Standard.

The live encoder within the Channel can be signaled to switch to a slate image. It can also be signaled to end an on-going slate.

The live encoder can be configured to switch to a slate image and mask the incoming video signal in certain situations – for example, during an ad break. If such a slate is not configured, input video is not masked during that ad break.

Name	Type	Description
InsertSlateOnAdMarker	Edm.Bool	When set to True, this setting configures the live encoder to insert a slate image during an ad break. The default value is true.
DefaultSlateAssetId	Edm.String	Optional. Specifies the Asset ID of the Media Services Asset which contains the slate image. Default is null. Before creating the Channel, the slate image, of 1920x1080 maximum resolution, in JPEG format, and at most 3 Mbytes in size, should be uploaded as a dedicated asset (no other files should be in this asset). The file name should have a *.jpg extension, and this AssetFile should be marked as the primary file for that asset. This Asset cannot be storage encrypted. If the default slate Asset ID is not specified, and insert slate on ad marker is set to true, a default Azure Media Services image will be used to mask the input stream.

For more detailed information about this type and its properties, see Overview of Channels that are enabled for Live Encoding.

Create Channels

Channels can be created using a POST HTTP request and specifying property values.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

The following request body shows how to create a channel that is enabled for live encoding.

{  
   "Id":null,  
   "Name":"testchannel001",     
   "Description":"",  
   "EncoderType":"Standard",  
   "Created":"0001-01-01T00:00:00",  
   "LastModified":"0001-01-01T00:00:00",  
   "State":null,  
   "Input":  
   {  
      "StreamingProtocol":"RTPMPEG2TS",  
      "AccessControl":  
      {  
         "IP":  
         {  
         "Allow":  
            [  
               {  
                  "Name":"testName1",  
                  "Address":"1.1.1.1",  
                  "SubnetPrefixLength":24  
               }  
            ]  
         }  
      },  
      "Endpoints":[]  
   },  
   "Encoding":  
   {  
      "SystemPreset":"Default720p",  
      "IgnoreCea708ClosedCaptions": false,  
      "AdMarkerSource": "Api",
      "VideoStream":  
      {  
         "Index":1,  
         "Name":"Video stream"  
      },  
      "AudioStreams":  
      [  
         {  
            "Index":0,  
            "Name":"English audio stream",  
            "Language":"ENG"  
         },  
         {  
            "Index":1,  
            "Name":"Spanish audio stream",  
            "Language":"SPA"  
         }  
      ]  
   },  
   "EncodingType": "Standard",  
   "Slate":  
   {  
      "InsertOnAdMarker":true,  
      "DefaultSlateAssetId": "nb:cid:UUID:01234567-0123-0123-0123-01234567"  
   },  
   "Preview":  
   {  
      "AccessControl":  
      {  
         "IP":  
         {  
            "Allow":  
            [  
               {  
                  "Name":"testName1",  
                  "Address":"1.1.1.1",  
                  "SubnetPrefixLength":24  
               }  
            ]  
         }  
      },  
      "Endpoints":[]  
   }  
}  
  

The following request body shows how to create a channel in the account that is not enabled for live encoding.

{  
"Id":null,  
"Name":"testchannel001",  
"Description":"",  
"Created":"0001-01-01T00:00:00",  
"LastModified":"0001-01-01T00:00:00",  
"State":null,  
"Input":  
   {  
   "KeyFrameInterval":null,  
   "StreamingProtocol":"FragmentedMP4",  
   "AccessControl":  
      {  
         "IP":  
         {  
            "Allow":[{"Name":"testName1","Address":"1.1.1.1","SubnetPrefixLength":24}]  
         }  
      },  
   "Endpoints":[]  
   },  
"Preview":  
   {  
   "AccessControl":  
      {  
         "IP":  
         {  
            "Allow":[{"Name":"testName1","Address":"1.1.1.1","SubnetPrefixLength":24}]  
         }  
      },  
      "Endpoints":[]  
   },  
"Output":  
   {  
   "Hls":  
      {  
         "FragmentsPerSegment":1  
      }  
   },  
"CrossSiteAccessPolicies":  
   {  
      "ClientAccessPolicy":null,  
      "CrossDomainPolicy":null  
   }  
}  

If successful, a 202 Accepted status code is returned along with a representation of the created entity in the response body.

The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

Start Channels

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channelid’)/Start	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/Start HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

Stop Channels

A channel can be stopped only when it is in the Running state, and all programs on the channel have been stopped.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channelid’)/Stop	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/Stop HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

List Channels

Channels can be retrieved using a GET HTTP request.

Method	Request URI	HTTP Version
GET	Get all Channels: https://<accountname>.restv2.<location>.media.azure.net/api/Channels Get a specified Channel. https://<accountname>.restv2.<location>.media.azure.net/api/Channels('channelid')	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

GET https://testrest.cloudapp.net/api/Channels HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, this operation returns a 200 OK status code and a list of all of the Channels created in your Media Services account.

Reset Channels

Resets runtime Channel state maintained throughout the streaming of a live presentation and allows for the reuse of a Channel in case of presentation resets or encoder reconfiguration. Stop all Programs before calling Reset. Reset can be called on a Channel that is in the running state.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channelid’)/Reset	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/Reset HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

Update Channels

Updates properties on an existing Channel. The Channel must be in the Stopped state.

Method	Request URI	HTTP Version
PATCH/PUT/MERGE For more information about these operations, see PATCH/PUT/MERGE.	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channelid’)	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

PATCH https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393') HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

Request body:

"Encoding":{"IgnoreCea708ClosedCaptions": true}  

If the update completes synchronously, it returns a 204 No Content status code; otherwise it returns a 202 Accepted status code. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

Start Advertisement

The live encoder can be signaled to start an advertisement or commercial break using a POST HTTP request and specifying property values of the in the StartAdvertisement Entity entity in the body of the request.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channeled’)/StartAdvertisement	HTTP/1.1

For more information, see Overview of Channels that are enabled for Live Encoding.

StartAdvertisement Entity

This entity represents the start-of-advertisement API – it is an asynchronous call to the live encoder to insert an advertisement or commercial breaks in the output stream.

For more information, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
duration	Edm.Duration	The duration, in seconds, of the commercial break. This has to be a non-zero positive value in order to start the commercial break. When a commercial break is in progress, and the duration is set to zero with the CueId matching the on-going commercial break, then that break is canceled.
cueId	Edm.Int	Unique ID for the commercial break, to be used by downstream application to take appropriate action(s). Needs to be a positive integer.
showSlate	Edm.Bool	Optional. Indicates to the live encoder within the Channel that it needs to switch to the default slate image during the commercial break (and mask the incoming video feed). Default is false. The image used will be the one specified via the default slate asset ID property at the time of the channel creation.

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/StartAdvertisement HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

Body

{  
   "duration":"PT45S",  
   "cueId":"67520935",  
   "showSlate":"true"  
}  
  

If successful, a 202 Accepted status code is returned.

End Advertisement

The live encoder can be signaled to end an on-going advertisement or commercial break using a POST HTTP request.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channeled’)/EndAdvertisement	HTTP/1.1

This call should only be invoked when there is an on-going advertisement.

For more information, see Overview of Channels that are enabled for Live Encoding.

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/EndAdvertisement HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, a 202 Accepted status code is returned.

Show Slate

Indicates to the live encoder within the Channel that it needs to switch to the default slate image during the commercial break (and mask the incoming video feed). Default is false. The image used will be the one specified via the default slate asset ID property at the time of the channel creation.

Use properties of ShowSlate Entity in the body of the HTTP request.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channeled’)/ShowSlate	HTTP/1.1

For more information, see Overview of Channels that are enabled for Live Encoding.

ShowSlate Entity

For more information, see Overview of Channels that are enabled for Live Encoding.

Name	Type	Description
duration	Edm.Duration	The duration, in seconds, of the slate. This has to be a non-zero positive value in order to start the slate. If there is an on-going slate, and duration of zero is specified, then that on-going slate will be terminated.
assetId	Edm.String	Specifies the Asset ID of the Media Services Asset which contains the slate image. Before creating the Channel, the slate image, of 1920x1080 resolution, in JPEG format, and at most 3 Mbytes in size, should be uploaded as a dedicated Asset (no other files should be in this Asset). The encoder can be signaled to switch to any arbitrary slate image (and not just the one specified via the DefaultSlateAssetId property at time of creating the Channel).

If the DefaultSlateAssetId property is specified, and AssetId is not specified, then the DefaultSlateAssetId image will be used to mask the input stream. For more information, see Slate.

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/ShowSlate HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

Body

{  
   "duration":"PT45S",  
   "assetId":"nb:cid:UUID:01234567-ABCD-ABCD-EFEF-01234567"  
}  
  

If successful, a 202 Accepted status code is returned.

Hide Slate

The live encoder can be signaled to end an on-going slate using a POST HTTP request.

Method	Request URI	HTTP Version
POST	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channelid’)/HideSlate	HTTP/1.1

This call should only be invoked when there is an on-going slate.

For more information, see Overview of Channels that are enabled for Live Encoding.

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

POST https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393')/HideSlate HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

Delete Channels

Delete a channel.

Method	Request URI	HTTP Version
DELETE	https://<accountname>.restv2.<location>.media.azure.net/api/Channels(‘channelid’)	HTTP/1.1

Sample Request

You can try out the following example in the Fiddler’s Composer tab.

To get the latest x-ms-version:, see Media Services REST.

Request headers:

DELETE https://testrest.cloudapp.net/api/Channels('nb:chid:UUID:2c30f424-ab90-40c6-ba41-52a993e9d393') HTTP/1.1  
DataServiceVersion: 3.0;NetFx  
MaxDataServiceVersion: 3.0;NetFx  
Accept: application/json;odata=minimalmetadata  
Accept-Charset: UTF-8  
x-ms-version: 2.19  
Content-Type: application/json;odata=minimalmetadata  
Host: <host URI>  
User-Agent: Microsoft ADO.NET Data Services  
Authorization: Bearer <token value>  
  

If successful, a 202 Accepted status code is returned. The 202 Accepted status code indicates an asynchronous operation, in which case the operation-id header value is also provided for use in polling and tracking the status of long-running operations, such as starting or stopping a Channel. Pass the operation-id header value into the Operation Entity to retrieve the status. For more information, see Manually Polling Long-Running Operations.

See Also

Delivering Live Streaming with Azure Media Services
Program