QMediaPlayer 类

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

头: #include <QMediaPlayer>
CMake: find_package(Qt6 REQUIRED COMPONENTS Multimedia)
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 }

特性

公共函数

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 isPlaying () 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 *)
void setVideoSink (QVideoSink * sink )
QUrl source () const
const QIODevice * sourceDevice () const
QList<QMediaMetaData> subtitleTracks () const
QObject * videoOutput () const
QVideoSink * videoSink () 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 playingChanged (bool playing )
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, &QMediaPlayer::positionChanged, this, &MediaExample::positionChanged);
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 The media player is currently playing content. This indicates the same as the playing 特性。
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] audioTracks : const QList < QMediaMetaData >

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

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

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

访问函数:

QList<QMediaMetaData> audioTracks () const

通知程序信号:

void tracksChanged ()

[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 )

[read-only] metaData : const QMediaMetaData

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

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

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

访问函数:

QMediaMetaData metaData () const

通知程序信号:

void metaDataChanged ()

playbackRate : qreal

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

This value is a multiplier applied to the media's standard playback rate. By default this value is 1.0, indicating that the media is playing at the standard speed. Values higher than 1.0 will increase the playback speed, while values between 0.0 and 1.0 results in slower playback. Negative playback rates are not supported.

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 )

[read-only] playbackState : const PlaybackState

返回 PlaybackState .

访问函数:

QMediaPlayer::PlaybackState playbackState () const

通知程序信号:

void playbackStateChanged (QMediaPlayer::PlaybackState newState )

另请参阅 playing .

[read-only, since 6.5] playing : const bool

此特性保持媒体是否在播放。

该特性在 Qt 6.5 引入。

访问函数:

bool isPlaying () const

通知程序信号:

void playingChanged (bool playing )

另请参阅 playbackState and PlayingState .

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 .

[read-only] subtitleTracks : const QList < QMediaMetaData >

Lists the set of available subtitle tracks inside the media.

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

访问函数:

QList<QMediaMetaData> subtitleTracks () const

通知程序信号:

void tracksChanged ()

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

[read-only] videoTracks : const QList < QMediaMetaData >

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

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

访问函数:

QList<QMediaMetaData> videoTracks () const

通知程序信号:

void tracksChanged ()

成员函数文档编制

[explicit] QMediaPlayer:: QMediaPlayer ( QObject * parent = nullptr)

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

[virtual noexcept] QMediaPlayer:: ~QMediaPlayer ()

销毁播放器对象。

float QMediaPlayer:: bufferProgress () const

Returns a number between 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。

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

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

注意: 通知程序信号对于特性 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。

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

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

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

QMediaPlayer::Error QMediaPlayer:: error () const

返回当前错误状态。

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

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

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 .

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

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

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

另请参阅 mediaStatus ().

[slot] void QMediaPlayer:: pause ()

暂停播放当前源。

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

[slot] void QMediaPlayer:: play ()

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

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

qreal QMediaPlayer:: playbackRate () const

返回当前回放速率。

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

另请参阅 setPlaybackRate ().

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

信号 playbackRate 已改变成 rate .

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

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

[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. Setting the media will stop the playback.

注意: 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.

注意: FFmpeg, used by the FFmpeg media backend, restricts use of nested protocols for security reasons. In controlled environments where all inputs are trusted, the list of approved protocols can be overridden using the QT_FFMPEG_PROTOCOL_WHITELIST environment variable. This environment variable is Qt's private API and can change between patch releases without notice.

注意: 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 还应该可寻址。

注意: 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 if an error occurs during loading.

另请参阅 sourceDevice ().

void QMediaPlayer:: setVideoSink ( QVideoSink * sink )

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

另请参阅 videoSink ().

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

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

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

const QIODevice *QMediaPlayer:: sourceDevice () const

返回媒体数据的流源。

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

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

[slot] void QMediaPlayer:: stop ()

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

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

QVideoSink *QMediaPlayer:: videoSink () const

返回 QVideoSink 实例。

另请参阅 setVideoSink ().