Meziantou.FrameworkMediaPlayer Class
The player of a media resource of a media element, created by MediaBackend.CreatePlayer: it gives the metadata of the resource (the duration, the dimensions, the tracks, the buffered and seekable ranges), holds the current playback position and gives the video frame to paint. The media element implements the rest: the ready states and the network states, the events, the promises of play(), loop, ended, played...
public abstract class MediaPlayer : IDisposableRemarks
The playback members have a default implementation that does not decode anything: the current playback position advances with the clock of the event loop (MediaResource.TimeProvider) at the playback rate while the element is playing, up to the duration. A backend that only reads the metadata of the resources overrides the metadata members; a backend that drives a real pipeline also overrides the playback members (MediaPlayer.CurrentTime, MediaPlayer.Play, MediaPlayer.Pause, MediaPlayer.Seek, MediaPlayer.PlaybackRate, MediaPlayer.SetVolume...).
The media element reads the state of the player when it needs it and at regular intervals while it is playing (to fire timeupdate and to detect the end of the resource). A player whose state changes by itself (the ready state of a streamed resource, the duration, the dimensions, the tracks, an error, the end of a seek) calls MediaPlayer.NotifyStateChanged, from any thread: the element then reads the state again from a task of its event loop and fires the events of the changes (durationchange, resize, waiting, canplay, error...).
The members are called on the thread of the event loop of the media element.
- Implements
Constructors
| Name | Description |
|---|---|
| MediaPlayer(TimeProvider) | Creates a player. |
MediaPlayer(TimeProvider)
MediaPlayer.csCreates a player.
protected MediaPlayer(TimeProvider timeProvider)Parameters
timeProviderTimeProvider- The clock of the media timeline (
MediaResource.TimeProvider), used by the default implementation of the playback members.
Properties
| Name | Description |
|---|---|
| AudioTracks | Gets the audio tracks of the resource, in their natural order (audioTracks). The first one is enabled. |
| Buffered | Gets the ranges of the media timeline that are buffered (buffered). The default is the whole resource. |
| CurrentTime | Gets the current playback position in seconds (https://html.spec.whatwg.org/multipage/media.html#current-playback-position), between 0 and MediaPlayer.Duration. The default implementation advances it with the clock at the MediaPlayer.PlaybackRate between MediaPlayer.Play and MediaPlayer.Pause. |
| DroppedVideoFrames | Gets the number of video frames that have been dropped instead of being displayed (VideoPlaybackQuality.droppedVideoFrames). The default is 0. |
| Duration | Gets the duration of the media resource in seconds (https://html.spec.whatwg.org/multipage/media.html#dom-media-duration): the time of the end of the resource on the media timeline, which starts at 0, or Double.PositiveInfinity when the resource is not known to be bounded (a stream). |
| Error | Gets the fatal error that stopped the player after its creation, or MediaPlayerError.None: the element then fails with MEDIA_ERR_NETWORK or MEDIA_ERR_DECODE and fires error. |
| ErrorMessage | Gets the diagnostic message of MediaPlayer.Error (MediaError.message), or an empty string. |
| IsSeeking | Gets a value indicating whether the player is still seeking: the data of the position of the last MediaPlayer.Seek is not available yet. A player that seeks asynchronously calls MediaPlayer.NotifyStateChanged when it is done. The default is false. |
| PlaybackRate | Gets or sets the playback rate (playbackRate): the speed of the playback, as a multiple of the intrinsic speed of the resource. A negative rate plays backwards. |
| ReadyState | Gets how much of the resource is available to render the current playback position. The default is MediaReadyState.HaveEnoughData: the whole resource is given to the backend. |
| Seekable | Gets the ranges of the media timeline the player can seek to (seekable). The default is the whole resource. |
| StartDate | Gets the date and time of the zero time of the media timeline, when the resource has one (https://html.spec.whatwg.org/multipage/media.html#timeline-offset, getStartDate()), or null. |
| TextTracks | Gets the text tracks of the resource and their cues (https://html.spec.whatwg.org/multipage/media.html#sourcing-in-band-text-tracks): they are exposed as the media-resource-specific text tracks of the element (textTracks) when the metadata of the resource is known. |
| TotalVideoFrames | Gets the number of video frames that have been displayed or dropped since the resource was loaded (VideoPlaybackQuality.totalVideoFrames, https://w3c.github.io/media-playback-quality/). The default is 0: nothing is decoded. |
| VideoHeight | Gets the natural height of the video in CSS pixels (videoHeight), or 0 when the resource has no video. |
| VideoTracks | Gets the video tracks of the resource, in their natural order (videoTracks). The first one is selected. |
| VideoWidth | Gets the natural width of the video in CSS pixels (videoWidth), or 0 when the resource has no video. |
AudioTracks
MediaPlayer.csGets the audio tracks of the resource, in their natural order (audioTracks). The first one is enabled.
public virtual IReadOnlyList<MediaTrackInfo> AudioTracks { get; }Property value
Buffered
MediaPlayer.csGets the ranges of the media timeline that are buffered (buffered). The default is the whole resource.
public virtual IReadOnlyList<MediaTimeRange> Buffered { get; }Property value
CurrentTime
MediaPlayer.csGets the current playback position in seconds (https://html.spec.whatwg.org/multipage/media.html#current-playback-position), between 0 and MediaPlayer.Duration. The default implementation advances it with the clock at the MediaPlayer.PlaybackRate between MediaPlayer.Play and MediaPlayer.Pause.
public virtual double CurrentTime { get; }Property value
DroppedVideoFrames
MediaPlayer.csDuration
Gets the duration of the media resource in seconds (https://html.spec.whatwg.org/multipage/media.html#dom-media-duration): the time of the end of the resource on the media timeline, which starts at 0, or Double.PositiveInfinity when the resource is not known to be bounded (a stream).
public abstract double Duration { get; }Property value
Error
MediaPlayer.csGets the fatal error that stopped the player after its creation, or MediaPlayerError.None: the element then fails with MEDIA_ERR_NETWORK or MEDIA_ERR_DECODE and fires error.
public virtual MediaPlayerError Error { get; }Property value
ErrorMessage
MediaPlayer.csGets the diagnostic message of MediaPlayer.Error (MediaError.message), or an empty string.
public virtual string ErrorMessage { get; }Property value
IsSeeking
MediaPlayer.csGets a value indicating whether the player is still seeking: the data of the position of the last MediaPlayer.Seek is not available yet. A player that seeks asynchronously calls MediaPlayer.NotifyStateChanged when it is done. The default is false.
public virtual bool IsSeeking { get; }Property value
PlaybackRate
MediaPlayer.csReadyState
MediaPlayer.csGets how much of the resource is available to render the current playback position. The default is MediaReadyState.HaveEnoughData: the whole resource is given to the backend.
public virtual MediaReadyState ReadyState { get; }Property value
Seekable
MediaPlayer.csGets the ranges of the media timeline the player can seek to (seekable). The default is the whole resource.
public virtual IReadOnlyList<MediaTimeRange> Seekable { get; }Property value
StartDate
MediaPlayer.csGets the date and time of the zero time of the media timeline, when the resource has one (https://html.spec.whatwg.org/multipage/media.html#timeline-offset, getStartDate()), or null.
public virtual DateTimeOffset? StartDate { get; }Property value
TextTracks
MediaPlayer.csGets the text tracks of the resource and their cues (https://html.spec.whatwg.org/multipage/media.html#sourcing-in-band-text-tracks): they are exposed as the media-resource-specific text tracks of the element (textTracks) when the metadata of the resource is known.
public virtual IReadOnlyList<MediaTextTrackInfo> TextTracks { get; }Property value
TotalVideoFrames
MediaPlayer.csVideoHeight
MediaPlayer.csVideoTracks
MediaPlayer.csGets the video tracks of the resource, in their natural order (videoTracks). The first one is selected.
public virtual IReadOnlyList<MediaTrackInfo> VideoTracks { get; }Property value
VideoWidth
MediaPlayer.csMethods
| Name | Description |
|---|---|
| Dispose() | Releases the resources of the player: the media element selected another resource, or it will never play again. |
| Dispose(bool) | Releases the resources of the player. |
| GetVideoFrame() | Returns the frame of the video at the current playback position, painted in the box of the video element (with object-fit) and drawn by drawImage(), or null when there is none (the element then paints nothing, or its poster frame). Return the same instance while the frame does not change: its image is created once. |
| NotifyStateChanged() | Tells the media element that the state of the player changed (the ready state, the duration, the dimensions, the ranges, an error, the end of a seek, a position that changed in a discontinuous way): the element reads it again from a task of its event loop. Can be called from any thread. |
| OnDataReceived(ReadOnlyMemory<byte>, bool) | More bytes of a resource that arrives over time were received (the player was created from an incomplete resource, see MediaResource.IsComplete). The element reads the state of the player again afterwards (its ready state, its buffered ranges...). The default implementation does nothing. |
| Pause() | Stops advancing the current playback position: the media element is no longer potentially playing (it is paused, it ended, it waits for data...). |
| Play() | Starts advancing the current playback position: the media element is potentially playing (https://html.spec.whatwg.org/multipage/media.html#potentially-playing) and its document is fully active. The element handles the end of the resource (ended, loop): the position just stops at MediaPlayer.Duration. |
| Seek(double) | Sets the current playback position (https://html.spec.whatwg.org/multipage/media.html#dom-media-seek). The element fires seeked once MediaPlayer.IsSeeking is false. |
| SelectVideoTrack(MediaTrackInfo?) | Selects the video track to play (VideoTrack.selected). The default implementation does nothing. |
| SetAudioTrackEnabled(MediaTrackInfo, bool) | Enables or disables an audio track (AudioTrack.enabled). The default implementation does nothing. |
| SetPreservesPitch(bool) | Sets whether the pitch of the audio is preserved when the playback rate is not 1 (preservesPitch). The default implementation does nothing. |
| SetVolume(double) | Sets the volume of the audio (https://html.spec.whatwg.org/multipage/media.html#effective-media-volume). The default implementation does nothing: there is no audio output. |
| SupportsPlaybackRate(double) | Returns whether the player supports a playback rate: the setter of playbackRate throws a NotSupportedError otherwise. The default is true. |
Dispose overloads
Dispose()
MediaPlayer.csReleases the resources of the player: the media element selected another resource, or it will never play again.
public void Dispose()Dispose(bool)
MediaPlayer.csReleases the resources of the player.
Parameters
disposingbool- Whether the method is called by
MediaPlayer.Dispose.
GetVideoFrame()
MediaPlayer.csReturns the frame of the video at the current playback position, painted in the box of the video element (with object-fit) and drawn by drawImage(), or null when there is none (the element then paints nothing, or its poster frame). Return the same instance while the frame does not change: its image is created once.
public virtual MediaVideoFrame? GetVideoFrame()Returns
NotifyStateChanged()
MediaPlayer.csTells the media element that the state of the player changed (the ready state, the duration, the dimensions, the ranges, an error, the end of a seek, a position that changed in a discontinuous way): the element reads it again from a task of its event loop. Can be called from any thread.
protected void NotifyStateChanged()OnDataReceived(ReadOnlyMemory<byte>, bool)
MediaPlayer.csMore bytes of a resource that arrives over time were received (the player was created from an incomplete resource, see MediaResource.IsComplete). The element reads the state of the player again afterwards (its ready state, its buffered ranges...). The default implementation does nothing.
public virtual void OnDataReceived(ReadOnlyMemory<byte> content, bool isComplete)Parameters
contentReadOnlyMemory<byte>- The bytes of the resource received so far, from its first byte.
isCompletebool- Whether
contentis the entire resource.
Pause()
MediaPlayer.csStops advancing the current playback position: the media element is no longer potentially playing (it is paused, it ended, it waits for data...).
public virtual void Pause()Play()
MediaPlayer.csStarts advancing the current playback position: the media element is potentially playing (https://html.spec.whatwg.org/multipage/media.html#potentially-playing) and its document is fully active. The element handles the end of the resource (ended, loop): the position just stops at MediaPlayer.Duration.
public virtual void Play()Seek(double)
MediaPlayer.csSets the current playback position (https://html.spec.whatwg.org/multipage/media.html#dom-media-seek). The element fires seeked once MediaPlayer.IsSeeking is false.
Parameters
timedouble- The new playback position in seconds, in one of the
MediaPlayer.Seekableranges.
SelectVideoTrack(MediaTrackInfo?)
MediaPlayer.csSelects the video track to play (VideoTrack.selected). The default implementation does nothing.
public virtual void SelectVideoTrack(MediaTrackInfo? track)Parameters
trackMediaTrackInfo?- A track of
MediaPlayer.VideoTracks, or null when no video track is selected.
SetAudioTrackEnabled(MediaTrackInfo, bool)
MediaPlayer.csEnables or disables an audio track (AudioTrack.enabled). The default implementation does nothing.
public virtual void SetAudioTrackEnabled(MediaTrackInfo track, bool enabled)Parameters
trackMediaTrackInfo- A track of
MediaPlayer.AudioTracks. enabledbool- Whether the track is enabled.
SetPreservesPitch(bool)
MediaPlayer.csSetVolume(double)
MediaPlayer.csSets the volume of the audio (https://html.spec.whatwg.org/multipage/media.html#effective-media-volume). The default implementation does nothing: there is no audio output.
Parameters
volumedouble- The effective media volume, from 0 (silent, e.g. the element is muted) to 1 (the loudest).