QMediaPlayer Class

player = new QMediaPlayer;
audioOutput = new QAudioOutput;
player->setAudioOutput(audioOutput);
connect(player, &QMediaPlayer::positionChanged, this, &MediaExample::positionChanged);
player->setSource(QUrl::fromLocalFile("/Users/me/Music/coolsong.mp3"));
audioOutput->setVolume(0.5);
player->play();

属性文档

activeAudioTrack : int

返回当前活动的音频轨道。

默认情况下，将选择第一个可用的音频轨道。

将index 设置为-1 可禁用所有音频轨道。

访问函数：

通知信号：

activeSubtitleTrack : int

返回当前活动的字幕轨道。

将index 设置为-1 可禁用字幕。

默认情况下，字幕处于禁用状态。

访问函数：

通知信号：

activeVideoTrack : int

返回当前活动的视频轨道。

默认情况下，将选择第一个可用的音频轨道。

将index 设置为-1 可禁用所有视频轨道。

访问函数：

通知信号：

[since 6.8] audioBufferOutput : QAudioBufferOutput*

此属性存储媒体播放器使用的输出音频缓冲区。

将音频缓冲区 `output ` 设置为媒体播放器的输出缓冲区。

如果指定了QAudioBufferOutput ，且媒体源包含音频流，则媒体播放器将发出QAudioBufferOutput::audioBufferReceived 信号，其中包含带有解码音频数据的音频缓冲区。在音频流结束时，QMediaPlayer 会发出一个空的QAudioBuffer 。

QMediaPlayer 在将匹配数据推送到音频输出（若已指定）的同时，也会输出音频缓冲区。不过，由于音频缓冲机制，声音播放可能会存在轻微延迟。

发出的音频缓冲区的格式取自指定的output ，或者如果output 返回无效格式，则取自匹配的音频流。发出的音频数据不会根据当前的播放速率进行缩放。

结合使用 `QAudioBufferOutput ` 与 `QMediaPlayer ` 的潜在应用场景包括：

• 音频可视化。如果媒体播放器的播放速率不是1 ，您可以根据可视化器的要求调整输出图像的尺寸或图像更新间隔。
• 任何 AI 音频处理，例如语音识别。
• 将数据发送至外部音频输出。应考虑播放速率变化、与视频的同步，以及在停止和寻址时的手动刷新。除非有充分理由，否则不建议为此目的使用音频缓冲区输出。

此枚举在 Qt 6.8 中引入。

访问函数：

通知器信号：

audioOutput : QAudioOutput*

该属性存储媒体播放器所使用的音频输出设备。

播放媒体时将使用的当前音频输出设备。设置新的音频输出将替换当前使用的输出设备。

将此属性设置为nullptr 将禁用所有音频输出。

访问函数：

通知信号：

[read-only] audioTracks : QList<QMediaMetaData>

列出媒体中可用的音频轨道集合。

返回的QMediaMetaData 描述了各个音轨的属性。

例如，不同的音轨可能包含不同语言的音频。

访问函数：

通知信号：

[read-only] bufferProgress : float

该属性表示在开始或恢复播放前，临时缓冲区的填充百分比，范围从0 （空）到1 （满）。

当播放器对象正在缓冲时，该属性表示临时缓冲区已填满的百分比。缓冲区必须达到 100% 才可开始或恢复播放，此时mediaStatus() 将返回BufferedMedia 或BufferingMedia 。如果该值低于100 ，则mediaStatus() 将返回StalledMedia 。

访问函数：

通知器信号：

另请参阅 mediaStatus()。

[read-only] duration : qint64

该属性存储当前媒体的时长。

该值为当前媒体的总播放时间（以毫秒为单位）。该值在QMediaPlayer 对象的生命周期内可能会发生变化，且在开始播放时可能不可用；请订阅durationChanged()信号以接收状态通知。

访问函数：

通知信号：

[read-only] error : Error

该属性包含一个字符串，用于描述最近的错误情况。

访问函数：

通知信号：

另请参阅 error()。

[read-only] errorString : QString

该属性存储一个字符串，用于更详细地描述当前的错误状况。

访问函数：

通知信号：

[read-only] hasAudio : bool

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

访问函数：

通知信号：

[read-only] hasVideo : bool

该属性用于指示媒体是否包含视频。

访问函数：

通知信号：

loops : int

确定媒体文件在播放器停止前被播放的次数。设置为QMediaPlayer::Infinite 可使当前媒体文件无限循环播放。

默认值为1 。将此属性设置为0 不会产生任何效果。

访问函数：

通知信号：

[read-only] mediaStatus : MediaStatus

该属性保存当前媒体流的状态。

流状态描述了当前流的播放进度。

默认情况下，该属性为QMediaPlayer::NoMedia

访问函数：

通知信号：

[read-only] metaData : QMediaMetaData

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

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

访问函数：

通知信号：

[since 6.10] pitchCompensation : bool

该属性保存了媒体播放器的音高补偿状态。

指示音高补偿是否已启用。启用后，更改播放速率不会影响音频信号的音高。

默认值为：如果支持音高补偿，则为 `true `；否则为 `false`。

此枚举在 Qt 6.10 中引入。

访问函数：

通知器信号：

[read-only, since 6.10] pitchCompensationAvailability : const PitchCompensationAvailability

该属性表示当前QtMultimedia 后端是否支持音高补偿功能。

表示当前后端上QMediaPlayer 的音高补偿功能是否可用。

有关详细信息，请参阅QMediaPlayer::PitchCompensationAvailability 。

该枚举在 Qt 6.10 中引入。

访问函数：

[since 6.10] playbackOptions : QPlaybackOptions

用于配置媒体播放和解码的高级播放选项。

该属性提供了QPlaybackOptions API，可对媒体播放选项进行底层控制。虽然我们强烈建议使用QMediaPlayer 的默认设置，但在默认选项不理想的情况下，可使用此API针对特定使用场景优化媒体播放。

播放选项将在下次调用QMediaPlayer::setSource() 时生效。

此枚举类型自 Qt 6.10 起引入。

访问函数：

通知信号：

playbackRate : qreal

该属性保存当前媒体的播放速率。

该值是应用于媒体标准播放速率的倍数。默认情况下，该值为 1.0，表示媒体正在以标准速度播放。大于 1.0 的值将加快播放速度，而介于 0.0 和 1.0 之间的值则会减慢播放速度。不支持负播放速率。

并非所有播放服务都支持更改播放速率。快进或快退时音频和视频的状态及质量由框架定义。

访问函数：

通知信号：

[read-only] playbackState : PlaybackState

返回PlaybackState 。

访问函数：

通知器信号：

另请参阅 playing 。

[read-only, since 6.5] playing : bool

该属性用于指示媒体是否正在播放。

该枚举在 Qt 6.5 中引入。

访问函数：

通知信号：

另请参阅 playbackState 和PlayingState 。

position : qint64

该属性存储当前媒体的播放位置。

该值表示当前播放位置，以自媒体文件开头起计算的毫秒数表示。位置的周期性变化将通过positionChanged()信号进行指示。

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

访问函数：

通知信号：

[read-only] seekable : bool

该属性表示当前媒体的可寻址状态

如果支持寻址，则该属性为 true；否则为 false。该属性的状态在QMediaPlayer 对象的生命周期内可能会发生变化，请使用seekableChanged 信号来监视变化。

访问函数：

通知信号：

source : QUrl

该属性存储播放器对象当前正在使用的活动媒体源。

播放器对象将使用 `QUrl ` 来选择要播放的内容。

默认情况下，此属性的QUrl 为 null。

将此属性设置为空的QUrl 会导致播放器丢弃与当前媒体源相关的所有信息，并停止与该媒体相关的所有I/O操作。

访问函数：

通知器信号：

另请参阅 QUrl 。

[read-only] subtitleTracks : QList<QMediaMetaData>

列出媒体中可用的字幕轨道集。

返回的QMediaMetaData 描述了各个字幕轨道的属性。

访问函数：

通知信号：

videoOutput : QObject*

该属性用于指定媒体播放器将使用的视频输出设备。

媒体播放器只能连接一个视频输出，因此设置此属性将替换之前连接的视频输出。

将此属性设置为nullptr 将禁用视频输出。

访问函数：

通知信号：

[read-only] videoTracks : QList<QMediaMetaData>

列出媒体中可用的视频轨道集合。

返回的QMediaMetaData 描述了各个音轨的属性。

访问函数：

通知信号：