DragonPlayer Class
Audio playback controller. More...
| Header: | #include <DragonPlayer> |
| CMake: | find_package(DragonMediaBackend REQUIRED COMPONENTS DragonMediaBackend)target_link_libraries(mytarget PRIVATE DragonMediaBackend::DragonMediaBackend) |
Public Types
| enum class | Error { NoError, ResourceError, FormatError, NetworkError, AccessDenied } |
| enum class | MediaStatus { NoMedia, LoadingMedia, LoadedMedia, BufferingMedia, StalledMedia, …, InvalidMedia } |
| enum class | PlaybackState { StoppedState, PlayingState, PausedState } |
Properties
|
|
Public Functions
| DragonPlayer(QObject *parent = nullptr) | |
| DragonPlayer(DragonAudioOutput::Backend requestedBackend, QObject *parent = nullptr) | |
| DragonAudioOutput * | audioOutput() const |
| qreal | bufferProgress() const |
| qint64 | duration() const |
| DragonPlayer::Error | error() const |
| QString | errorString() const |
| QUrl | nextSource() const |
| DragonPlayer::PlaybackState | playbackState() const |
| qint64 | position() const |
| int32_t | prefinishMark() const |
| bool | seekable() const |
| QUrl | source() const |
| DragonPlayer::MediaStatus | status() const |
Public Slots
| void | pause() |
| void | play() |
| void | setNextSource(const QUrl &nextSource) |
| void | setPosition(qint64 positionMs) |
| void | setPrefinishMark(int32_t msec) |
| void | setSource(const QUrl &source) |
| void | setStreamName(const QString &name) |
| void | stop() |
Signals
| void | aboutToFinish() |
| void | bufferProgressChanged(qreal progress) |
| void | currentPlayingForRadiosChanged(const DragonIcyMetadata &metadata) |
| void | durationChanged(qint64 durationMs) |
| void | errorChanged(DragonPlayer::Error error) |
| void | nextSourceChanged() |
| void | positionChanged(qint64 positionMs) |
| void | prefinishMarkChanged(int32_t msec) |
| void | seekableChanged(bool seekable) |
| void | sourceChanged() |
| void | stateChanged(DragonPlayer::PlaybackState newState, DragonPlayer::PlaybackState oldState) |
| void | statusChanged(DragonPlayer::MediaStatus status) |
| void | trackChanged() |
Detailed Description
DragonPlayer is the main entry point of Dragon Media Backend. It manages the state machine for media selection and playback of audio files.
It can support gapless playback between sequential tracks: when aboutToFinish() is emitted the application can set nextSource() and it will play that track immediately after the current track is finished..
See also DragonAudioOutput, DragonSpectrumAnalyzer, and DragonIcyMetadata.
Member Type Documentation
enum class DragonPlayer::Error
The error state of the player.
| Constant | Value | Description |
|---|---|---|
DragonPlayer::Error::NoError | 0 | No error occurred. |
DragonPlayer::Error::ResourceError | 1 | An audio resource could not be acquired. |
DragonPlayer::Error::FormatError | 2 | The media format is not supported. |
DragonPlayer::Error::NetworkError | 3 | A network error occurred while streaming. |
DragonPlayer::Error::AccessDenied | 4 | Access to the source is denied. |
enum class DragonPlayer::MediaStatus
The status of the loaded media.
| Constant | Value | Description |
|---|---|---|
DragonPlayer::MediaStatus::NoMedia | 0 | No source has been set. |
DragonPlayer::MediaStatus::LoadingMedia | 1 | The source is being opened and probed. |
DragonPlayer::MediaStatus::LoadedMedia | 2 | The source is loaded and possibly playing. |
DragonPlayer::MediaStatus::BufferingMedia | 3 | Buffering the network stream. |
DragonPlayer::MediaStatus::StalledMedia | 4 | The network stream has stalled. |
DragonPlayer::MediaStatus::BufferedMedia | 5 | Enough of a network stream is buffered for playback. |
DragonPlayer::MediaStatus::EndOfMedia | 6 | Playback reached the end of the source. |
DragonPlayer::MediaStatus::InvalidMedia | 7 | Something if off; check the DragonPlayer::error. |
enum class DragonPlayer::PlaybackState
The playback state of the player.
| Constant | Value | Description |
|---|---|---|
DragonPlayer::PlaybackState::StoppedState | 0 | No media is being played. |
DragonPlayer::PlaybackState::PlayingState | 1 | Media is being played. |
DragonPlayer::PlaybackState::PausedState | 2 | Playback is paused and can be resumed with play(). |
Property Documentation
[read-only] bufferProgress : qreal
How much of a network stream has been buffered, from 0.0 to 1.0. Always 1.0 for fully buffered local files.
Access functions:
| qreal | bufferProgress() const |
Notifier signal:
| void | bufferProgressChanged(qreal progress) |
[read-only] duration : qint64
The duration of the current source in milliseconds, or 0 for streams of unknown duration.
Access functions:
| qint64 | duration() const |
Notifier signal:
| void | durationChanged(qint64 durationMs) |
[read-only] error : Error
The error state of the player, NoError when there is no error.
Access functions:
| DragonPlayer::Error | error() const |
Notifier signal:
| void | errorChanged(DragonPlayer::Error error) |
[read-only] errorString : QString
A human-readable description of the current error, if any.
Access functions:
| QString | errorString() const |
Notifier signal:
| void | errorChanged(DragonPlayer::Error error) |
nextSource : QUrl
The source played when the current track finishes, used for gapless transitions. Set it in response to aboutToFinish().
Access functions:
| QUrl | nextSource() const |
| void | setNextSource(const QUrl &nextSource) |
Notifier signal:
| void | nextSourceChanged() |
See also aboutToFinish().
[read-only] playbackState : PlaybackState
The current playback state.
Access functions:
| DragonPlayer::PlaybackState | playbackState() const |
Notifier signal:
| void | stateChanged(DragonPlayer::PlaybackState newState, DragonPlayer::PlaybackState oldState) |
position : qint64
The playback position in milliseconds. Setting it while a source is loaded seeks playback.
Access functions:
| qint64 | position() const |
| void | setPosition(qint64 positionMs) |
Notifier signal:
| void | positionChanged(qint64 positionMs) |
prefinishMark : int32_t
How many milliseconds before the end of the source aboutToFinish() is emitted, allowing the next source to be queued for a gapless transition. The default is 100 milliseconds.
Access functions:
| int32_t | prefinishMark() const |
| void | setPrefinishMark(int32_t msec) |
Notifier signal:
| void | prefinishMarkChanged(int32_t msec) |
See also aboutToFinish().
[read-only] seekable : bool
Whether the playback position of the current source can be changed. Radio streams are typically not seekable.
Access functions:
| bool | seekable() const |
Notifier signal:
| void | seekableChanged(bool seekable) |
source : QUrl
The media being played. If it's currently playing, setting a new source stops playback, resets the position, and starts loading the new media.
Access functions:
Notifier signal:
| void | sourceChanged() |
[read-only] status : MediaStatus
The status of the loaded media.
Access functions:
| DragonPlayer::MediaStatus | status() const |
Notifier signal:
| void | statusChanged(DragonPlayer::MediaStatus status) |
Member Function Documentation
[explicit] DragonPlayer::DragonPlayer(QObject *parent = nullptr)
Constructs the main controller. The audio output backends - PipeWire, PulseAudio, SDL3 - are probed in that order until a functional backend is found. Note that SDL Audio itself has a similar driver abstraction layer with multiple backends and is likely used anywhere outside of the Linux/Unix desktop environment.
[explicit] DragonPlayer::DragonPlayer(DragonAudioOutput::Backend requestedBackend, QObject *parent = nullptr)
Constructs a player using the audio backend requestedBackend, falling back to probing when it is not available.
[signal] void DragonPlayer::aboutToFinish()
Emitted prefinishMark() milliseconds before the current source finishes. Set nextSource() in response to queue the next track for a gapless transition.
See also nextSource, setNextSource(), and prefinishMark.
DragonAudioOutput *DragonPlayer::audioOutput() const
Returns the DragonAudioOutput instance controlling volume and mute for this player. The instance is owned by the player.
qreal DragonPlayer::bufferProgress() const
Returns how much of a network stream has been buffered, from 0.0 to 1.0.
Note: Getter function for property bufferProgress.
[signal] void DragonPlayer::bufferProgressChanged(qreal progress)
Emitted when the buffered amount of a network stream changes, with the new fraction in progress.
Note: Notifier signal for property bufferProgress.
[signal] void DragonPlayer::currentPlayingForRadiosChanged(const DragonIcyMetadata &metadata)
Emitted when the ICY metadata of a radio stream changes, with the new metadata. Typically reports the track currently playing.
qint64 DragonPlayer::duration() const
Returns the duration of the current source in milliseconds.
Note: Getter function for property duration.
[signal] void DragonPlayer::durationChanged(qint64 durationMs)
Emitted when the duration of the current source changes to durationMs milliseconds.
Note: Notifier signal for property duration.
DragonPlayer::Error DragonPlayer::error() const
Returns the error state of the player.
Note: Getter function for property error.
[signal] void DragonPlayer::errorChanged(DragonPlayer::Error error)
Emitted when the error state changes to error.
Note: Notifier signal for properties error and errorString.
QString DragonPlayer::errorString() const
Returns a human-readable description of the current error, if any.
Note: Getter function for property errorString.
QUrl DragonPlayer::nextSource() const
Returns the source queued for the gapless transition at the end of the current track, or an empty URL if none is set.
Note: Getter function for property nextSource.
See also setNextSource().
[signal] void DragonPlayer::nextSourceChanged()
Emitted when the queued next source changes.
Note: Notifier signal for property nextSource.
[slot] void DragonPlayer::pause()
Pauses playback. Call play() to resume from the same position.
[slot] void DragonPlayer::play()
Starts or resumes playback of the current source.
DragonPlayer::PlaybackState DragonPlayer::playbackState() const
Returns the current playback state.
Note: Getter function for property playbackState.
qint64 DragonPlayer::position() const
Returns the playback position in milliseconds.
Note: Getter function for property position.
See also setPosition().
[signal] void DragonPlayer::positionChanged(qint64 positionMs)
Emitted while playing, when the playback position changes to positionMs milliseconds.
Note: Notifier signal for property position.
int32_t DragonPlayer::prefinishMark() const
Returns how many milliseconds before the end of the source aboutToFinish() is emitted.
Note: Getter function for property prefinishMark.
See also setPrefinishMark().
[signal] void DragonPlayer::prefinishMarkChanged(int32_t msec)
Emitted when the prefinish mark changes to msec milliseconds.
Note: Notifier signal for property prefinishMark.
bool DragonPlayer::seekable() const
Returns whether the current source is seekable.
Note: Getter function for property seekable.
[signal] void DragonPlayer::seekableChanged(bool seekable)
Emitted when the seekable state of the current source changes to seekable.
Note: Notifier signal for property seekable.
[slot] void DragonPlayer::setNextSource(const QUrl &nextSource)
Queues nextSource to be played when the current source finishes, providing a gapless transition.
Note: Setter function for property nextSource.
See also nextSource().
[slot] void DragonPlayer::setPosition(qint64 positionMs)
Seeks to positionMs milliseconds into the current source, when it is seekable.
Note: Setter function for property position.
See also position().
[slot] void DragonPlayer::setPrefinishMark(int32_t msec)
Sets the prefinish mark to msec milliseconds.
Note: Setter function for property prefinishMark.
See also prefinishMark() and aboutToFinish().
[slot] void DragonPlayer::setSource(const QUrl &source)
Sets the media to be played to source. Any current playback is stopped and the position is reset.
Note: Setter function for property source.
See also source().
[slot] void DragonPlayer::setStreamName(const QString &name)
Sets the display name of the stream being played to name. Used when reporting ICY metadata for radio streams.
QUrl DragonPlayer::source() const
Returns the media being played.
Note: Getter function for property source.
See also setSource().
[signal] void DragonPlayer::sourceChanged()
Emitted when the source property changes.
Note: Notifier signal for property source.
[signal] void DragonPlayer::stateChanged(DragonPlayer::PlaybackState newState, DragonPlayer::PlaybackState oldState)
Emitted when the playback state changes to newState, with the previous state in oldState.
Note: Notifier signal for property playbackState.
DragonPlayer::MediaStatus DragonPlayer::status() const
Returns the status of the loaded media.
Note: Getter function for property status.
[signal] void DragonPlayer::statusChanged(DragonPlayer::MediaStatus status)
Emitted when the media status changes to status.
Note: Notifier signal for property status.
[slot] void DragonPlayer::stop()
Stops playback and resets the position. The source remains loaded and playback can be restarted with play().
[signal] void DragonPlayer::trackChanged()
Emitted when the playing track changes, for example on a gapless transition or a source change.