[SailfishDevel] Updates to resource policy implementation in QtMultimedia (update8)

[Juho Hämäläinen]

Updates to resource policy implementation in QtMultimedia
=========================================================

In next update (update8) there will be QtMultimedia with updates to the 
resource policy implementation. The goal of these resource policy 
implementation changes is to allow easier and simpler use of Qt/QML 
audio APIs while behind the scene playing nicely with the system 
resource manager.

There are three types of Qt classes for audio handling with resource 
policy implementation,
  * QMediaPlayer  [1]
  * QSoundEffect  [2]
  * QAudioOutput  [3]

There are two QML types for use with resource policy implementation
  * Audio  [4]
  * SoundEffect  [5]

In real life applications only QAudioOutput functionality changes 
noticeably (QAudioOutput didn't have any resource policy support 
previously), QMediaPlayer has already resource policy support and 
QSoundEffect resource policy support is improved.

QMediaPlayer / Audio
====================

This class is meant for playing longer audio files, for example if 
implementing media player or background music for game.

When QMediaPlayer object is created, it will automatically connect to 
the resource manager in the background and is immediately ready to use. 
When setting the object to playing state, QMediaPlayer internally tries 
to acquire resources for the application, and if resources are aqcuired, 
playback starts immediately. Otherwise playback will stall. When 
QMediaPlayer is in end of media or set to paused or stopped, after 2 
second timeout the object will release resources it has acquired.

QSoundEffect / SoundEffect
==========================

This class is meant for playing short sound effects, for example 
application UI clicks or other notifications, game sounds, etc. All 
sound effect type sounds are mixed on top of other sounds, so there can 
be media player playing music while sound effects are played.

When QSoundEffect object is created, it will automatically connect to 
the resource manager in the background and is immediately ready to use. 
When higher priority application is active (voice call, ringtone), 
calling play for the object does nothing. When no higher priority 
applications are active, or media player object is active, sound effect 
is played.

QAudioOutput
============

This class is meant for example when audio data is streamed.

When QAudioOutput object is created, it will automatically connect to 
the resource manager in the background and is immediately ready to use. 
  When setting the object to playing state, QAudioOutput internally 
tries to acquire resources for the application, and if resources are 
aqcuired, playback starts immediately. Otherwise playback will stall. 
When QAudioOutput is set to paused or stopped state, after 2 second 
timeout the object will release resources it has acquired.

Notes for both QMediaPlayer and QAudioOutput
============================================

User needs to  follow state changed signals from the object, since the 
change can  happen even without interaction with the application itself. 
(Other application acquires resources, voice call acquires resources)

Only one media player or audio output object can be in playing state at 
given time. Last object acquiring resources gets the resources.

Short note about volume behavior
================================

Unless volume or category is explicitly set for the classes, all follow 
system media volume (changed with the hardware volume keys).


[1] http://doc.qt.digia.com/qt-5.1/qtmultimedia/qmediaplayer.html
[2] http://doc.qt.digia.com/qt-5.1/qtmultimedia/qsoundeffect.html
[3] http://doc.qt.digia.com/qt-5.1/qtmultimedia/qaudiooutput.html
[4] http://doc.qt.digia.com/qt-5.1/qtmultimedia/qml-qtmultimedia5-audio.html
[5] 
http://doc.qt.digia.com/qt-5.1/qtmultimedia/qml-qtmultimedia5-soundeffect.html


Regards,
Juho Hämäläinen / jusa_