Share via

Deprecated. Azure Video Analyzer Edge client library for .NET

  • Article

Deprecated. We’re retiring the Azure Video Analyzer preview service, you're advised to transition your applications off of Video Analyzer by 01 December 2022. This SDK is not longer maintained.

Azure Video Analyzer is an Azure Applied AI Service that provides a platform for you to build intelligent video applications that can span both edge and cloud infrastructures. The platform offers the capability to capture, record, and analyze live video along with publishing the results, video and video analytics, to Azure services at the edge or in the cloud. It is designed to be an extensible platform, enabling you to connect different video inferencing edge modules such as Cognitive services modules, or custom inferencing modules that have been trained with your own data using either open-source machine learning or Azure Machine Learning.

Use the client library for Video Analyzer Edge to:

  • Simplify interactions with the Microsoft Azure IoT SDKs
  • Programmatically construct pipeline topologies and live pipelines

Product documentation | Direct methods | Pipelines | Source code | Samples

Getting started

This is a models-only SDK. All client operations are done using the Microsoft Azure IoT SDKs. This SDK provides models you can use to interact with the Azure IoT SDKs.

Authenticate the client

The client is coming from Azure IoT SDK. You will need to obtain an IoT device connection string in order to authenticate the Azure IoT SDK. For more information please visit: https://github.com/Azure/azure-iot-sdk-csharp.

string connectionString = System.Environment.GetEnvironmentVariable("iothub_connectionstring", EnvironmentVariableTarget.User);
var serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Install the package

Install the Video Analyzer Edge client library for .NET with NuGet:

dotnet add package Azure.Media.VideoAnalyzer.Edge --prerelease

Install the Azure IoT Hub SDk for .NET with NuGet:

dotnet add package Microsoft.Azure.Devices

Prerequisites

  • You need an active Azure subscription and an IoT device connection string to use this package.

  • You will need to use the version of the SDK that corresponds to the version of the Video Analyzer Edge module you are using.

    SDK Video Analyzer edge module
    1.0.0-beta.5 1.1
    1.0.0-beta.4 1.0
    1.0.0-beta.3 1.0
    1.0.0-beta.2 1.0
    1.0.0-beta.1 1.0

Creating a pipeline topology and making requests

Please visit the Examples for starter code.

Key concepts

Pipeline topology vs live pipeline

A pipeline topology is a blueprint or template for instantiating live pipelines. It defines the parameters of the pipeline using placeholders as values for them. A live pipeline references a pipeline topology and specifies the parameters. This way you are able to have multiple live pipelines referencing the same topology but with different values for parameters. For more information please visit pipeline topologies and live pipelines.

CloudToDeviceMethod

The CloudToDeviceMethod is part of the azure-iot-hub SDk. This method allows you to communicate one way notifications to a device in your IoT hub. In our case, we want to communicate various methods such as PipelineTopologySetRequest and PipelineTopologyGetRequest. To use CloudToDeviceMethod you need to pass in one parameter: MethodName and then set the JSON payload of that method.

The parameter MethodName is the name of the request you are sending. Make sure to use each method's predefined MethodName property. For example, PipelineTopologySetRequest.MethodName.

To set the Json payload of the cloud method, use the pipeline request method's GetPayloadAsJson() function. For example, directCloudMethod.SetPayloadJson(PipelineTopologySetRequest.GetPayloadAsJson())

Thread safety

We guarantee that all client instance methods are thread-safe and independent of each other (guideline). This ensures that the recommendation of reusing client instances is always safe, even across threads.

Additional concepts

Client options | Accessing the response | Long-running operations | Handling failures | Diagnostics | Mocking | Client lifetime

Examples

Creating a pipeline topology

To create a pipeline topology you need to define sources and sinks.

Define Parameters

pipelineTopologyProperties.Parameters.Add(new ParameterDeclaration("rtspUserName", ParameterType.String)
{
    Description = "rtsp source user name.",
    Default = "exampleUserName"
});
pipelineTopologyProperties.Parameters.Add(new ParameterDeclaration("rtspPassword", ParameterType.SecretString)
{
    Description = "rtsp source password.",
    Default = "examplePassword"
});
pipelineTopologyProperties.Parameters.Add(new ParameterDeclaration("rtspUrl", ParameterType.String)
{
    Description = "rtsp Url"
});

Define a Source

pipelineTopologyProps.Sources.Add(new RtspSource("rtspSource", new UnsecuredEndpoint("${rtspUrl}")
{
    Credentials = new UsernamePasswordCredentials("${rtspUserName}", "${rtspPassword}")
})
);

Define a Sink

var nodeInput = new List<NodeInput>
{
    new NodeInput("rtspSource")
};
pipelineTopologyProps.Sinks.Add(new VideoSink("videoSink", nodeInput, "video", "/var/lib/videoanalyzer/tmp/", "1024"));

Set the topology properties and create a topology

var pipelineTopologyProps = new PipelineTopologyProperties
{
    Description = "Continuous video recording to a Video Analyzer video",
};
SetParameters(pipelineTopologyProps);
SetSources(pipelineTopologyProps);
SetSinks(pipelineTopologyProps);
return new PipelineTopology("ContinuousRecording")
{
    Properties = pipelineTopologyProps
};

Creating a live pipeline

To create a live pipeline, you need to have an existing pipeline topology.

var livePipelineProps = new LivePipelineProperties
{
    Description = "Sample description",
    TopologyName = topologyName,
};

livePipelineProps.Parameters.Add(new ParameterDefinition("rtspUrl", "rtsp://sample.com"));

return new LivePipeline("livePIpeline")
{
    Properties = livePipelineProps
};

Invoking a direct method

To invoke a direct method on your device you need to first define the request using the Video Analyzer Edge SDK, then send that method request using the IoT SDK's CloudToDeviceMethod.

var setPipelineTopRequest = new PipelineTopologySetRequest(pipelineTopology);

var directMethod = new CloudToDeviceMethod(setPipelineTopRequest.MethodName);
directMethod.SetPayloadJson(setPipelineTopRequest.GetPayloadAsJson());

var setPipelineTopResponse = await _serviceClient.InvokeDeviceMethodAsync(_deviceId, _moduleId, directMethod);

To try different pipeline topologies with the SDK, please see the official Samples.

Troubleshooting

  • When sending a method request using the IoT Hub's CloudToDeviceMethod remember to not type in the method request name directly. Instead use MethodRequestName.MethodName

Next steps

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

If you encounter any issues, please open an issue on our Github.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Impressions