Playing Media

The most basic case of multimedia integration in a QML application is for it to playback media. The QtMultimedia module supports this by providing a dedicated QML component: the MediaPlayer.

The MediaPlayer component is a non-visual item that connects a media source to one or several output channel(s). Depending on the nature of the media (i.e. audio, image or video) various output channel(s) can be configured.

Playing audio

In the following example, the MediaPlayer plays a mp3 sample audio file from a remote URL in an empty window:

  1. import QtQuick
  2. import QtMultimedia
  4. Window {
  5.     width: 1024
  6.     height: 768
  7.     visible: true
  9.     MediaPlayer {
  10.         id: player
  11.         source: "https://file-examples-com.github.io/uploads/2017/11/file_example_MP3_2MG.mp3"
  12.         audioOutput: AudioOutput {}
  13.     }
  15.     Component.onCompleted: {
  16.         player.play()
  17.     }
  18. }

In this example, the MediaPlayer defines two attributes:

  • source: it contains the URL of the media to play. It can either be embedded (qrc://), local (file://) or remote (https://).
  • audioOutput: it contains an audio output channel, AudioOutput, connected to a physical output device. By default, it will use the default audio output device of the system.

As soon as the main component has been fully initialized, the player’s play function is called:

  1. Component.onCompleted: {
  2.     player.play()
  3. }

Playing a video

If you want to play visual media such as pictures or videos, you must also define a VideoOutput element to place the resulting image or video in the user interface.

In the following example, the MediaPlayer plays a mp4 sample video file from a remote URL and centers the video content in the window:

  1. import QtQuick
  2. import QtMultimedia
  4. Window {
  5.     width: 1920
  6.     height: 1080
  7.     visible: true
  9.     MediaPlayer {
  10.         id: player
  11.         source: "https://file-examples-com.github.io/uploads/2017/04/file_example_MP4_1920_18MG.mp4"
  12.         audioOutput: AudioOutput {}
  13.         videoOutput: videoOutput
  14.     }
  16.     VideoOutput {
  17.         id: videoOutput
  18.         anchors.fill: parent
  19.         anchors.margins: 20
  20.     }
  22.     Component.onCompleted: {
  23.         player.play()
  24.     }
  25. }

In this example, the MediaPlayer defines a third attribute:

  • videoOutput: it contains the video output channel, VideoOutput, representing the visual space reserved to display the video in the user interface.

WARNING

Please note that the VideoOutput component is a visual item. As such, it’s essential that it is created within the visual components hierarchy and not within the MediaPlayer itself.

Controlling the playback

The MediaPlayer component offers several useful properties. For instance, the duration and position properties can be used to build a progress bar. If the seekable property is true, it is even possible to update the position when the progress bar is tapped.

It’s also possible to leverage AudioOutput and VideoOutput properties to customize the experience and provide, for instance, volume control.

The following example adds custom controls for the playback:

  • a volume slider
  • a play/pause button
  • a progress slider
  1. import QtQuick
  2. import QtQuick.Controls
  3. import QtMultimedia
  5. Window {
  6.     id: root
  7.     width: 960
  8.     height: 400
  9.     visible: true
  11.     MediaPlayer {
  12.         id: player
  13.         source: "file:///path-to-your-video-file.mp4"
  14.         audioOutput: audioOutput
  15.         videoOutput: videoOutput
  16.     }
  18.     AudioOutput {
  19.         id: audioOutput
  20.         volume: volumeSlider.value
  21.     }
  23.     VideoOutput {
  24.         id: videoOutput
  25.         width: videoOutput.sourceRect.width
  26.         height: videoOutput.sourceRect.height
  27.         anchors.horizontalCenter: parent.horizontalCenter
  28.     }
  30.     Slider {
  31.         id: volumeSlider
  32.         anchors.top: parent.top
  33.         anchors.right: parent.right
  34.         anchors.margins: 20
  35.         orientation: Qt.Vertical
  36.         value: 0.5
  37.     }
  39.     Item {
  40.         height: 50
  41.         anchors.left: parent.left
  42.         anchors.right: parent.right
  43.         anchors.bottom: parent.bottom
  44.         anchors.margins: 20
  46.         Button {
  47.             anchors.horizontalCenter: parent.horizontalCenter
  48.             text: player.playbackState ===  MediaPlayer.PlayingState ? qsTr("Pause") : qsTr("Play")
  49.             onClicked: {
  50.                 switch(player.playbackState) {
  51.                     case MediaPlayer.PlayingState: player.pause(); break;
  52.                     case MediaPlayer.PausedState: player.play(); break;
  53.                     case MediaPlayer.StoppedState: player.play(); break;
  54.                 }
  55.             }
  56.         }
  58.         Slider {
  59.             id: progressSlider
  60.             width: parent.width
  61.             anchors.bottom: parent.bottom
  62.             enabled: player.seekable
  63.             value: player.duration > 0 ? player.position / player.duration : 0
  64.             background: Rectangle {
  65.                 implicitHeight: 8
  66.                 color: "white"
  67.                 radius: 3
  68.                 Rectangle {
  69.                     width: progressSlider.visualPosition * parent.width
  70.                     height: parent.height
  71.                     color: "#1D8BF8"
  72.                     radius: 3
  73.                 }
  74.             }
  75.             handle: Item {}
  76.             onMoved: function () {
  77.                 player.position = player.duration * progressSlider.position
  78.             }
  79.         }
  80.     }
  82.     Component.onCompleted: {
  83.         player.play()
  84.     }
  85. }

The volume slider

A vertical Slider component is added on the top right corner of the window, allowing the user to control the volume of the media:

  1. Slider {
  2.     id: volumeSlider
  3.     anchors.top: parent.top
  4.     anchors.right: parent.right
  5.     anchors.margins: 20
  6.     orientation: Qt.Vertical
  7.     value: 0.5
  8. }

The volume attribute of the AudioOutput is then mapped to the value of the slider:

  1. AudioOutput {
  2.     id: audioOutput
  3.     volume: volumeSlider.value
  4. }

Play / Pause

A Button component reflects the playback state of the media and allows the user to control this state:

  1. Button {
  2.     anchors.horizontalCenter: parent.horizontalCenter
  3.     text: player.playbackState ===  MediaPlayer.PlayingState ? qsTr("Pause") : qsTr("Play")
  4.     onClicked: {
  5.         switch(player.playbackState) {
  6.             case MediaPlayer.PlayingState: player.pause(); break;
  7.             case MediaPlayer.PausedState: player.play(); break;
  8.             case MediaPlayer.StoppedState: player.play(); break;
  9.         }
  10.     }
  11. }

Depending on the playback state, a different text will be displayed in the button. When clicked, the corresponding action will be triggered and will either play or pause the media.

TIP

The possible playback states are listed below:

  • MediaPlayer.PlayingState: The media is currently playing.
  • MediaPlayer.PausedState: Playback of the media has been suspended.
  • MediaPlayer.StoppedState: Playback of the media is yet to begin.

Interactive progress slider

A Slider component is added to reflect the current progress of the playback. It also allows the user to control the current position of the playback.

  1. Slider {
  2.     id: progressSlider
  3.     width: parent.width
  4.     anchors.bottom: parent.bottom
  5.     enabled: player.seekable
  6.     value: player.duration > 0 ? player.position / player.duration : 0
  7.     background: Rectangle {
  8.         implicitHeight: 8
  9.         color: "white"
  10.         radius: 3
  11.         Rectangle {
  12.             width: progressSlider.visualPosition * parent.width
  13.             height: parent.height
  14.             color: "#1D8BF8"
  15.             radius: 3
  16.         }
  17.     }
  18.     handle: Item {}
  19.     onMoved: function () {
  20.         player.position = player.duration * progressSlider.position
  21.     }
  22. }

This slider will only be enabled when the media is seekable:

  1. Slider {
  2.     /* ... */
  3.     enabled: player.seekable
  4.     /* ... */
  5. }

Its value will be set to the current media progress, i.e. player.position / player.duration:

  1. Slider {
  2.     /* ... */
  3.     value: player.duration > 0 ? player.position / player.duration : 0
  4.     /* ... */
  5. }

When the slider is moved by the user, the media position will be updated:

  1. Slider {
  2.     /* ... */
  3.     onMoved: function () {
  4.         player.position = player.duration * progressSlider.position
  5.     }
  6.     /* ... */
  7. }

The media status

When using MediaPlayer to build a media player, it is good to monitor the status property of the player. Here is an enumeration of the possible statuses, ranging from MediaPlayer.Buffered to MediaPlayer.InvalidMedia. The possible values are summarized in the bullets below:

  • MediaPlayer.NoMedia. No media has been set. Playback is stopped.
  • MediaPlayer.Loading. The media is currently being loaded.
  • MediaPlayer.Loaded. The media has been loaded. Playback is stopped.
  • MediaPlayer.Buffering. The media is buffering data.
  • MediaPlayer.Stalled. The playback has been interrupted while the media is buffering data.
  • MediaPlayer.Buffered. The media has been buffered, this means that the player can start playing the media.
  • MediaPlayer.EndOfMedia. The end of the media has been reached. Playback is stopped.
  • MediaPlayer.InvalidMedia. The media cannot be played. Playback is stopped.
  • MediaPlayer.UnknownStatus. The status of the media is unknown.

As mentioned in the bullets above, the playback state can vary over time. Calling play, pause or stop alters the state, but the media in question can also have an effect. For example, the end can be reached, or it can be invalid, causing playback to stop.

TIP

It is also possible to let the MediaPlayer to loop a media item. The loops property controls how many times the source is to be played. Setting the property to MediaPlayer.Infinite causes endless looping. Great for continuous animations or a looping background song.