En esta página

Ejemplo de reproductor multimedia QML

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

Reproductor de vídeo que muestra los controles de reproducción y el área de vista previa del vídeo

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:

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: 720

A 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 subtitleTracksInfo

Estos 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.value

El 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.duration

Metadatos 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.

Ajustes de reproducción seleccionables por el usuario e información de metadatos

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.25

El 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()

Proyecto de ejemplo en @code.qt.io

© 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.