QMediaPlayer 類

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

頭: #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 ()

詳細描述

The QMediaPlayer class is a high level media playback class. It can be used to playback audio of video media files. The content to playback is specified as a 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 can be used with QMediaPlayer for video rendering.

另請參閱 QVideoWidget .

成員類型文檔編製

enum QMediaPlayer:: Error

定義媒體播放器錯誤條件。

常量 描述
QMediaPlayer::NoError 0 沒有齣現錯誤。
QMediaPlayer::ResourceError 1 無法解析媒體資源。
QMediaPlayer::FormatError 2 不 (完全) 支持媒體資源格式。仍可能可以迴放,但沒有音頻或視頻組件。
QMediaPlayer::NetworkError 3 發生網絡錯誤。
QMediaPlayer::AccessDeniedError 4 沒有適當權限來播放媒體資源。

enum QMediaPlayer:: Loops

Some predefined constants for the loops 特性。

常量 描述
QMediaPlayer::Infinite -1 Loop forever.
QMediaPlayer::Once 1 Play the media once (the default).

enum QMediaPlayer:: MediaStatus

定義媒體播放器當前媒體的狀態。

常量 描述
QMediaPlayer::NoMedia 0 The is no current media. The player is in the 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

Returns the currently active audio track.

By default, the first available audio track will be chosen.

Set index to -1 to disable all audio tracks.

訪問函數:

int activeAudioTrack () const
void setActiveAudioTrack (int index )

通知程序信號:

void activeTracksChanged ()

activeSubtitleTrack : int

Returns the currently active subtitle track.

Set index to -1 to disable subtitles.

Subtitles are disabled by default.

訪問函數:

int activeSubtitleTrack () const
void setActiveSubtitleTrack (int index )

通知程序信號:

void activeTracksChanged ()

activeVideoTrack : int

Returns the currently active video track.

By default, the first available audio track will be chosen.

Set index to -1 to disable all video tracks.

訪問函數:

int activeVideoTrack () const
void setActiveVideoTrack (int index )

通知程序信號:

void activeTracksChanged ()

audioOutput : QAudioOutput *

This property holds the audio output device used by the media player.

The current audio output to be used when playing back media. Setting a new audio output will replace the currently used output.

把此特性設為 nullptr will disable any audio output.

訪問函數:

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

通知程序信號:

void audioOutputChanged ()

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

Lists the set of available audio tracks inside the media.

The QMediaMetaData returned describes the properties of individual tracks.

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

訪問函數:

QList<QMediaMetaData> audioTracks () const

通知程序信號:

void tracksChanged ()

[read-only] bufferProgress : const float

此特性保持填充臨時緩衝的百分比,在迴放開始 (或再繼續) 前。從 0 . (empty) to 1 . (full).

當緩衝播放器對象時,此特性保持填充臨時緩衝的百分比。在迴放可以開始 (或再繼續) 前,填充緩衝需要達到 100%,此時 mediaStatus () 會返迴 BufferedMedia or BufferingMedia 。若是任何值小於 100 , mediaStatus () 會返迴 StalledMedia .

訪問函數:

float bufferProgress () const

通知程序信號:

void bufferProgressChanged (float filled )

另請參閱 mediaStatus ().

[read-only] duration : const qint64

此特性保持當前媒體的持續時間。

值是當前媒體的總迴放時間 (以毫秒為單位)。值可能跨存活時間改變對於 QMediaPlayer 對象且可能不可用 (當初始迴放開始時),連接到 durationChanged () 信號以接收狀態通知。

訪問函數:

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

此特性保持媒體是否包含音頻。

訪問函數:

bool hasAudio () const

通知程序信號:

void hasAudioChanged (bool available )

[read-only] hasVideo : const bool

此特性保持媒體是否包含視頻。

訪問函數:

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

Returns meta data for the current media used by the media player.

Meta data can contain information such as the title of the video or its creation date.

注意: The Windows implementation provides metadata only for media located on the local file system.

訪問函數:

QMediaMetaData metaData () const

通知程序信號:

void metaDataChanged ()

playbackRate : qreal

此特性保持當前媒體的迴放速率。

此值是應用於媒體標準播放速率的乘數。默認情況下,此值為 1.0,指示媒體以標準步速播放。值 > 1.0 將提高播放速率。可以設置 < 0 的值,並指示媒體應以標準步速的乘數倒帶。

並非所有迴放服務,都支持迴放速率的改變。它由音頻和視頻狀態和品質的框架定義,當快進 (或倒帶) 時。

訪問函數:

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

This property holds whether the media is playing.

This property was introduced in 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 為選擇要播放的內容。

默認情況下,此特性擁有 null QUrl .

將此特性設為 null QUrl 將導緻播放器丟棄與當前媒體源相關的所有信息,並停息與該媒體相關的所有 I/O 操作。

訪問函數:

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 returned describes the properties of individual tracks.

訪問函數:

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 will disable video output.

訪問函數:

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

通知程序信號:

void videoOutputChanged ()

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

Lists the set of available video tracks inside the media.

The QMediaMetaData returned describes the properties of individual tracks.

訪問函數:

QList<QMediaMetaData> videoTracks () const

通知程序信號:

void tracksChanged ()

成員函數文檔編製

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

Constructs a QMediaPlayer instance as a child of parent .

[虛擬] 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 function for property 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 describing the currently buffered data.

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 the duration of the current media 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 函數對於特性 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 )

發射信號,當 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

Returns true if the media player is supported on this platform.

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

Returns the current playback rate.

注意: Getter function for property 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 )

Signals the position of the content has changed to position ,錶達 (以毫秒為單位)。

注意: 通知程序信號對於特性 position .

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

信號 seekable 播放器對象狀態已改變。

注意: 通知程序信號對於特性 seekable .

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

設置當前 source .

將媒體設為 null QUrl 將導緻播放器丟棄與當前媒體源相關的所有信息,並停息與該媒體相關的所有 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.

注意: setter 函數對於特性 source .

另請參閱 source ().

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

Sets the current source device .

The media data will be read from devicesourceUrl can be provided to resolve additional information about the media, mime type etc. The device must be open and readable.

For macOS the device should also be seek-able.

注意: 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 instance to retrieve video data.

另請參閱 videoSink ().

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

發射信號,當媒體源已變成 media .

注意: 通知程序信號對於特性 source .

const QIODevice *QMediaPlayer:: sourceDevice () const

返迴媒體數據的流源。

這纔有效,若把流傳遞給 setSource ().

另請參閱 setSourceDevice () 和 setSource ().

[slot] void QMediaPlayer:: stop ()

停止播放,然後將播放位置重置到起始。

另請參閱 play () 和 pause ().

QVideoSink *QMediaPlayer:: videoSink () const

返迴 QVideoSink 實例。

另請參閱 setVideoSink ().