DragonPlayer Class
Audio playback controller. More...
| Header: | #include <DragonPlayer> |
| CMake: | find_package(DragonMediaBackend REQUIRED COMPONENTS DragonMediaBackend)target_link_libraries(mytarget PRIVATE DragonMediaBackend::DragonMediaBackend) |
| In QML: | DragonPlayer |
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 |
| std::optional<std::chrono::milliseconds> | duration() const |
| DragonPlayer::Error | error() const |
| QString | errorString() const |
| QUrl | nextSource() const |
| DragonPlayer::PlaybackState | playbackState() const |
| std::chrono::milliseconds | position() const |
| std::chrono::milliseconds | 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(std::chrono::milliseconds position) |
| void | setPrefinishMark(std::chrono::milliseconds 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(std::optional<std::chrono::milliseconds> duration) |
| void | errorChanged(DragonPlayer::Error error) |
| void | nextSourceChanged() |
| void | positionChanged(std::chrono::milliseconds position) |
| void | prefinishMarkChanged(std::chrono::milliseconds 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] audioOutput : DragonAudioOutput* const
The DragonAudioOutput instance controlling volume and mute for this player. The instance is owned by the player and constant for its lifetime.
Access functions:
| DragonAudioOutput * | audioOutput() const |
[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 : DragonDuration
The duration of the current source as a dragonDuration value, which is invalid for streams of unknown duration. C++ code should use duration(), which reports unknown durations as an empty std::optional.
Access functions:
| std::optional<std::chrono::milliseconds> | duration() const |
Notifier signal:
| void | durationChanged(std::optional<std::chrono::milliseconds> duration) |
[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 : DragonDuration
The playback position as a dragonDuration value. Setting it while a source is loaded seeks playback. C++ code should use position() and setPosition() with std::chrono::milliseconds.
Access functions:
| std::chrono::milliseconds | position() const |
| void | setPosition(std::chrono::milliseconds position) |
Notifier signal:
| void | positionChanged(std::chrono::milliseconds position) |
prefinishMark : DragonDuration
How long before the end of the source aboutToFinish() is emitted, allowing the next source to be queued for a gapless transition. The default is 2 seconds.
Access functions:
| std::chrono::milliseconds | prefinishMark() const |
| void | setPrefinishMark(std::chrono::milliseconds msec) |
Notifier signal:
| void | prefinishMarkChanged(std::chrono::milliseconds 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.
Note: Getter function for property audioOutput.
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.
std::optional<std::chrono::milliseconds> DragonPlayer::duration() const
Returns the duration of the current source, or an empty std::optional for streams of unknown duration.
Note: Getter function for property duration.
[signal] void DragonPlayer::durationChanged(std::optional<std::chrono::milliseconds> duration)
Emitted when the duration of the current source changes to duration. The optional is empty for streams of unknown duration.
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.
std::chrono::milliseconds DragonPlayer::position() const
Returns the playback position.
Note: Getter function for property position.
See also setPosition().
[signal] void DragonPlayer::positionChanged(std::chrono::milliseconds position)
Emitted while playing, when the playback position changes to position.
Note: Notifier signal for property position.
std::chrono::milliseconds DragonPlayer::prefinishMark() const
Returns how long before the end of the source aboutToFinish() is emitted.
Note: Getter function for property prefinishMark.
See also setPrefinishMark().
[signal] void DragonPlayer::prefinishMarkChanged(std::chrono::milliseconds msec)
Emitted when the prefinish mark changes to msec.
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(std::chrono::milliseconds position)
Seeks to position into the current source, when it is seekable.
Note: Setter function for property position.
See also position().
[slot] void DragonPlayer::setPrefinishMark(std::chrono::milliseconds msec)
Sets the prefinish mark to msec.
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 audio stream to name, as shown by the audio server (for example PipeWire's media.name or PulseAudio's media.name property). If name is empty, the application display name is used instead. The name is applied live when a stream is open and seeds the stream properties when playback opens one.
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.