AppCaptureMetadataWriter Class

Definition

Namespace:

Windows.Media.Capture

Enables an app to store metadata that the system will insert into captured video files or broadcast streams of app content.

public ref class AppCaptureMetadataWriter sealed : IClosable

/// [Windows.Foundation.Metadata.Activatable(65536, "Windows.Media.Capture.AppCaptureMetadataContract")]
/// [Windows.Foundation.Metadata.ContractVersion(Windows.Media.Capture.AppCaptureMetadataContract, 65536)]
/// [Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
/// [Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
class AppCaptureMetadataWriter final : IClosable

[Windows.Foundation.Metadata.Activatable(65536, "Windows.Media.Capture.AppCaptureMetadataContract")]
[Windows.Foundation.Metadata.ContractVersion(typeof(Windows.Media.Capture.AppCaptureMetadataContract), 65536)]
[Windows.Foundation.Metadata.MarshalingBehavior(Windows.Foundation.Metadata.MarshalingType.Agile)]
[Windows.Foundation.Metadata.Threading(Windows.Foundation.Metadata.ThreadingModel.Both)]
public sealed class AppCaptureMetadataWriter : System.IDisposable

function AppCaptureMetadataWriter()

Public NotInheritable Class AppCaptureMetadataWriter
Implements IDisposable

Inheritance

Object Platform::Object IInspectable AppCaptureMetadataWriter

Attributes

ActivatableAttribute ContractVersionAttribute MarshalingBehaviorAttribute ThreadingAttribute

Implements

IClosable IDisposable

Windows requirements

Device family	Windows Desktop Extension SDK (introduced in 10.0.16299.0)
API contract	Windows.Media.Capture.AppCaptureMetadataContract (introduced in v1.0)

Remarks

When you create an instance of AppCaptureMetadataWriter, the system initializes a unique instance for your app and is then ready for you to write metadata items. Although only one app can be capturing or broadcasting at a time, the system can accumulate metadata for multiple apps simultaneously. AppCaptureMetadataWriter does not initiate or modify the current capture or broadcast state. You should create and hold onto the instance of AppCaptureMetadataWriter as long as you want the system to hold the metadata in memory. When the instance of AppCaptureMetadataWriter is released, all metadata associated with that instance of AppCaptureMetadataWriter is released as well.

When you write a metadata item, the system associates a timestamp with the item so that it is automatically included with the captured or broadcast time range to which it applies.

Currently, two different types of metadata items are supported AppCaptureMetadataWriter: events and state. A metadata event is associated with a single point in time and usually is associated with a instantaneous action, such as a player in a game scoring a point. A state is a metadata item that applies across a window of time. An example of this is a state that contains the name of the game map that a player is currently in. Once a state value has been set, the system maintains that value for the state until it is set to a different value, until it is stopped with a call StopState, or until all states are ended with a call to StopAllStates. Both events and states are represented as a key/value pair where the key is the state or event name and the value is either an integer, a double, or a string value.

When historical app capture is enabled, the system accumulates metadata written with AppCaptureMetadataWriter even when not actively capturing or broadcasting. When, for example, a capture of the previous 30 seconds is written to a video file on disk, the metadata associated with the recorded time window is included in the file. The system imposes a limit on the storage space that is allocated per app for storing accumulated metadata. You can get the currently available storage space by checking the RemainingStorageBytesAvailable property.

When the all of the allotted space has been filled, the system will begin purging metadata using the AppCaptureMetadataPriority value, specified when the metadata items were written, and the age of each item in order to delete the oldest, least important data first. When this occurs, the MetadataPurged event is raised. In response to this event, you may choose to reduce the amount of metadata your app is writing, but this is not required.

Metadata items are classified as Important or Informational as specified with the AppCaptureMetadataPriority enumeration. Important priority means the metadata will be uploaded to the Xbox Live service. The metadata will be used to help users search clips or annotate broadcasts, among other things. Both Important and Informational metadata are embedded in the generated .mp4 file, so you should not include any private user information in the metadata.

This API may throw an error if the background service has shut down due to idle timeout.

Constructors

AppCaptureMetadataWriter()

Initializes a new instance of the AppCaptureMetadataWriter class.

Properties

RemainingStorageBytesAvailable

Gets the number of bytes remaining in the storage space allocated by the system for app capture metadata items.

Methods

AddDoubleEvent(String, Double, AppCaptureMetadataPriority)	Adds a new double metadata event.
AddInt32Event(String, Int32, AppCaptureMetadataPriority)	Adds a new integer metadata event.
AddStringEvent(String, String, AppCaptureMetadataPriority)	Adds a new string metadata event.
Close()	Disposes of the object and associated resources.
Dispose()	Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.
StartDoubleState(String, Double, AppCaptureMetadataPriority)	Adds a new double metadata state.
StartInt32State(String, Int32, AppCaptureMetadataPriority)	Adds a new double metadata state.
StartStringState(String, String, AppCaptureMetadataPriority)	Adds a new double metadata state.
StopAllStates()	Stops all metadata states.
StopState(String)	Stops the metadata state with the specified identifier.

Events

MetadataPurged

Occurs when the system purges previously stored metadata items.