Add audio role API to QMediaPlayer.

Change-Id: Ia5e3e2fe714f10b6aad62f0a4801c607905c7e0d
Task-number: QTBUG-41054
Reviewed-by: Yoann Lopes <yoann.lopes@theqtcompany.com>

src/imports/multimedia/Video.qml

@@ -32,7 +32,7 @@
 ****************************************************************************/
 
 import QtQuick 2.0
-import QtMultimedia 5.0
+import QtMultimedia 5.6
 
 /*!
     \qmltype Video
@@ -268,6 +268,35 @@ Item {
     */
     property alias position:        player.position
 
+    /*!
+        \qmlproperty enumeration Video::audioRole
+
+        This property holds the role of the audio stream. It can be set to specify the type of audio
+        being played, allowing the system to make appropriate decisions when it comes to volume,
+        routing or post-processing.
+
+        The audio role must be set before setting the source property.
+
+        Supported values can be retrieved with supportedAudioRoles().
+
+        The value can be one of:
+        \list
+        \li MediaPlayer.UnknownRole - the role is unknown or undefined.
+        \li MediaPlayer.MusicRole - music.
+        \li MediaPlayer.VideoRole - soundtrack from a movie or a video.
+        \li MediaPlayer.VoiceCommunicationRole - voice communications, such as telephony.
+        \li MediaPlayer.AlarmRole - alarm.
+        \li MediaPlayer.NotificationRole - notification, such as an incoming e-mail or a chat request.
+        \li MediaPlayer.RingtoneRole - ringtone.
+        \li MediaPlayer.AccessibilityRole - for accessibility, such as with a screen reader.
+        \li MediaPlayer.SonificationRole - sonification, such as with user interface sounds.
+        \li MediaPlayer.GameRole - game audio.
+        \endlist
+
+        \since 5.6
+    */
+    property alias audioRole:       player.audioRole
+
     /*!
         \qmlproperty bool Video::seekable
 
@@ -413,6 +442,20 @@ Item {
         player.seek(offset);
     }
 
+    /*!
+        \qmlmethod list<int> Video::supportedAudioRoles()
+
+        Returns a list of supported audio roles.
+
+        If setting the audio role is not supported, an empty list is returned.
+
+        \since 5.6
+        \sa audioRole
+    */
+    function supportedAudioRoles() {
+        return player.supportedAudioRoles();
+    }
+
 }
 
 // ***************************************

src/imports/multimedia/plugins.qmltypes

@@ -1,12 +1,13 @@
-import QtQuick.tooling 1.1
+import QtQuick.tooling 1.2
 
 // This file describes the plugin-supplied types contained in the library.
 // It is used for QML tooling purposes only.
 //
 // This file was auto-generated by:
-// 'qmlplugindump -nonrelocatable QtMultimedia 5.5'
+// 'qmlplugindump -nonrelocatable QtMultimedia 5.6'
 
 Module {
+    dependencies: ["QtQuick 2.0"]
     Component {
         name: "QAbstractVideoFilter"
         prototype: "QObject"
@@ -195,6 +196,21 @@ Module {
                 "ResourceMissing": 3
             }
         }
+        Enum {
+            name: "AudioRole"
+            values: {
+                "UnknownRole": 0,
+                "AccessibilityRole": 7,
+                "AlarmRole": 4,
+                "GameRole": 9,
+                "MusicRole": 1,
+                "NotificationRole": 5,
+                "RingtoneRole": 6,
+                "SonificationRole": 8,
+                "VideoRole": 2,
+                "VoiceCommunicationRole": 3
+            }
+        }
         Property { name: "source"; type: "QUrl" }
         Property { name: "loops"; type: "int" }
         Property { name: "playbackState"; type: "PlaybackState"; isReadonly: true }
@@ -220,10 +236,12 @@ Module {
         }
         Property { name: "mediaObject"; type: "QObject"; isReadonly: true; isPointer: true }
         Property { name: "availability"; type: "Availability"; isReadonly: true }
+        Property { name: "audioRole"; revision: 1; type: "AudioRole" }
         Signal { name: "loopCountChanged" }
         Signal { name: "paused" }
         Signal { name: "stopped" }
         Signal { name: "playing" }
+        Signal { name: "audioRoleChanged"; revision: 1 }
         Signal {
             name: "availabilityChanged"
             Parameter { name: "availability"; type: "Availability" }
@@ -240,6 +258,7 @@ Module {
             name: "seek"
             Parameter { name: "position"; type: "int" }
         }
+        Method { name: "supportedAudioRoles"; revision: 1; type: "QJSValue" }
     }
     Component {
         name: "QDeclarativeCamera"

src/imports/multimedia/qdeclarativeaudio.cpp

@@ -46,6 +46,7 @@
 #include "qdeclarativemediametadata_p.h"
 
 #include <QTimerEvent>
+#include <QtQml/qqmlengine.h>
 
 QT_BEGIN_NAMESPACE
 
@@ -112,6 +113,7 @@ QDeclarativeAudio::QDeclarativeAudio(QObject *parent)
     , m_position(0)
     , m_vol(1.0)
     , m_playbackRate(1.0)
+    , m_audioRole(UnknownRole)
     , m_playbackState(QMediaPlayer::StoppedState)
     , m_status(QMediaPlayer::NoMedia)
     , m_error(QMediaPlayer::ServiceMissingError)
@@ -152,6 +154,78 @@ QDeclarativeAudio::Availability QDeclarativeAudio::availability() const
     return Availability(m_player->availability());
 }
 
+/*!
+    \qmlproperty enumeration QtMultimedia::Audio::audioRole
+
+    This property holds the role of the audio stream. It can be set to specify the type of audio
+    being played, allowing the system to make appropriate decisions when it comes to volume,
+    routing or post-processing.
+
+    The audio role must be set before setting the source property.
+
+    Supported values can be retrieved with supportedAudioRoles().
+
+    The value can be one of:
+    \list
+    \li UnknownRole - the role is unknown or undefined.
+    \li MusicRole - music.
+    \li VideoRole - soundtrack from a movie or a video.
+    \li VoiceCommunicationRole - voice communications, such as telephony.
+    \li AlarmRole - alarm.
+    \li NotificationRole - notification, such as an incoming e-mail or a chat request.
+    \li RingtoneRole - ringtone.
+    \li AccessibilityRole - for accessibility, such as with a screen reader.
+    \li SonificationRole - sonification, such as with user interface sounds.
+    \li GameRole - game audio.
+    \endlist
+
+    \since 5.6
+*/
+QDeclarativeAudio::AudioRole QDeclarativeAudio::audioRole() const
+{
+    return !m_complete ? m_audioRole : AudioRole(m_player->audioRole());
+}
+
+void QDeclarativeAudio::setAudioRole(QDeclarativeAudio::AudioRole audioRole)
+{
+    if (this->audioRole() == audioRole)
+        return;
+
+    if (m_complete) {
+        m_player->setAudioRole(QAudio::Role(audioRole));
+    } else {
+        m_audioRole = audioRole;
+        emit audioRoleChanged();
+    }
+}
+
+/*!
+    \qmlmethod list<int> QtMultimedia::Audio::supportedAudioRoles()
+
+    Returns a list of supported audio roles.
+
+    If setting the audio role is not supported, an empty list is returned.
+
+    \since 5.6
+    \sa audioRole
+*/
+QJSValue QDeclarativeAudio::supportedAudioRoles() const
+{
+    QJSEngine *engine = qmlEngine(this);
+
+    if (!m_complete)
+        return engine->newArray();
+
+    QList<QAudio::Role> roles = m_player->supportedAudioRoles();
+    int size = roles.size();
+
+    QJSValue result = engine->newArray(size);
+    for (int i = 0; i < size; ++i)
+        result.setProperty(i, roles.at(i));
+
+    return result;
+}
+
 QUrl QDeclarativeAudio::source() const
 {
     return m_source;
@@ -734,6 +808,8 @@ void QDeclarativeAudio::classBegin()
             this, SIGNAL(hasAudioChanged()));
     connect(m_player, SIGNAL(videoAvailableChanged(bool)),
             this, SIGNAL(hasVideoChanged()));
+    connect(m_player, SIGNAL(audioRoleChanged(QAudio::Role)),
+            this, SIGNAL(audioRoleChanged()));
 
     m_error = m_player->availability() == QMultimedia::ServiceMissing ? QMediaPlayer::ServiceMissingError : QMediaPlayer::NoError;
 
@@ -756,6 +832,8 @@ void QDeclarativeAudio::componentComplete()
         m_player->setMuted(m_muted);
     if (!qFuzzyCompare(m_playbackRate, qreal(1.0)))
         m_player->setPlaybackRate(m_playbackRate);
+    if (m_audioRole != UnknownRole)
+        m_player->setAudioRole(QAudio::Role(m_audioRole));
 
     if (!m_content.isNull() && (m_autoLoad || m_autoPlay)) {
         m_player->setMedia(m_content, 0);
@@ -1289,6 +1367,45 @@ void QDeclarativeAudio::_q_mediaChanged(const QMediaContent &media)
     \endtable
  */
 
+/*!
+    \qmlproperty enumeration QtMultimedia::MediaPlayer::audioRole
+
+    This property holds the role of the audio stream. It can be set to specify the type of audio
+    being played, allowing the system to make appropriate decisions when it comes to volume,
+    routing or post-processing.
+
+    The audio role must be set before setting the source property.
+
+    Supported values can be retrieved with supportedAudioRoles().
+
+    The value can be one of:
+    \list
+    \li UnknownRole - the role is unknown or undefined.
+    \li MusicRole - music.
+    \li VideoRole - soundtrack from a movie or a video.
+    \li VoiceCommunicationRole - voice communications, such as telephony.
+    \li AlarmRole - alarm.
+    \li NotificationRole - notification, such as an incoming e-mail or a chat request.
+    \li RingtoneRole - ringtone.
+    \li AccessibilityRole - for accessibility, such as with a screen reader.
+    \li SonificationRole - sonification, such as with user interface sounds.
+    \li GameRole - game audio.
+    \endlist
+
+    \since 5.6
+*/
+
+/*!
+    \qmlmethod list<int> QtMultimedia::MediaPlayer::supportedAudioRoles()
+
+    Returns a list of supported audio roles.
+
+    If setting the audio role is not supported, an empty list is returned.
+
+    \since 5.6
+    \sa audioRole
+*/
+
 /*!
     \qmlmethod QtMultimedia::MediaPlayer::play()
 

src/imports/multimedia/qdeclarativeaudio_p.h

@@ -48,6 +48,7 @@
 #include <QtCore/qbasictimer.h>
 #include <QtQml/qqmlparserstatus.h>
 #include <QtQml/qqml.h>
+#include <QtQml/qjsvalue.h>
 
 #include <qmediaplayer.h>
 
@@ -87,11 +88,13 @@ class QDeclarativeAudio : public QObject, public QQmlParserStatus
     Q_PROPERTY(QDeclarativeMediaMetaData *metaData READ metaData CONSTANT)
     Q_PROPERTY(QObject *mediaObject READ mediaObject NOTIFY mediaObjectChanged SCRIPTABLE false DESIGNABLE false)
     Q_PROPERTY(Availability availability READ availability NOTIFY availabilityChanged)
+    Q_PROPERTY(AudioRole audioRole READ audioRole WRITE setAudioRole NOTIFY audioRoleChanged REVISION 1)
     Q_ENUMS(Status)
     Q_ENUMS(Error)
     Q_ENUMS(Loop)
     Q_ENUMS(PlaybackState)
     Q_ENUMS(Availability)
+    Q_ENUMS(AudioRole)
     Q_INTERFACES(QQmlParserStatus)
 public:
     enum Status
@@ -136,6 +139,19 @@ public:
         ResourceMissing = QMultimedia::ResourceError
     };
 
+    enum AudioRole {
+        UnknownRole = QAudio::UnknownRole,
+        AccessibilityRole = QAudio::AccessibilityRole,
+        AlarmRole = QAudio::AlarmRole,
+        GameRole = QAudio::GameRole,
+        MusicRole = QAudio::MusicRole,
+        NotificationRole = QAudio::NotificationRole,
+        RingtoneRole = QAudio::RingtoneRole,
+        SonificationRole = QAudio::SonificationRole,
+        VideoRole = QAudio::VideoRole,
+        VoiceCommunicationRole = QAudio::VoiceCommunicationRole
+    };
+
     QDeclarativeAudio(QObject *parent = 0);
     ~QDeclarativeAudio();
 
@@ -154,6 +170,9 @@ public:
 
     Availability availability() const;
 
+    AudioRole audioRole() const;
+    void setAudioRole(AudioRole audioRole);
+
     QUrl source() const;
     void setSource(const QUrl &url);
 
@@ -196,6 +215,8 @@ public Q_SLOTS:
     void stop();
     void seek(int position);
 
+    Q_REVISION(1) QJSValue supportedAudioRoles() const;
+
 Q_SIGNALS:
     Q_REVISION(1) void playlistChanged();
 
@@ -225,6 +246,8 @@ Q_SIGNALS:
     void seekableChanged();
     void playbackRateChanged();
 
+    Q_REVISION(1) void audioRoleChanged();
+
     void availabilityChanged(Availability availability);
 
     void errorChanged();
@@ -253,6 +276,7 @@ private:
     int m_position;
     qreal m_vol;
     qreal m_playbackRate;
+    AudioRole m_audioRole;
 
     QMediaPlayer::State m_playbackState;
     QMediaPlayer::MediaStatus m_status;

src/multimedia/audio/qaudio.cpp

@@ -42,6 +42,7 @@ static void qRegisterAudioMetaTypes()
     qRegisterMetaType<QAudio::Error>();
     qRegisterMetaType<QAudio::State>();
     qRegisterMetaType<QAudio::Mode>();
+    qRegisterMetaType<QAudio::Role>();
 }
 
 Q_CONSTRUCTOR_FUNCTION(qRegisterAudioMetaTypes)
@@ -83,6 +84,26 @@ Q_CONSTRUCTOR_FUNCTION(qRegisterAudioMetaTypes)
     \value AudioInput    audio input device
 */
 
+/*!
+    \enum QAudio::Role
+
+    This enum describes the role of an audio stream.
+
+    \value UnknownRole              The role is unknown or undefined
+    \value MusicRole                Music
+    \value VideoRole                Soundtrack from a movie or a video
+    \value VoiceCommunicationRole   Voice communications, such as telephony
+    \value AlarmRole                Alarm
+    \value NotificationRole         Notification, such as an incoming e-mail or a chat request
+    \value RingtoneRole             Ringtone
+    \value AccessibilityRole        For accessibility, such as with a screen reader
+    \value SonificationRole         Sonification, such as with user interface sounds
+    \value GameRole                 Game audio
+
+    \since 5.6
+    \sa QMediaPlayer::setAudioRole()
+*/
+
 #ifndef QT_NO_DEBUG_STREAM
 QDebug operator<<(QDebug dbg, QAudio::Error error)
 {
@@ -143,6 +164,45 @@ QDebug operator<<(QDebug dbg, QAudio::Mode mode)
     }
     return dbg;
 }
+
+QDebug operator<<(QDebug dbg, QAudio::Role role)
+{
+    QDebugStateSaver saver(dbg);
+    dbg.nospace();
+    switch (role) {
+    case QAudio::UnknownRole:
+        dbg << "UnknownRole";
+        break;
+    case QAudio::AccessibilityRole:
+        dbg << "AccessibilityRole";
+        break;
+    case QAudio::AlarmRole:
+        dbg << "AlarmRole";
+        break;
+    case QAudio::GameRole:
+        dbg << "GameRole";
+        break;
+    case QAudio::MusicRole:
+        dbg << "MusicRole";
+        break;
+    case QAudio::NotificationRole:
+        dbg << "NotificationRole";
+        break;
+    case QAudio::RingtoneRole:
+        dbg << "RingtoneRole";
+        break;
+    case QAudio::SonificationRole:
+        dbg << "SonificationRole";
+        break;
+    case QAudio::VideoRole:
+        dbg << "VideoRole";
+        break;
+    case QAudio::VoiceCommunicationRole:
+        dbg << "VoiceCommunicationRole";
+        break;
+    }
+    return dbg;
+}
 #endif
 
 

src/multimedia/audio/qaudio.h

@@ -51,12 +51,26 @@ namespace QAudio
     enum Error { NoError, OpenError, IOError, UnderrunError, FatalError };
     enum State { ActiveState, SuspendedState, StoppedState, IdleState };
     enum Mode { AudioInput, AudioOutput };
+
+    enum Role {
+        UnknownRole,
+        MusicRole,
+        VideoRole,
+        VoiceCommunicationRole,
+        AlarmRole,
+        NotificationRole,
+        RingtoneRole,
+        AccessibilityRole,
+        SonificationRole,
+        GameRole
+    };
 }
 
 #ifndef QT_NO_DEBUG_STREAM
 Q_MULTIMEDIA_EXPORT QDebug operator<<(QDebug dbg, QAudio::Error error);
 Q_MULTIMEDIA_EXPORT QDebug operator<<(QDebug dbg, QAudio::State state);
 Q_MULTIMEDIA_EXPORT QDebug operator<<(QDebug dbg, QAudio::Mode mode);
+Q_MULTIMEDIA_EXPORT QDebug operator<<(QDebug dbg, QAudio::Role role);
 #endif
 
 QT_END_NAMESPACE
@@ -64,5 +78,6 @@ QT_END_NAMESPACE
 Q_DECLARE_METATYPE(QAudio::Error)
 Q_DECLARE_METATYPE(QAudio::State)
 Q_DECLARE_METATYPE(QAudio::Mode)
+Q_DECLARE_METATYPE(QAudio::Role)
 
 #endif // QAUDIO_H

src/multimedia/controls/controls.pri

@@ -36,7 +36,8 @@ PUBLIC_HEADERS += \
     controls/qvideowindowcontrol.h \
     controls/qmediaaudioprobecontrol.h \
     controls/qmediavideoprobecontrol.h \
-    controls/qmediaavailabilitycontrol.h
+    controls/qmediaavailabilitycontrol.h \
+    controls/qaudiorolecontrol.h
 
 PRIVATE_HEADERS += \
     controls/qmediaplaylistcontrol_p.h \
@@ -79,5 +80,6 @@ SOURCES += \
     controls/qaudioencodersettingscontrol.cpp \
     controls/qaudioinputselectorcontrol.cpp \
     controls/qaudiooutputselectorcontrol.cpp \
-    controls/qvideodeviceselectorcontrol.cpp
+    controls/qvideodeviceselectorcontrol.cpp \
+    controls/qaudiorolecontrol.cpp
 

src/multimedia/controls/qaudiorolecontrol.cpp

@@ -0,0 +1,111 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL21$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 or version 3 as published by the Free
+** Software Foundation and appearing in the file LICENSE.LGPLv21 and
+** LICENSE.LGPLv3 included in the packaging of this file. Please review the
+** following information to ensure the GNU Lesser General Public License
+** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** As a special exception, The Qt Company gives you certain additional
+** rights. These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#include "qmediacontrol_p.h"
+#include "qaudiorolecontrol.h"
+
+QT_BEGIN_NAMESPACE
+
+/*!
+    \class QAudioRoleControl
+    \inmodule QtMultimedia
+    \ingroup multimedia_control
+    \since 5.6
+
+    \brief The QAudioRoleControl class provides control over the audio role of a media object.
+
+    If a QMediaService supports audio roles it will implement QAudioRoleControl.
+
+    The functionality provided by this control is exposed to application code through the
+    QMediaPlayer class.
+
+    The interface name of QAudioRoleControl is \c org.qt-project.qt.audiorolecontrol/5.6 as
+    defined in QAudioRoleControl_iid.
+
+    \sa QMediaService::requestControl(), QMediaPlayer
+*/
+
+/*!
+    \macro QAudioRoleControl_iid
+
+    \c org.qt-project.qt.audiorolecontrol/5.6
+
+    Defines the interface name of the QAudioRoleControl class.
+
+    \relates QAudioRoleControl
+*/
+
+/*!
+    Construct a QAudioRoleControl with the given \a parent.
+*/
+QAudioRoleControl::QAudioRoleControl(QObject *parent)
+    : QMediaControl(*new QMediaControlPrivate, parent)
+{
+
+}
+
+/*!
+    Destroys the audio role control.
+*/
+QAudioRoleControl::~QAudioRoleControl()
+{
+
+}
+
+/*!
+    \fn QAudio::Role QAudioRoleControl::audioRole() const
+
+    Returns the audio role of the media played by the media service.
+*/
+
+/*!
+    \fn void QAudioRoleControl::setAudioRole(QAudio::Role role)
+
+    Sets the audio \a role of the media played by the media service.
+*/
+
+/*!
+    \fn QList<QAudio::Role> QAudioRoleControl::supportedAudioRoles() const
+
+    Returns a list of audio roles that the media service supports.
+*/
+
+/*!
+    \fn void QAudioRoleControl::audioRoleChanged(QAudio::Role role)
+
+    Signal emitted when the audio \a role has changed.
+ */
+
+
+#include "moc_qaudiorolecontrol.cpp"
+QT_END_NAMESPACE

src/multimedia/controls/qaudiorolecontrol.h

@@ -0,0 +1,69 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL21$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 or version 3 as published by the Free
+** Software Foundation and appearing in the file LICENSE.LGPLv21 and
+** LICENSE.LGPLv3 included in the packaging of this file. Please review the
+** following information to ensure the GNU Lesser General Public License
+** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** As a special exception, The Qt Company gives you certain additional
+** rights. These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef QAUDIOROLECONTROL_H
+#define QAUDIOROLECONTROL_H
+
+#include <QtMultimedia/qmediacontrol.h>
+#include <QtMultimedia/qaudio.h>
+
+QT_BEGIN_NAMESPACE
+
+// Class forward declaration required for QDoc bug
+class QString;
+
+class Q_MULTIMEDIA_EXPORT QAudioRoleControl : public QMediaControl
+{
+    Q_OBJECT
+
+public:
+    virtual ~QAudioRoleControl();
+
+    virtual QAudio::Role audioRole() const = 0;
+    virtual void setAudioRole(QAudio::Role role) = 0;
+
+    virtual QList<QAudio::Role> supportedAudioRoles() const = 0;
+
+Q_SIGNALS:
+    void audioRoleChanged(QAudio::Role role);
+
+protected:
+    explicit QAudioRoleControl(QObject *parent = 0);
+};
+
+#define QAudioRoleControl_iid "org.qt-project.qt.audiorolecontrol/5.6"
+Q_MEDIA_DECLARE_CONTROL(QAudioRoleControl, QAudioRoleControl_iid)
+
+QT_END_NAMESPACE
+
+#endif // QAUDIOROLECONTROL_H

src/multimedia/controls/qmediaplayercontrol.cpp

@@ -111,6 +111,7 @@ QMediaPlayerControl::QMediaPlayerControl(QObject *parent):
     Returns the status of the current media.
 */
 
+
 /*!
     \fn QMediaPlayerControl::mediaStatusChanged(QMediaPlayer::MediaStatus status)
 

src/multimedia/playback/qmediaplayer.cpp

@@ -42,6 +42,7 @@
 #include <qmediaplaylistcontrol_p.h>
 #include <qmediaplaylistsourcecontrol_p.h>
 #include <qmedianetworkaccesscontrol.h>
+#include <qaudiorolecontrol.h>
 
 #include <QtCore/qcoreevent.h>
 #include <QtCore/qmetaobject.h>
@@ -104,6 +105,7 @@ public:
     QMediaPlayerPrivate()
         : provider(0)
         , control(0)
+        , audioRoleControl(0)
         , state(QMediaPlayer::StoppedState)
         , status(QMediaPlayer::UnknownMediaStatus)
         , error(QMediaPlayer::NoError)
@@ -116,6 +118,7 @@ public:
 
     QMediaServiceProvider *provider;
     QMediaPlayerControl* control;
+    QAudioRoleControl *audioRoleControl;
     QMediaPlayer::State state;
     QMediaPlayer::MediaStatus status;
     QMediaPlayer::Error error;
@@ -596,6 +599,12 @@ QMediaPlayer::QMediaPlayer(QObject *parent, QMediaPlayer::Flags flags):
                 addPropertyWatch("bufferStatus");
 
             d->hasStreamPlaybackFeature = d->provider->supportedFeatures(d->service).testFlag(QMediaServiceProviderHint::StreamPlayback);
+
+            d->audioRoleControl = qobject_cast<QAudioRoleControl*>(d->service->requestControl(QAudioRoleControl_iid));
+            if (d->audioRoleControl) {
+                connect(d->audioRoleControl, &QAudioRoleControl::audioRoleChanged,
+                        this, &QMediaPlayer::audioRoleChanged);
+            }
         }
         if (d->networkAccessControl != 0) {
             connect(d->networkAccessControl, SIGNAL(configurationChanged(QNetworkConfiguration)),
@@ -616,6 +625,8 @@ QMediaPlayer::~QMediaPlayer()
     if (d->service) {
         if (d->control)
             d->service->releaseControl(d->control);
+        if (d->audioRoleControl)
+            d->service->releaseControl(d->audioRoleControl);
 
         d->provider->releaseService(d->service);
     }
@@ -1109,6 +1120,41 @@ QMultimedia::AvailabilityStatus QMediaPlayer::availability() const
     return QMediaObject::availability();
 }
 
+QAudio::Role QMediaPlayer::audioRole() const
+{
+    Q_D(const QMediaPlayer);
+
+    if (d->audioRoleControl != NULL)
+        return d->audioRoleControl->audioRole();
+
+    return QAudio::UnknownRole;
+}
+
+void QMediaPlayer::setAudioRole(QAudio::Role audioRole)
+{
+    Q_D(QMediaPlayer);
+
+    if (d->audioRoleControl)
+        d->audioRoleControl->setAudioRole(audioRole);
+}
+
+/*!
+    Returns a list of supported audio roles.
+
+    If setting the audio role is not supported, an empty list is returned.
+
+    \since 5.6
+    \sa audioRole
+*/
+QList<QAudio::Role> QMediaPlayer::supportedAudioRoles() const
+{
+    Q_D(const QMediaPlayer);
+
+    if (d->audioRoleControl)
+        return d->audioRoleControl->supportedAudioRoles();
+
+    return QList<QAudio::Role>();
+}
 
 // Enums
 /*!
@@ -1209,6 +1255,14 @@ QMultimedia::AvailabilityStatus QMediaPlayer::availability() const
     Signals the \a seekable status of the player object has changed.
 */
 
+/*!
+    \fn void QMediaPlayer::audioRoleChanged(QAudio::Role role)
+
+    Signals that the audio \a role of the media player has changed.
+
+    \since 5.6
+*/
+
 // Properties
 /*!
     \property QMediaPlayer::state
@@ -1376,6 +1430,19 @@ QMultimedia::AvailabilityStatus QMediaPlayer::availability() const
     while fast forwarding or rewinding.
 */
 
+/*!
+    \property QMediaPlayer::audioRole
+    \brief the role of the audio stream played by the media player.
+
+    It can be set to specify the type of audio being played, allowing the system to make
+    appropriate decisions when it comes to volume, routing or post-processing.
+
+    The audio role must be set before calling setMedia().
+
+    \since 5.6
+    \sa supportedAudioRoles()
+*/
+
 /*!
     \fn void QMediaPlayer::durationChanged(qint64 duration)
 

src/multimedia/playback/qmediaplayer.h

@@ -37,6 +37,7 @@
 #include <QtMultimedia/qmediaobject.h>
 #include <QtMultimedia/qmediacontent.h>
 #include <QtMultimedia/qmediaenumdebug.h>
+#include <QtMultimedia/qaudio.h>
 
 #include <QtNetwork/qnetworkconfiguration.h>
 
@@ -66,6 +67,7 @@ class Q_MULTIMEDIA_EXPORT QMediaPlayer : public QMediaObject
     Q_PROPERTY(qreal playbackRate READ playbackRate WRITE setPlaybackRate NOTIFY playbackRateChanged)
     Q_PROPERTY(State state READ state NOTIFY stateChanged)
     Q_PROPERTY(MediaStatus mediaStatus READ mediaStatus NOTIFY mediaStatusChanged)
+    Q_PROPERTY(QAudio::Role audioRole READ audioRole WRITE setAudioRole)
     Q_PROPERTY(QString error READ errorString)
     Q_ENUMS(State)
     Q_ENUMS(MediaStatus)
@@ -151,6 +153,10 @@ public:
 
     QMultimedia::AvailabilityStatus availability() const;
 
+    QAudio::Role audioRole() const;
+    void setAudioRole(QAudio::Role audioRole);
+    QList<QAudio::Role> supportedAudioRoles() const;
+
 public Q_SLOTS:
     void play();
     void pause();
@@ -187,6 +193,8 @@ Q_SIGNALS:
     void seekableChanged(bool seekable);
     void playbackRateChanged(qreal rate);
 
+    void audioRoleChanged(QAudio::Role role);
+
     void error(QMediaPlayer::Error error);
 
     void networkConfigurationChanged(const QNetworkConfiguration &configuration);

tests/auto/unit/qdeclarativeaudio/qdeclarativeaudio.pro

@@ -13,3 +13,7 @@ SOURCES += \
 
 INCLUDEPATH += ../../../../src/imports/multimedia
 DEFINES += QT_DISABLE_DEPRECATED_BEFORE=0
+
+include (../qmultimedia_common/mock.pri)
+include (../qmultimedia_common/mockplayer.pri)
+

tests/auto/unit/qdeclarativeaudio/tst_qdeclarativeaudio.cpp

@@ -38,6 +38,9 @@
 #include "qdeclarativeaudio_p.h"
 #include "qdeclarativemediametadata_p.h"
 
+#include "mockmediaserviceprovider.h"
+#include "mockmediaplayerservice.h"
+
 #include <QtMultimedia/qmediametadata.h>
 #include <qmediaplayercontrol.h>
 #include <qmediaservice.h>
@@ -45,6 +48,8 @@
 #include <qmetadatareadercontrol.h>
 
 #include <QtGui/qguiapplication.h>
+#include <QtQml/qqmlengine.h>
+#include <QtQml/qqmlcomponent.h>
 
 class tst_QDeclarativeAudio : public QObject
 {
@@ -73,9 +78,11 @@ private slots:
     void metaData();
     void error();
     void loops();
+    void audioRole();
 };
 
 Q_DECLARE_METATYPE(QDeclarativeAudio::Error);
+Q_DECLARE_METATYPE(QDeclarativeAudio::AudioRole);
 
 class QtTestMediaPlayerControl : public QMediaPlayerControl
 {
@@ -285,6 +292,7 @@ public:
 void tst_QDeclarativeAudio::initTestCase()
 {
     qRegisterMetaType<QDeclarativeAudio::Error>();
+    qRegisterMetaType<QDeclarativeAudio::AudioRole>();
 }
 
 void tst_QDeclarativeAudio::nullPlayerControl()
@@ -1007,6 +1015,47 @@ void tst_QDeclarativeAudio::loops()
     qDebug() << "Testing version 5";
 }
 
+void tst_QDeclarativeAudio::audioRole()
+{
+    MockMediaPlayerService mockService;
+    MockMediaServiceProvider mockProvider(&mockService);
+    QMediaServiceProvider::setDefaultServiceProvider(&mockProvider);
+
+    QQmlEngine engine;
+    QQmlComponent component(&engine);
+    component.setData("import QtQuick 2.0 \n import QtMultimedia 5.6 \n Audio { }", QUrl());
+
+    {
+        mockService.setHasAudioRole(false);
+        QDeclarativeAudio *audio = static_cast<QDeclarativeAudio*>(component.create());
+
+        QCOMPARE(audio->audioRole(), QDeclarativeAudio::UnknownRole);
+        QVERIFY(audio->supportedAudioRoles().isArray());
+        QVERIFY(audio->supportedAudioRoles().toVariant().toList().isEmpty());
+
+        QSignalSpy spy(audio, SIGNAL(audioRoleChanged()));
+        audio->setAudioRole(QDeclarativeAudio::MusicRole);
+        QCOMPARE(audio->audioRole(), QDeclarativeAudio::UnknownRole);
+        QCOMPARE(spy.count(), 0);
+    }
+
+    {
+        mockService.reset();
+        mockService.setHasAudioRole(true);
+        QDeclarativeAudio *audio = static_cast<QDeclarativeAudio*>(component.create());
+        QSignalSpy spy(audio, SIGNAL(audioRoleChanged()));
+
+        QCOMPARE(audio->audioRole(), QDeclarativeAudio::UnknownRole);
+        QVERIFY(audio->supportedAudioRoles().isArray());
+        QVERIFY(!audio->supportedAudioRoles().toVariant().toList().isEmpty());
+
+        audio->setAudioRole(QDeclarativeAudio::MusicRole);
+        QCOMPARE(audio->audioRole(), QDeclarativeAudio::MusicRole);
+        QCOMPARE(mockService.mockAudioRoleControl->audioRole(), QAudio::MusicRole);
+        QCOMPARE(spy.count(), 1);
+    }
+}
+
 QTEST_MAIN(tst_QDeclarativeAudio)
 
 #include "tst_qdeclarativeaudio.moc"

tests/auto/unit/qmediaplayer/tst_qmediaplayer.cpp

@@ -135,6 +135,7 @@ private slots:
     void testSupportedMimeTypes();
     void testQrc_data();
     void testQrc();
+    void testAudioRole();
 
 private:
     void setupCommonTestData();
@@ -1296,5 +1297,45 @@ void tst_QMediaPlayer::testQrc()
     QCOMPARE(bool(mockService->mockControl->mediaStream()), backendHasStream);
 }
 
+void tst_QMediaPlayer::testAudioRole()
+{
+    {
+        mockService->setHasAudioRole(false);
+        QMediaPlayer player;
+
+        QCOMPARE(player.audioRole(), QAudio::UnknownRole);
+        QVERIFY(player.supportedAudioRoles().isEmpty());
+
+        QSignalSpy spy(&player, SIGNAL(audioRoleChanged(QAudio::Role)));
+        player.setAudioRole(QAudio::MusicRole);
+        QCOMPARE(player.audioRole(), QAudio::UnknownRole);
+        QCOMPARE(spy.count(), 0);
+    }
+
+    {
+        mockService->reset();
+        mockService->setHasAudioRole(true);
+        QMediaPlayer player;
+        QSignalSpy spy(&player, SIGNAL(audioRoleChanged(QAudio::Role)));
+
+        QCOMPARE(player.audioRole(), QAudio::UnknownRole);
+        QVERIFY(!player.supportedAudioRoles().isEmpty());
+
+        player.setAudioRole(QAudio::MusicRole);
+        QCOMPARE(player.audioRole(), QAudio::MusicRole);
+        QCOMPARE(mockService->mockAudioRoleControl->audioRole(), QAudio::MusicRole);
+        QCOMPARE(spy.count(), 1);
+        QCOMPARE(qvariant_cast<QAudio::Role>(spy.last().value(0)), QAudio::MusicRole);
+
+        spy.clear();
+
+        player.setProperty("audioRole", qVariantFromValue(QAudio::AlarmRole));
+        QCOMPARE(qvariant_cast<QAudio::Role>(player.property("audioRole")), QAudio::AlarmRole);
+        QCOMPARE(mockService->mockAudioRoleControl->audioRole(), QAudio::AlarmRole);
+        QCOMPARE(spy.count(), 1);
+        QCOMPARE(qvariant_cast<QAudio::Role>(spy.last().value(0)), QAudio::AlarmRole);
+    }
+}
+
 QTEST_GUILESS_MAIN(tst_QMediaPlayer)
 #include "tst_qmediaplayer.moc"

tests/auto/unit/qmultimedia_common/mockaudiorolecontrol.h

@@ -0,0 +1,72 @@
+/****************************************************************************
+**
+** Copyright (C) 2015 The Qt Company Ltd.
+** Contact: http://www.qt.io/licensing/
+**
+** This file is part of the test suite of the Qt Toolkit.
+**
+** $QT_BEGIN_LICENSE:LGPL21$
+** Commercial License Usage
+** Licensees holding valid commercial Qt licenses may use this file in
+** accordance with the commercial license agreement provided with the
+** Software or, alternatively, in accordance with the terms contained in
+** a written agreement between you and The Qt Company. For licensing terms
+** and conditions see http://www.qt.io/terms-conditions. For further
+** information use the contact form at http://www.qt.io/contact-us.
+**
+** GNU Lesser General Public License Usage
+** Alternatively, this file may be used under the terms of the GNU Lesser
+** General Public License version 2.1 or version 3 as published by the Free
+** Software Foundation and appearing in the file LICENSE.LGPLv21 and
+** LICENSE.LGPLv3 included in the packaging of this file. Please review the
+** following information to ensure the GNU Lesser General Public License
+** requirements will be met: https://www.gnu.org/licenses/lgpl.html and
+** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
+**
+** As a special exception, The Qt Company gives you certain additional
+** rights. These rights are described in The Qt Company LGPL Exception
+** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
+**
+** $QT_END_LICENSE$
+**
+****************************************************************************/
+
+#ifndef MOCKAUDIOROLECONTROL_H
+#define MOCKAUDIOROLECONTROL_H
+
+#include <qaudiorolecontrol.h>
+
+class MockAudioRoleControl : public QAudioRoleControl
+{
+    friend class MockMediaPlayerService;
+
+public:
+    MockAudioRoleControl()
+        : QAudioRoleControl()
+        , m_audioRole(QAudio::UnknownRole)
+    {
+    }
+
+    QAudio::Role audioRole() const
+    {
+        return m_audioRole;
+    }
+
+    void setAudioRole(QAudio::Role role)
+    {
+        if (role != m_audioRole)
+            emit audioRoleChanged(m_audioRole = role);
+    }
+
+    QList<QAudio::Role> supportedAudioRoles() const
+    {
+        return QList<QAudio::Role>() << QAudio::MusicRole
+                                     << QAudio::AlarmRole
+                                     << QAudio::NotificationRole;
+    }
+
+    QAudio::Role m_audioRole;
+};
+
+#endif // MOCKAUDIOROLECONTROL_H
+

tests/auto/unit/qmultimedia_common/mockmediaplayerservice.h

@@ -42,6 +42,7 @@
 #include "mockvideorenderercontrol.h"
 #include "mockvideoprobecontrol.h"
 #include "mockvideowindowcontrol.h"
+#include "mockaudiorolecontrol.h"
 
 class MockMediaPlayerService : public QMediaService
 {
@@ -51,6 +52,7 @@ public:
     MockMediaPlayerService():QMediaService(0)
     {
         mockControl = new MockMediaPlayerControl;
+        mockAudioRoleControl = new MockAudioRoleControl;
         mockStreamsControl = new MockStreamsControl;
         mockNetworkControl = new MockNetworkAccessControl;
         rendererControl = new MockVideoRendererControl;
@@ -58,11 +60,13 @@ public:
         mockVideoProbeControl = new MockVideoProbeControl;
         windowControl = new MockVideoWindowControl;
         windowRef = 0;
+        enableAudioRole = true;
     }
 
     ~MockMediaPlayerService()
     {
         delete mockControl;
+        delete mockAudioRoleControl;
         delete mockStreamsControl;
         delete mockNetworkControl;
         delete rendererControl;
@@ -87,6 +91,8 @@ public:
                 windowRef += 1;
                 return windowControl;
             }
+        } else if (enableAudioRole && qstrcmp(iid, QAudioRoleControl_iid) == 0) {
+            return mockAudioRoleControl;
         }
 
         if (qstrcmp(iid, QMediaNetworkAccessControl_iid) == 0)
@@ -125,6 +131,8 @@ public:
 
     void selectCurrentConfiguration(QNetworkConfiguration config) { mockNetworkControl->setCurrentConfiguration(config); }
 
+    void setHasAudioRole(bool enable) { enableAudioRole = enable; }
+
     void reset()
     {
         mockControl->_state = QMediaPlayer::StoppedState;
@@ -143,11 +151,15 @@ public:
         mockControl->_isValid = false;
         mockControl->_errorString = QString();
 
+        enableAudioRole = true;
+        mockAudioRoleControl->m_audioRole = QAudio::UnknownRole;
+
         mockNetworkControl->_current = QNetworkConfiguration();
         mockNetworkControl->_configurations = QList<QNetworkConfiguration>();
     }
 
     MockMediaPlayerControl *mockControl;
+    MockAudioRoleControl *mockAudioRoleControl;
     MockStreamsControl *mockStreamsControl;
     MockNetworkAccessControl *mockNetworkControl;
     MockVideoRendererControl *rendererControl;
@@ -155,6 +167,7 @@ public:
     MockVideoWindowControl *windowControl;
     int windowRef;
     int rendererRef;
+    bool enableAudioRole;
 };
 
 

tests/auto/unit/qmultimedia_common/mockplayer.pri

@@ -8,6 +8,7 @@ HEADERS *= \
     ../qmultimedia_common/mockmediaplayercontrol.h \
     ../qmultimedia_common/mockmediastreamscontrol.h \
     ../qmultimedia_common/mockmedianetworkaccesscontrol.h \
-    ../qmultimedia_common/mockvideoprobecontrol.h
+    ../qmultimedia_common/mockvideoprobecontrol.h \
+    ../qmultimedia_common/mockaudiorolecontrol.h
 
 include(mockvideo.pri)