NowPlayingController

Since: BlackBerry 10.2.0

#include <bb/multimedia/NowPlayingController>

To link against this class, add the following line to your .pro file: LIBS += -lbbmultimedia

Provides system access to media controlling features.

The NowPlayingController class provides the ability to control media which has been acquired using NowPlayingConnection. Provides notification of the current position, duration, state and meta data of the active media.

A now playing sample in C++:

        // create controller object
        NowPlayingController *npc = new NowPlayingController(this);

        QVariantMap metadata;

        // get metadata for the currently being played track
        metadata = npc->metaData();

        // extract metadata values
        m_title = metadata[MetaData::Title];
        m_artist = metadata[MetaData::Artist];
        m_album = metadata[MetaData::Album];

        ...

        // start playing track
        npc->play();
        // set volume to 50% of maximum value
        npc->setVolume(0.5);

Controlling methods can be used to set volume (mute included), play, pause, stop media playing, skip to the next or return to the previous track, fast forward and rewind.

A now playing sample in QML:

    import bb.cascades 1.0
    import bb.multimedia 1.2   // import the multimedia library for access to the NowPlayingController

    Page {
        Container {
            layout: StackLayout  {
                orientation: LayoutOrientation.TopToBottom
            }
            topPadding:40

            attachedObjects: [
                // Create a NowPlayingController object
                NowPlayingController {
                    id: nowPlayingController

                    // handle various events sent by the NowPlayingController and update the controls
                    onDurationChanged: {
                        length.text = duration;
                    }

                    onNextEnabledChanged: {
                        next.enabled = nextEnabled;
                    }

                    onPreviousEnabledChanged: {
                        prev.enabled = previousEnabled;
                    }

                    onMediaStateChanged: {
                        playState.text = mediaState;
                    }

                    onMetaDataChanged: {
                        artist.text = metaData["artist"];
                        album.text  = metaData["album"];
                        title.text  = metaData["title"];
                    }

                    onPositionChanged: {
                        currentPosition.text = nowPlayingController.position;
                    }

                    onIconUrlChanged: {
                        albumArt.imageSource = nowPlayingController.iconUrl
                    };

            }

            ]

            ImageView {
                id: albumArt
                imageSource: "asset:///artwork.png"
                preferredHeight: 320
                minHeight:320
                minWidth:320
                scalingMethod: ScalingMethod.Fill
                horizontalAlignment: HorizontalAlignment.Fill
                verticalAlignment: VerticalAlignment.Top
            }

            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Label {
                    text: "Artist:"
                }
                Label {
                    id: artist
                    text: ""
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Label {
                    text: "Album:"
            }
                Label {
                    id: album
                    text: ""
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Label {
                    text: "Title:"
                }
                Label {
                    id: title
                    text: ""
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Label {
                    text: "Duration (ms):"
                }
                Label {
                    id: length
                    text: ""
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Label {
                    text: "Position (ms):"
                }
                Label {
                    id: currentPosition
                    text: ""
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Button {
                    id: volUp
                    text: "Vol Up"
                    onClicked: {
                        nowPlayingController.volumeUp();
                    }
                }

                Button {
                    id: volDown
                    text: "Vol Down"
                    onClicked: {
                        nowPlayingController.volumeDown();
                    }
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Button {
                    id: play
                    text: "Play"
                    onClicked: {
                        nowPlayingController.play();
                    }
                }
                Button {
                    id: pause
                    text: "Pause"
                    onClicked: {
                        nowPlayingController.pause();
                    }
                }
                Button {
                    id: playPause
                    text: "PlayPause"
                    onClicked: {
                        nowPlayingController.playPause();
                    }
                }
            }
            Container {
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Button {
                    id: prev
                    text: "Previous"
                    onClicked: {
                        nowPlayingController.previous();
                    }
                }
                Button {
                    id: next
                    text: "Next"
                    onClicked: {
                        nowPlayingController.next();
                    }
                }
            }
            Container {
                topPadding: 10
                verticalAlignment: VerticalAlignment.Center
                horizontalAlignment: HorizontalAlignment.Center
                layout: StackLayout {
                    orientation: LayoutOrientation.LeftToRight
                }
                Label {
                    text: "Play State:"
                }
                Label {
                    id: playState
                    text: ""
                }
            }
        }
    }


Overview

Public Functions Index

Signals Index

voiddurationChanged (unsigned int duration)
voidiconUrlChanged (const QUrl &iconUrl)
voidmediaStateChanged (bb::multimedia::MediaState::Type mediaState)
voidmetaDataChanged (const QVariantMap &metaData)
voidnextEnabledChanged (bool nextEnabled)
voidpositionChanged (unsigned int position)
voidpreviousEnabledChanged (bool prevEnabled)
voidrepeatModeChanged (bb::multimedia::RepeatMode::Type repeatMode)
voidshuffleModeChanged (bb::multimedia::ShuffleMode::Type shuffleMode)
voidtrackChanged ()

Properties

QVariant duration[read-only]

Represents duration of track being played in milliseconds.

Since:

BlackBerry 10.2.0

QUrl iconUrl[read-only]

Represents the current album art location Uri.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaState::Type mediaState[read-only]

Represents a value of the media play state.

Out of all MediaState values there should be only three: Stopped, Paused, and Started.

Since:

BlackBerry 10.2.0

QVariantMap metaData[read-only]

Represents metadata of the track being played.

The metadata is presented as QVariableMap. Use bb::multimedia::MetaData strings to extract required fields.

Since:

BlackBerry 10.2.0

bool nextEnabled[read-only]

Represents a flag if more tacks are availalble.

Since:

BlackBerry 10.2.0

QVariant position[read-only]

Represents the current position, in milliseconds, of the track being played.

Since:

BlackBerry 10.2.0

bool previousEnabled[read-only]

Represents a flag if preceeding tracks are available.

Since:

BlackBerry 10.2.0

bb::multimedia::RepeatMode::Type repeatMode[read-only]

Represents the current repeat mode for an active player.

Since:

BlackBerry 10.3.0

bb::multimedia::ShuffleMode::Type shuffleMode[read-only]

Represents the current shuffle mode for an active player.

Since:

BlackBerry 10.3.0

Public Functions

NowPlayingController (

NowPlayingController class constructor.

Parameters
parent

An optional parameter to specify the parent of this QObject.

Since:

BlackBerry 10.2.0

virtual~NowPlayingController ()

Destructor.

Since:

BlackBerry 10.2.0

unsigned int duration ()

Used to determine the track duration.

Return:

Returns a number representing the duration in milliseconds of the track being played.

Since:

BlackBerry 10.2.0

QUrl iconUrl ()

Used to determine the album art uri.

Return:

Returns album art uri.

Since:

BlackBerry 10.2.0

bool isNextEnabled ()

Used to get a flag indicating if there are more tracks available.

Return:

boolean. Returns true when enabled, and false otherwise.

Since:

BlackBerry 10.2.0

bool isPreviousEnabled ()

Used to get a flag indicating if any preceding track available.

Return:

boolean. Returns true when enabled, and false otherwise.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaState::Type mediaState ()

Used to determine the current state of media player.

Return:

Returns state of the player - started, paused, stopped.

Since:

BlackBerry 10.2.0

QVariantMap metaData ()

Used to determine the metadata of the track being played.

Return:

Returns an object containing the metadata associated with the connection that is currently playing.

Since:

BlackBerry 10.2.0

unsigned int position ()

Used to determine the track position.

Return:

Returns a number representing the current playback position in milliseconds of the track being played.

Since:

BlackBerry 10.2.0

bb::multimedia::RepeatMode::Type repeatMode ()

Retrieves the current player repeat mode as set by a call from setRepeatMode().

Return:

Returns the current player repeat mode.

Since:

BlackBerry 10.3.0

bb::multimedia::ShuffleMode::Type shuffleMode ()

Retrieves the current player shuffle mode as set by a call from setShuffleMode().

Return:

Returns the current player shuffle mode.

Since:

BlackBerry 10.3.0

Public Slots

bb::multimedia::MediaError::Type forward ()

This method causes the content that is currently playing to advance its playing position.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type next ()

This method sends next commmand for advancing playback to the next track.

If the media source is a playlist, this function will move to the next track.

If the media source is not a playlist then calling this function does nothing.

Regrdless of the flag 'NextEnabled' the command is passed on successfully and in case if 'NextEnabled' flag is set to false the command is ignored.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type pause ()

This method sends pause command to pause the playback of the current track.

On success a mediaStateChanged signal may be emitted with value paused. Call play() to restart playback.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type play ()

This method sends play command to begin playback of selected track.

This function will start playback of a track. Successful playback may emit a mediaStateChanged signal with state value set to started.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

This command has no effect if the player has not been acquired or if the player does not support the command.
Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type playPause ()

This method sends playPause command to toggle playback from play mode to pause mode, or vice versa.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type previous ()

This method sends previous command for returning playback to the previous track.

If the media source is a playlist, this function will move to the previous track.

Regrdless of the flag 'PreviousEnabled' the command is passed on successfully and in case if 'PreviousEnabled' flag is set to false the command is ignored.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type repeat ()

This method causes the content that is currently playing to toggle repeat modes.

This command has no effect if the player has not been acquired or if the player does not support the command.

If a player handled the repeat notification it will result in a repeatModeChanged() signal.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.3.0

bb::multimedia::MediaError::Type repeat (

This method causes the content that is currently playing to change the repeat mode.

This command has no effect if the player has not been acquired or if the player does not support the command.

If a player handled the repeat notification it will result in a repeatModeChanged() signal.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.3.0

bb::multimedia::MediaError::Type rewind ()

This method causes the content that is currently playing to move its playing position backwards.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type setMute (
  • boolmuted)

This method is used to set the value of mute to On or Off.

This command has no effect if the player has not been acquired or if the player does not support the command.

Parameters
muted

Boolean value to represent the required mute state. This value is set to true for mute, and to false to cancel mute.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type setVolume (
  • doublevalue)

This method sets the volume method to the given value.

This command has no effect if the player has not been acquired or if the player does not support the command.

Parameters
value

Any value between 0.0 and 1.0 where 0.0 represents no volume at all, and 1.0 represents the maximum volume possible

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type shuffle ()

This method causes the content that is currently playing to toggle shuffle modes.

This command has no effect if the player has not been acquired or if the player does not support the command.

If a player handled the shuffle notification it will result in a shuffleModeChanged() signal.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.3.0

bb::multimedia::MediaError::Type shuffle (

This method causes the content that is currently playing to change the shuffle mode.

This command has no effect if the player has not been acquired or if the player does not support the command.

If a player handled the shuffle notification it will result in a shuffleModeChanged() signal.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.3.0

bb::multimedia::MediaError::Type stop ()

This method sends stop command to terminate the playback or recording of the current track.

This function will move the player into the stopped state. Calling play() will result in the media commencing playing back from the start. This function may result in the mediaStateChanged signal being emitted with value stopped.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type volumeDown ()

This method reduces volume level by one step.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

bb::multimedia::MediaError::Type volumeUp ()

This method increases volume level by one step.

This command has no effect if the player has not been acquired or if the player does not support the command.

Return:

Returns MediaError::None on success, otherwise a specific media error code.

Since:

BlackBerry 10.2.0

Signals

void durationChanged (
  • unsigned intduration)

This signal is emitted to indicate a change in the duration of the track.

Retrieving the duration of some tracks may not be known when the track is changed. This signal will notify of the duration when available.

Parameters
duration

The value for duration expressed in milliseconds.

Since:

BlackBerry 10.2.0

void iconUrlChanged (
  • const QUrl &iconUrl)

This signal is emitted to indicate a change of the album art Uri.

Parameters
iconUrl

Since:

BlackBerry 10.2.0

void mediaStateChanged (

This signal is emitted to indicate a change in the playback state.

Parameters
mediaState

New media state - started, paused, or stopped

Since:

BlackBerry 10.2.0

void metaDataChanged (

This signal is emitted to indicate that new metadata is available.

Parameters
metaData

Object containing map of string values for the metadata.

Since:

BlackBerry 10.2.0

void nextEnabledChanged (
  • boolnextEnabled)

This signal is emitted on notification that flag indicating availability of the next track has changed.

Parameters
nextEnabled

This value is true when next track is available, and false otherwise.

Since:

BlackBerry 10.2.0

void positionChanged (
  • unsigned intposition)

This signal is emitted to indicate a change in the position of the track that is currently playing.

This signal will be emitted approximately once per second or when normal status updates occur.

Parameters
position

The value of the current track's position expressed in milliseconds.

Since:

BlackBerry 10.2.0

void previousEnabledChanged (
  • boolprevEnabled)

This signal is emitted on notification that flag indicating availability of the preceding track has changed.

Parameters
prevEnabled

This value is true when preceding track is available, and false otherwise.

Since:

BlackBerry 10.2.0

void repeatModeChanged (

This signal is emitted when the player repeat value has changed.

Parameters
repeatMode

The new repeat value that the player has changed to.

Since:

BlackBerry 10.3.0

void shuffleModeChanged (

This signal is emitted when the player shuffle value has changed.

Parameters
repeatMode

The new shuffle value that the player has changed to.

Since:

BlackBerry 10.3.0

void trackChanged ()

This signal is emitted to indicate that the track currently playing has changed.

This is a light notification for delimiting tracks, which could be used for performance reasons instead of metaDataChanged().

Since:

BlackBerry 10.2.0

Last modified: 2014-09-30



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus