内容

公共类型
特性
公共函数
公共槽
信号
详细描述

QMediaPlayer 类

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

头：	#include <QMediaPlayer>
CMake:	find_package(Qt6 COMPONENTS Multimedia REQUIRED) target_link_libraries(mytarget PRIVATE Qt6::Multimedia)
qmake:	QT += multimedia
实例化：	MediaPlayer
继承：	QObject

所有成员列表，包括继承成员

公共类型

enum	Error { NoError, ResourceError, FormatError, NetworkError, AccessDeniedError }
enum	Loops { Infinite, Once }
enum	MediaStatus { NoMedia, LoadingMedia, LoadedMedia, StalledMedia, BufferingMedia, …, InvalidMedia }
enum	PlaybackState { StoppedState, PlayingState, PausedState }

特性

activeAudioTrack : int
activeSubtitleTrack : int
activeVideoTrack : int
audioOutput : QAudioOutput*
bufferProgress : const float
duration : const qint64
error : const Error
errorString : const QString
hasAudio : const bool

hasVideo : const bool
loops : int
mediaStatus : const MediaStatus
playbackRate : qreal
position : qint64
seekable : const bool
source : QUrl
videoOutput : QObject*

公共函数

	QMediaPlayer (QObject * parent = nullptr)
virtual	~QMediaPlayer ()
int	activeAudioTrack () const
int	activeSubtitleTrack () const
int	activeVideoTrack () const
QAudioOutput *	audioOutput () const
QList<QMediaMetaData>	audioTracks () const
float	bufferProgress () const
QMediaTimeRange	bufferedTimeRange () const
qint64	duration () const
QMediaPlayer::Error	error () const
QString	errorString () const
bool	hasAudio () const
bool	hasVideo () const
bool	isAvailable () const
bool	isSeekable () const
int	loops () const
QMediaPlayer::MediaStatus	mediaStatus () const
QMediaMetaData	metaData () const
qreal	playbackRate () const
QMediaPlayer::PlaybackState	playbackState () const
qint64	position () const
void	setActiveAudioTrack (int index )
void	setActiveSubtitleTrack (int index )
void	setActiveVideoTrack (int index )
void	setAudioOutput (QAudioOutput * output )
void	setLoops (int loops )
void	setVideoOutput (QObject *)
QUrl	source () const
const QIODevice *	sourceDevice () const
QList<QMediaMetaData>	subtitleTracks () const
QObject *	videoOutput () const
QList<QMediaMetaData>	videoTracks () const

公共槽

void	pause ()
void	play ()
void	setPlaybackRate (qreal rate )
void	setPosition (qint64 position )
void	setSource (const QUrl & source )
void	setSourceDevice (QIODevice * device , const QUrl & sourceUrl = QUrl())
void	stop ()

信号

void	activeTracksChanged ()
void	audioOutputChanged ()
void	bufferProgressChanged (float filled )
void	durationChanged (qint64 duration )
void	errorChanged ()
void	errorOccurred (QMediaPlayer::Error error , const QString & errorString )
void	hasAudioChanged (bool available )
void	hasVideoChanged (bool videoAvailable )
void	loopsChanged ()
void	mediaStatusChanged (QMediaPlayer::MediaStatus status )
void	metaDataChanged ()
void	playbackRateChanged (qreal rate )
void	playbackStateChanged (QMediaPlayer::PlaybackState newState )
void	positionChanged (qint64 position )
void	seekableChanged (bool seekable )
void	sourceChanged (const QUrl & media )
void	tracksChanged ()
void	videoOutputChanged ()

详细描述

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

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

QVideoWidget 可以用于 QMediaPlayer 为渲染视频。

另请参阅 QVideoWidget .

成员类型文档编制

enum QMediaPlayer:: Error

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

常量	值	描述
`QMediaPlayer::NoError`	`0`	没有出现错误。
`QMediaPlayer::ResourceError`	`1`	无法解析媒体资源。
`QMediaPlayer::FormatError`	`2`	不 (完全) 支持媒体资源格式。仍可能可以回放，但没有音频或视频组件。
`QMediaPlayer::NetworkError`	`3`	发生网络错误。
`QMediaPlayer::AccessDeniedError`	`4`	没有适当权限来播放媒体资源。

enum QMediaPlayer:: Loops

一些预定义常量对于 loops 特性。

常量	值	描述
`QMediaPlayer::Infinite`	`-1`	永远循环。
`QMediaPlayer::Once`	`1`	播放媒体一次 (默认)。

enum QMediaPlayer:: MediaStatus

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

常量	值	描述
`QMediaPlayer::NoMedia`	`0`	当前没有媒体。播放器处于 StoppedState .
`QMediaPlayer::LoadingMedia`	`1`	正加载当前媒体。播放器可能处于任何状态。
`QMediaPlayer::LoadedMedia`	`2`	当前媒体已加载。播放器处于 StoppedState .
`QMediaPlayer::StalledMedia`	`3`	当前媒体的回放已失速，由于缓冲不足或某些其它临时中断。播放器在 PlayingState or PausedState .
`QMediaPlayer::BufferingMedia`	`4`	播放器正在缓冲数据，但已缓冲足够数据，以便在不久的将来能继续回放。播放器在 PlayingState or PausedState .
`QMediaPlayer::BufferedMedia`	`5`	播放器已完全缓冲当前媒体。播放器处于 PlayingState or PausedState .
`QMediaPlayer::EndOfMedia`	`6`	回放已到达当前媒体结尾。播放器处于 StoppedState .
`QMediaPlayer::InvalidMedia`	`7`	当前媒体无法播放。播放器处于 StoppedState .

enum QMediaPlayer:: PlaybackState

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

常量	值	描述
`QMediaPlayer::StoppedState`	`0`	媒体播放器未播放内容，回放将从当前轨道的起始开始。
`QMediaPlayer::PlayingState`	`1`	媒体播放器目前正在播放内容。
`QMediaPlayer::PausedState`	`2`	媒体播放器已暂停回放，当前轨道的回放将从播放器暂停位置处再继续。

特性文档编制

activeAudioTrack : int

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

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

Set index to -1 以禁用所有音频轨道。

访问函数：

int	activeAudioTrack () const
void	setActiveAudioTrack (int index )

通知程序信号：

void	activeTracksChanged ()

activeSubtitleTrack : int

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

Set index to -1 以禁用字幕。

默认情况下，禁用字幕。

访问函数：

int	activeSubtitleTrack () const
void	setActiveSubtitleTrack (int index )

通知程序信号：

void	activeTracksChanged ()

activeVideoTrack : int

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

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

Set index to -1 以禁用所有视频轨道。

访问函数：

int	activeVideoTrack () const
void	setActiveVideoTrack (int index )

通知程序信号：

void	activeTracksChanged ()

audioOutput : QAudioOutput *

此特性保持媒体播放器所用的音频输出设备。

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

把此特性设为 nullptr 将禁用任何音频输出。

访问函数：

QAudioOutput *	audioOutput () const
void	setAudioOutput (QAudioOutput * output )

通知程序信号：

void	audioOutputChanged ()

`[read-only]` bufferProgress : const float

This property holds the percentage of the temporary buffer filled before playback begins or resumes, from 0 . (empty) to 1 . (full).

When the player object is buffering; this property holds the percentage of the temporary buffer that is filled. The buffer will need to reach 100% filled before playback can start or resume, at which time mediaStatus () 会返回 BufferedMedia or BufferingMedia . If the value is anything lower than 100 , mediaStatus () 会返回 StalledMedia .

访问函数：

float

bufferProgress () const

通知程序信号：

void	bufferProgressChanged (float filled )

另请参阅 mediaStatus ().

`[read-only]` duration : const qint64

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

The value is the total playback time in milliseconds of the current media. The value may change across the life time of the QMediaPlayer object and may not be available when initial playback begins, connect to the durationChanged () signal to receive status notifications.

访问函数：

qint64

duration () const

通知程序信号：

void	durationChanged (qint64 duration )

`[read-only]` error : const Error

此特性保持描述最后一个错误条件的字符串。

访问函数：

QMediaPlayer::Error

error () const

通知程序信号：

void	errorChanged ()

另请参阅 error ().

`[read-only]` errorString : const QString

This property holds a string describing the current error condition in more detail.

访问函数：

QString

errorString () const

通知程序信号：

void	errorChanged ()

`[read-only]` hasAudio : const bool

This property holds whether the media contains audio.

访问函数：

bool	hasAudio () const

通知程序信号：

void	hasAudioChanged (bool available )

`[read-only]` hasVideo : const bool

This property holds whether the media contains video.

访问函数：

bool	hasVideo () const

通知程序信号：

void	hasVideoChanged (bool videoAvailable )

loops : int

Determines how often the media is played before the player stops. Set to QMediaPlayer::Infinite to loop the current media file forever.

默认值为 1 。把此特性设为 0 不起作用。

访问函数：

int	loops () const
void	setLoops (int loops )

通知程序信号：

void	loopsChanged ()

`[read-only]` mediaStatus : const MediaStatus

此特性保持当前媒体流的状态。

流状态描述当前流的回放进展。

默认情况下此特性为 QMediaPlayer::NoMedia

访问函数：

QMediaPlayer::MediaStatus

mediaStatus () const

通知程序信号：

void	mediaStatusChanged (QMediaPlayer::MediaStatus status )

playbackRate : qreal

此特性保持当前媒体的回放速率。

This value is a multiplier applied to the media's standard play rate. By default this value is 1.0, indicating that the media is playing at the standard pace. Values higher than 1.0 will increase the rate of play. Values less than zero can be set and indicate the media should rewind at the multiplier of the standard pace.

Not all playback services support change of the playback rate. It is framework defined as to the status and quality of audio and video while fast forwarding or rewinding.

访问函数：

qreal	playbackRate () const
void	setPlaybackRate (qreal rate )

通知程序信号：

void	playbackRateChanged (qreal rate )

position : qint64

此特性保持当前媒体的回放位置。

The value is the current playback position, expressed in milliseconds since the beginning of the media. Periodically changes in the position will be indicated with the positionChanged () 信号。

若 seekable property is true, this property can be set to milliseconds.

访问函数：

qint64	position () const
void	setPosition (qint64 position )

通知程序信号：

void	positionChanged (qint64 position )

`[read-only]` seekable : const bool

此特性保持当前媒体的可寻址状态

若支持寻址，此特性为 true；否则为 false。此特性的状态可能改变，当跨存活时间在 QMediaPlayer 对象，使用 seekableChanged 信号以监视改变。

访问函数：

bool	isSeekable () const

通知程序信号：

void	seekableChanged (bool seekable )

source : QUrl

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

播放器对象将使用 QUrl for selection of the content to be played.

默认情况下,此特性拥有 null QUrl .

将此特性设为 null QUrl will cause the player to discard all information relating to the current media source and to cease all I/O operations related to that media.

访问函数：

QUrl	source () const
void	setSource (const QUrl & source )

通知程序信号：

void	sourceChanged (const QUrl & media )

另请参阅 QUrl .

videoOutput : QObject *

This property holds the video output to be used by the media player.

A media player can only have one video output attached, so setting this property will replace the previously connected video output.

把此特性设为 nullptr 将禁用视频输出。

访问函数：

QObject *	videoOutput () const
void	setVideoOutput (QObject *)

通知程序信号：

void	videoOutputChanged ()

成员函数文档编制

QMediaPlayer:: QMediaPlayer ( QObject * parent = nullptr)

构造 QMediaPlayer 实例作为子级对于 parent .

`[signal]` void QMediaPlayer:: bufferProgressChanged ( float filled )

Signals the amount of the local buffer filled as a number between 0 and 1.

注意： 通知程序信号对于特性 bufferProgress .

`[signal]` void QMediaPlayer:: durationChanged ( qint64 duration )

Signals the duration of the content has changed to duration ，表达 (以毫秒为单位)。

注意： 通知程序信号对于特性 duration .

`[signal]` void QMediaPlayer:: errorOccurred ( QMediaPlayer::Error error , const QString & errorString )

Signals that an error condition has occurred, with errorString containing a description of the error.

另请参阅 errorString ().

`[signal]` void QMediaPlayer:: hasAudioChanged ( bool available )

信号音频内容的可用性已改变成 available .

注意： 通知程序信号对于特性 hasAudio .

`[signal]` void QMediaPlayer:: hasVideoChanged ( bool videoAvailable )

Signals the availability of visual content has changed to videoAvailable .

注意： 通知程序信号对于特性 hasVideo .

`[signal]` void QMediaPlayer:: mediaStatusChanged ( QMediaPlayer::MediaStatus status )

信号 status 若当前媒体已改变。

注意： 通知程序信号对于特性 mediaStatus .

另请参阅 mediaStatus ().

`[slot]` void QMediaPlayer:: pause ()

暂停播放当前源。

另请参阅 play () 和 stop ().

`[slot]` void QMediaPlayer:: play ()

开始 (或再继续) 播放当前源。

另请参阅 pause () 和 stop ().

`[signal]` void QMediaPlayer:: playbackRateChanged ( qreal rate )

信号 playbackRate 已改变成 rate .

注意： 通知程序信号对于特性 playbackRate .

`[signal]` void QMediaPlayer:: positionChanged ( qint64 position )

发射信号若内容的位置已改变成 position ，表达 (以毫秒为单位)。

注意： 通知程序信号对于特性 position .

`[signal]` void QMediaPlayer:: seekableChanged ( bool seekable )

信号 seekable 播放器对象状态已改变。

注意： 通知程序信号对于特性 seekable .

`[slot]` void QMediaPlayer:: setSource (const QUrl & source )

设置当前 source .

将媒体设为 null QUrl will cause the player to discard all information relating to the current media source and to cease all I/O operations related to that media.

注意： This function returns immediately after recording the specified source of the media. It does not wait for the media to finish loading and does not check for errors. Listen for the mediaStatusChanged () 和 error () signals to be notified when the media is loaded and when an error occurs during loading.

注意： setter 函数对于特性 source .

另请参阅 source ().

`[slot]` void QMediaPlayer:: setSourceDevice ( QIODevice * device , const QUrl & sourceUrl = QUrl())

设置当前源 device .

媒体数据将读取自 device 。 sourceUrl can be provided to resolve additional information about the media, mime type etc. The device must be open and readable.

对于 macOS device 还应该可寻址。

另请参阅 sourceDevice ().

`[signal]` void QMediaPlayer:: sourceChanged (const QUrl & media )

发射信号当媒体源已变为 media .

注意： 通知程序信号对于特性 source .

`[slot]` void QMediaPlayer:: stop ()

停止播放，然后将播放位置重置到起始。

另请参阅 play () 和 pause ().

`[虚拟]` QMediaPlayer:: ~QMediaPlayer ()

销毁播放器对象。

QList < QMediaMetaData > QMediaPlayer:: audioTracks () const

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

QMediaMetaData 返回单个轨道的特性描述。

Different audio tracks can for example contain audio in different languages.

注意： getter 函数对于特性 audioTracks。

float QMediaPlayer:: bufferProgress () const

Returns a number betwee 0 and 1 when buffering data.

0 means that there is no buffered data available, playback is usually stalled in this case. Playback will resume once the buffer reaches 1, meaning enough data has been buffered to be able to resume playback.

bufferProgress() will always return 1 for local files.

注意： getter 函数对于特性 bufferProgress。

QMediaTimeRange QMediaPlayer:: bufferedTimeRange () const

返回 QMediaTimeRange 描述目前缓冲的数据。

When streaming media from a remote source, different parts of the media file can be available locally. The returned QMediaTimeRange object describes the time ranges that are buffered and available for immediate playback.

另请参阅 QMediaTimeRange .

qint64 QMediaPlayer:: duration () const

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

Returns 0 if the media player doesn't have a valid media file or stream. For live streams, the duration usually changes during playback as more data becomes available.

注意： getter 函数对于特性 duration。

QMediaPlayer::Error QMediaPlayer:: error () const

返回当前错误状态。

注意： getter 函数对于特性 error。

bool QMediaPlayer:: isAvailable () const

返回 true，若此平台支持媒体播放器。

bool QMediaPlayer:: isSeekable () const

Returns true if the media is seekable. Most file based media files are seekable, but live streams usually are not.

注意： getter 函数对于特性 seekable .

另请参阅 position .

QMediaMetaData QMediaPlayer:: metaData () const

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

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

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

注意： getter 函数对于特性 metaData。

qreal QMediaPlayer:: playbackRate () const

返回当前回放速率。

注意： getter 函数对于特性 playbackRate。

另请参阅 setPlaybackRate ().

qint64 QMediaPlayer:: position () const

Returns the current position inside the media being played back in ms.

Returns 0 if the media player doesn't have a valid media file or stream. For live streams, the duration usually changes during playback as more data becomes available.

注意： getter 函数对于特性 position。

另请参阅 setPosition ().

const QIODevice *QMediaPlayer:: sourceDevice () const

返回媒体数据的流源。

This is only valid if a stream was passed to setSource ().

另请参阅 setSourceDevice () 和 setSource ().

QList < QMediaMetaData > QMediaPlayer:: subtitleTracks () const

Lists the set of available subtitle tracks inside the media.

QMediaMetaData 返回单个轨道的特性描述。

注意： getter 函数对于特性 subtitleTracks。

QList < QMediaMetaData > QMediaPlayer:: videoTracks () const

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

QMediaMetaData 返回单个轨道的特性描述。

注意： getter 函数对于特性 videoTracks。

内容

QMediaPlayer 类

公共类型

特性

公共函数

公共槽

信号

详细描述

成员类型文档编制

enum QMediaPlayer:: Error

enum QMediaPlayer:: Loops

enum QMediaPlayer:: MediaStatus

enum QMediaPlayer:: PlaybackState

特性文档编制

activeAudioTrack : int

activeSubtitleTrack : int

activeVideoTrack : int

audioOutput : QAudioOutput *

[read-only] bufferProgress : const float

[read-only] duration : const qint64

[read-only] error : const Error

[read-only] errorString : const QString

[read-only] hasAudio : const bool

[read-only] hasVideo : const bool

loops : int

[read-only] mediaStatus : const MediaStatus

playbackRate : qreal

position : qint64

[read-only] seekable : const bool

source : QUrl

videoOutput : QObject *

成员函数文档编制

QMediaPlayer:: QMediaPlayer ( QObject * parent = nullptr)

[signal] void QMediaPlayer:: bufferProgressChanged ( float filled )

[signal] void QMediaPlayer:: durationChanged ( qint64 duration )

[signal] void QMediaPlayer:: errorOccurred ( QMediaPlayer::Error error , const QString & errorString )

[signal] void QMediaPlayer:: hasAudioChanged ( bool available )

[signal] void QMediaPlayer:: hasVideoChanged ( bool videoAvailable )

[signal] void QMediaPlayer:: mediaStatusChanged ( QMediaPlayer::MediaStatus status )

[slot] void QMediaPlayer:: pause ()

[slot] void QMediaPlayer:: play ()

[signal] void QMediaPlayer:: playbackRateChanged ( qreal rate )

[signal] void QMediaPlayer:: positionChanged ( qint64 position )

[signal] void QMediaPlayer:: seekableChanged ( bool seekable )

[slot] void QMediaPlayer:: setSource (const QUrl & source )

[slot] void QMediaPlayer:: setSourceDevice ( QIODevice * device , const QUrl & sourceUrl = QUrl())

[signal] void QMediaPlayer:: sourceChanged (const QUrl & media )

[slot] void QMediaPlayer:: stop ()

[虚拟] QMediaPlayer:: ~QMediaPlayer ()

QList < QMediaMetaData > QMediaPlayer:: audioTracks () const

float QMediaPlayer:: bufferProgress () const

QMediaTimeRange QMediaPlayer:: bufferedTimeRange () const

qint64 QMediaPlayer:: duration () const

QMediaPlayer::Error QMediaPlayer:: error () const

bool QMediaPlayer:: isAvailable () const

bool QMediaPlayer:: isSeekable () const

QMediaMetaData QMediaPlayer:: metaData () const

qreal QMediaPlayer:: playbackRate () const

qint64 QMediaPlayer:: position () const

const QIODevice *QMediaPlayer:: sourceDevice () const

QList < QMediaMetaData > QMediaPlayer:: subtitleTracks () const

QList < QMediaMetaData > QMediaPlayer:: videoTracks () const

`[read-only]` bufferProgress : const float

`[read-only]` duration : const qint64

`[read-only]` error : const Error

`[read-only]` errorString : const QString

`[read-only]` hasAudio : const bool

`[read-only]` hasVideo : const bool

`[read-only]` mediaStatus : const MediaStatus

`[read-only]` seekable : const bool

`[signal]` void QMediaPlayer:: bufferProgressChanged ( float filled )

`[signal]` void QMediaPlayer:: durationChanged ( qint64 duration )

`[signal]` void QMediaPlayer:: errorOccurred ( QMediaPlayer::Error error , const QString & errorString )

`[signal]` void QMediaPlayer:: hasAudioChanged ( bool available )

`[signal]` void QMediaPlayer:: hasVideoChanged ( bool videoAvailable )

`[signal]` void QMediaPlayer:: mediaStatusChanged ( QMediaPlayer::MediaStatus status )

`[slot]` void QMediaPlayer:: pause ()

`[slot]` void QMediaPlayer:: play ()

`[signal]` void QMediaPlayer:: playbackRateChanged ( qreal rate )

`[signal]` void QMediaPlayer:: positionChanged ( qint64 position )

`[signal]` void QMediaPlayer:: seekableChanged ( bool seekable )

`[slot]` void QMediaPlayer:: setSource (const QUrl & source )

`[slot]` void QMediaPlayer:: setSourceDevice ( QIODevice * device , const QUrl & sourceUrl = QUrl())

`[signal]` void QMediaPlayer:: sourceChanged (const QUrl & media )

`[slot]` void QMediaPlayer:: stop ()

`[虚拟]` QMediaPlayer:: ~QMediaPlayer ()