Add audio role API to QMediaPlayer.

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

4 files changed, 206 insertions, 3 deletions

diff --git a/src/imports/multimedia/Video.qml b/src/imports/multimedia/Video.qml
index fda876805..9d28cabbd 100644
--- a/src/imports/multimedia/Video.qml
+++ b/src/imports/multimedia/Video.qml
@@ -32,7 +32,7 @@
 ****************************************************************************/
 
 import QtQuick 2.0
-import QtMultimedia 5.0
+import QtMultimedia 5.6
 
 /*!
     \qmltype Video
@@ -269,6 +269,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
 
         This property holds whether the playback position of the video can be
@@ -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();
+    }
+
 }
 
 // ***************************************
diff --git a/src/imports/multimedia/plugins.qmltypes b/src/imports/multimedia/plugins.qmltypes
index d01c988ba..11d423f24 100644
--- a/src/imports/multimedia/plugins.qmltypes
+++ b/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"
diff --git a/src/imports/multimedia/qdeclarativeaudio.cpp b/src/imports/multimedia/qdeclarativeaudio.cpp
index 60af6234b..5ef9ead15 100644
--- a/src/imports/multimedia/qdeclarativeaudio.cpp
+++ b/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);
@@ -1290,6 +1368,45 @@ void QDeclarativeAudio::_q_mediaChanged(const QMediaContent &media)
  */
 
 /*!
+    \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()
 
     Starts playback of the media.
diff --git a/src/imports/multimedia/qdeclarativeaudio_p.h b/src/imports/multimedia/qdeclarativeaudio_p.h
index eef705479..d8363969d 100644
--- a/src/imports/multimedia/qdeclarativeaudio_p.h
+++ b/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;