Back to Qt.io
Contact Us Blog Download Qt

MediaPlayer QML Type

为场景添加媒体播放。更多

Import Statement: import QtMultimedia
In C++: QMediaPlayer

属性

信号

方法

详细说明

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

您可以将 MediaPlayer 与 MultiMedia::AudioOutput 结合使用以播放音频内容，也可以将其与 Multimedia::VideoOutput 结合使用以渲染视频。

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

另请参阅 AudioOutput 和VideoOutput 。

属性文档

activeAudioTrack : int

该属性保存当前活动音轨的音轨编号。设置为-1 可禁用音轨。

默认属性值为0 ：第一个音轨。


activeSubtitleTrack : int

该属性表示当前活动字幕轨道的轨道编号。设置为-1 可禁用字幕音轨。

默认属性值为-1 ：无活动字幕。


activeVideoTrack : int

该属性表示当前激活的视频音频轨道的轨道编号。设置为-1 可禁用视频音轨。

默认属性值为0 ：第一个视频轨道。


audioBufferOutput : QAudioBufferOutput [since 6.8]

该属性用于保存目标音频缓冲输出。

正常使用 QML 中的MediaPlayer 时不需要使用此属性。

此属性在 Qt 6.8 中引入。

另请参阅 QMediaPlayer::audioBufferOutput().


audioOutput : AudioOutput

此属性保存目标音频输出。接受一个AudioOutput 元素。

另请参阅 QMediaPlayer::setAudioOutput().


audioTracks : list<mediaMetaData> [read-only]

该属性包含一个元数据列表。每个索引指向一个音轨。

元数据包含描述各个音轨的属性。对于音轨而言，Language 通常是最重要的属性。

另请参阅 mediaMetaData 。


autoPlay : bool [since 6.7]

该属性控制媒体加载后是否开始自动播放。默认值为false 。

该属性在 Qt 6.7 中引入。


bufferProgress : real [read-only]

该属性表示数据缓冲区当前被填满的程度，从0.0 （空）到1.0 （满）。

只有当缓冲区全部填满时，才能开始或继续播放。缓冲区已满时，MediaPlayer.Buffered 为 true。当缓冲区进度介于0.0 和1.0 之间时，MediaPlayer.Buffering 将被设置为true 。

值小于1.0 意味着属性MediaPlayer.StalledMedia 为true 。

另请参阅 mediaStatus 。


duration : int [read-only]

该属性以毫秒为单位保存媒体的持续时间。

如果媒体没有固定的持续时间（例如直播流），则该属性将设置为0 。


error : enumeration [read-only]

此属性表示音频的错误状态。它可以是以下值之一。

值说明
NoError当前没有错误。
资源错误由于资源分配问题，音频无法播放。
格式错误不支持音频格式。
网络错误由于网络问题，音频无法播放。
访问拒绝错误由于权限不足，音频无法播放。

errorString : string [read-only]

该属性包含一个字符串，详细描述了当前的错误状况。


hasAudio : bool [read-only]

该属性显示媒体是否包含音频。


hasVideo : bool [read-only]

该属性包含媒体是否包含视频。


loops : int

决定播放器停止播放媒体的频率。设置为 MediaPlayer::Infinite 时，将永远循环播放当前媒体文件。

默认值为1 。将此属性设置为0 没有任何作用。


mediaStatus : enumeration [read-only]

此属性用于保存媒体加载状态。它可以是以下其中之一：

属性值说明
无媒体未设置媒体。
正在加载媒体当前正在加载媒体。
已加载媒体媒体已加载。
缓冲媒体媒体正在缓冲数据。
停滞媒体媒体正在缓冲数据时播放被中断。
缓冲媒体媒体正在缓冲数据。
媒体结束媒体已播放结束。
无效媒体媒体无法播放。

metaData : mediaMetaData [read-only]

返回媒体播放器使用的当前媒体的元数据。

元数据可包含视频标题或创建日期等信息。

注意： Windows 实现只为位于本地文件系统中的媒体提供元数据。


playbackRate : real

该属性用于保存媒体的播放速率，即正常速率的倍数。

更多信息，请参阅QMediaPlayer::playbackRate 。

默认为1.0 。


playbackState : enumeration [read-only]

该属性用于保存媒体播放状态。可以是以下内容之一：

属性值属性值
播放状态媒体当前正在播放。其指示与playing 属性相同。
暂停状态媒体播放已暂停。
停止状态媒体的播放尚未开始。

playing : bool [read-only, since 6.5]

表示媒体当前是否正在播放。

此属性在 Qt 6.5 中引入。

另请参阅 playbackState 。


position : int

该值是媒体开始播放后的当前播放位置，以毫秒为单位。位置的周期性变化将通过 positionChanged() 信号显示。

如果seekable 属性为 true，该属性可设置为毫秒。


seekable : bool [read-only]

该属性表示是否可以更改媒体的position 。


source : url

该属性包含媒体的源 URL。

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

另请参阅 QMediaPlayer::setSource().


subtitleTracks : list<mediaMetaData> [read-only]

该属性包含一个元数据列表。每个索引指向一个字幕轨道。

元数据包含描述各个轨道的属性。对于字幕轨道，Language 通常是最重要的属性。

另请参阅 mediaMetaData 。


videoOutput : VideoOutput

该属性包含目标视频输出。接受一个VideoOutput 元素。

另请参阅 QMediaPlayer::setVideoOutput() 。


videoTracks : list<mediaMetaData> [read-only]

该属性包含一个元数据列表。每个索引指向一个视频轨。

元数据包含描述各轨道的属性。

另请参阅 mediaMetaData 。


信号文档

errorOccurred(error, errorString)

该信号在error 出现时发出。errorString 参数可能包含有关错误的更详细信息。

注意： 相应的处理程序是onErrorOccurred 。

另请参阅 QMediaPlayer::Error 。


playbackStateChanged()

当playbackState 属性被更改时，会发出该信号。

注： 相应的处理程序是onPlaybackStateChanged 。


playingChanged()

当playing 属性发生变化时，将发出此信号。

注： 相应的处理程序是onPlayingChanged 。


方法文档

pause()

暂停媒体播放。

将playbackState 属性设置为 PausedState，并将playing 更改为false 。


play()

开始或恢复媒体播放。

将playbackState 属性设置为 PlayingState，并将playing 更改为true 。


stop()

停止媒体播放。

将playbackState 属性设置为 StoppedState，并将playing 更改为false 。


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