就业培训     下载中心     Wiki     联络
登录   注册
  1. 首页
  2. Qt 5.12.12
  3. Qt Multimedia
  4. C++ 类
  5. QMediaPlayer

内容

QMediaPlayer 类

The QMediaPlayer class allows the playing of a media source. 更多...

头： #include <QMediaPlayer>
qmake: QT += multimedia
继承： QMediaObject

公共类型

enum Error { NoError, ResourceError, FormatError, NetworkError, AccessDeniedError, ServiceMissingError }
enum Flag { LowLatency, StreamPlayback, VideoSurface }
flags Flags
enum MediaStatus { UnknownMediaStatus, NoMedia, LoadingMedia, LoadedMedia, ..., InvalidMedia }
enum State { StoppedState, PlayingState, PausedState }

特性

公共函数

QMediaPlayer (QObject * parent = nullptr, QMediaPlayer::Flags flags = Flags())
virtual ~QMediaPlayer ()
QAudio::Role audioRole () const
int bufferStatus () const
QMediaContent currentMedia () const
QNetworkConfiguration currentNetworkConfiguration () const
QString customAudioRole () const
qint64 duration () const
QMediaPlayer::Error error () const
QString errorString () const
bool isAudioAvailable () const
bool isMuted () const
bool isSeekable () const
bool isVideoAvailable () const
QMediaContent media () const
QMediaPlayer::MediaStatus mediaStatus () const
const QIODevice * mediaStream () const
qreal playbackRate () const
QMediaPlaylist * playlist () const
qint64 position () const
void setAudioRole (QAudio::Role audioRole )
void setCustomAudioRole (const QString & audioRole )
void setVideoOutput (QVideoWidget * output )
void setVideoOutput (QGraphicsVideoItem * output )
void setVideoOutput (QAbstractVideoSurface * surface )
QMediaPlayer::State state () const
QList<QAudio::Role> supportedAudioRoles () const
QStringList supportedCustomAudioRoles () const
int volume () const

重实现公共函数

virtual QMultimedia::AvailabilityStatus availability () const override

公共槽

void pause ()
void play ()
void setMedia (const QMediaContent & media , QIODevice * stream = nullptr)
void setMuted (bool muted )
void setNetworkConfigurations (const QList<QNetworkConfiguration> & configurations )
void setPlaybackRate (qreal rate )
void setPlaylist (QMediaPlaylist * playlist )
void setPosition (qint64 position )
void setVolume (int volume )
void stop ()

信号

void audioAvailableChanged (bool available )
void audioRoleChanged (QAudio::Role role )
void bufferStatusChanged (int percentFilled )
void currentMediaChanged (const QMediaContent & media )
void customAudioRoleChanged (const QString & role )
void durationChanged (qint64 duration )
void error (QMediaPlayer::Error error )
void mediaChanged (const QMediaContent & media )
void mediaStatusChanged (QMediaPlayer::MediaStatus status )
void mutedChanged (bool muted )
void networkConfigurationChanged (const QNetworkConfiguration & configuration )
void playbackRateChanged (qreal rate )
void positionChanged (qint64 position )
void seekableChanged (bool seekable )
void stateChanged (QMediaPlayer::State state )
void videoAvailableChanged (bool videoAvailable )
void volumeChanged (int volume )

静态公共成员

QMultimedia::SupportEstimate hasSupport (const QString & mimeType , const QStringList & codecs = QStringList(), QMediaPlayer::Flags flags = Flags())
const QMetaObject staticMetaObject

额外继承成员

详细描述

The QMediaPlayer class allows the playing of a media source.

The QMediaPlayer class is a high level media playback class. It can be used to playback such content as songs, movies and internet radio. The content to playback is specified as a QMediaContent 对象，可以认为是附加了额外信息的主 URL 或典型 URL。当提供采用 QMediaContent 回放也许可以开始。 

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

QVideoWidget 可以使用 QMediaPlayer for video rendering and QMediaPlaylist 为访问播放列表功能。 

playlist = new QMediaPlaylist;
playlist->addMedia(QUrl("http://example.com/movie1.mp4"));
playlist->addMedia(QUrl("http://example.com/movie2.mp4"));
playlist->addMedia(QUrl("http://example.com/movie3.mp4"));
playlist->setCurrentIndex(1);
player = new QMediaPlayer;
player->setPlaylist(playlist);
videoWidget = new QVideoWidget;
player->setVideoOutput(videoWidget);
videoWidget->show();
player->play();

由于 QMediaPlayer 是 QMediaObject ，可以使用几个 QMediaObject 函数对于像这样的事情：

另请参阅 QMediaObject , QMediaService , QVideoWidget ，和 QMediaPlaylist .

成员类型文档编制

enum QMediaPlayer:: Error

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

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

enum QMediaPlayer:: Flag
flags QMediaPlayer:: Flags

常量 值 描述
QMediaPlayer::LowLatency 0x01 播放器期望用于简单音频格式，但回放应该始于没有显著延迟。这种回放服务可以用于蜂鸣声、铃声、等。
QMediaPlayer::StreamPlayback 0x02 播放器期望播放 QIODevice 基流。若传递给 QMediaPlayer 构造函数，将选择支持流回放的服务。
QMediaPlayer::VideoSurface 0x04 播放器期望能够渲染到 QAbstractVideoSurface output .

Flags 类型是 typedef 对于 QFlags <Flag>。它存储 Flag 值的 OR (或) 组合。

enum QMediaPlayer:: MediaStatus

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

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

enum QMediaPlayer:: State

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

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

特性文档编制

audioAvailable : const bool

此特性保持当前媒体的音频可用性状态。

由于存活时间对于 QMediaPlayer 可以长于回放的某个 QMediaContent ，此特性可能随时间推移改变， audioAvailableChanged 信号可以用于监视其状态。

访问函数：

bool isAudioAvailable () const

通知程序信号：

void audioAvailableChanged (bool available )

audioRole : QAudio::Role

此特性保持由媒体播放器播放的音频流角色。

可以把它设为正播放的指定音频类型，允许系统做出适当决定，当涉及到音量、路由、或后期处理时。

必须设置音频角色，先于调用 setMedia ().

customAudioRole 被清零，当把此特性设为任何值除了 QAudio::CustomRole .

该特性在 Qt 5.6 引入。

访问函数：

QAudio::Role audioRole () const
void setAudioRole (QAudio::Role audioRole )

通知程序信号：

void audioRoleChanged (QAudio::Role role )

另请参阅 supportedAudioRoles ().

bufferStatus : const int

此特性保持填充临时缓冲的百分比，在回放开始 (或再继续) 前。从 0 (空) 到 100 (完整)。

当缓冲播放器对象时，此特性保持填充临时缓冲的百分比。在回放可以开始 (或再继续) 前，填充缓冲需要达到 100%，此时 mediaStatus () 会返回 BufferedMedia or BufferingMedia 。若是任何值小于 100 , mediaStatus () 会返回 StalledMedia .

访问函数：

int bufferStatus () const

通知程序信号：

void bufferStatusChanged (int percentFilled )

另请参阅 mediaStatus ().

currentMedia : const QMediaContent

此特性保持由播放器对象，正播放的当前活动媒体内容。该值可以不同于 QMediaPlayer::media 特性，若使用播放列表。在此情况下，currentMedia 指示播放器正处理的当前媒体内容，当 QMediaPlayer::media 特性包含原始播放列表。

访问函数：

QMediaContent currentMedia () const

通知程序信号：

void currentMediaChanged (const QMediaContent & media )

另请参阅 QMediaContent and media ().

customAudioRole : QString

此特性保持由媒体播放器播放的音频流角色。

可以设置它以指定正播放的音频类型，当后端支持 Qt 未知的音频角色时。指定角色允许系统做出适当决定，当涉及音量、路由、或后处理时。

必须设置音频角色，先于调用 setMedia ().

audioRole 被设为 QAudio::CustomRole 当此特性有设置。

该特性在 Qt 5.11 引入。

访问函数：

QString customAudioRole () const
void setCustomAudioRole (const QString & audioRole )

通知程序信号：

void customAudioRoleChanged (const QString & role )

另请参阅 supportedCustomAudioRoles ().

duration : const qint64

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

值是当前媒体的总回放时间 (以毫秒为单位)。值可能跨存活时间改变对于 QMediaPlayer 对象且可能不可用 (当初始回放开始时)，连接到 durationChanged () 信号以接收状态通知。

访问函数：

qint64 duration () const

通知程序信号：

void durationChanged (qint64 duration )

error : const QString

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

访问函数：

QString errorString () const

另请参阅 error ().

media : QMediaContent

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

播放器对象将使用 QMediaContent 为选择要播放的内容。

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

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

访问函数：

QMediaContent media () const
void setMedia (const QMediaContent & media , QIODevice * stream = nullptr)

通知程序信号：

void mediaChanged (const QMediaContent & media )

另请参阅 QMediaContent and currentMedia ().

mediaStatus : const MediaStatus

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

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

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

访问函数：

QMediaPlayer::MediaStatus mediaStatus () const

通知程序信号：

void mediaStatusChanged (QMediaPlayer::MediaStatus status )

另请参阅 state .

muted : bool

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

值将为 true 若回放音量静音；否则 false。

访问函数：

bool isMuted () const
void setMuted (bool muted )

通知程序信号：

void mutedChanged (bool muted )

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 will rewind at the multiplier of the standard pace.

并非所有回放服务，都支持回放速率的改变。它由音频和视频状态和品质的框架定义，当快进 (或倒带) 时。

访问函数：

qreal playbackRate () const
void setPlaybackRate (qreal rate )

通知程序信号：

void playbackRateChanged (qreal rate )

playlist : QMediaPlaylist *

此特性保持播放器对象正使用的媒体播放列表。

播放器对象将使用当前播放列表项，为选择要播放的内容。

默认情况下，此特性被设为 null。

若把媒体播放列表用作源， QMediaPlayer::currentMedia is updated with a current playlist item. The current source should be selected with QMediaPlaylist::setCurrentIndex (int) instead of QMediaPlayer::setMedia (), otherwise the current playlist will be discarded.

访问函数：

QMediaPlaylist * playlist () const
void setPlaylist (QMediaPlaylist * playlist )

另请参阅 QMediaContent .

position : qint64

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

值是当前回放位置，以从媒体开始起的毫秒数表达。将指示位置的周期性变化采用信号 positionChanged ()，可以设置更新间隔采用 QMediaObject 的方法 setNotifyInterval ().

访问函数：

qint64 position () const
void setPosition (qint64 position )

通知程序信号：

void positionChanged (qint64 position )

seekable : const bool

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

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

访问函数：

bool isSeekable () const

通知程序信号：

void seekableChanged (bool seekable )

state : const State

此特性保持媒体播放器的回放状态。

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

访问函数：

QMediaPlayer::State state () const

通知程序信号：

void stateChanged (QMediaPlayer::State state )

另请参阅 mediaStatus (), play (), pause ()，和 stop ().

videoAvailable : const bool

此特性保持用于当前媒体的视频可用性状态。

若可用， QVideoWidget 类可以用于查看视频。由于存活时间对于 QMediaPlayer 可以长于回放的某个 QMediaContent ，此特性可能随时间推移改变， videoAvailableChanged 信号可以用于监视其状态。

访问函数：

bool isVideoAvailable () const

通知程序信号：

void videoAvailableChanged (bool videoAvailable )

另请参阅 QVideoWidget and QMediaContent .

volume : int

此特性保持当前回放音量。

播放音量是按线性比例缩放的，范围从 0 (无声) 到 100 (全音量)。将钳制超出此范围的值。

默认情况下，音量为 100 .

通常，UI 音量控件应按非线性比例缩放。例如，使用对数比例缩放将产生感知响度的线性变化，这通常是用户期望的音量控制。见 QAudio::convertVolume () 了解更多细节。

访问函数：

int volume () const
void setVolume (int volume )

通知程序信号：

void volumeChanged (int volume )

成员函数文档编制

QMediaPlayer:: QMediaPlayer ( QObject * parent = nullptr, QMediaPlayer::Flags flags = Flags())

构造 QMediaPlayer instance parented to parent 和采用 flags .

[虚拟] QMediaPlayer:: ~QMediaPlayer ()

销毁播放器对象。

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

发射信号，当音频内容的可用性已变成 available .

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

[signal] void QMediaPlayer:: audioRoleChanged ( QAudio::Role role )

发射信号，当音频 role 为媒体播放器已改变。

该函数在 Qt 5.6 引入。

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

[override virtual] QMultimedia::AvailabilityStatus QMediaPlayer:: availability () const

重实现自 QMediaObject::availability ().

[signal] void QMediaPlayer:: bufferStatusChanged ( int percentFilled )

发射信号，当以百分比方式表示本地缓冲填充量通过 percentFilled .

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

[signal] void QMediaPlayer:: currentMediaChanged (const QMediaContent & media )

发射信号，当当前播放内容已变为 media .

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

另请参阅 currentMedia () 和 mediaChanged ().

QNetworkConfiguration QMediaPlayer:: currentNetworkConfiguration () const

Returns the current network access point in use. If a default contructed QNetworkConfiguration is returned this feature is not available or that none of the current supplied configurations are in use.

[signal] void QMediaPlayer:: customAudioRoleChanged (const QString & role )

发射信号，当音频 role 为媒体播放器已改变。

该函数在 Qt 5.11 引入。

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

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

发射信号，当内容持续时间已变成 duration ，表达 (以毫秒为单位)。

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

QMediaPlayer::Error QMediaPlayer:: error () const

返回当前错误状态。

[signal] void QMediaPlayer:: error ( QMediaPlayer::Error error )

发射信号，当 error 条件出现。

注意： 信号 error 在此类中被重载。通过使用函数指针句法连接到此信号，Qt 提供用于获得如此范例展示的函数指针的方便帮助程序： 

connect(mediaPlayer, QOverload<QMediaPlayer::Error>::of(&QMediaPlayer::error),
    [=](QMediaPlayer::Error error){ /* ... */ });

另请参阅 errorString ().

[static] QMultimedia::SupportEstimate QMediaPlayer:: hasSupport (const QString & mimeType , const QStringList & codecs = QStringList(), QMediaPlayer::Flags flags = Flags())

返回支持的级别，媒体播放器拥有 mimeType 和一组 codecs .

The flags 自变量允许指定额外要求，譬如：性能指示器。

[signal] void QMediaPlayer:: mediaChanged (const QMediaContent & media )

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

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

另请参阅 media () 和 currentMediaChanged ().

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

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

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

另请参阅 mediaStatus ().

const QIODevice *QMediaPlayer:: mediaStream () const

返回媒体数据的流源。

这才有效，若把流传递给 setMedia ().

另请参阅 setMedia ().

[signal] void QMediaPlayer:: mutedChanged ( bool muted )

发射信号，当静音状态已变成 muted .

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

[signal] void QMediaPlayer:: networkConfigurationChanged (const QNetworkConfiguration & configuration )

Signal that the active in use network access point has been changed to configuration and all subsequent network access will use this configuration .

[slot] void QMediaPlayer:: pause ()

暂停播放当前源。

[slot] void QMediaPlayer:: play ()

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

[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:: setMedia (const QMediaContent & media , QIODevice * stream = nullptr)

设置当前 media 源。

若 stream is supplied; media data will be read from it instead of resolving the media source. In this case the media source may still be used to resolve additional information about the media such as mime type. The stream must be open and readable.

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

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

从 Qt 5.12.2 起，URL 方案 gst-pipeline provides custom pipelines for the GStreamer backend. 

player = new QMediaPlayer;
player->setMedia(QUrl("gst-pipeline: videotestsrc ! autovideosink"));
player->play();

If the pipeline contains a video sink element named qtvideosink ，当前 QVideoWidget can be used to render the video.

若管道包含 appsrc 元素，将使用它来推送数据从 stream . 

QImage img("images/qt-logo.png");
img = img.convertToFormat(QImage::Format_ARGB32);
QByteArray ba(reinterpret_cast<const char *>(img.bits()), img.sizeInBytes());
QBuffer buffer(&ba);
buffer.open(QIODevice::ReadOnly);
player = new QMediaPlayer;
player->setMedia(QUrl("gst-pipeline: appsrc blocksize=4294967295 ! \
    video/x-raw,format=BGRx,framerate=30/1,width=200,height=147 ! \
    coloreffects preset=heat ! videoconvert ! video/x-raw,format=I420 ! jpegenc ! rtpjpegpay ! \
    udpsink host=127.0.0.1 port=5000"), &buffer);
player->play();
QMediaPlayer *receiver = new QMediaPlayer;
videoWidget = new QVideoWidget;
receiver->setVideoOutput(videoWidget);
receiver->setMedia(QUrl("gst-pipeline: udpsrc port=5000 ! \
    application/x-rtp,encoding-name=JPEG,payload=26 ! rtpjpegdepay ! jpegdec ! \
    xvimagesink name=qtvideosink"));
receiver->play();
// Content will be shown in this widget.
videoWidget->show();

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

另请参阅 media ().

[slot] void QMediaPlayer:: setNetworkConfigurations (const QList < QNetworkConfiguration > & configurations )

Sets the network access points for remote media playback. configurations contains, in ascending preferential order, a list of configuration that can be used for network access.

This will invalidate the choice of previous configurations.

void QMediaPlayer:: setVideoOutput ( QVideoWidget * output )

附加 QVideoWidget 视频 output 到媒体播放器。

若媒体播放器已经有附加视频输出，将以新的替换它。

void QMediaPlayer:: setVideoOutput ( QGraphicsVideoItem * output )

附加 QGraphicsVideoItem 视频 output 到媒体播放器。

若媒体播放器已经有附加视频输出，将以新的替换它。

void QMediaPlayer:: setVideoOutput ( QAbstractVideoSurface * surface )

设置视频 surface 作为媒体播放器的视频输出。

若媒体播放器已经有设置，新表面将替换视频输出。

[signal] void QMediaPlayer:: stateChanged ( QMediaPlayer::State state )

发射信号，当 state 对于播放器对象已改变。

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

[slot] void QMediaPlayer:: stop ()

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

QList < QAudio::Role > QMediaPlayer:: supportedAudioRoles () const

返回支持的音频角色列表。

若不支持设置的音频角色，返回空列表。

该函数在 Qt 5.6 引入。

另请参阅 audioRole .

QStringList QMediaPlayer:: supportedCustomAudioRoles () const

返回支持的自定义音频角色列表。空列表可以指示支持的自定义音频角色未知。列表可能并不完整。

该函数在 Qt 5.11 引入。

另请参阅 customAudioRole .

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

发射信号，当视觉内容的可用性已变成 videoAvailable .

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

[signal] void QMediaPlayer:: volumeChanged ( int volume )

发射信号，当回放音量已变成 volume .

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