- Qt 6.12
- Qt Multimedia
- QML Types
- MediaPlayer
- Qt 6.12.0 Reference Documentation

# MediaPlayer QML Type

Adds media playback to a scene. More...

Import Statement: | `import QtMultimedia`
In C++: | QMediaPlayer

- List of all members, including inherited members

## Properties

- activeAudioTrack : int
- activeSubtitleTrack : int
- activeVideoTrack : int
- audioBufferOutput : QAudioBufferOutput `(since 6.8)`
- audioOutput : AudioOutput
- audioTracks : list<mediaMetaData>
- autoPlay : bool `(since 6.7)`
- bufferProgress : real
- duration : int
- error : enumeration
- errorString : string
- hasAudio : bool
- hasVideo : bool
- loops : int
- mediaStatus : enumeration
- metaData : mediaMetaData
- pitchCompensation : bool `(since 6.10)`
- pitchCompensationAvailability : enumeration `(since 6.10)`
- playbackOptions : PlaybackOptions `(since 6.10)`
- playbackRate : real
- playbackState : enumeration
- playing : bool `(since 6.5)`
- position : int
- seekable : bool
- source : url
- subtitleTracks : list<mediaMetaData>
- videoOutput : VideoOutput
- videoTracks : list<mediaMetaData>

## Signals

- errorOccurred(error, errorString)
- playbackStateChanged()
- playingChanged()
- tracksChanged()

## Methods

- void pause()
- void play()
- void stop()

## Detailed Description

     Text {
         text: "Click Me!";
         font.pointSize: 24;
         width: 150; height: 50;

         MediaPlayer {
             id: playMusic
             source: "music.wav"
             audioOutput: AudioOutput {}
         }
         MouseArea {
             anchors.fill: parent
             onPressed:  { playMusic.play() }
         }
     }

You can use MediaPlayer together with a MultiMedia::AudioOutput to play audio content, or you can use it in conjunction with a Multimedia::VideoOutput for rendering video.

     Item {
         MediaPlayer {
             id: mediaplayer
             source: "groovy_video.mp4"
             audioOutput: AudioOutput {}
             videoOutput: videoOutput
         }

         VideoOutput {
             id: videoOutput
             anchors.fill: parent
         }

         MouseArea {
             anchors.fill: parent
             onPressed: mediaplayer.play();
         }
     }

See also AudioOutput and VideoOutput.

## Property Documentation

### activeAudioTrack : int

This property holds the track number of the currently active audio track. Set to `-1` to disable audio track.

The default property value is `0`: the first audio track.

### activeSubtitleTrack : int

This property holds the track number of the currently active subtitle track. Set to `-1` to disable subtitle track.

The default property value is `-1`: no subtitles active.

### activeVideoTrack : int

This property holds the track number of the currently active video audio track. Set to `-1` to disable video track.

The default property value is `0`: the first video track.

### audioBufferOutput : QAudioBufferOutput `[since 6.8]`

This property holds the target audio buffer output.

Normal usage of MediaPlayer from QML should not require using this property.

This property was introduced in Qt 6.8.

See also QMediaPlayer::audioBufferOutput().

### audioOutput : AudioOutput

This property holds the target audio output. Accepts one AudioOutput elements.

See also QMediaPlayer::setAudioOutput().

### audioTracks : list<mediaMetaData> `[read-only]`

This property holds a list of metadata. Each index refers to an audio track.

The metadata holds properties describing the individual tracks. For audio tracks the Language is usually the most important property.

This property emits the tracksChanged signal when modified.

See also mediaMetaData.

### autoPlay : bool `[since 6.7]`

This property controls whether the media begins to play automatically after it gets loaded. Defaults to `false`.

This property was introduced in Qt 6.7.

### bufferProgress : real `[read-only]`

This property holds how much of the data buffer is currently filled, from `0.0` (empty) to `1.0` (full).

Playback can start or resume only when the buffer is entirely filled. When the buffer is filled, `MediaPlayer.Buffered` is true. When buffer progress is between `0.0` and `1.0`, `MediaPlayer.Buffering` is set to `true`.

A value lower than `1.0` implies that the property `MediaPlayer.StalledMedia` is `true`.

See also mediaStatus.

### duration : int `[read-only]`

This property holds the duration of the media in milliseconds.

If the media doesn't have a fixed duration (a live stream for example) this will be set to `0`.

### error : enumeration `[read-only]`

This property holds the error state of the audio. It can be one of the following.

Constant | Description
--- | ---
`MediaPlayer.NoError` | No error has occurred.
`MediaPlayer.ResourceError` | A media resource couldn't be resolved.
`MediaPlayer.FormatError` | The format of a media resource isn't (fully) supported. Playback may still be possible, but without an audio or video component.
`MediaPlayer.NetworkError` | A network error occurred.
`MediaPlayer.AccessDeniedError` | There are not the appropriate permissions to play a media resource.

### errorString : string `[read-only]`

This property holds a string describing the current error condition in more detail.

### hasAudio : bool `[read-only]`

This property holds whether the media contains audio.

### hasVideo : bool `[read-only]`

This property holds whether the media contains video.

### loops : int

Determines how often the media is played before the player stops. Set to MediaPlayer::Infinite to loop the current media file forever.

The default value is `1`. Setting this property to `0` has no effect.

### mediaStatus : enumeration `[read-only]`

This property holds the status of media loading. It can be one of the following:

Constant | Description
--- | ---
`MediaPlayer.NoMedia` | The is no current media. The player is in the StoppedState.
`MediaPlayer.LoadingMedia` | The current media is being loaded. The player may be in any state.
`MediaPlayer.LoadedMedia` | The current media has been loaded. The player is in the StoppedState.
`MediaPlayer.StalledMedia` | Playback of the current media has stalled due to insufficient buffering or some other temporary interruption. The player is in the PlayingState or PausedState.
`MediaPlayer.BufferingMedia` | The player is buffering data but has enough data buffered for playback to continue for the immediate future. The player is in the PlayingState or PausedState.
`MediaPlayer.BufferedMedia` | The player has fully buffered the current media. The player is in the PlayingState or PausedState.
`MediaPlayer.EndOfMedia` | Playback has reached the end of the current media. The player is in the StoppedState.
`MediaPlayer.InvalidMedia` | The current media cannot be played. The player is in the StoppedState.

### metaData : mediaMetaData `[read-only]`

Returns meta data for the current media used by the media player.

Meta data can contain information such as the title of the video or its creation date.

Note: The Windows implementation provides metadata only for media located on the local file system.

### pitchCompensation : bool `[since 6.10]`

This property holds whether pitch compensation is enabled.

This property was introduced in Qt 6.10.

### pitchCompensationAvailability : enumeration `[read-only, since 6.10]`

Indicates the availability of pitch compensation of the `MediaPlayer` on the current backend. The enumeration `PitchCompensationAvailability` is scoped.

Constant | Description
--- | ---
`MediaPlayer.AlwaysOn` | The media player is always performing pitch compensation.
`MediaPlayer.Available` | The media player can be configured to use pitch compensation. If pitch compensation is available on the current platform, it will be enabled by default, but users can disable if needed.
`MediaPlayer.Unavailable` | The media player is not able to perform pitch compensation on the current platform.

This property was introduced in Qt 6.10.

### playbackOptions : PlaybackOptions `[since 6.10]`

This property exposes the PlaybackOptions API that gives low-level control of media playback options. Although we strongly recommend to rely on the default settings of MediaPlayer, this API can be used to optimize media playback for specific use cases where the default options are not ideal.

Playback options take effect the next time MediaPlayer::source is changed.

This property was introduced in Qt 6.10.

### playbackRate : real

This property holds the rate at which media is played at as a multiple of the normal rate.

For more information, see QMediaPlayer::playbackRate.

Defaults to `1.0`.

### playbackState : enumeration `[read-only]`

This property holds the state of media playback. It can be one of the following:

Property value | Description
--- | ---
PlayingState | The media is currently playing. This indicates the same as the playing property.
PausedState | Playback of the media has been suspended.
StoppedState | Playback of the media is yet to begin.

### playing : bool `[read-only, since 6.5]`

Indicates whether the media is currently playing.

This property was introduced in Qt 6.5.

See also playbackState.

### position : int

The value is the current playback position, expressed in milliseconds since the beginning of the media. Periodically changes in the position will be indicated with the positionChanged() signal.

If the seekable property is true, this property can be set to milliseconds.

### seekable : bool `[read-only]`

This property holds whether the position of the media can be changed.

### source : url

This property holds the source URL of the media.

     Item {
         MediaPlayer {
             id: mediaplayer
             source: "file:///test.mp4"
             videoOutput: videoOutput
             audioOutput: AudioOutput {

             }
         }

         VideoOutput {
             id: videoOutput
             anchors.fill: parent
         }

         MouseArea {
             id: playArea
             anchors.fill: parent
             onPressed: mediaplayer.play();
         }
     }

See also QMediaPlayer::setSource().

### subtitleTracks : list<mediaMetaData> `[read-only]`

This property holds a list of metadata. Each index refers to a subtitle track.

The metadata holds properties describing the individual tracks. For subtitle tracks the Language is usually the most important property.

This property emits the tracksChanged signal when modified.

See also mediaMetaData.

### videoOutput : VideoOutput

This property holds the target video output. Accepts one VideoOutput elements.

See also QMediaPlayer::setVideoOutput().

### videoTracks : list<mediaMetaData> `[read-only]`

This property holds a list of metadata. Each index refers to a video track.

The metadata holds properties describing the individual tracks.

This property emits the tracksChanged signal when modified.

See also mediaMetaData.

## Signal Documentation

### errorOccurred(error, errorString)

This signal is emitted when an error has occurred. The errorString parameter may contain more detailed information about the error.

Note: The corresponding handler is `onErrorOccurred`.

See also QMediaPlayer::Error.

### playbackStateChanged()

This signal is emitted when the playbackState property is altered.

Note: The corresponding handler is `onPlaybackStateChanged`.

### playingChanged()

This signal is emitted when the playing property changes.

Note: The corresponding handler is `onPlayingChanged`.

### tracksChanged()

This signal is emitted when the audioTracks, subtitleTracks or videoTracks properties are changed.

Note: The corresponding handler is `onTracksChanged`.

## Method Documentation

### void pause()

Pauses playback of the media.

Sets the playbackState property to PausedState, and changes playing to `false`.

### void play()

Starts or resumes playback of the media.

Sets the playbackState property to PlayingState, and changes playing to `true`.

### void stop()

Stops playback of the media.

Sets the playbackState property to StoppedState, and changes playing to `false`.