Add audio role API to QMediaPlayer.

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

8 files changed, 335 insertions, 2 deletions

diff --git a/src/multimedia/audio/qaudio.cpp b/src/multimedia/audio/qaudio.cpp
index 8b452a118..72c24ad9f 100644
--- a/src/multimedia/audio/qaudio.cpp
+++ b/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
 
 
diff --git a/src/multimedia/audio/qaudio.h b/src/multimedia/audio/qaudio.h
index 63953145c..2ee66bcc1 100644
--- a/src/multimedia/audio/qaudio.h
+++ b/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
diff --git a/src/multimedia/controls/controls.pri b/src/multimedia/controls/controls.pri
index b19532fdc..7ab2e51c4 100644
--- a/src/multimedia/controls/controls.pri
+++ b/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
 
diff --git a/src/multimedia/controls/qaudiorolecontrol.cpp b/src/multimedia/controls/qaudiorolecontrol.cpp
new file mode 100644
index 000000000..62696f013
--- /dev/null
+++ b/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
diff --git a/src/multimedia/controls/qaudiorolecontrol.h b/src/multimedia/controls/qaudiorolecontrol.h
new file mode 100644
index 000000000..983b2aed0
--- /dev/null
+++ b/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
diff --git a/src/multimedia/controls/qmediaplayercontrol.cpp b/src/multimedia/controls/qmediaplayercontrol.cpp
index 9ea6fde82..0c891a1d4 100644
--- a/src/multimedia/controls/qmediaplayercontrol.cpp
+++ b/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)
 
diff --git a/src/multimedia/playback/qmediaplayer.cpp b/src/multimedia/playback/qmediaplayer.cpp
index 5b271bcf3..396508aa9 100644
--- a/src/multimedia/playback/qmediaplayer.cpp
+++ b/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
@@ -1377,6 +1431,19 @@ QMultimedia::AvailabilityStatus QMediaPlayer::availability() const
 */
 
 /*!
+    \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)
 
     Signal the duration of the content has changed to \a duration, expressed in milliseconds.
diff --git a/src/multimedia/playback/qmediaplayer.h b/src/multimedia/playback/qmediaplayer.h
index 735f11130..437bf58ad 100644
--- a/src/multimedia/playback/qmediaplayer.h
+++ b/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);