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
| 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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()
Prerelease. Stops all metadata states.
public : void StopAllStates()public void StopAllStates()Public Function StopAllStates() As void// You can use this method in JavaScript.
Remarks
Start a metadata state by calling StartDoubleState, StartInt32State, or StartStringState. Stop a single state by calling StopState.
- See Also
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.
- 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.