Ejemplo de reproductor multimedia QML
Reproducción de audio y vídeo mediante el tipo « MediaPlayer » de QML.

Este ejemplo muestra un reproductor multimedia sencillo capaz de reproducir archivos de audio y vídeo utilizando diversos códecs.
Ejecución del ejemplo
Puedes ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde Command Palette y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
Creación de una instancia de MediaPlayer
El punto de entrada del código QML en este ejemplo es Main.qml. Aquí se crea un ApplicationWindow y se establecen propiedades como id, title, width y height.
ApplicationWindow {
id: root
title: qsTr("Multimedia Player")
width: 1280
height: 720A continuación, se crea el ` MediaPlayer ` y se definen las dos propiedades responsables de la salida de vídeo y audio. En primer lugar, ` videoOutput `, que se encarga de mostrar el visor de vídeo, y en segundo lugar, ` audioOutput `, que proporciona la salida de audio para el reproductor.
MediaPlayer {
id: mediaPlayer
...
videoOutput: videoOutput
audioOutput: AudioOutput {
id: audio
muted: playbackController.muted
volume: playbackController.volume
}
...
VideoOutput {
id: videoOutput
anchors.fill: parent
visible: mediaPlayer.mediaStatus > 0
TapHandler {
onDoubleTapped: {
root.fullScreen ? root.showNormal() : root.showFullScreen()
root.fullScreen = !root.fullScreen
}
}
}La propiedad « visible » del tipo « VideoOutput » se establece en « true » cuando la propiedad « mediaStatus » del « MediaPlayer » es mayor que 0. « mediaStatus » es de tipo enumeración y es igual a 0 cuando no se ha establecido ningún contenido multimedia, y mayor que 0 en caso contrario. Por lo tanto, el « VideoOutput » es visible cuando se ha establecido contenido multimedia.
El tipo « MediaPlayer » tiene una propiedad de señal denominada « onErrorOccurred » que puede sobrescribirse específicamente para gestionar errores. En este caso, la señal abre un « MessageDialog » mediante el método « open() » y establece su propiedad « text » en una propiedad « MediaPlayer » denominada « errorString ».
onErrorOccurred: {
mediaError.text = mediaPlayer.errorString
mediaError.open()
}Controles de reproducción
Para disponer de un reproductor multimedia funcional, es necesario contar con una interfaz que controle la reproducción. Esta se crea en su propio archivo de componente, PlaybackControl.qml, y se instancia en Main.qml.
PlaybackControl {
id: playbackController
...
onTracksChanged: {
audioTracksInfo.read(mediaPlayer.audioTracks)
videoTracksInfo.read(mediaPlayer.videoTracks)
subtitleTracksInfo.read(mediaPlayer.subtitleTracks, 6) /* QMediaMetaData::Language = 6 */
updateMetadata()
mediaPlayer.play()
}Una vez creado, se transfieren a este tipo objetos como la información de la pista, los metadatos y el propio objeto MediaPlayer. En PlaybackControl.qml, cada uno de estos objetos tiene una propiedad required property, lo que significa que estas propiedades deben establecerse al crear el objeto PlaybackControl.
Item {
id: playbackController
required property MediaPlayer mediaPlayer
required property MetadataInfo metadataInfo
required property TracksInfo audioTracksInfo
required property TracksInfo videoTracksInfo
required property TracksInfo subtitleTracksInfoEstos controles de reproducción se pueden dividir en secciones. En la parte superior izquierda del panel hay un conjunto de botones que sirven para abrir un archivo, ya sea seleccionándolo en un explorador de archivos o introduciendo una URL. El archivo se carga en el ` MediaPlayer ` estableciendo la propiedad ` source `. Ambos botones se instancian utilizando un ` CustomButton ` ` custom component`.
CustomButton {
id: fileDialogButton
icon.source: "../images/open_new.svg"
flat: false
onClicked: fileDialog.open()
}
CustomButton {
id: openUrlButton
icon.source: "../images/link.svg"
flat: false
onClicked: urlPopup.open()
}Se crean tres botones y se centran en este panel, que controlan la reproducción, la pausa y el avance o retroceso de diez segundos. El contenido multimedia se reproduce y se pausa mediante los métodos play() y pause(), respectivamente. Para saber cuándo dibujar un botón de reproducción o de pausa, se consulta la propiedad playbackState. Por ejemplo, cuando es igual al valor de la enumeración MediaPlayer.PlayingState, se dibuja el botón de pausa.
CustomRoundButton {
id: playButton
visible: playbackController.mediaPlayer.playbackState !== MediaPlayer.PlayingState
icon.source: "../images/play_symbol.svg"
onClicked: playbackController.mediaPlayer.play()
}
CustomRoundButton {
id: pauseButton
visible: playbackController.mediaPlayer.playbackState === MediaPlayer.PlayingState
icon.source: "../images/pause_symbol.svg"
onClicked: playbackController.mediaPlayer.pause()
}Para avanzar o retroceder diez segundos, el campo « position », de tipo « MediaPlayer », se incrementa en 10 000 milisegundos y se establece mediante el método « setPosition() ».
CustomRoundButton {
id: forward10Button
icon.source: "../images/forward10.svg"
onClicked: {
const pos = Math.min(playbackController.mediaPlayer.duration,
playbackController.mediaPlayer.position + 10000)
playbackController.mediaPlayer.setPosition(pos)
}
}Búsqueda en la reproducción y audio
En PlaybackControl.qml se instancian un AudioControl y un PlaybackSeekControl. Ambos están definidos en su propio archivo de componentes y se encargan del control de volumen y del desplazamiento en la reproducción, respectivamente. El tipo AudioControl define un botón para silenciar y un Slider, procedente de QtQuick Controls, para ajustar el volumen del reproductor. Ambos atributos se exponen mediante la definición de las propiedades mute y volume, y se accede a ellos desde la definición de AudioOutput en Main.qml.
property alias muted: muteButton.checked
property real volume: slider.valueEl elemento « PlaybackSeekControl » utiliza un « RowLayout » que contiene un « Slider » con un elemento « Text » a cada lado. Los dos elementos « Text » muestran la hora actual y el tiempo restante del contenido multimedia que se está reproduciendo. Ambos se calculan utilizando dos propiedades de tipo « MediaPlayer »: « position », que indica la posición actual de reproducción en milisegundos, y « duration », que indica la duración del contenido multimedia en milisegundos.
Label {
id: currentTime
Layout.preferredWidth: 45
text: seekController.formatToMinutes(seekController.mediaPlayer.position)
horizontalAlignment: Text.AlignLeft
font.pixelSize: 11
}
...
Label {
id: remainingTime
Layout.preferredWidth: 45
text: seekController.formatToMinutes(seekController.mediaPlayer.duration - seekController.mediaPlayer.position)
horizontalAlignment: Text.AlignRight
font.pixelSize: 11
}La propiedad ` Slider ` solo está habilitada cuando el reproductor multimedia permite el desplazamiento y no se trata, por ejemplo, de contenido en directo. El tipo ` MediaPlayer ` dispone de una propiedad para ello denominada ` seekable`. La propiedad ` value ` de ` Slider ` se calcula utilizando las propiedades ` position ` y ` duration ` de ` MediaPlayer`.
enabled: seekController.mediaPlayer.seekable
value: seekController.mediaPlayer.position / seekController.mediaPlayer.durationMetadatos e información de la pista
El tipo PlaybackControl crea una instancia de SettingsPopup, que contiene información sobre los metadatos del contenido multimedia cargado actualmente y la selección de pista, así como la capacidad de actualizar la velocidad de reproducción. Este Popup se define en SettingsPopup.qml.

Los metadatos se encuentran en su propio archivo de componentes, MetadataInfo.qml. Contiene un ListModel, una función para borrarlo, clear(), y una función para rellenarlo, read(MediaMetadata metadata). La función ` read(MediaMetadata metadata) ` toma como parámetro un objeto de tipo ` MediaMetaData` y recorre su estructura clave-valor para extraer sus datos y colocarlos en el campo ` model ` del objeto ` ListView`. Los métodos utilizados para ello son ` keys()`, que devuelve todas las claves del ` MediaMetaData`, y `{stringValue(Key key)}`, que devuelve el ` value ` correspondiente a una clave dada ` key`.
function read(metadata) {
if (!metadata)
return
for (const key of metadata.keys())
if (metadata.stringValue(key))
listModel.append({
name: metadata.metaDataKeyToString(key),
value: metadata.stringValue(key)
})
}
ListModel {
id: listModel
}A continuación, los datos se muestran en SettingsPopup.qml en un tipo ListView. El delegate de este ListView es una fila de dos elementos Text, que se corresponden con los pares clave-valor extraídos del elemento MediaMetaData.
En el otro lado del Popup se encuentran los controles de velocidad de reproducción y la selección de pistas para audio, vídeo y subtítulos. La velocidad de reproducción se elige de un ComboBox y se establece mediante la propiedad playbackRate.
settingsController.mediaPlayer.playbackRate = (currentIndex + 1) * 0.25El tipo denominado « TracksInfo », definido en TracksInfo.qml, contiene los datos sobre las pistas. Más concretamente, un « ListModel » que contiene los títulos de las pistas o, en el caso específico de los subtítulos, los idiomas. Esta información se rellena en Main.qml llamando a la función « read(MediaMetadata mediaMetadata) », definida en el tipo « TracksInfo ».
onTracksChanged: {
audioTracksInfo.read(mediaPlayer.audioTracks)
videoTracksInfo.read(mediaPlayer.videoTracks)
subtitleTracksInfo.read(mediaPlayer.subtitleTracks, 6) /* QMediaMetaData::Language = 6 */
updateMetadata()
mediaPlayer.play()
}A continuación, se consulta el model definido en TracksInfo en el ComboBoxes del SettingsPopup para seleccionar la pista actual.
settingsController.mediaPlayer.pause()
tracksInfo.selectedTrack = currentIndex
settingsController.mediaPlayer.play()© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.