How to Use Media Services
This guide shows you how to start programming with Windows Azure Media Services using Java. The guide includes a technical overview of Media Services, steps to configure your Windows Azure account for Media Services, and code that shows how to accomplish typical programming tasks.
Table of Contents
What are Media Services?
Windows Azure Media Services form an extensible media platform that integrates the best of the Microsoft Media Platform and third-party media components in Windows Azure. Media Services provide a media pipeline in the cloud that enables industry partners to extend or replace component technologies. ISVs and media providers can use Media Services to build end-to-end media solutions. This overview describes the general architecture and common development scenarios for Media Services.
The following diagram illustrates the basic Media Services architecture.
Media Services Feature Support
The current release of Media Services provides the following feature set for developing media applications in the cloud.
- Ingest. Ingest operations bring assets into the system, for example by uploading them and encrypting them before they are placed into Windows Azure Storage. By the RTM release, Media Services will offer integration with partner components to provide fast UDP (User Datagram Protocol) upload solutions.
- Encode. Encode operations include encoding, transforming and converting media assets. You can run encoding tasks in the cloud using the Media Encoder that is included in Media Services. Encoding options include the following:
- Use the Windows Azure Media Encoder and work with a range of standard codecs and formats, including industry-leading IIS Smooth Streaming, MP4, and conversion to Apple HTTP Live Streaming.
- Convert entire libraries or individual files with total control over input and output.
- A large set of supported file types, formats, and codecs (see [Supported File Types for Media Services]).
- Supported format conversions. Media Services enable you to convert ISO MP4 (.mp4) to Smooth Streaming File Format (PIFF 1.3) (.ismv; .isma). You can also convert Smooth Streaming File Format (PIFF) to Apple HTTP Live Streaming (.msu8, .ts).
- Protect. Protecting content means encrypting live streaming or on demand content for secure transport, storage, and delivery. Media Services provide a DRM technology-agnostic solution for protecting content. Currently supported DRM technologies are Microsoft PlayReady Protection and MPEG Common Encryption. Support for additional DRM technologies will be available.
- Stream. Streaming content involves sending it live or on demand to clients, or you can retrieve or download specific media files from the cloud. Media Services provide a format-agnostic solution for streaming content. Media Services provide streaming origin support for Smooth Streaming, Apple HTTP Live Streaming, and MP4 formats. Support for additional formats will be available. You can also seamlessly deliver streaming content by using Windows Azure CDN or a third-party CDN, which enables the option to scale to millions of users.
Media Services Development Scenarios
Media Services support several common media development scenarios as described in the following table.
|Scenario ||Description |
|Building end-to-end workflows ||Build comprehensive media workflows entirely in the cloud. From uploading media to distributing content, Media Services provide a range of components that can be combined to handle specific application workflows. Current capabilities include upload, storage, encoding, format conversion, content protection, and on-demand streaming delivery. |
|Building hybrid workflows ||You can integrate Media Services with existing tools and processes. For example, encode content on-site then upload to Media Services for transcoding into multiple formats and deliver through Windows Azure CDN, or a third-party CDN. Media Services can be called individually via standard REST APIs for integration with external applications and services. |
|Providing cloud support for media players ||You can create, manage, and deliver media across multiple devices (including iOS, Android, and Windows devices) and platforms. |
Media Services Client Development
Extend the reach of your Media Services solution by using SDKs and player frameworks to build media client applications. These clients are for developers who want to build Media Services applications that offer compelling user experiences across a range of devices and platforms. Depending on the devices that you want to build client applications for, there are options for SDKs and player frameworks available from Microsoft and other third-party partners.
The following provides a list of available client SDKs and player frameworks. For more information on these and other planned SDKs and player frameworks, and the functionality they can support, see Media Services Client Development.
Mac and PC client support
For PCs and Macs you can target a streaming experience using Microsoft Silverlight or Adobe Open Source Media Framework.
Windows 8 applications
Xbox supports Xbox LIVE applications that can consume Smooth Streaming content. The Xbox LIVE Application Development Kit (ADK) includes:
- Smooth Streaming client for Xbox LIVE ADK
- Microsoft Media Platform: Player Framework for Xbox LIVE ADK
Embedded or dedicated devices
Devices such as connected TVs, set-top boxes, Blu-Ray players, OTT TV boxes, and mobile devices that have a custom application development framework and a custom media pipeline. Microsoft provides the following porting kits that can be licensed, and enables partners to port Smooth Streaming playback for the platform.
Microsoft provides an SDK that can be used to build premium video applications for Windows Phone.
For iOS devices including iPhone, iPod, and iPad, Microsoft ships an SDK that you can use to build applications for these platforms to deliver premium video content: Smooth Streaming SDK for iOS Devices with PlayReady. The SDK is available only to licensees, so for more information, please email Microsoft. For information on iOS development, see the iOS Developer Center.
Several Microsoft partners ship SDKs for the Android platform that add the capability to play back Smooth Streaming on an Android device. Please email Microsoft for more details on the partners.
Setting up a Windows Azure account for Media Services
To set up your Media Services account, use the Windows Azure Management Portal. See the topic How to Create a Media Services Account. After creating your account in the Management Portal, you are ready to set up your computer for Media Services development.
This section contains general prerequisites for Media Services development using the Media Services SDK for Java.
How to: Use Media Services with Java
The following code shows how to create an asset, upload a media file to the asset, run a job with a task to transform the asset, and download the output files of the transformed asset.
You'll need to set up a media services account before using this code. For information about setting up an account, see How to Create a Media Services Account.
Substitute your values for the
clientSecret variables. The code also relies on a locally stored file,
c:/media/MPEG4-H264.mp4. You'll need to provide your own file to use. The code also requires an output folder,
c:/output, which is where the output files will be downloaded.
public class HelloMediaServices
private static MediaContract mediaService;
private static AssetInfo assetToEncode, encodedAsset;
public static void main(String args)
// Set up the MediaContract object to call into the media services.
// Upload a local file to a media asset.
// Transform the asset.
// Retrieve the URL of the asset's transformed output.
// Delete all assets.
// When you want to delete the assets that have been uploaded,
// comment out the calls to Upload(), Transfer(), and Download(),
// and uncomment the following call to Cleanup().
catch (ServiceException se)
catch (Exception e)
// Initialize the server context to get programmatic access to the Media Services programming objects.
// The media services URI, OAuth URI and scope can be used exactly as shown.
// Substitute your media service account name and access key for the clientId and clientSecret variables.
// You can obtain your media service account name and access key from the Media Services section
// of the Windows Azure Management portal, https://manage.windowsazure.com.
private static void Init() throws ServiceException
String mediaServiceUri = "https://media.windows.net/API/";
String oAuthUri = "https://wamsprodglobal001acs.accesscontrol.windows.net/v2/OAuth2-13";
String clientId = "your_client_id"; // Use your media service account name.
String clientSecret = "your_client_secret"; // Use your media service access key.
String scope = "urn:WindowsAzureMediaServices";
// Specify the configuration values to use with the MediaContract object.
Configuration configuration = MediaConfiguration
.configureWithOAuthAuthentication(mediaServiceUri, oAuthUri, clientId, clientSecret, scope);
// Create the MediaContract object using the specified configuration.
mediaService = MediaService.create(configuration);
// Upload a media file to your Media Services account.
// This code creates an asset, an access policy (using Write access) and a locator,
// and uses those objects to upload a local file to the asset.
private static void Upload() throws ServiceException, FileNotFoundException, NoSuchAlgorithmException
LocatorInfo uploadLocator = null;
// Create an asset.
assetToEncode = mediaService.create(Asset.create().setName("myAsset").setAlternateId("altId"));
System.out.println("Created asset with id: " + assetToEncode.getId());
// Create an access policy that provides Write access for 15 minutes.
uploadAccessPolicy = mediaService.create(AccessPolicy.create("uploadAccessPolicy",
System.out.println("Created upload access policy with id: "
// Create a locator using the access policy and asset.
// This will provide the location information needed to add files to the asset.
uploadLocator = mediaService.create(Locator.create(uploadAccessPolicy.getId(),
System.out.println("Created upload locator with id: " + uploadLocator.getId());
// Create the blob writer using the locator.
uploader = mediaService.createBlobWriter(uploadLocator);
// The name of the file as it will exist in your Media Services account.
String fileName = "MPEG4-H264.mp4";
// The local file that will be uploaded to your Media Services account.
InputStream input = new FileInputStream(new File("c:/media/" + fileName));
// Upload the local file to the asset.
// Inform Media Services about the uploaded files.
System.out.println("Deleting upload locator and access policy.");
// Create a job that contains a task to transform the asset.
// In this example, the asset will be transformed using the Windows Azure Media Encoder.
private static void Transform() throws ServiceException, InterruptedException
// Use the Windows Azure Media Encoder, by specifying it by name.
// Retrieve the list of media processors that match this name.
ListResult<MediaProcessorInfo> mediaProcessors = mediaService
.set("$filter", "Name eq 'Windows Azure Media Encoder'"));
// Use the latest version of the media processor.
MediaProcessorInfo mediaProcessor = null;
for (MediaProcessorInfo info : mediaProcessors)
if (null == mediaProcessor || info.getVersion().compareTo(mediaProcessor.getVersion()) > 0)
mediaProcessor = info;
System.out.println("Using processor: " + mediaProcessor.getName() +
" " + mediaProcessor.getVersion());
// Create a task with the specified media processor, in this case to transform the original asset to the H264 Broadband 720p preset.
// Information on the various configurations can be found at
// This example uses only one task, but others could be added.
Task.CreateBatchOperation task = Task.create(
.setConfiguration("H264 Broadband 720p").setName("MyTask");
// Create a job creator that specifies the asset, priority and task for the job.
Job.Creator jobCreator = Job.create()
// Create the job within your Media Services account.
// Creating the job automatically schedules and runs it.
JobInfo jobInfo = mediaService.create(jobCreator);
String jobId = jobInfo.getId();
System.out.println("Created job with id: " + jobId);
// Check to see if the job has completed.
// Done with the job.
// Retrieve the output asset.
ListResult<AssetInfo> outputAssets = mediaService.list(Asset.list(jobInfo.getOutputAssetsLink()));
encodedAsset = outputAssets.get(0);
// Download the output assets of the transformed asset.
private static void Download() throws ServiceException, URISyntaxException, FileNotFoundException, StorageException, IOException
AccessPolicyInfo downloadAccessPolicy = null;
mediaService.create(AccessPolicy.create("Download", 15.0, EnumSet.of(AccessPolicyPermission.READ)));
System.out.println("Created download access policy with id: "
LocatorInfo downloadLocator = null;
downloadLocator = mediaService.create(
Locator.create(downloadAccessPolicy.getId(), encodedAsset.getId(), LocatorType.SAS));
System.out.println("Created download locator with id: " + downloadLocator.getId());
System.out.println("Accessing the output files of the encoded asset.");
// Iterate through the files associated with the encoded asset.
for(AssetFileInfo assetFile: mediaService.list(AssetFile.list(encodedAsset.getAssetFilesLink())))
String fileName = assetFile.getName();
System.out.print("Downloading file: " + fileName + ". ");
String locatorPath = downloadLocator.getPath();
int startOfSas = locatorPath.indexOf("?");
String blobPath = locatorPath + fileName;
if (startOfSas >= 0)
blobPath = locatorPath.substring(0, startOfSas) + "/" + fileName + locatorPath.substring(startOfSas);
URI baseuri = new URI(blobPath);
blobClient = new CloudBlobClient(baseuri);
// Ensure that you have a c:\output folder, or modify the path specified in the following statement.
String localFileName = "c:/output/" + fileName;
sasBlob = new CloudBlockBlob(baseuri, blobClient);
File fileTarget = new File(localFileName);
System.out.println("Deleting download locator and access policy.");
// Remove all assets from your Media Services account.
// You could instead remove assets by name or ID, etc., but for
// simplicity this example removes all of them.
private static void Cleanup() throws ServiceException
// Retrieve a list of all assets.
List<AssetInfo> assets = mediaService.list(Asset.list());
// Iterate through the list, deleting each asset.
for (AssetInfo asset: assets)
System.out.println("Deleting asset named " + asset.getName() + " (" + asset.getId() + ")");
// Helper function to check to on the status of the job.
private static void CheckJobStatus(String jobId) throws InterruptedException, ServiceException
int maxRetries = 12; // Number of times to retry. Small jobs often take 2 minutes.
JobState jobState = null;
while (maxRetries > 0)
Thread.sleep(10000); // Sleep for 10 seconds, or use another interval.
// Determine the job state.
jobState = mediaService.get(Job.get(jobId)).getState();
System.out.println("Job state is " + jobState);
if (jobState == JobState.Finished ||
jobState == JobState.Canceled ||
jobState == JobState.Error)
// The job is done.
// The job is not done. Sleep and loop if max retries
// has not been reached.
The assets that you create are stored in Windows Azure storage. However, use only the Windows Azure media services APIs (not Windows Azure storage APIs) to add, update, or delete assets.
Determining which media processors are available
The code above used a media processor by accessing it via a specific media processor name (and if there was more than one version, it would use the latest version). To determine which media processors are available, you could use the following code.
for (MediaProcessorInfo mediaProcessor: mediaService.list(MediaProcessor.list()))
System.out.print(mediaProcessor.getName() + ", ");
System.out.print(mediaProcessor.getId() + ", ");
System.out.print(mediaProcessor.getVendor() + ", ");
Alternatively, the following code shows how to retrieve the ID of a media processor by name.
String mediaProcessorName = "Storage Decryption";
operation = MediaProcessor.list();
operation.getQueryParameters().putSingle("$filter", "Name eq '" + mediaProcessorName + "'");
processor = mediaService.list(operation).get(0);
System.out.println("Processor named " + mediaProcessorName +
" has ID of " + processor.getId());
Canceling a job
Should you need to cancel a job that hasn't finished processing, the following code shows how to cancel a job by job ID.
For Media Services Javadoc documentation, see Windows Azure Libraries for Java documentation.