En esta página

MediaPlayer QML Type

Añade la reproducción de archivos multimedia a una escena. Más...

Import Statement: import QtMultimedia
In C++: QMediaPlayer

Propiedades

Señales

Métodos

Descripción detallada

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

Puedes utilizar MediaPlayer junto con un MultiMedia::AudioOutput para reproducir contenido de audio, o bien puedes utilizarlo junto con un Multimedia::VideoOutput para reproducir vídeo.

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();
    }
}

Véase también AudioOutput y VideoOutput.

Documentación de propiedades

activeAudioTrack : int

Esta propiedad contiene el número de la pista de audio actualmente activa. Establece el valor « -1 » para desactivar la pista de audio.

El valor predeterminado de la propiedad es « 0 »: la primera pista de audio.

activeSubtitleTrack : int

Esta propiedad contiene el número de pista de la pista de subtítulos actualmente activa. Establece el valor « -1 » para desactivar la pista de subtítulos.

El valor predeterminado de la propiedad es « -1 »: no hay subtítulos activos.

activeVideoTrack : int

Esta propiedad contiene el número de pista de la pista de audio del vídeo que está activa en ese momento. Establece el valor en « -1 » para desactivar la pista de vídeo.

El valor predeterminado de la propiedad es « 0 »: la primera pista de vídeo.

audioBufferOutput : QAudioBufferOutput [since 6.8]

Esta propiedad contiene la salida del búfer de audio de destino.

El uso normal de « MediaPlayer » desde QML no debería requerir el uso de esta propiedad.

Esta propiedad se introdujo en Qt 6.8.

Véase también QMediaPlayer::audioBufferOutput().

audioOutput : AudioOutput

Esta propiedad contiene la salida de audio de destino. Admite un elemento « AudioOutput ».

Véase también QMediaPlayer::setAudioOutput().

audioTracks : list<mediaMetaData> [read-only]

Esta propiedad contiene una lista de metadatos. Cada índice hace referencia a una pista de audio.

Los metadatos contienen propiedades que describen las pistas individuales. En el caso de las pistas de audio, la propiedad « Language » suele ser la más importante.

Esta propiedad emite la señal « tracksChanged » cuando se modifica.

Véase también « mediaMetaData ».

autoPlay : bool [since 6.7]

Esta propiedad controla si el contenido multimedia comienza a reproducirse automáticamente una vez cargado. El valor predeterminado es « false ».

Esta propiedad se introdujo en Qt 6.7.

bufferProgress : real [read-only]

Esta propiedad indica en qué medida está lleno actualmente el búfer de datos, desde « 0.0 » (vacío) hasta « 1.0 » (lleno).

La reproducción solo puede iniciarse o reanudarse cuando el búfer está completamente lleno. Cuando el búfer está lleno, MediaPlayer.Buffered es verdadero. Cuando el progreso del búfer se encuentra entre 0.0 y 1.0, MediaPlayer.Buffering se establece en true.

Un valor inferior a 1.0 implica que la propiedad MediaPlayer.StalledMedia es true.

Véase también mediaStatus.

duration : int [read-only]

Esta propiedad indica la duración del contenido multimedia en milisegundos.

Si el contenido multimedia no tiene una duración fija (por ejemplo, una retransmisión en directo), este valor se establecerá en « 0 ».

error : enumeration [read-only]

Esta propiedad contiene el estado de error del audio. Puede adoptar uno de los siguientes valores.

ConstanteDescripción
MediaPlayer.NoErrorNo se ha producido ningún error.
MediaPlayer.ResourceErrorNo se ha podido resolver un recurso multimedia.
MediaPlayer.FormatErrorEl formato de un recurso multimedia no es (totalmente) compatible. Es posible que la reproducción siga siendo posible, pero sin el componente de audio o vídeo.
MediaPlayer.NetworkErrorSe ha producido un error de red.
MediaPlayer.AccessDeniedErrorNo se dispone de los permisos adecuados para reproducir un recurso multimedia.

errorString : string [read-only]

Esta propiedad contiene una cadena de caracteres que describe con más detalle la condición de error actual.

hasAudio : bool [read-only]

Esta propiedad es válida independientemente de si el archivo multimedia contiene audio.

hasVideo : bool [read-only]

Esta propiedad se mantiene independientemente de si el archivo multimedia contiene vídeo.

loops : int

Determina cuántas veces se reproduce el archivo multimedia antes de que el reproductor se detenga. Establece este valor en MediaPlayer::Infinite para reproducir el archivo multimedia actual en bucle de forma indefinida.

El valor por defecto es « 1 ». Establecer esta propiedad en « 0 » no tiene ningún efecto.

mediaStatus : enumeration [read-only]

Esta propiedad indica el estado de carga del contenido multimedia. Puede adoptar uno de los siguientes valores:

ConstanteDescripción
MediaPlayer.NoMediaNo hay ningún contenido multimedia actualmente. El reproductor se encuentra en el estado «StoppedState».
MediaPlayer.LoadingMediaEl contenido multimedia actual se está cargando. El reproductor puede encontrarse en cualquier estado.
MediaPlayer.LoadedMediaEl contenido multimedia actual se ha cargado. El reproductor se encuentra en el estado «StoppedState».
MediaPlayer.StalledMediaLa reproducción del contenido multimedia actual se ha detenido debido a un almacenamiento en búfer insuficiente o a alguna otra interrupción temporal. El reproductor se encuentra en el estado «PlayingState» o «PausedState».
MediaPlayer.BufferingMediaEl reproductor está almacenando datos en el búfer, pero dispone de datos suficientes para que la reproducción continúe en el futuro inmediato. El reproductor se encuentra en el estado «PlayingState» o «PausedState».
MediaPlayer.BufferedMediaEl reproductor ha almacenado en el búfer todo el contenido multimedia actual. El reproductor se encuentra en el estado «PlayingState» o «PausedState».
MediaPlayer.EndOfMediaLa reproducción ha llegado al final del archivo multimedia actual. El reproductor se encuentra en el estado «StoppedState».
MediaPlayer.InvalidMediaEl contenido multimedia actual no se puede reproducir. El reproductor se encuentra en el estado «StoppedState».

metaData : mediaMetaData [read-only]

Devuelve los metadatos del archivo multimedia actual que está reproduciendo el reproductor multimedia.

Los metadatos pueden contener información como el título del vídeo o su fecha de creación.

Nota: La implementación de Windows solo proporciona metadatos para los archivos multimedia ubicados en el sistema de archivos local.

pitchCompensation : bool [since 6.10]

Esta propiedad indica si la compensación de tono está activada.

Esta propiedad se introdujo en Qt 6.10.

pitchCompensationAvailability : enumeration [read-only, since 6.10]

Indica la disponibilidad de la compensación de tono de la función « MediaPlayer » en el backend actual. La enumeración « PitchCompensationAvailability » tiene un ámbito limitado.

ConstanteDescripción
MediaPlayer.AlwaysOnEl reproductor multimedia realiza siempre la compensación de tono.
MediaPlayer.AvailableEl reproductor multimedia puede configurarse para utilizar la compensación de tono. Si la compensación de tono está disponible en la plataforma actual, estará activada de forma predeterminada, pero los usuarios pueden desactivarla si es necesario.
MediaPlayer.UnavailableEl reproductor multimedia no puede realizar la compensación de tono en la plataforma actual.

Esta propiedad se introdujo en Qt 6.10.

playbackOptions : PlaybackOptions [since 6.10]

Esta propiedad expone la API « PlaybackOptions », que permite un control de bajo nivel sobre las opciones de reproducción multimedia. Aunque recomendamos encarecidamente utilizar la configuración predeterminada de « MediaPlayer », esta API se puede utilizar para optimizar la reproducción multimedia en casos de uso específicos en los que las opciones predeterminadas no sean las más adecuadas.

Las opciones de reproducción surtirán efecto la próxima vez que se modifique MediaPlayer::source.

Esta propiedad se introdujo en Qt 6.10.

playbackRate : real

Esta propiedad indica la velocidad a la que se reproduce el contenido multimedia, expresada como un múltiplo de la velocidad normal.

Para obtener más información, consulta QMediaPlayer::playbackRate.

El valor predeterminado es 1.0.

playbackState : enumeration [read-only]

Esta propiedad contiene el estado de la reproducción multimedia. Puede adoptar uno de los siguientes valores:

Valor de la propiedadDescripción
PlayingStateEl contenido multimedia se está reproduciendo actualmente. Esto indica lo mismo que la propiedad « playing ».
PausedStateSe ha suspendido la reproducción del contenido multimedia.
StoppedStateLa reproducción del contenido aún no ha comenzado.

playing : bool [read-only, since 6.5]

Indica si el contenido multimedia se está reproduciendo en este momento.

Esta propiedad se introdujo en Qt 6.5.

Véase también playbackState.

position : int

El valor corresponde a la posición actual de reproducción, expresada en milisegundos desde el inicio del archivo multimedia. Los cambios periódicos en la posición se indicarán mediante la señal positionChanged().

Si la propiedad « seekable » es «true», esta propiedad se puede establecer en milisegundos.

seekable : bool [read-only]

Esta propiedad indica si se puede modificar el « position » del medio.

source : url

Esta propiedad contiene la URL de origen del contenido multimedia.

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();
    }
}

Véase también QMediaPlayer::setSource().

subtitleTracks : list<mediaMetaData> [read-only]

Esta propiedad contiene una lista de metadatos. Cada índice hace referencia a una pista de subtítulos.

Los metadatos contienen propiedades que describen las pistas individuales. En el caso de las pistas de subtítulos, la propiedad « Language » suele ser la más importante.

Esta propiedad emite la señal « tracksChanged » cuando se modifica.

Véase también « mediaMetaData ».

videoOutput : VideoOutput

Esta propiedad contiene la salida de vídeo de destino. Admite un elemento de tipo « VideoOutput ».

Véase también QMediaPlayer::setVideoOutput().

videoTracks : list<mediaMetaData> [read-only]

Esta propiedad contiene una lista de metadatos. Cada índice hace referencia a una pista de vídeo.

Los metadatos contienen propiedades que describen las pistas individuales.

Esta propiedad emite la señal « tracksChanged » cuando se modifica.

Véase también mediaMetaData.

Documentación de la señal

errorOccurred(error, errorString)

Esta señal se emite cuando se ha producido un error de tipo « error ». El parámetro « errorString » puede contener información más detallada sobre el error.

Nota: El controlador correspondiente es onErrorOccurred.

Véase también QMediaPlayer::Error.

playbackStateChanged()

Esta señal se emite cuando se modifica la propiedad playbackState.

Nota: El controlador correspondiente es onPlaybackStateChanged.

playingChanged()

Esta señal se emite cuando cambia la propiedad playing.

Nota: El controlador correspondiente es onPlayingChanged.

tracksChanged()

Esta señal se emite cuando se modifican las propiedades audioTracks, subtitleTracks o videoTracks.

Nota: El controlador correspondiente es onTracksChanged.

Documentación del método

void pause()

Pausa la reproducción del contenido multimedia.

Establece la propiedad « playbackState » en «PausedState» y cambia « playing » a « false ».

void play()

Inicia o reanuda la reproducción del contenido multimedia.

Establece la propiedad « playbackState » en «PlayingState» y cambia « playing » a « true ».

void stop()

Detiene la reproducción del contenido multimedia.

Establece la propiedad « playbackState » en «StoppedState» y cambia « playing » a « false ».

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