MediaStreamSource MediaStreamSource MediaStreamSource MediaStreamSource Class

Definition

Represents a media source that delivers media samples directly to the media pipeline.

public sealed class MediaStreamSourcepublic sealed class MediaStreamSourcePublic NotInheritable Class MediaStreamSourcepublic sealed class MediaStreamSource
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

See the MediaStreamSource Sample for an example of using Media Stream Source in a Windows Store app.

MediaStreamSource is a new generic media source for Windows Store app which is introduced in Windows 8.1. MediaStreamSource allows apps to send compressed or uncompressed audio and video samples to the media pipeline for playback, transcoding, and streaming. Media samples can be dynamically generated by the app, or de-multiplexed from a stream or files. This flexibility enables apps to more easily extend platform support for new media formats or solve complex problems, such as adaptive streaming.

The MediaStreamSource API are very similar to the Microsoft SilverlightAPI of the same name.

MediaStreamSource can be used with audio and video objects in Windows app using JavaScript, MediaElement objects in Windows Store app using C++, C#, or Visual Basic, and the MediaTranscoder.

The MediaStreamSource Sample demonstrates how to use the @Windows.Media.Core.MediaStreamSource.Here are some of the main MediaStreamSource API. The order outlines the basic flow of how MediaStreamSource functions. You'll notice that the MediaStreamSource sends request objects to the app through event arguments. These request objects enable the app to interact with the MediaStreamSource and pass data back to it.

APIDescription
MediaStreamSource Represents a media source that delivers media samples directly to the media pipeline. MediaStreamSource consumes MediaStreamSample objects that are provided by the application.
MediaStreamSample Represents a media sample used by the @Windows.Media.Core.MediaStreamSource.</td></tr>
Starting (event)The MediaStreamSource uses this event to notify the app that it is ready to start processing media data.
MediaStreamSourceStartingRequest Represents a request from the MediaStreamSource that it is ready to start processing media data. Apps should reply as soon as possible to this request by calling SetActualStartPosition(TimeSpan) on the request. If an app needs to delay the MediaStreamSource from processing data, it can get an asynchronous deferral from GetDeferral(). When the app is ready for the MediaStreamSource to start, it calls Complete() on the deferral object. The starting request is accessed through the MediaStreamSourceStartingEventArgs that are passed to the Starting event handler.
SampleRequested (event)The MediaStreamSource uses this event to notify the app that it is ready for a MediaStreamSample. Apps are required to register a handler for this event.
MediaStreamSourceSampleRequest Represents a request from the MediaStreamSource for a new media sample. Setting the Sample property to the new MediaStreamSample triggers the MediaStreamSource to retrieve the media sample and continue processing the media data. Apps should reply as soon as possible to this request. If an app needs time before sending the MediaStreamSample, it can get an asynchronous deferral from GetDeferral(). When the app is finished with the deferral, it calls Complete() on the deferral object. The sample request is accessed through the MediaStreamSourceSampleRequestedEventArgs that are passed to the SampleRequested event handler. The app indicates it has reached the end of the stream by responding to a MediaStreamSourceSampleRequest without providing a MediaStreamSample, or by assigning the Sample property to null.
Closed (event)The MediaStreamSource uses this event to notify the app that it has shut down.
MediaStreamSourceClosedRequest Represents a request from the MediaStreamSource that it has closed. The close request is accessed through the MediaStreamSourceClosedEventArgs that are passed to the Closed event handler.
SetMediaStreamSource(IMediaSource) Sets the source of the MediaElement to a @Windows.Media.Core.MediaStreamSource.</td></tr>

Constructors

MediaStreamSource(IMediaStreamDescriptor) MediaStreamSource(IMediaStreamDescriptor) MediaStreamSource(IMediaStreamDescriptor) MediaStreamSource(IMediaStreamDescriptor)

Creates an instance of MediaStreamSource from the specified IMediaStreamDescriptor.

public MediaStreamSource(IMediaStreamDescriptor descriptor)public New(IMediaStreamDescriptor descriptor)Public Sub New(descriptor As IMediaStreamDescriptor)public MediaStreamSource(IMediaStreamDescriptor descriptor)
Parameters
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This constructor creates a MediaStreamSource using a single AudioStreamDescriptor or VideoStreamDescriptor object. If the MediaStreamSource needs descriptors, the @Windows.Media.Core.MediaStreamSource.#ctor(Windows.Media.Core.IMediaStreamDescriptor,Windows.Media.Core.IMediaStreamDescriptor) constructor overload which takes two descriptor can be used.

It is possible to add additional descriptors to a MediaStreamSource after it has been created, by invoking the AddStreamDescriptor(IMediaStreamDescriptor) method.

MediaStreamSource(IMediaStreamDescriptor, IMediaStreamDescriptor) MediaStreamSource(IMediaStreamDescriptor, IMediaStreamDescriptor) MediaStreamSource(IMediaStreamDescriptor, IMediaStreamDescriptor) MediaStreamSource(IMediaStreamDescriptor, IMediaStreamDescriptor)

Creates an instance of MediaStreamSource from two IMediaStreamDescriptor objects.

public MediaStreamSource(IMediaStreamDescriptor descriptor, IMediaStreamDescriptor descriptor2)public New(IMediaStreamDescriptor descriptor, IMediaStreamDescriptor descriptor2)Public Sub New(descriptor As IMediaStreamDescriptor, descriptor2 As IMediaStreamDescriptor)public MediaStreamSource(IMediaStreamDescriptor descriptor, IMediaStreamDescriptor descriptor2)
Parameters
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This constructor creates a MediaStreamSource using a two AudioStreamDescriptor or VideoStreamDescriptor objects. If the MediaStreamSource needs only on descriptor, the @Windows.Media.Core.MediaStreamSource.#ctor(Windows.Media.Core.IMediaStreamDescriptor) constructor overload which takes two descriptor can be used.

It is possible to add additional descriptors to a MediaStreamSource after it has been created, by invoking the AddStreamDescriptor(IMediaStreamDescriptor) method.

Properties

BufferTime BufferTime BufferTime BufferTime

Gets or sets the amount of data that is buffered by the MediaStreamSource.

public TimeSpan BufferTime { get; set; }public TimeSpan BufferTime { get; set; }Public ReadWrite Property BufferTime As TimeSpanpublic TimeSpan BufferTime { get; set; }
Value
TimeSpan TimeSpan TimeSpan TimeSpan

The duration of the buffer which corresponds to the number of MediaStreamSample the MediaStreamSource requests. The default value is 3 seconds.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The MediaStreamSource will request a number of MediaStreamSample in advance. The amount is controlled by the BufferTime property. The default value is 3 seconds.

Requesting MediaStreamSample in advance helps prevent glitches that would otherwise occur if the application does not deliver MediaStreamSample on time.

CanSeek CanSeek CanSeek CanSeek

Gets or sets whether or not the application supports changing its position in the media time-line.

public bool CanSeek { get; set; }public bool CanSeek { get; set; }Public ReadWrite Property CanSeek As boolpublic bool CanSeek { get; set; }
Value
bool bool bool bool

true if the application supports changing its position in the media time-line; otherwise, false. The default value is false.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Setting the CanSeek property to true implies that the application is able to handle a Starting event that specifies a start offset other than the current position.

The default value is false.

Applications are allowed to change the value of this property at any time.

Duration Duration Duration Duration

Gets or sets the duration of the media time-line.

public TimeSpan Duration { get; set; }public TimeSpan Duration { get; set; }Public ReadWrite Property Duration As TimeSpanpublic TimeSpan Duration { get; set; }
Value
TimeSpan TimeSpan TimeSpan TimeSpan

The duration of the media time-line. The default value is 0.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Applications that support seeking and set CanSeek to true must also assign a value to the Duration property.

The default value is 0, which means that the duration is unspecified. Live media or media that is being generated in real-time might have a Duration value of 0, since the actual duration is unknown.

Applications are allowed to change the value of this property at any time. For example, after a live broadcast has ended, the Duration value can be updated from 0 to the actual length of the live broadcast.

MaxSupportedPlaybackRate MaxSupportedPlaybackRate MaxSupportedPlaybackRate MaxSupportedPlaybackRate

Prerelease. Gets the maxiumum supported playback rate for the MediaStreamSource.

public IReference<double> MaxSupportedPlaybackRate { get; set; }public IReference<double> MaxSupportedPlaybackRate { get; set; }Public ReadWrite Property MaxSupportedPlaybackRate As IReference<double>public IReference<double> MaxSupportedPlaybackRate { get; set; }
Value

The maxiumum supported playback rate for the MediaStreamSource.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This value is expressed as a ratio of the maximum playrate to the normal playback rate, so 1.0 indicates normal speed and 2.0 indicates double the normal speed.

MediaProtectionManager MediaProtectionManager MediaProtectionManager MediaProtectionManager

Gets or sets the Digital Rights Management (DRM)MediaProtectionManager used to protect the media.

public MediaProtectionManager MediaProtectionManager { get; set; }public MediaProtectionManager MediaProtectionManager { get; set; }Public ReadWrite Property MediaProtectionManager As MediaProtectionManagerpublic MediaProtectionManager MediaProtectionManager { get; set; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If any of the streams are protected, the application must set the MediaProtectionManager property on the MediaStreamSource.

The MediaStreamSource requires that the following properties be present in the PropertySet object returned by Properties:

  • Properties
  • [Windows.Media.Protection.MediaProtectionSystemIdMapping

](../windows.media.protection/mediaprotectionmanager_properties.md) MediaStreamSource will use the value of the following optional property when initializing the content protection system:

MusicProperties MusicProperties MusicProperties MusicProperties

Gets the music properties which are used for music-related metadata.

public MusicProperties MusicProperties { get; }public MusicProperties MusicProperties { get; }Public ReadOnly Property MusicProperties As MusicPropertiespublic MusicProperties MusicProperties { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

MusicProperties is a music-oriented view of the MediaStreamSource properties.

Applications are allowed to modify the properties of MusicProperties at any time.

Applications should be aware that there is overlap with VideoProperties. A change to the MusicProperties may modify a similar property in the VideoProperties, and vice versa.

Thumbnail Thumbnail Thumbnail Thumbnail

Gets or sets the thumbnail which is a reference to a stream for a video thumbnail image or music album art.

public IRandomAccessStreamReference Thumbnail { get; set; }public IRandomAccessStreamReference Thumbnail { get; set; }Public ReadWrite Property Thumbnail As IRandomAccessStreamReferencepublic IRandomAccessStreamReference Thumbnail { get; set; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The stream is treated as a video thumbnail if the MediaStreamSource has at least one video stream; otherwise, the stream is treated as music album art.

VideoProperties VideoProperties VideoProperties VideoProperties

Gets the video properties which are used for video related metadata.

public VideoProperties VideoProperties { get; }public VideoProperties VideoProperties { get; }Public ReadOnly Property VideoProperties As VideoPropertiespublic VideoProperties VideoProperties { get; }
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

VideoProperties is a video-oriented view of the MediaStreamSource properties.

Applications are allowed to modify the properties of VideoProperties at any time.

Applications should be aware that there is overlap with MusicProperties. A change to the VideoProperties may modify a similar property in the MusicProperties property, and vice versa.

Methods

AddProtectionKey(IMediaStreamDescriptor, Byte[], Byte[]) AddProtectionKey(IMediaStreamDescriptor, Byte[], Byte[]) AddProtectionKey(IMediaStreamDescriptor, Byte[], Byte[]) AddProtectionKey(IMediaStreamDescriptor, Byte[], Byte[])

Adds a Digital Rights Management (DRM) protection key which is used by the MediaProtectionManager to encrypt and decrypt the specified stream.

public void AddProtectionKey(IMediaStreamDescriptor streamDescriptor, Byte[] keyIdentifier, Byte[] licenseData)public void AddProtectionKey(IMediaStreamDescriptor streamDescriptor, Byte[] keyIdentifier, Byte[] licenseData)Public Function AddProtectionKey(streamDescriptor As IMediaStreamDescriptor, keyIdentifier As Byte[], licenseData As Byte[]) As voidpublic void AddProtectionKey(IMediaStreamDescriptor streamDescriptor, Byte[] keyIdentifier, Byte[] licenseData)
Parameters
streamDescriptor
IMediaStreamDescriptor IMediaStreamDescriptor IMediaStreamDescriptor IMediaStreamDescriptor

The stream the key is used to encrypt and decrypt.

keyIdentifier
System.Byte[] System.Byte[] System.Byte[] System.Byte[]

The key used to encrypt and decrypt the stream.

licenseData
System.Byte[] System.Byte[] System.Byte[] System.Byte[]

The Digital Rights Management (DRM) licence for the media.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

AddStreamDescriptor(IMediaStreamDescriptor) AddStreamDescriptor(IMediaStreamDescriptor) AddStreamDescriptor(IMediaStreamDescriptor) AddStreamDescriptor(IMediaStreamDescriptor)

Adds a new stream descriptor to the MediaStreamSource.

public void AddStreamDescriptor(IMediaStreamDescriptor descriptor)public void AddStreamDescriptor(IMediaStreamDescriptor descriptor)Public Function AddStreamDescriptor(descriptor As IMediaStreamDescriptor) As voidpublic void AddStreamDescriptor(IMediaStreamDescriptor descriptor)
Parameters
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This method can only be invoked when the MediaStreamSource is not yet in use by the media pipeline, for example by a video object, a MediaElement, or a MediaTranscoder.

It is possible to invoke this method multiple times.

NotifyError(MediaStreamSourceErrorStatus) NotifyError(MediaStreamSourceErrorStatus) NotifyError(MediaStreamSourceErrorStatus) NotifyError(MediaStreamSourceErrorStatus)

Notifies the MediaStreamSource that an error has occurred which is preventing the application from continuing to deliver data to the MediaStreamSource.

public void NotifyError(MediaStreamSourceErrorStatus errorStatus)public void NotifyError(MediaStreamSourceErrorStatus errorStatus)Public Function NotifyError(errorStatus As MediaStreamSourceErrorStatus) As voidpublic void NotifyError(MediaStreamSourceErrorStatus errorStatus)
Parameters
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The application should invoke this method when it has encountered an unrecoverable error, for example, loss of the network connection to a media server or an out-of-memory condition.

The MediaStreamSource will raise the Closed event when this method is invoked.

SetBufferedRange(TimeSpan, TimeSpan) SetBufferedRange(TimeSpan, TimeSpan) SetBufferedRange(TimeSpan, TimeSpan) SetBufferedRange(TimeSpan, TimeSpan)

Sets the range of data that the application is currently buffering.

public void SetBufferedRange(TimeSpan startOffset, TimeSpan endOffset)public void SetBufferedRange(TimeSpan startOffset, TimeSpan endOffset)Public Function SetBufferedRange(startOffset As TimeSpan, endOffset As TimeSpan) As voidpublic void SetBufferedRange(TimeSpan startOffset, TimeSpan endOffset)
Parameters
startOffset
TimeSpan TimeSpan TimeSpan TimeSpan

The smallest time stamp of a MediaStreamSample buffered by the application.

endOffset
TimeSpan TimeSpan TimeSpan TimeSpan

The largest time stamp of a MediaStreamSample buffered by the application.

Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Applications that use the network to stream or download the data for MediaStreamSample should invoke SetBufferedRange(TimeSpan, TimeSpan) to specify what portion of the time-line is currently buffered. If the buffered range extends from 0 to the value of Duration, and Duration is non-zero, the operating system may allow the network hardware to enter a power saving mode.

By default, the buffered range is assumed to be empty when the CanSeek property is false or when the Duration property is 0. If CanSeek is true, the buffered range default is 0 to Duration

Events

Closed Closed Closed Closed

Occurs when the MediaStreamSource is shutting down.

public event TypedEventHandler Closedpublic event TypedEventHandler ClosedPublic Event Closedpublic event TypedEventHandler Closed
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

If the MediaStreamSource is shutting down due to an error, the Reason property on the MediaStreamSourceClosedRequest object, which can be obtained from MediaStreamSourceClosedEventArgs, provides information about the nature of the error.

Upon receiving this event, the application should remove all of its event handlers from the MediaStreamSource object, and refrain from further use of this instance of the MediaStreamSource object.

Applications are not required to have a handler for this event.

Paused Paused Paused Paused

Occurs when the MediaStreamSource is paused and stops requesting MediaStreamSample objects for an unspecified period of time, but is expected to resume requesting MediaStreamSample objects from the current position.

public event TypedEventHandler Pausedpublic event TypedEventHandler PausedPublic Event Pausedpublic event TypedEventHandler Paused
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This event might be raised by the user pressing a “Pause” button in the UI. When the user decides to resume playback, it is likely that the Starting event will indicate that the MediaStreamSample objects should continue to be delivered from the current position. The Paused event serves as a hint to the application that the next Starting event will specify the current position.

The event is informational. Applications are not required to have a handler for this event.

SampleRendered SampleRendered SampleRendered SampleRendered

Occurs when a sample from the MediaStreamSource is rendered.

public event TypedEventHandler SampleRenderedpublic event TypedEventHandler SampleRenderedPublic Event SampleRenderedpublic event TypedEventHandler SampleRendered
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Use this event to determine if there is a lag in the rendering of a sample, in which case you may decide to switch to a lower-bandwidth stream.

SampleRequested SampleRequested SampleRequested SampleRequested

Occurs when the MediaStreamSource request a MediaStreamSample for a specified stream.

public event TypedEventHandler SampleRequestedpublic event TypedEventHandler SampleRequestedPublic Event SampleRequestedpublic event TypedEventHandler SampleRequested
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

Upon receiving this event, the application should assign a MediaStreamSample for the requested stream to the Sample property of the MediaStreamSourceSampleRequest object.

If the application is temporarily unable to deliver the MediaStreamSample, it should obtain the MediaStreamSourceSampleRequestDeferral object and invoke ReportSampleProgress(UInt32) on a regular basis until it assigns a MediaStreamSample to the Sample property and calls Complete() on the MediaStreamSourceSampleRequestDeferral object. The recommended interval between each invocation of ReportSampleProgress(UInt32) is 500 milliseconds.

If the specified stream does not have any more samples, the application should leave the Sample property unassigned or set it to null.

Starting Starting Starting Starting

Occurs when the MediaStreamSource is ready to start requesting MediaStreamSample objects. The event can specify a position in the media time-line from which the first MediaStreamSample should be delivered.

public event TypedEventHandler Startingpublic event TypedEventHandler StartingPublic Event Startingpublic event TypedEventHandler Starting
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

The MediaStreamSource raises this event before it starts requesting MediaStreamSample for the first time. It also raises the event when it resumes requesting MediaStreamSample after a Paused event has occurred.

Upon receiving this event, the application must invoke the SetActualStartPosition(TimeSpan) method on the MediaStreamSourceStartingRequest object to specify the actual position in the time-line from which MediaStreamSample objects will be retrieved.

This event cancels any SampleRequested events the application has not delivered the requested MediaStreamSample for. However, application must still invoke the Complete() method on the MediaStreamSourceSampleRequestDeferral object for any previous SampleRequested events.

Applications are only required to have a handler for the Starting event if CanSeek is set to true and they support seeking.

SwitchStreamsRequested SwitchStreamsRequested SwitchStreamsRequested SwitchStreamsRequested

Occurs when the MediaStreamSource will stop requesting MediaStreamSample objects for a certain stream and will start requesting MediaStreamSample objects from a different stream instead.

public event TypedEventHandler SwitchStreamsRequestedpublic event TypedEventHandler SwitchStreamsRequestedPublic Event SwitchStreamsRequestedpublic event TypedEventHandler SwitchStreamsRequested
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

This event can be raised when there are multiple audio stream descriptors or multiple video stream descriptors. Normally, only one audio stream and one video stream will be selected at any given time. This event is raised when the currently selected audio or video stream is replaced by a different stream.

The event is informational. Applications are not required to have a handler for this event.