PySide6.QtMultimedia.QMediaPlayer

class QMediaPlayer

QMediaPlayer 类允许播放媒体文件。更多…

PySide6.QtMultimedia.QMediaPlayer 的继承图

概要

属性

方法

插槽

信号

注意

本文档可能包含从C++自动翻译到Python的代码片段。我们始终欢迎对代码片段翻译的贡献。如果您发现翻译问题，您也可以通过在我们的https:/bugreports.qt.io/projects/PYSIDE上创建工单来告知我们。

详细描述

警告

本节包含从C++自动翻译到Python的代码片段，可能包含错误。

QMediaPlayer 类是一个高级媒体播放类。它可以用于播放音频或视频媒体文件。要播放的内容被指定为一个 QUrl 对象。

player = QMediaPlayer()
audioOutput = QAudioOutput()
player.setAudioOutput(audioOutput)
player.positionChanged.connect(self.positionChanged)
player.setSource(QUrl.fromLocalFile("/Users/me/Music/coolsong.mp3"))
audioOutput.setVolume(50)
player.play()

QVideoWidget 可以与 QMediaPlayer 一起用于视频渲染。

另请参阅

QVideoWidget

class PlaybackState

定义媒体播放器的当前状态。

常量

描述

QMediaPlayer.StoppedState

媒体播放器未播放内容，播放将从当前曲目的开头开始。

QMediaPlayer.PlayingState

媒体播放器当前正在播放内容。这与playing属性表示相同。

QMediaPlayer.PausedState

媒体播放器已暂停播放，当前曲目的播放将从播放器暂停的位置恢复。

在版本6.1中添加。

class MediaStatus

定义媒体播放器当前媒体的状态。

常量

描述

QMediaPlayer.NoMedia

当前没有媒体。播放器处于StoppedState状态。

QMediaPlayer.LoadingMedia

当前媒体正在加载中。播放器可能处于任何状态。

QMediaPlayer.LoadedMedia

当前媒体已加载。播放器处于StoppedState状态。

QMediaPlayer.StalledMedia

当前媒体的播放由于缓冲不足或其他临时中断而停滞。播放器处于PlayingState或PausedState。

QMediaPlayer.BufferingMedia

播放器正在缓冲数据，但已经有足够的数据缓冲，可以在不久的将来继续播放。播放器处于PlayingState或PausedState。

QMediaPlayer.BufferedMedia

播放器已经完全缓冲了当前媒体。播放器处于PlayingState或PausedState状态。

QMediaPlayer.EndOfMedia

播放已达到当前媒体的末尾。播放器处于StoppedState。

QMediaPlayer.InvalidMedia

当前媒体无法播放。播放器处于StoppedState。
class Error

定义媒体播放器错误条件。

常量

描述

QMediaPlayer.NoError

没有发生错误。

QMediaPlayer.ResourceError

无法解析媒体资源。

QMediaPlayer.FormatError

媒体资源的格式不受（完全）支持。播放可能仍然可行，但没有音频或视频组件。

QMediaPlayer.NetworkError

发生了一个网络错误。

QMediaPlayer.AccessDeniedError

没有适当的权限来播放媒体资源。
class Loops

(继承自 enum.IntEnum) 一些为 loops 属性预定义的常量。

常量

描述

QMediaPlayer.Infinite

无限循环。

QMediaPlayer.Once

播放媒体一次（默认）。

在版本6.2.3中添加。

注意

当使用from __feature__ import true_property时，属性可以直接使用，否则通过访问器函数使用。

property activeAudioTrackᅟ: int

此属性返回当前活动的音轨。

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

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

Access functions:
property activeSubtitleTrackᅟ: int

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

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

默认情况下，字幕是禁用的。

Access functions:
property activeVideoTrackᅟ: int

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

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

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

Access functions:
property audioBufferOutputᅟ: QAudioBufferOutput

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

设置音频缓冲区 output 到媒体播放器。

如果指定了QAudioBufferOutput并且媒体源包含音频流，媒体播放器将发出信号audioBufferReceived，其中包含解码后的音频数据的音频缓冲区。在音频流的末尾，QMediaPlayer会发出一个空的QAudioBuffer。

QMediaPlayer 在将匹配的数据推送到音频输出时，同时发出音频缓冲区。然而，由于音频缓冲的原因，声音可能会有轻微的延迟。

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

利用 QAudioBufferOutput 与 QMediaPlayer 的潜在用例可能是：

  • 音频可视化。如果媒体播放器的播放速率不是1，您可以根据可视化工具的要求缩放输出图像的尺寸或图像更新间隔。

  • 任何AI声音处理，例如语音识别。

  • 将数据发送到外部音频输出。应考虑播放速率变化、与视频的同步以及在停止和搜索时的手动刷新。除非有充分的理由，否则我们不建议为此目的使用音频缓冲区输出。

Access functions:
property audioOutputᅟ: QAudioOutput

此属性保存媒体播放器使用的音频输出设备。

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

将此属性设置为nullptr将禁用任何音频输出。

Access functions:
property audioTracksᅟ: list of QMediaMetaData

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

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

不同的音轨可以包含不同语言的音频。

Access functions:
property bufferProgressᅟ: float

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

当播放器对象正在缓冲时；此属性保存临时缓冲区的填充百分比。在播放可以开始或恢复之前，缓冲区需要达到100%的填充，此时mediaStatus()将返回BufferedMedia或BufferingMedia。如果值低于100，mediaStatus()将返回StalledMedia。

另请参阅

mediaStatus()

Access functions:
property durationᅟ: int

此属性保存当前媒体的持续时间。

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

Access functions:
property errorᅟ: QMediaPlayer.Error

此属性包含描述最后一个错误条件的字符串。

另请参阅

error()

Access functions:
property errorStringᅟ: str

此属性包含一个字符串，用于更详细地描述当前错误条件。

Access functions:
property hasAudioᅟ: bool

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

Access functions:
property hasVideoᅟ: bool

此属性表示媒体是否包含视频。

Access functions:
property loopsᅟ: int

确定媒体在播放器停止之前播放的频率。设置为Infinite以无限循环播放当前媒体文件。

默认值为1。将此属性设置为0无效。

Access functions:
property mediaStatusᅟ: QMediaPlayer.MediaStatus

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

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

默认情况下，此属性为 NoMedia

Access functions:
property metaDataᅟ: QMediaMetaData

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

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

注意

Windows 实现仅提供位于本地文件系统上的媒体的元数据。

Access functions:
property playbackRateᅟ: float

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

此值是一个应用于媒体标准播放速度的乘数。默认情况下，此值为1.0，表示媒体以标准速度播放。大于1.0的值将增加播放速度，而介于0.0和1.0之间的值将导致播放速度变慢。不支持负的播放速率。

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

Access functions:
property playbackStateᅟ: QMediaPlayer.PlaybackState

返回 PlaybackState 。

另请参阅

playing

Access functions:
property playingᅟ: bool

此属性表示媒体是否正在播放。

Access functions:
property positionᅟ: int

此属性保存当前媒体的播放位置。

该值是当前的播放位置，以毫秒表示，从媒体开始计算。位置的周期性变化将通过positionChanged()信号指示。

如果 seekable 属性为 true，则此属性可以设置为毫秒。

Access functions:
property seekableᅟ: bool

此属性保存当前媒体的可搜索状态。

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

Access functions:
property sourceᅟ: QUrl

此属性保存播放器对象正在使用的活动媒体源。

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

默认情况下，此属性具有一个空的 QUrl。

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

另请参阅

QUrl

Access functions:
property subtitleTracksᅟ: list of QMediaMetaData

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

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

Access functions:
property videoOutputᅟ: QObject

此属性保存媒体播放器使用的视频输出。

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

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

Access functions:
property videoTracksᅟ: list of QMediaMetaData

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

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

Access functions:
__init__([parent=None])
Parameters:

父对象 – QObject

构造一个QMediaPlayer实例作为parent的子对象。

activeAudioTrack()
Return type:

整数

另请参阅

setActiveAudioTrack()

属性 activeAudioTrackᅟ 的获取器。

activeSubtitleTrack()
Return type:

整数

另请参阅

setActiveSubtitleTrack()

属性 activeSubtitleTrackᅟ 的获取器。

activeTracksChanged()

属性 activeAudioTrackᅟ 的通知信号。

activeVideoTrack()
Return type:

整数

另请参阅

setActiveVideoTrack()

属性 activeVideoTrackᅟ 的获取器。

audioBufferOutput()
Return type:

QAudioBufferOutput

另请参阅

setAudioBufferOutput()

属性 audioBufferOutputᅟ 的获取器。

audioBufferOutputChanged()

属性 audioBufferOutputᅟ 的通知信号。

audioOutput()
Return type:

QAudioOutput

另请参阅

setAudioOutput()

属性 audioOutputᅟ 的获取器。

audioOutputChanged()

属性 audioOutputᅟ 的通知信号。

audioTracks()
Return type:

QMediaMetaData的列表

属性 audioTracksᅟ 的获取器。

bufferProgress()
Return type:

浮点数

在缓冲数据时返回一个介于0和1之间的数字。

0 表示没有可用的缓冲数据，通常在这种情况下播放会暂停。一旦缓冲区达到 1，播放将恢复，这意味着已经缓冲了足够的数据以能够恢复播放。

对于本地文件，bufferProgress() 将始终返回 1。

属性 bufferProgressᅟ 的获取器。

bufferProgressChanged(progress)
Parameters:

progress – 浮点数

表示本地缓冲区的填充量，作为一个介于0和1之间的数字。

属性 bufferProgressᅟ 的通知信号。

bufferedTimeRange()
Return type:

QMediaTimeRange

返回一个QMediaTimeRange，描述当前缓冲的数据。

当从远程源流式传输媒体时，媒体文件的不同部分可以在本地可用。返回的QMediaTimeRange对象描述了已缓冲并可立即播放的时间范围。

另请参阅

QMediaTimeRange

duration()
Return type:

整数

返回当前媒体的持续时间，单位为毫秒。

如果媒体播放器没有有效的媒体文件或流，则返回0。对于直播流，随着更多数据的可用，播放期间的持续时间通常会发生变化。

属性 durationᅟ 的获取器。

durationChanged(duration)
Parameters:

duration – int

表示内容的持续时间已更改为duration，以毫秒表示。

属性 durationᅟ 的通知信号。

error()
Return type:

错误

返回当前的错误状态。

属性 errorᅟ 的获取器。

errorChanged()

属性 errorᅟ 的通知信号。

errorOccurred(error, errorString)
Parameters:

  • 错误 – Error

  • errorString – str

表示发生了error条件，其中errorString包含错误的描述。

另请参阅

errorString()

errorString()
Return type:

字符串

属性 errorStringᅟ 的获取器。

hasAudio()
Return type:

布尔

属性 hasAudioᅟ 的获取器。

hasAudioChanged(available)
Parameters:

可用 – bool

音频内容的可用性已更改为available。

属性 hasAudioᅟ 的通知信号。

hasVideo()
Return type:

布尔

属性 hasVideoᅟ 的获取器。

hasVideoChanged(videoAvailable)
Parameters:

videoAvailable – 布尔值

视觉内容的可用性已更改为 videoAvailable。

属性 hasVideoᅟ 的通知信号。

isAvailable()
Return type:

布尔

如果此平台支持媒体播放器，则返回true。

isPlaying()
Return type:

布尔

属性 playingᅟ 的获取器。

isSeekable()
Return type:

布尔

如果媒体是可搜索的，则返回true。大多数基于文件的媒体文件是可搜索的，但实时流通常不可搜索。

另请参阅

position

属性 seekableᅟ 的获取器。

loops()
Return type:

整数

另请参阅

setLoops()

属性 loopsᅟ 的获取器。

loopsChanged()

属性 loopsᅟ 的通知信号。

mediaStatus()
Return type:

MediaStatus

属性 mediaStatusᅟ 的获取器。

mediaStatusChanged(status)
Parameters:

状态 – MediaStatus

表示当前媒体的status状态已发生变化。

另请参阅

mediaStatus()

属性 mediaStatusᅟ 的通知信号。

metaData()
Return type:

QMediaMetaData

属性 metaDataᅟ 的获取器。

metaDataChanged()

属性 metaDataᅟ 的通知信号。

pause()

暂停播放当前源。

另请参阅

play() stop()

play()

开始或继续播放当前源。

另请参阅

pause() stop()

playbackRate()
Return type:

浮点数

返回当前的播放速率。

另请参阅

setPlaybackRate()

属性 playbackRateᅟ 的获取器。

playbackRateChanged(rate)
Parameters:

rate – 浮点数

表示playbackRate已更改为rate。

属性 playbackRateᅟ 的通知信号。

playbackState()
Return type:

PlaybackState

属性 playbackStateᅟ 的获取器。

playbackStateChanged(newState)
Parameters:

newState – PlaybackState

属性 playbackStateᅟ 的通知信号。

playingChanged(playing)
Parameters:

playing – 布尔值

属性 playingᅟ 的通知信号。

position()
Return type:

整数

返回媒体播放中当前位置，单位为毫秒。

如果媒体播放器没有有效的媒体文件或流，则返回0。对于直播流，随着更多数据的可用，播放期间的持续时间通常会发生变化。

另请参阅

setPosition()

属性 positionᅟ 的获取器。

positionChanged(position)
Parameters:

position – int

表示内容的位置已更改为position，以毫秒表示。

属性 positionᅟ 的通知信号。

seekableChanged(seekable)
Parameters:

seekable – 布尔值

表示播放器对象的seekable状态已更改。

属性 seekableᅟ 的通知信号。

setActiveAudioTrack(index)
Parameters:

索引 – int

另请参阅

activeAudioTrack()

属性 activeAudioTrackᅟ 的设置器。

setActiveSubtitleTrack(index)
Parameters:

索引 – int

另请参阅

activeSubtitleTrack()

属性 activeSubtitleTrackᅟ 的设置器。

setActiveVideoTrack(index)
Parameters:

索引 – int

另请参阅

activeVideoTrack()

属性 activeVideoTrackᅟ 的设置器。

setAudioBufferOutput(output)
Parameters:

输出 – QAudioBufferOutput

另请参阅

audioBufferOutput()

属性 audioBufferOutputᅟ 的设置器。

setAudioOutput(output)
Parameters:

输出 – QAudioOutput

另请参阅

audioOutput()

属性 audioOutputᅟ 的设置器。

setLoops(loops)
Parameters:

循环次数 – int

另请参阅

loops()

属性 loopsᅟ 的设置器。

setPlaybackRate(rate)
Parameters:

rate – 浮点数

另请参阅

playbackRate()

属性 playbackRateᅟ 的设置器。

setPosition(position)
Parameters:

position – int

另请参阅

position()

属性 positionᅟ 的设置器。

setSource(source)
Parameters:

source – QUrl

设置当前的source。

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

注意

此函数在记录指定的媒体源后立即返回。它不会等待媒体加载完成，也不会检查错误。请监听mediaStatusChanged()和error()信号，以便在媒体加载完成或加载过程中发生错误时收到通知。

注意

FFmpeg，由FFmpeg媒体后端使用，出于安全原因限制了嵌套协议的使用。在所有输入都受信任的受控环境中，可以使用QT_FFMPEG_PROTOCOL_WHITELIST环境变量覆盖已批准的协议列表。此环境变量是Qt的私有API，可能会在补丁版本之间更改而不另行通知。

另请参阅

source()

属性 sourceᅟ 的设置器。

setSourceDevice(device[, sourceUrl=QUrl()])
Parameters:

设置当前源device。

媒体数据将从device读取。可以提供sourceUrl来解析有关媒体的附加信息，如MIME类型等。device必须已打开且可读。

对于macOS，device 也应该是可寻址的。

注意

此函数在记录指定的媒体源后立即返回。它不会等待媒体加载完成，也不会检查错误。请监听mediaStatusChanged()和error()信号，以便在媒体加载完成时收到通知，以及在加载过程中发生错误时收到通知。

另请参阅

sourceDevice()

setVideoOutput(arg__1)
Parameters:

arg__1 – QObject

另请参阅

videoOutput()

属性 videoOutputᅟ 的设置器。

setVideoSink(sink)
Parameters:

sink – QVideoSink

将 sink 设置为 QVideoSink 实例以检索视频数据。

另请参阅

videoSink()

source()
Return type:

QUrl

另请参阅

setSource()

属性 sourceᅟ 的获取器。

sourceChanged(media)
Parameters:

媒体 – QUrl

表示媒体源已更改为 media。

属性 sourceᅟ 的通知信号。

sourceDevice()
Return type:

QIODevice

返回媒体数据的流源。

这仅在流被传递给 setSource() 时有效。

stop()

停止播放，并将播放位置重置到开始处。

另请参阅

play() pause()

subtitleTracks()
Return type:

QMediaMetaData的列表

属性 subtitleTracksᅟ 的获取器。

tracksChanged()

属性 audioTracksᅟ 的通知信号。

videoOutput()
Return type:

QObject

另请参阅

setVideoOutput()

属性 videoOutputᅟ 的获取器。

videoOutputChanged()

属性 videoOutputᅟ 的通知信号。

videoSink()
Return type:

QVideoSink

返回QVideoSink实例。

另请参阅

setVideoSink()

videoTracks()
Return type:

QMediaMetaData的列表

属性 videoTracksᅟ 的获取器。