How to perform live streaming using Azure Media Services to create multi-bitrate streams with .NET
Note
To complete this tutorial, you need an Azure account. For details, see Azure Free Trial.
Overview
This tutorial walks you through the steps of creating a Channel that receives a single-bitrate live stream and encodes it to multi-bitrate stream.
For more conceptual information related to Channels that are enabled for live encoding, see Live streaming using Azure Media Services to create multi-bitrate streams.
Common Live Streaming Scenario
The following steps describe tasks involved in creating common live streaming applications.
Note
Currently, the max recommended duration of a live event is 8 hours. Please contact amshelp@microsoft.com if you need to run a Channel for longer periods of time.
Connect a video camera to a computer. Launch and configure an on-premises live encoder that can output a single bitrate stream in one of the following protocols: RTMP or Smooth Streaming. For more information, see Azure Media Services RTMP Support and Live Encoders.
This step could also be performed after you create your Channel.
Create and start a Channel.
Retrieve the Channel ingest URL.
The ingest URL is used by the live encoder to send the stream to the Channel.
Retrieve the Channel preview URL.
Use this URL to verify that your channel is properly receiving the live stream.
Create an asset.
If you want for the asset to be dynamically encrypted during playback, do the following:
Create a content key.
Configure the content key's authorization policy.
Configure asset delivery policy (used by dynamic packaging and dynamic encryption).
Create a program and specify to use the asset that you created.
Publish the asset associated with the program by creating an OnDemand locator.
Note
When your AMS account is created a default streaming endpoint is added to your account in the Stopped state. The streaming endpoint from which you want to stream content has to be in the Running state.
Start the program when you are ready to start streaming and archiving.
Optionally, the live encoder can be signaled to start an advertisement. The advertisement is inserted in the output stream.
Stop the program whenever you want to stop streaming and archiving the event.
Delete the Program (and optionally delete the asset).
What you'll learn
This article shows you how to execute different operations on channels and programs using Media Services .NET SDK. Because many operations are long-running .NET APIs that manage long running operations are used.
The article shows how to do the following:
- Create and start a channel. Long-running APIs are used.
- Get the channels ingest (input) endpoint. This endpoint should be provided to the encoder that can send a single bitrate live stream.
- Get the preview endpoint. This endpoint is used to preview your stream.
- Create an asset that is used to store your content. The asset delivery policies should be configured as well, as shown in this example.
- Create a program and specify to use the asset that was created earlier. Start the program. Long-running APIs are used.
- Create a locator for the asset, so the content gets published and can be streamed to your clients.
- Show and hide slates. Start and stop advertisements. Long-running APIs are used.
- Clean up your channel and all the associated resources.
Prerequisites
The following are required to complete the tutorial.
- An Azure account. If you don't have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial. You get credits that can be used to try out paid Azure services. Even after the credits are used up, you can keep the account and use free Azure services and features, such as the Web Apps feature in Azure App Service.
- A Media Services account. To create a Media Services account, see Create Account.
- Visual Studio 2010 SP1 (Professional, Premium, Ultimate, or Express) or later versions.
- You must use Media Services .NET SDK version 3.2.0.0 or newer.
- A webcam and an encoder that can send a single bitrate live stream.
Considerations
- Currently, the max recommended duration of a live event is 8 hours. Please contact amshelp@microsoft.com if you need to run a Channel for longer periods of time.
- There is a limit of 1,000,000 policies for different AMS policies (for example, for Locator policy or ContentKeyAuthorizationPolicy). You should use the same policy ID if you are always using the same days / access permissions, for example, policies for locators that are intended to remain in place for a long time (non-upload policies). For more information, see this article.
Set up for development with Media Services SDK for .NET
Set up your development environment and populate the app.config file with connection information, as described in Media Services development with .NET.
Code example
using System;
using System.Collections.Generic;
using System.Configuration;
using System.IO;
using System.Linq;
using System.Net;
using Microsoft.WindowsAzure.MediaServices.Client;
using Microsoft.WindowsAzure.MediaServices.Client.DynamicEncryption;
namespace EncodeLiveStreamWithAmsClear
{
class Program
{
private const string ChannelName = "channel001";
private const string AssetName = "asset001";
private const string ProgramName = "program001";
// Read values from the App.config file.
private static readonly string _AADTenantDomain =
ConfigurationManager.AppSettings["AMSAADTenantDomain"];
private static readonly string _RESTAPIEndpoint =
ConfigurationManager.AppSettings["AMSRESTAPIEndpoint"];
private static readonly string _AMSClientId =
ConfigurationManager.AppSettings["AMSClientId"];
private static readonly string _AMSClientSecret =
ConfigurationManager.AppSettings["AMSClientSecret"];
private static CloudMediaContext _context = null;
static void Main(string[] args)
{
AzureAdTokenCredentials tokenCredentials =
new AzureAdTokenCredentials(_AADTenantDomain,
new AzureAdClientSymmetricKey(_AMSClientId, _AMSClientSecret),
AzureEnvironments.AzureCloudEnvironment);
var tokenProvider = new AzureAdTokenProvider(tokenCredentials);
_context = new CloudMediaContext(new Uri(_RESTAPIEndpoint), tokenProvider);
IChannel channel = CreateAndStartChannel();
// The channel's input endpoint:
string ingestUrl = channel.Input.Endpoints.FirstOrDefault().Url.ToString();
Console.WriteLine("Intest URL: {0}", ingestUrl);
// Use the previewEndpoint to preview and verify
// that the input from the encoder is actually reaching the Channel.
string previewEndpoint = channel.Preview.Endpoints.FirstOrDefault().Url.ToString();
Console.WriteLine("Preview URL: {0}", previewEndpoint);
// When Live Encoding is enabled, you can now get a preview of the live feed as it reaches the Channel.
// This can be a valuable tool to check whether your live feed is actually reaching the Channel.
// The thumbnail is exposed via the same end-point as the Channel Preview URL.
string thumbnailUri = new UriBuilder
{
Scheme = Uri.UriSchemeHttps,
Host = channel.Preview.Endpoints.FirstOrDefault().Url.Host,
Path = "thumbnails/input.jpg"
}.Uri.ToString();
Console.WriteLine("Thumbain URL: {0}", thumbnailUri);
// Once you previewed your stream and verified that it is flowing into your Channel,
// you can create an event by creating an Asset, Program, and Streaming Locator.
IAsset asset = CreateAndConfigureAsset();
IProgram program = CreateAndStartProgram(channel, asset);
ILocator locator = CreateLocatorForAsset(program.Asset, program.ArchiveWindowLength);
// You can use slates and ads only if the channel type is Standard.
StartStopAdsSlates(channel);
// Once you are done streaming, clean up your resources.
Cleanup(channel);
}
public static IChannel CreateAndStartChannel()
{
var channelInput = CreateChannelInput();
var channelPreview = CreateChannelPreview();
var channelEncoding = CreateChannelEncoding();
ChannelCreationOptions options = new ChannelCreationOptions
{
EncodingType = ChannelEncodingType.Standard,
Name = ChannelName,
Input = channelInput,
Preview = channelPreview,
Encoding = channelEncoding
};
Log("Creating channel");
IOperation channelCreateOperation = _context.Channels.SendCreateOperation(options);
string channelId = TrackOperation(channelCreateOperation, "Channel create");
IChannel channel = _context.Channels.FirstOrDefault(c => c.Id == channelId);
Log("Starting channel");
var channelStartOperation = channel.SendStartOperation();
TrackOperation(channelStartOperation, "Channel start");
return channel;
}
/// <summary>
/// Create channel input, used in channel creation options.
/// </summary>
/// <returns></returns>
private static ChannelInput CreateChannelInput()
{
// When creating a Channel, you can specify allowed IP addresses in one of the following formats:
// IpV4 address with 4 numbers
// CIDR address range
return new ChannelInput
{
StreamingProtocol = StreamingProtocol.FragmentedMP4,
AccessControl = new ChannelAccessControl
{
IPAllowList = new List<IPRange>
{
new IPRange
{
Name = "TestChannelInput001",
Address = IPAddress.Parse("0.0.0.0"),
SubnetPrefixLength = 0
}
}
}
};
}
/// <summary>
/// Create channel preview, used in channel creation options.
/// </summary>
/// <returns></returns>
private static ChannelPreview CreateChannelPreview()
{
// When creating a Channel, you can specify allowed IP addresses in one of the following formats:
// IpV4 address with 4 numbers
// CIDR address range
return new ChannelPreview
{
AccessControl = new ChannelAccessControl
{
IPAllowList = new List<IPRange>
{
new IPRange
{
Name = "TestChannelPreview001",
Address = IPAddress.Parse("0.0.0.0"),
SubnetPrefixLength = 0
}
}
}
};
}
/// <summary>
/// Create channel encoding, used in channel creation options.
/// </summary>
/// <returns></returns>
private static ChannelEncoding CreateChannelEncoding()
{
return new ChannelEncoding
{
SystemPreset = "Default720p",
IgnoreCea708ClosedCaptions = false,
AdMarkerSource = AdMarkerSource.Api
};
}
/// <summary>
/// Create an asset and configure asset delivery policies.
/// </summary>
/// <returns></returns>
public static IAsset CreateAndConfigureAsset()
{
IAsset asset = _context.Assets.Create(AssetName, AssetCreationOptions.None);
IAssetDeliveryPolicy policy =
_context.AssetDeliveryPolicies.Create("Clear Policy",
AssetDeliveryPolicyType.NoDynamicEncryption,
AssetDeliveryProtocol.HLS | AssetDeliveryProtocol.SmoothStreaming | AssetDeliveryProtocol.Dash, null);
asset.DeliveryPolicies.Add(policy);
return asset;
}
/// <summary>
/// Create a Program on the Channel. You can have multiple Programs that overlap or are sequential;
/// however each Program must have a unique name within your Media Services account.
/// </summary>
/// <param name="channel"></param>
/// <param name="asset"></param>
/// <returns></returns>
public static IProgram CreateAndStartProgram(IChannel channel, IAsset asset)
{
IProgram program = channel.Programs.Create(ProgramName, TimeSpan.FromHours(3), asset.Id);
Log("Program created", program.Id);
Log("Starting program");
var programStartOperation = program.SendStartOperation();
TrackOperation(programStartOperation, "Program start");
return program;
}
/// <summary>
/// Create locators in order to be able to publish and stream the video.
/// </summary>
/// <param name="asset"></param>
/// <param name="ArchiveWindowLength"></param>
/// <returns></returns>
public static ILocator CreateLocatorForAsset(IAsset asset, TimeSpan ArchiveWindowLength)
{
// You cannot create a streaming locator using an AccessPolicy that includes write or delete permissions.
var locator = _context.Locators.CreateLocator
(
LocatorType.OnDemandOrigin,
asset,
_context.AccessPolicies.Create
(
"Live Stream Policy",
ArchiveWindowLength,
AccessPermissions.Read
)
);
return locator;
}
/// <summary>
/// Perform operations on slates.
/// </summary>
/// <param name="channel"></param>
public static void StartStopAdsSlates(IChannel channel)
{
int cueId = new Random().Next(int.MaxValue);
var path = Path.GetFullPath(Path.Combine(AppDomain.CurrentDomain.BaseDirectory, @"..\\..\\SlateJPG\\DefaultAzurePortalSlate.jpg"));
Log("Creating asset");
var slateAsset = _context.Assets.Create("Slate test asset " + DateTime.Now.ToString("yyyy-MM-dd HH-mm"), AssetCreationOptions.None);
Log("Slate asset created", slateAsset.Id);
Log("Uploading file");
var assetFile = slateAsset.AssetFiles.Create("DefaultAzurePortalSlate.jpg");
assetFile.Upload(path);
assetFile.IsPrimary = true;
assetFile.Update();
Log("Showing slate");
var showSlateOperation = channel.SendShowSlateOperation(TimeSpan.FromMinutes(1), slateAsset.Id);
TrackOperation(showSlateOperation, "Show slate");
Log("Hiding slate");
var hideSlateOperation = channel.SendHideSlateOperation();
TrackOperation(hideSlateOperation, "Hide slate");
Log("Starting ad");
var startAdOperation = channel.SendStartAdvertisementOperation(TimeSpan.FromMinutes(1), cueId, false);
TrackOperation(startAdOperation, "Start ad");
Log("Ending ad");
var endAdOperation = channel.SendEndAdvertisementOperation(cueId);
TrackOperation(endAdOperation, "End ad");
Log("Deleting slate asset");
slateAsset.Delete();
}
/// <summary>
/// Clean up resources associated with the channel.
/// </summary>
/// <param name="channel"></param>
public static void Cleanup(IChannel channel)
{
IAsset asset;
if (channel != null)
{
foreach (var program in channel.Programs)
{
asset = _context.Assets.FirstOrDefault(se => se.Id == program.AssetId);
Log("Stopping program");
var programStopOperation = program.SendStopOperation();
TrackOperation(programStopOperation, "Program stop");
program.Delete();
if (asset != null)
{
Log("Deleting locators");
foreach (var l in asset.Locators)
l.Delete();
Log("Deleting asset");
asset.Delete();
}
}
Log("Stopping channel");
var channelStopOperation = channel.SendStopOperation();
TrackOperation(channelStopOperation, "Channel stop");
Log("Deleting channel");
var channelDeleteOperation = channel.SendDeleteOperation();
TrackOperation(channelDeleteOperation, "Channel delete");
}
}
/// <summary>
/// Track long running operations.
/// </summary>
/// <param name="operation"></param>
/// <param name="description"></param>
/// <returns></returns>
public static string TrackOperation(IOperation operation, string description)
{
string entityId = null;
bool isCompleted = false;
Log("starting to track ", null, operation.Id);
while (isCompleted == false)
{
operation = _context.Operations.GetOperation(operation.Id);
isCompleted = IsCompleted(operation, out entityId);
System.Threading.Thread.Sleep(TimeSpan.FromSeconds(30));
}
// If we got here, the operation succeeded.
Log(description + " in completed", operation.TargetEntityId, operation.Id);
return entityId;
}
/// <summary>
/// Checks if the operation has been completed.
/// If the operation succeeded, the created entity Id is returned in the out parameter.
/// </summary>
/// <param name="operationId">The operation Id.</param>
/// <param name="channel">
/// If the operation succeeded,
/// the entity Id associated with the successful operation is returned in the out parameter.</param>
/// <returns>Returns false if the operation is still in progress; otherwise, true.</returns>
private static bool IsCompleted(IOperation operation, out string entityId)
{
bool completed = false;
entityId = null;
switch (operation.State)
{
case OperationState.Failed:
// Handle the failure.
// For example, throw an exception.
// Use the following information in the exception: operationId, operation.ErrorMessage.
Log("operation failed", operation.TargetEntityId, operation.Id);
break;
case OperationState.Succeeded:
completed = true;
entityId = operation.TargetEntityId;
break;
case OperationState.InProgress:
completed = false;
Log("operation in progress", operation.TargetEntityId, operation.Id);
break;
}
return completed;
}
private static void Log(string action, string entityId = null, string operationId = null)
{
Console.WriteLine(
"{0,-21}{1,-51}{2,-51}{3,-51}",
DateTime.Now.ToString("yyyy'-'MM'-'dd HH':'mm':'ss"),
action,
entityId ?? string.Empty,
operationId ?? string.Empty);
}
}
}