AppCaptureMetadataWriter AppCaptureMetadataWriter AppCaptureMetadataWriter AppCaptureMetadataWriter Class

Definition

Some information relates to pre-released product which may be substantially modified before it’s commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

Prerelease APIs are identified by a Prerelease label.

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

public : sealed class AppCaptureMetadataWriter : IClosable, IAppCaptureMetadataWriterpublic sealed class AppCaptureMetadataWriter : IDisposable, IAppCaptureMetadataWriterPublic NotInheritable Class AppCaptureMetadataWriter Implements IDisposable, IAppCaptureMetadataWriter// You can use this class in JavaScript.
Attributes
Windows 10 requirements
Device family
Windows Desktop Extension SDK (introduced v10.0.16257.0)
API contract
Windows.Media.Capture.AppCaptureMetadataContract (introduced v1)

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.

Constructors

AppCaptureMetadataWriter() AppCaptureMetadataWriter() AppCaptureMetadataWriter() AppCaptureMetadataWriter()

Prerelease. Initializes a new instance of the AppCaptureMetadataWriter class.

public : AppCaptureMetadataWriter()public AppCaptureMetadataWriter()Public Sub New()// You can use this method in JavaScript.

Properties

RemainingStorageBytesAvailable RemainingStorageBytesAvailable RemainingStorageBytesAvailable RemainingStorageBytesAvailable

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

public : ulong RemainingStorageBytesAvailable { get; }public ulong RemainingStorageBytesAvailable { get; }Public ReadOnly Property RemainingStorageBytesAvailable As ulong// You can use this property in JavaScript.
Value
ulong ulong ulong ulong

The number of bytes remaining for metadata storage.

Remarks

Because historical app capture is supported, 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.

Methods

AddDoubleEvent(String, Double, AppCaptureMetadataPriority) AddDoubleEvent(String, Double, AppCaptureMetadataPriority) AddDoubleEvent(String, Double, AppCaptureMetadataPriority) AddDoubleEvent(String, Double, AppCaptureMetadataPriority)

Prerelease. Adds a new double metadata event.

public : void AddDoubleEvent(PlatForm::String name, double value, AppCaptureMetadataPriority priority)public void AddDoubleEvent(String name, Double value, AppCaptureMetadataPriority priority)Public Function AddDoubleEvent(name As String, value As Double, priority As AppCaptureMetadataPriority) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the metadata event.

value
double Double Double Double

The value of the metadata event.

priority
AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority

A member of the AppCaptureMetadataPriority enumeration specifying the relative importance of the metadata item. This value and the age of a metadata item are used by the system to determine which metadata items should be purged first when the limit of the allocated storage space for accumulated metadata is reached.

Remarks

The system associates a metadata event with a timestamp when this method is called. To store a double value that applies to a window of time, use StartDoubleState.

AddInt32Event(String, Int32, AppCaptureMetadataPriority) AddInt32Event(String, Int32, AppCaptureMetadataPriority) AddInt32Event(String, Int32, AppCaptureMetadataPriority) AddInt32Event(String, Int32, AppCaptureMetadataPriority)

Prerelease. Adds a new integer metadata event.

public : void AddInt32Event(PlatForm::String name, int value, AppCaptureMetadataPriority priority)public void AddInt32Event(String name, Int32 value, AppCaptureMetadataPriority priority)Public Function AddInt32Event(name As String, value As Int32, priority As AppCaptureMetadataPriority) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the metadata event.

value
int Int32 Int32 Int32

The value of the metadata event.

priority
AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority

A member of the AppCaptureMetadataPriority enumeration specifying the relative importance of the metadata item. This value and the age of a metadata item are used by the system to determine which metadata items should be purged first when the limit of the allocated storage space for accumulated metadata is reached.

Remarks

The system associates a metadata event with a timestamp when this method is called. To store an integer value that applies to a window of time, use StartInt32State.

AddStringEvent(String, String, AppCaptureMetadataPriority) AddStringEvent(String, String, AppCaptureMetadataPriority) AddStringEvent(String, String, AppCaptureMetadataPriority) AddStringEvent(String, String, AppCaptureMetadataPriority)

Prerelease. Adds a new string metadata event.

public : void AddStringEvent(PlatForm::String name, PlatForm::String value, AppCaptureMetadataPriority priority)public void AddStringEvent(String name, String value, AppCaptureMetadataPriority priority)Public Function AddStringEvent(name As String, value As String, priority As AppCaptureMetadataPriority) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the metadata event.

value
PlatForm::String String String String

The value of the metadata event.

priority
AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority

A member of the AppCaptureMetadataPriority enumeration specifying the relative importance of the metadata item. This value and the age of a metadata item are used by the system to determine which metadata items should be purged first when the limit of the allocated storage space for accumulated metadata is reached.

Remarks

The system associates a metadata event with a timestamp when this method is called. To store a string value that applies to a window of time, use StartStringState.

Close() Close() Close() Close()

Prerelease. Disposes of the object and associated resources.

public : void Close()This member is not implemented in C#This member is not implemented in VB.Net// You can use this method in JavaScript.

Dispose() Dispose() Dispose() Dispose()

Performs application-defined tasks associated with freeing, releasing, or resetting unmanaged resources.

This member is not implemented in C++void Dispose()Sub Disposevoid Dispose()

StartDoubleState(String, Double, AppCaptureMetadataPriority) StartDoubleState(String, Double, AppCaptureMetadataPriority) StartDoubleState(String, Double, AppCaptureMetadataPriority) StartDoubleState(String, Double, AppCaptureMetadataPriority)

Prerelease. Adds a new double metadata state.

public : void StartDoubleState(PlatForm::String name, double value, AppCaptureMetadataPriority priority)public void StartDoubleState(String name, Double value, AppCaptureMetadataPriority priority)Public Function StartDoubleState(name As String, value As Double, priority As AppCaptureMetadataPriority) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the metadata state.

value
double Double Double Double

The value of the metadata state.

priority
AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority

A member of the AppCaptureMetadataPriority enumeration specifying the relative importance of the metadata item. This value and the age of a metadata item are used by the system to determine which metadata items should be purged first when the limit of the allocated storage space for accumulated metadata is reached.

Remarks

The system associates a metadata state with the window of time between when the state is started and when it's value is changed or the state is stopped with a call to StopAllStates. To store a double value that applies to an instantaneous moment in time, use AddDoubleEvent.

StartInt32State(String, Int32, AppCaptureMetadataPriority) StartInt32State(String, Int32, AppCaptureMetadataPriority) StartInt32State(String, Int32, AppCaptureMetadataPriority) StartInt32State(String, Int32, AppCaptureMetadataPriority)

Prerelease. Adds a new double metadata state.

public : void StartInt32State(PlatForm::String name, int value, AppCaptureMetadataPriority priority)public void StartInt32State(String name, Int32 value, AppCaptureMetadataPriority priority)Public Function StartInt32State(name As String, value As Int32, priority As AppCaptureMetadataPriority) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the metadata state.

value
int Int32 Int32 Int32

The value of the metadata state.

priority
AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority

A member of the AppCaptureMetadataPriority enumeration specifying the relative importance of the metadata item. This value and the age of a metadata item are used by the system to determine which metadata items should be purged first when the limit of the allocated storage space for accumulated metadata is reached.

Remarks

The system associates a metadata state with the window of time between when the state is started and when it's value is changed or the state is stopped with a call to StopAllStates. To store a integer value that applies to an instantaneous moment in time, use AddInt32Event.

StartStringState(String, String, AppCaptureMetadataPriority) StartStringState(String, String, AppCaptureMetadataPriority) StartStringState(String, String, AppCaptureMetadataPriority) StartStringState(String, String, AppCaptureMetadataPriority)

Prerelease. Adds a new double metadata state.

public : void StartStringState(PlatForm::String name, PlatForm::String value, AppCaptureMetadataPriority priority)public void StartStringState(String name, String value, AppCaptureMetadataPriority priority)Public Function StartStringState(name As String, value As String, priority As AppCaptureMetadataPriority) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The name of the metadata state.

value
PlatForm::String String String String

The value of the metadata state.

priority
AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority AppCaptureMetadataPriority

A member of the AppCaptureMetadataPriority enumeration specifying the relative importance of the metadata item. This value and the age of a metadata item are used by the system to determine which metadata items should be purged first when the limit of the allocated storage space for accumulated metadata is reached.

Remarks

The system associates a metadata state with the window of time between when the state is started and when it's value is changed or the state is stopped with a call to StopAllStates. To store a string value that applies to an instantaneous moment in time, use AddStringEvent.

StopAllStates() StopAllStates() StopAllStates() StopAllStates()

StopState(String) StopState(String) StopState(String) StopState(String)

Prerelease. Stops the metadata state with the specified identifier.

public : void StopState(PlatForm::String name)public void StopState(String name)Public Function StopState(name As String) As void// You can use this method in JavaScript.
Parameters
name
PlatForm::String String String String

The identifier of the state to be stopped.

Remarks

Start a metadata state by calling StartDoubleState, StartInt32State, or StartStringState, specifying the state identifier that you can later pass into StopState. Stop all states with a single call to StopAllStates.

See Also

Events

MetadataPurged MetadataPurged MetadataPurged MetadataPurged

Prerelease. Occurs when the system purges previously stored metadata items.

public : event TypedEventHandler MetadataPurged<AppCaptureMetadataWriter,  object>public event TypedEventHandler MetadataPurged<AppCaptureMetadataWriter,  object>Public Event MetadataPurged<AppCaptureMetadataWriter,  object>// You can use this event in JavaScript.

Remarks

Because historical app capture is supported, 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.