Media Services live events

Media Services logo v3


Warning

Azure Media Services will be retired June 30th, 2024. For more information, see the AMS Retirement Guide.

Azure Media Services lets you deliver live events to your customers on the Azure cloud.

Tip

If you are migrating from Media Services v2 APIs, the live event entity replaces Channel in v2 and live output replaces program.

Live events

Live events ingest and process live video feeds. When you create a live event, an ingest endpoint is created. The ingest endpoint consumes a live signal from a remote encoder. The remote live encoder sends the feed to the input endpoint using either the RTMP or Smooth Streaming (fragmented-MP4) input protocol. For the RTMP ingest protocol, the content can be sent in the clear (rtmp://) or securely encrypted on the wire(rtmps://). For the Smooth Streaming ingest protocol, the supported URL schemes are http:// or https://.

The default allocation is 5 live events per Media Services account.

Live event types

A live event can be set to either a basic or standard pass-through or live encoding. The types are set during creation using the live event encoding type.

  • Passthrough basic: An on-premises live encoder sends a multiple bitrate stream. The basic pass-through is limited to a peak ingress of 5 Mbps, 8-hour DVR window, and live transcription is not supported.
  • Passthrough standard: An on-premises live encoder sends a multiple bitrate stream. The standard pass-through has higher ingest limits, 25-hour DVR window, and support for live transcriptions.
  • Standard: An on-premises live encoder sends a single bitrate stream to the live event and Media Services creates multiple bitrate streams. If the contribution feed is of 720p or higher resolution, the Default720p preset will encode a set of 6 resolution/bitrates pairs.
  • Premium 1080p: An on-premises live encoder sends a single bitrate stream to the live event and Media Services creates multiple bitrate streams. The Default1080p preset specifies the output set of resolution/bitrates pairs.

Note

The max framerate is 30 fps for both Standard and Premium encoding.

Pass-through live event

When using the basic or standard pass-through live event, you use your on-premises live encoder to generate a multiple bitrate video stream and send that to the live event (using RTMP or fragmented-MP4 protocol). The live event then carries through the incoming video streams without any further processing. A pass-through live event is optimized for long-running live events or 24x365 linear live streaming. When creating this type of live event, specify pass-through "basic" or "standard".

You can send the feed at resolutions up to 4K and at a frame rate of 60 frames/second, with either H.264/AVC or H.265/HEVC (Smooth ingest only) video codecs, and AAC (AAC-LC, HE-AACv1, or HE-AACv2) audio codec. For more information, see Live event types comparison.

Note

Using a pass-through method is the most economical way to do live streaming when you're doing multiple events over a long period of time, and you have already invested in on-premises encoders. See Pricing details.

Live encoding live event

When using live encoding, you configure your on-premises live encoder to send a single bitrate video to the live event (using RTMP or Fragmented-Mp4 protocol). You then set up a live event so that it encodes the incoming single bitrate stream to a multiple bitrate video stream. This makes the output available for delivery to play back devices via protocols like MPEG-DASH, HLS, and Smooth Streaming.

In this case, you can send the contribution feed only at resolutions up to 1080p resolution at a frame rate of 30 frames/second, with H.264/AVC video codec and AAC (AAC-LC, HE-AACv1, or HE-AACv2) audio codec. For more information, see Live event types comparison.

Low Latency HLS and DASH streaming options

For details on how to achieve low latency with live event encoding see the Low Latency HLS (LL-HLS) and DASH streaming options.

Live encoding output resolution and bitrates

The resolutions and bitrates in the resulting output from the live encoder is determined by the preset:

  • When you use the Standard live encoder, the Default720p preset specifies a set of six resolution/bit rate pairs, going from 720p at 3.5 Mbps down to 192p at 200 kbps.
  • When you use a Premium1080p live encoder, the Default1080p preset specifies a set of six resolution/bit rate pairs, going from 1080p at 3.5 Mbps down to 180p at 200 kbps.

For information, see System presets.

Note

If you need to customize the live encoding preset, please open a support ticket via Azure Portal. You should specify the desired table of video resolution/bitrates and audio bitrates. For video, verify that there is only one layer at 720p, and at most 6 layers for video. For audio, you can customize with the following discrete AAC audio bitrates (96k, 112k, 128k, 160k, 192k, 224k, 256k, 320k, 384k, 448k, 512k). Multiple audio tracks at different bitrates are allowed and can be included in the custom preset. Also please specify that you are requesting a custom preset in the support ticket.

See the REST API for LiveEventEncodingType or the .Net, Node.JS or Python SDKs. Additionally, you can try the Live Event sample code.

Live event options

When creating a live event, you can specify the following options:

  • Name and description.
  • For Standard and Premium encoding, you can choose the stretch mode of the encoded video:
    • None: Strictly respects the output resolution specified in the encoding preset without considering the pixel aspect ratio or display aspect ratio of the input video.
    • AutoSize: Overrides the output resolution and changes it to match the display aspect ratio of the input, without padding. For example, if the input is 1920x1080 and the encoding preset asks for 1280x1280, then the value in the preset is overridden, and the output will be at 1280x720, which maintains the input aspect ratio of 16:9.
    • AutoFit: Pads the output (with either letterbox or pillar box) to honor the output resolution, while ensuring that the active video region in the output has the same aspect ratio as the input. For example, if the input is 1920x1080 and the encoding preset asks for 1280x1280, then the output will be at 1280x1280, which contains an inner rectangle of 1280x720 at aspect ratio of 16:9, with pillar box regions 280 pixels wide at the left and right.
  • Streaming protocol RTMP or Smooth streaming. Note: You can't change the protocol option while the live event or its associated live outputs are running. If you require different protocols, create a separate live event for each streaming protocol.
  • Input ID which is a globally unique identifier for the live event input stream.
  • Static hostname prefix which includes none (in which case a random 128 bit hex string will be used), Use live event name, or Use custom name. When you choose to use a customer name, this value is the Custom hostname prefix.
  • Input key frame interval, which is the duration (in seconds) of each media segment in the HLS output. The value should be a non-zero integer in the range of 0.5 to 20 seconds. The value defaults to 2 seconds if neither of the input or output key frame intervals are set. The key frame interval is only allowed on pass-through events.
  • Autostart. When autostart is set to true, the live event will be started after creation. The billing starts as soon as the live event starts running. You must explicitly stop the live event to halt further billing. Alternatively, you can start the event when you're ready to start streaming.
  • IP restrictions on the ingest and preview. You can define the IP addresses that are allowed to ingest a video to this live event. Allowed IP addresses can be specified as either a single IP address (for example '10.0.0.1'), an IP range using an IP address and a CIDR subnet mask (for example, '10.0.0.1/22'), or an IP range using an IP address and a dotted decimal subnet mask (for example, '10.0.0.1(255.255.252.0)').
    • If no IP addresses are specified and there's no rule definition, then no IP address will be allowed. To allow any IP address, create a rule and set 0.0.0.0/0. The IP addresses have to be in one of the following formats: IpV4 or IPv6 addresses with four numbers or CIDR address range. For more information about using IPv4 or IPv6, see Restrict access to DRM license and AES key delivery using IP allowlists.
    • If you want to enable certain IPs on your own firewalls or want to constrain inputs to your live events to Azure IP addresses, download a JSON file from Azure Datacenter IP address ranges. For details about this file, select the Details section on the page.
  • Live transcription which is disabled by default. For more information about live transcription read Live transcription.

StandBy mode

When you create a live event, you can set it to StandBy mode. While the event is in StandBy mode, you can edit the description and the static hostname prefix as well as restrict input and preview access settings. StandBy mode is still a billable mode, but is priced differently than when you start a live stream.

For more information, see Live event states and billing.

Live outputs

Once you have set up a stream from an on-premises encoder to a live event, you can begin the streaming event by creating an Asset, live output, and Streaming Locator. Live output will archive the stream and make it available to viewers through the Streaming Endpoint.

Live event output questions

See the live event questions in the FAQ. For information on live event quotas, see quotas and limits

More details about setting up live events

Naming rules

  • Max live event name is 32 characters.
  • The name should follow this regex pattern: ^[a-zA-Z0-9]+(-*[a-zA-Z0-9])*$.

Also see Streaming Endpoints naming conventions.

Tip

To guarantee uniqueness of your live event name, you can generate a GUID then remove all the hyphens and curly brackets (if any). The string will be unique across all live events and its length is guaranteed to be 32.

Live event ingest URLs

Once the live event is created, you can get ingest URLs that you'll provide to the live on-premises encoder. The live encoder uses these URLs to input a live stream. For more information, see Recommended on-premises live encoders.

Note

As of the 2020-05-01 API release, "vanity" URLs are known as Static Host Names (useStaticHostname: true)

Note

For an ingest URL to be static and predictable for use in a hardware encoder setup, set the useStaticHostname property to true and set the accessToken property to the same GUID on each creation.

  • Non static hostname

    A non static hostname is the default mode in Media Services v3 when creating a LiveEvent. You can get the live event allocated slightly more quickly, but the ingest URL that you would need for your live encoding hardware or software will be randomized . The URL will change if you do stop/start the live event. Non static hostnames are only useful in scenarios where an end user wants to stream using an app that needs to get a live event very quickly and having a dynamic ingest URL isn't a problem.

    If a client app doesn't need to pre-generate an ingest URL before the live event is created, let Media Services auto-generate the Access Token for the live event.

  • Static Hostnames

    Static hostname mode is preferred by most operators that wish to pre-configure their live encoding hardware or software with an RTMP ingest URL that never changes on creation or stop/start of a specific live event. These operators want a predictive RTMP ingest URL which doesn't change over time. This is also very useful when you need to push a static RTMP ingest URL into the configuration settings of a hardware encoding device like the BlackMagic Atem Mini Pro, or similar hardware encoding and production tools.

    Note

    In the Azure portal, the static hostname URL is called "Static hostname prefix".

    To specify this mode in the API, set useStaticHostName to true at creation time (default is false). When useStaticHostname is set to true, the hostnamePrefix specifies the first part of the hostname assigned to the live event preview and ingest endpoints. The final hostname would be a combination of this prefix, the media service account name and a short code for the Azure Media Services data center.

    To avoid a random token in the URL, you also need to pass your own access token (LiveEventInput.accessToken) at creation time. The access token has to be a valid GUID string (with or without the hyphens). Once the mode is set, it can't be updated.

    The access token must be unique for the Azure region and for the Media Services account. If your app needs to use a static hostname ingest URL, you are encouraged to always create fresh GUID instance for use with a specific combination of region, media services account, and live event.

    Use the following APIs to enable the static hostname URL and set the access token to a valid GUID (for example, "accessToken": "1fce2e4b-fb15-4718-8adc-68c6eb4c26a7").

    Language Enable static hostname URL Set access token
    REST properties.useStaticHostname LiveEventInput.useStaticHostname
    CLI --use-static-hostname --access-token
    .NET LiveEvent.useStaticHostname LiveEventInput.AccessToken

Live ingest URL naming rules

  • The random string below is a 128-bit hex number (which is composed of 32 characters of 0-9 a-f).
  • your access token: The valid GUID string you set when using the static hostname setting. For example, "1fce2e4b-fb15-4718-8adc-68c6eb4c26a7".
  • stream name: Indicates the stream name for a specific connection. The stream name value is usually added by the live encoder you use. You can configure the live encoder to use any name to describe the connection, for example: "video1_audio1", "video2_audio1", "stream".

Warning

If you use any special characters or spaces in the name of your stream, your live ingest will fail. See Media Services resource naming conventions in the developer concepts overview.

Non-static hostname ingest URL

RTMP

rtmp://<random 128bit hex string>.channel.media.chinacloudapi.cn:1935/live/<auto-generated access token>/<stream name>
rtmp://<random 128bit hex string>.channel.media.chinacloudapi.cn:1936/live/<auto-generated access token>/<stream name>
rtmps://<random 128bit hex string>.channel.media.chinacloudapi.cn:2935/live/<auto-generated access token>/<stream name>
rtmps://<random 128bit hex string>.channel.media.chinacloudapi.cn:2936/live/<auto-generated access token>/<stream name>

Smooth streaming

http://<random 128bit hex string>.channel.media.chinacloudapi.cn/<auto-generated access token>/ingest.isml/streams(<stream name>)
https://<random 128bit hex string>.channel.media.chinacloudapi.cn/<auto-generated access token>/ingest.isml/streams(<stream name>)

Static hostname ingest URL

In the following paths, <live-event-name> means either the name given to the event or the custom name used in the creation of the live event.

RTMP

rtmp://<live event name>-<ams account name>-<region abbrev name>.channel.media.chinacloudapi.cn:1935/live/<your access token>/<stream name>
rtmp://<live event name>-<ams account name>-<region abbrev name>.channel.media.chinacloudapi.cn:1936/live/<your access token>/<stream name>
rtmps://<live event name>-<ams account name>-<region abbrev name>.channel.media.chinacloudapi.cn:2935/live/<your access token>/<stream name>
rtmps://<live event name>-<ams account name>-<region abbrev name>.channel.media.chinacloudapi.cn:2936/live/<your access token>/<stream name>

Smooth streaming

http://<live event name>-<ams account name>-<region abbrev name>.channel.media.chinacloudapi.cn/<your access token>/ingest.isml/streams(<stream name>)
https://<live event name>-<ams account name>-<region abbrev name>.channel.media.chinacloudapi.cn/<your access token>/ingest.isml/streams(<stream name>)

Live event preview URL

Once the live event starts receiving the contribution feed, you can use its preview endpoint to preview and validate that you're receiving the live stream before further publishing. After you've checked that the preview stream is good, you can use the live event to make the live stream available for delivery through one or more (pre-created) Streaming Endpoints. To accomplish this, create a new live output on the live event.

Important

Make sure that the video is flowing to the preview URL before continuing!

Live event long-running operations

For details, see long-running operations.