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 .
定义媒体播放器错误条件。
常量 | 值 | 描述 |
---|---|---|
QMediaPlayer::NoError
|
0
|
没有出现错误。 |
QMediaPlayer::ResourceError
|
1
|
无法解析媒体资源。 |
QMediaPlayer::FormatError
|
2
|
不 (完全) 支持媒体资源格式。仍可能可以回放,但没有音频或视频组件。 |
QMediaPlayer::NetworkError
|
3
|
发生网络错误。 |
QMediaPlayer::AccessDeniedError
|
4
|
没有适当权限来播放媒体资源。 |
一些预定义常量对于 loops 特性。
常量 | 值 | 描述 |
---|---|---|
QMediaPlayer::Infinite
|
-1
|
永远循环。 |
QMediaPlayer::Once
|
1
|
播放媒体一次 (默认)。 |
定义媒体播放器当前媒体的状态。
常量 | 值 | 描述 |
---|---|---|
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 . |
定义媒体播放器的当前状态。
常量 | 值 | 描述 |
---|---|---|
QMediaPlayer::StoppedState
|
0
|
媒体播放器未播放内容,回放将从当前轨道的起始开始。 |
QMediaPlayer::PlayingState
|
1
|
The media player is currently playing content. This indicates the same as the playing 特性。 |
QMediaPlayer::PausedState
|
2
|
媒体播放器已暂停回放,当前轨道的回放将从播放器暂停位置处再继续。 |
返回目前活动的音频轨道。
默认情况下,将选取第一可用音频轨道。
Set
index
to
-1
以禁用所有音频轨道。
访问函数:
int | activeAudioTrack () const |
void | setActiveAudioTrack (int index ) |
通知程序信号:
void | activeTracksChanged () |
返回目前活动的字幕轨道。
Set
index
to
-1
以禁用字幕。
默认情况下,禁用字幕。
访问函数:
int | activeSubtitleTrack () const |
void | setActiveSubtitleTrack (int index ) |
通知程序信号:
void | activeTracksChanged () |
返回当前活动的视频轨道。
默认情况下,将选取第一可用音频轨道。
Set
index
to
-1
以禁用所有视频轨道。
访问函数:
int | activeVideoTrack () const |
void | setActiveVideoTrack (int index ) |
通知程序信号:
void | activeTracksChanged () |
此特性保持媒体播放器所用的音频输出设备。
当回放媒体时要使用的当前音频输出。设置新的音频输出将替换目前使用的输出。
把此特性设为
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 ) |
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 () |
此特性保持当前媒体的回放速率。
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 .
此特性保持当前媒体的回放位置。
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 ) |
此特性保持播放器对象正在使用的活动媒体源。
播放器对象将使用 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 () |
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
()
销毁播放器对象。
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 描述目前缓冲的数据。
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 .
返回当前媒体的持续时间,以毫秒为单位。
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 .
返回当前错误状态。
注意: 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 .
返回 true,若此平台支持媒体播放器。
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
()
暂停播放当前源。
[slot]
void
QMediaPlayer::
play
()
开始 (或再继续) 播放当前源。
返回当前回放速率。
注意: getter 函数对于特性 playbackRate。
另请参阅 setPlaybackRate ().
[signal]
void
QMediaPlayer::
playbackRateChanged
(
qreal
rate
)
信号 playbackRate 已改变成 rate .
注意: 通知程序信号对于特性 playbackRate .
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 ().
设置 sink 为 QVideoSink 实例以检索视频数据。
另请参阅 videoSink ().
[signal]
void
QMediaPlayer::
sourceChanged
(const
QUrl
&
media
)
发射信号当媒体源已变为 media .
注意: 通知程序信号对于特性 source .
返回媒体数据的流源。
This is only valid if a stream was passed to setSource ().
另请参阅 setSourceDevice () 和 setSource ().
[slot]
void
QMediaPlayer::
stop
()
停止播放,然后将播放位置重置到起始。
返回 QVideoSink 实例。
另请参阅 setVideoSink ().