Common questions about Azure Media Services

See the Azure Media Services retirement guide

Here's a listing:

• OpenAPI Specification (Swagger)
• Azure CLI
• .NET
• Java
• Python
• Node.js
• Go

We don't recommend that you try to wrap the REST API for Media Services directly into your own library code. Doing so properly for production purposes would require you to implement the full Azure Resource Manager retry logic and understand how to manage long-running operations in Resource Manager APIs. The client SDKs for various languages - for example, .NET, Java, TypeScript, Python, and Ruby - handle this for you automatically, to reduce the chances of problems with retry logic or failed API calls.

See the samples pages. There are samples for Accounts, Assets, Live Streaming, VOD Streaming, Content Protection, Encoding, Analytics, and using Players.

When you're using pagination, you should always use the next link to enumerate the collection and not depend on a particular page size. For details and examples, see Filtering, ordering, and paging entities.

For information about using the Azure CLI to pair Media Services with Azure Key Vault to encrypt your data, see the Use a Key Vault key to encrypt data into a Media Services account tutorial.

If you want Media Services to access a storage account when the storage account is configured to block requests from unknown IP addresses, follow the steps in Access storage with a Media Services managed identity.

See Moving a Media Services account between subscriptions.

See Azure role-based access control (Azure RBAC) for Media Services accounts.

Media Services defines the following built-in roles:

• Media Services Account Administrator
• Media Services Media Operator
• Media Services Policy Administrator
• Media Services Streaming Endpoints Administrator
• Media Services Live Events Administrator

These roles are detailed in Azure role-based access control (Azure RBAC) for Media Services accounts.

These roles can be used to give fine-grained access to a Media Services account. To allow all access to a Media Services account, the “Owner” or “Contributor” role can be used. Media Services has an older API on the deprecation path that does not support fine-grained access control. Customers who require fine-grained access control should not select “Enable classic APIs” when creating a Media Services account using the portal (or use the 2020-05-01 API version if they are using the API to create accounts).

The following built-in Azure Policy can be used to block the creation of accounts that support the old API: Azure Media Services accounts that allow access to the legacy v2 API should be blocked - Microsoft Azure

A Media Services asset is an Azure Storage account container that's used for each video file that you upload. It has a unique identifier that's used with transforms and other operations. See Assets in Azure Media Services v3.

Every time you want to upload a media file and do something with it, like encoding or streaming, you create an asset to store the media file and associated files. Assets are automatically created for you if you use the Azure portal. If you're not using the portal to upload files, you must create an asset first.

The common encoding formats are available with Media Services Standard Encoder. For a list of all formats, see Standard Encoder formats and codecs.

You can create a job in the Azure portal by using the Azure CLI, REST, or any of the SDKs. See the Media Services samples for the language that you prefer.

Yes. See Encode with an auto-generated bitrate ladder.

Yes. Media Services can perform a two-pass analysis on a video. It can then recommend the best adaptive bitrate set, resolutions, and encoding settings based on contents of the video.

Yes. For details and links to a sample application that shows how to upload a single-bitrate MP4 file that's pre-encoded and generate the server manifest (.ism) and client manifest (.ismc), see the answer to the question "Can I stream existing MP4 files that are pre-encoded or encoded in another solution?" in the section about packaging and delivery. That answer also describes the performance impact on the origin.

We don't recommend it. Very short content that's less than a minute or two in duration is not ideal for adaptive bitrate streaming. If you intend to stream very short-form files, we recommend that you pre-encode the content into a format that's easily streamed using a single bitrate.

Because most adaptive bitrate players need time to buffer multiple segments of video, as well as time to analyze the network bandwidth before "shifting" up or down the adaptive bitrate ladder, it's often useless to provide a lot of bitrates for content that's under 30 seconds long. By the time the player locks its heuristic algorithm on the right bitrate to play based on network conditions, the file will be done streaming.

In addition, some players default to buffering up to three segments of video. Each segment can be two to six seconds long. For very short-format videos, the player is likely to buffer and begin playback of the first selected bitrate of the adaptive bitrate set. For this reason, we recommend using a single-bitrate MP4 file, and uploading it to an asset if you need HLS or DASH manifest generation. For details on how to achieve this, see the answer to the question "Can I stream existing MP4 files that are pre-encoded or encoded in another solution?" in the section about packaging and delivery.

It's necessary to deliver the files in HLS or DASH format only if you want to benefit from the capabilities of those protocols. For single-bitrate streams, they can still offer a lot - such as faster seeking, digital rights management (DRM) support, and increased difficulty to download via URL (but still possible!) than a progressive download MP4 in blob storage. Caption support for VTT and IMSC1 is another benefit. In addition, the ability to late bind additional audio renditions, or dubbings in alternate languages, makes this a valuable choice for some situations.

If you are looking for ways to use a Media Services encoder to do things like rotate a video, subclip a video, stitch videos, create thumbnails and sprites, we have a ton of code samples on the Code Samples page. Available sample languages include Node.JS, Python, .NET, and Java.

A Media Services live event is the process of ingesting live video feeds and broadcasting them through an RTMPS protocol or Smooth Streaming. For more information, see Live events and live outputs in Media Services.

The first step is to choose an on-premises encoder. We've provided examples for creating a live event with Wirecast and OBS. If you would rather start with an overview of Media Services live events, see Live event types.

Azure Media Service delivers video, audio, and text in various protocols. When you publish your live stream by using MPEG-DASH or HLS/CMAF, then along with video and audio, the service delivers the transcribed text in IMSC1.1-compatible TTML. For more information, see Live transcription.

You can monitor live events by subscribing to Azure Event Grid events. For more information, see the Event Grid event schema. You can either:

• Subscribe to the stream-level Microsoft.Media.LiveEventEncoderDisconnected events and monitor that no reconnections come in for a while to stop and delete your live event.
• Subscribe to the track-level heartbeat events. If all tracks have an incoming bitrate dropping to 0 or the last time stamp is no longer increasing, you can safely shut down the live event. The heartbeat events come in every 20 seconds for every track, so it might be a bit verbose.

No, you can't easily use the same streaming URL if you stop and start a live event. Each time you create and publish a new live output (and asset), a new streaming URL (GUID) will be used for the new locator. That way, you're sure there won't be any cache conflict in the streaming endpoint and the content delivery network (CDN). You can prepare (and know) the streaming URLs in advance because you can force a specific GUID for the streaming locator, and then decide the manifest name to use for the live output.

Let's say that you decide to use GUID 1a7ed69e-a361-433d-8a56-29c61872744f for the live output that you'll create tomorrow. When the day comes, you start the live event and create a live output. You can decide to use "conference1" for the manifest and force the GUID for the locator.

The streaming URL is predictable and is http://<youraccountname>-<azureregion>.streaming.media.azure.net/1a7ed69e-a361-433d-8a56-29c61872744f/conference1.ism/manifest.

You can't reuse the same live output or asset multiple times. Think of the combination of the live output and asset as a tape recording. After the live output has been recorded to the asset, you can't reuse it for another recording. There will be blob conflict or overwrites if you do that again. Unless you plan to fully purge the blobs in the storage account, and purge the CDN completely, there will be problems. There will likely still be problems because the fragments are already cached downstream at the CDN or in client device caches (for example, the browser cache).

One of the most common reasons is that you don't have the streaming endpoint from which you're trying to play back in the running state.

In Media Services, a streaming endpoint represents a dynamic (just-in-time) packaging and origin service that can deliver your live and on-demand content directly to a client player app by using one of the common streaming media protocols (HLS or DASH). In addition, the streaming endpoint provides dynamic (just-in-time) encryption to industry-leading DRM systems. For more information, see Streaming endpoints (origin) in Azure Media Services.

To make videos available to clients for playback, you create a streaming locator and then build streaming URLs. Streaming locators are also used to apply streaming policies that contain rules for how the media files are consumed.

To build a streaming URL, you first create a streaming locator. You then concatenate the streaming endpoint's host name and the streaming locator's path.

Streaming policies enable you to define streaming protocols and encryption options for your streaming locators. Media Services v3 provides some predefined streaming policies. For more information, see Streaming policies.

For a list of predefined policies that you can use to get started, see Streaming policies.

Make sure you have (format=m3u8-cmaf) at the end of your path (after the /manifest portion of the URL) to tell the streaming origin server to return HLS content for consumption on Apple iOS-native devices. For details, see Delivering content.

Yes, the Media Services origin server (streaming endpoint) supports dynamic packaging of MP4 files to HLS or DASH streaming format. However, the content must be encoded in closed-GOP format, with short GOPs in the duration range of two to six seconds. We recommend the following settings: two-second GOPs, key frame maximum and minimum distance of two seconds, constant bitrate encoding (CBR mode). Most content in this format that's encoded through H.264 or HEVC video codec, along with AAC audio format, can be supported. Additional audio formats that are pre-encoded might also be supported, such as Dolby DD+.

The key to making it work is to create an asset, upload the pre-encoded assets into the asset's container by using Azure Blob Storage client SDKs, and then generate the required server manifest (.ism) and client manifest files. For details, see the .NET sample project in Stream existing MP4 files.

Keep in mind that there are performance implications when you use this approach, because the built-in encoder in Media Services also generates binary indexes (.mpi files) that improve the access time into the MP4 files. Without these files, the server can use slightly more CPU at high load. For more information, see Streaming an existing single bitrate MP4 file with HLS or Dash.

When you're scaling up with this approach, you should monitor the streaming endpoint's CPU load. If you're planning to go to production with a large library of MP4 files that are pre-encoded outside Media Services, file a support ticket to have your architecture reviewed and ask about ways to improve the origin server performance of pre-encoded MP4 content.

Streaming locators created with v2 API will continue to work after our v2 API is turned off. Once the Streaming Locator data is created in the Media Services backend database, there is no dependency on the v2 REST API for streaming. We will not remove v2 specific records from the database when v2 is turned off in February 2024.

There are some properties of assets and locators created with v2 that cannot be accessed or updated using the new v3 API. For example, v2 exposes an Asset Files API that does not have an equivalent feature in the v3 API. Often this is not a problem for most of our customers, since it is not a widely used feature and you can still stream old locators and delete them when they are no longer needed.

After migration, you should avoid making any calls to the v2 API to modify streaming locators or assets.

Dynamic encryption is securing your media from the time it leaves your computer all the way through storage, processing, and delivery. With Media Services, you can deliver your live and on-demand content encrypted dynamically with Advanced Encryption Standard (AES-128) or any of the three major DRM systems: Microsoft PlayReady, Google Widevine, and Apple FairPlay. For more information, see Protect your content with Media Services dynamic encryption.

Customers often wonder whether they should use AES encryption or a DRM system. The main difference between the two systems is that with AES encryption, the content key is transmitted to the client over TLS. The key is encrypted in transit without any additional encryption ("in the clear"). As a result, the key that's used to decrypt the content is accessible to the client player and can be viewed in a network trace on the client in plain text. AES-128 clear key encryption is suitable for use cases where the viewer is a trusted party (for example, encrypting corporate videos distributed within a company to be viewed by employees).

DRM systems like PlayReady, Widevine, and FairPlay provide an additional level of encryption on the key that's used to decrypt the content, compared to an AES-128 clear key. The content key is encrypted to a key protected by the DRM runtime in addition to any transport-level encryption that TLS provides. Decryption is handled in a secure environment at the operating system level, where it's more difficult for a malicious user to attack. We recommend DRM for use cases where the viewer might not be a trusted party and you need the highest level of security.

You don't have to use any specific token provider such as Azure Active Directory (Azure AD). You can create your own JWT provider (so-called Secure Token Service, or STS) by using asymmetric key encryption. In your custom STS, you can add claims based on your business logic.

Make sure that the issuer, audience, and claims all match up exactly between what's in JWT and the ContentKeyPolicyRestriction value used in ContentKeyPolicy.

For more information, see Protect your content by using Media Services dynamic encryption.

For production, you need to have Secure Token Service (that is, a web service), which issues a JWT token upon an HTTPS request. For test, you can use the code shown in the GetTokenAsync method defined in Program.cs.

After a user is authenticated, the player makes a request to STS for such a token and assigns it as the value of the token. You can use the Azure Media Player API.

For an example of running STS with either a symmetric key or an asymmetric key, see the JWT tool. For an example of a player based on Azure Media Player that uses such a JWT token, see the Azure media test tool. (Expand the player_settings link to see the token input.)

The correct approach is to use Secure Token Service. In STS, depending on the user profile, add different claims (such as "Premium User," "Basic User," or "Free Trial User"). With different claims in a JWT, the user can see different contents. For different contents or assets, ContentKeyPolicyRestriction will have the corresponding RequiredClaims value.

Use Azure Media Services APIs for configuring license/key delivery and encrypting your assets (as shown in this sample).

This behavior seems to be by design of the sample app. When an alternate audio track is present (which is the case for HLS) during offline mode, both iOS 10 and iOS 11 default to the alternate audio track. To compensate for this behavior in FPS offline mode, remove the alternate audio track from the stream. To do this on Media Services, add the dynamic manifest filter audio-only=false. In other words, an HLS URL ends with .ism/manifest(format=m3u8-aapl,audio-only=false).

Depending on the cache key design for the content delivery network, the content might be cached. Purge the cache.

The downloaded file structure on an iOS device looks like the following screenshot. The _keys folder stores downloaded FPS licenses, with one stored file for each license service host. The .movpkg folder stores audio and video content.

The first folder with a name that ends with a dash followed by a number contains video content. The numeric value is the peak bandwidth of the video renditions. The second folder with a name that ends with a dash followed by 0 contains audio content. The third folder named Data contains the master playlist of the FPS content. Finally, boot.xml provides a complete description of the .movpkg folder content.

Here's a sample boot.xml file:

<?xml version="1.0" encoding="UTF-8"?>
<HLSMoviePackage xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance" xmlns="http://apple.com/IMG/Schemas/HLSMoviePackage" xsi:schemaLocation="http://apple.com/IMG/Schemas/HLSMoviePackage /System/Library/Schemas/HLSMoviePackage.xsd">
  <Version>1.0</Version>
  <HLSMoviePackageType>PersistedStore</HLSMoviePackageType>
  <Streams>
    <Stream ID="1-4DTFY3A3VDRCNZ53YZ3RJ2NPG2AJHNBD-0" Path="1-4DTFY3A3VDRCNZ53YZ3RJ2NPG2AJHNBD-0" NetworkURL="https://example.streaming.mediaservices.windows.net/e7c76dbb-8e38-44b3-be8c-5c78890c4bb4/MicrosoftElite01.ism/QualityLevels(127000)/Manifest(aac_eng_2_127,format=m3u8-aapl)">
      <Complete>YES</Complete>
    </Stream>
    <Stream ID="0-HC6H5GWC5IU62P4VHE7NWNGO2SZGPKUJ-310656" Path="0-HC6H5GWC5IU62P4VHE7NWNGO2SZGPKUJ-310656" NetworkURL="https://example.streaming.mediaservices.windows.net/e7c76dbb-8e38-44b3-be8c-5c78890c4bb4/MicrosoftElite01.ism/QualityLevels(161000)/Manifest(video,format=m3u8-aapl)">
      <Complete>YES</Complete>
    </Stream>
  </Streams>
  <MasterPlaylist>
    <NetworkURL>https://example.streaming.mediaservices.windows.net/e7c76dbb-8e38-44b3-be8c-5c78890c4bb4/MicrosoftElite01.ism/manifest(format=m3u8-aapl,audio-only=false)</NetworkURL>
  </MasterPlaylist>
  <DataItems Directory="Data">
    <DataItem>
      <ID>CB50F631-8227-477A-BCEC-365BBF12BCC0</ID>
      <Category>Playlist</Category>
      <Name>master.m3u8</Name>
      <DataPath>Playlist-master.m3u8-CB50F631-8227-477A-BCEC-365BBF12BCC0.data</DataPath>
      <Role>Master</Role>
    </DataItem>
  </DataItems>
</HLSMoviePackage>

Because Media Services v3 allows an asset to have multiple StreamingLocator instances, you can have:

• One ContentKeyPolicy instance with license_type = "persistent", ContentKeyPolicyRestriction with a claim on "persistent", and its StreamingLocator instance.
• Another ContentKeyPolicy instance with license_type="nonpersistent", ContentKeyPolicyRestriction with a claim on "nonpersistent", and its StreamingLocator instance.
• Two StreamingLocator instances that have different ContentKey values.

Depending on business logic of custom STS, different claims are issued in the JWT token. With the token, only the corresponding license can be obtained and only the corresponding URL can be played.

Google's Widevine DRM Architecture Overview defines three security levels. However, the Azure Media Services documentation on the Widevine license template outlines five security levels (client robustness requirements for playback).

Google Widevine defines both sets of security levels. The difference is in usage level: architecture or API. The five security levels are used in the Widevine API. The Azure Media Services Widevine license service deserializes the content_key_specs object, which contains security_level, and passes it to the Widevine global delivery service. The following table shows the mapping between the two sets of security levels.

Use Azure Monitor to keep track of what's happening with your Media Services resources. For more information, see Monitor Media Services. How to guides are listed at the end of the page.

Use Azure Event Grid to monitor your live event without a polling service. See Create and monitor Media Services events with Event Grid using the Azure portal.

Media Services works with many players. See the list of compatible media players or try the 3rd party player samples.

For information about Media Services and high availability, see High availability with Media Services and Video on Demand (VOD).

We've created a comprehensive guide for migration from v2 to v3. We're interested in knowing about your migration experience and needs, so feel free to provide feedback via GitHub issue or support ticket.

We've documented error codes in the following references: Streaming endpoint error codes, Live event error codes, and Job error codes. If you can't find answers there, please create a support ticket.

You can reset your account credentials by using the Azure CLI.

See the Media Services pricing guide.

See Media Services quotas and limits.

Customers attach their own storage accounts to their Azure Media Services accounts. All asset data is stored in these associated storage accounts, and the customer controls the location and replication type of this storage.

Additional data associated with a Media Services account (including content encryption keys, token verification keys, JobInputHttp URLs, and other entity metadata) is stored in Microsoft-owned storage within the region selected for the Media Services account.

Due to data residency requirements in Brazil South and Southeast Asia, additional account data is stored in a zone-redundant fashion and is contained in a single region. For Southeast Asia, all the additional account data is stored in Singapore. For Brazil South, the data is stored in Brazil. In regions other than Brazil South and Southeast Asia, additional account data might also be stored in Microsoft-owned storage in the paired region.

Azure Media Services is a regional service and does not provide high availability or data replication. We encourage customers who need these features to build a solution by using Media Services accounts in multiple regions. A sample that shows how to build a solution for high availability with Media Services video on demand is available as a guide.