Audio Manager API

Introduction

Audio Manager is implemented as two PulseAudio modules, one module contains general logic which is platform independent, the other module is specific for MRST platform, both of these two modules provides DBUS API to audio applications. If user just wants to write cooperative applications that are not specific for MRST, using the APIs and signals provided by generic module is enough; If user want to write cooperative applications that related to LPE and 3G functionality, the APIs and signals provided by MRST module are needed.
If user wants API for their own platform, just add their APIs into their self written platform module, and could use MRST platform implementation as example.
User are also recommend to read the code of audio manager to know more details of the APIs.

Methods

Methods for general audio apps

General audio applications refer to normal audio applications that use PulseAudio APIs. They are not involved with LPE or 3G. To write AM-compliant general audio applications, using methods and signals for general audio applications is enough.
Methods for general audio apps are provided at:
Name: org.moblin.audiomanager
Path: /org/moblin/audiomanager
Interface: org.moblin.audiomanager

Register
int32 register()
This API is to notify AM the coming of a cooperative APP, AM will record its DBUS sender id, process id, app binary name, etc. And if the app quits or accidentally died, AM could perform clean up. Audio manager compliant applications *must* use this API to notify audio manager, otherwise, audio manager will not emit any DBUS signals to notify the application to do pause or resume. This will reduce the traffic amount on DBUS since un-compliant applications will not introduce any un-necessary DBUS signals.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “Register”, &error, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
None None

Possible Return Values:
-1 Register failed
0 Register succeeded

Error codes:
-1 Register failed

Unregister
int32 unregister()
This API is to notify AM the leave of a cooperative APP, AM could perform clean up.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “Unregister”, &error, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
None None

Possible Return Values:
-1 UnRegister failed
0 UnRegister succeeded

Error codes:
-1 Register failed

StreamNotifyPause
int32 stream_notify_pause(uint32 stream_id, gboolean am_triggered)
Since all the pause need App to perform, so there need a way to notify AM whether this pause is user specific pause or is a result of internal pause signal which was previously sent from AM to notify APP to do pause. If am_triggered is FALSE, then it is to notify AM that user is going to perform an explicit pause, so that AM will NOT take this stream into consideration when performing reevaluation. So, user’s explicit pause will not be resumed by AM. If am_triggered is TRUE, it is to notify AM that the incoming pause is resulted from an pause signal, so that AM will take this stream into consideration when perform re-evaluation. This API is expected to be invoked inside user’s explicit pause function, and invoke with am_triggered as FALSE. This API is also expected to be invoked inside user’s internal pause signal handler, and invoke with am_triggered as TRUE. It should be invoked as the first line of code inside the function that performs the real pause. AM will use DBUS sender id to check whether sender owns the stream to ensure security.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “StreamNotifyPause”, &error, G_TYPE_UINT, stream_id, G_TYPE_BOOLEAN, am_triggered, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
stream_id audio manager stream id that will be notified
am_triggered Indicate whether the incoming pause is a user explicit pause (pause resulted from user action) or an internal pause (pause resulted from internal pause signal)
TRUE indicates it is an internal pause
FALSE indicates it is an explicitly user pause

Possible Return Values:
-1 Notification failed
0 Notification succeeded

Error codes:
-1 Notification failed

StreamNotifyResume
int32 stream_notify_resume(uint32 stream_id, gboolean am_triggered)
Since all the resume need App to perform, so there need a way to notify AM whether this resume is user specific resume or is a result of resume signal which was previously sent from AM to notify APP to do resume. If am_triggered is FALSE, then it is to notify AM that user is going to perform a explicit resume. If am_triggered is TRUE, then it is to notify AM that the resume is resulted from internal resume signal. This API is expected to be invoked inside user’s explicit resume function, and invoke with am_triggered as FALSE. This API is also expected to be invoked inside user’s internal resume signal handler, and invoke with am_triggered as TRUE. And it SHOULD be the first line of code inside the function that performs the real resume. AM will use DBUS sender id to check whether sender owns the stream to ensure security.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “StreamNotifyResume”, &error, G_TYPE_UINT, stream_id, G_TYPE_BOOLEAN, am_triggered, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
stream_id audio manager stream id that will be notified
am_triggered Indicate whether the incoming resume is a user explicit resume(resume resulted from user action) or an internal resume (resume resulted from internal resume signal)
TRUE indicates it is an internal resume
FALSE indicates it is an explicitly user resume

Possible Return Values:
-1 Notification failed
0 Notification succeeded

Error codes:
-1 Notification failed

Methods For MRST LPE Audio Apps

LPE audio applications refer to audio applications that want to use LPE functionality, no matter it directly use LPE driver interface or use MMF which in turn use LPE driver interface. To write AM-compliant LPE audio applications, developer need to use methods and signals both for generic audio apps and for LPE audio apps.
Methods for MRST audio apps are provided at:
Name: org.moblin.audiomanager
Path: /org/moblin/audiomanager/lpe
Interface: org.moblin.audiomanager.lpe

LPEStreamRegister
int32 lpe_stream_register(uint32 lpe_stream_id, char* media_role, char* lpe_stream_name, uint32 stream_type)
This API is to register a LPE fire-n-forget stream into AM, then AM will be aware of the existence of LPE stream. LPE APP/MMF is required to use this API to register LPE stream. If the some devices that does not prefer fire-n-forget are already in system, the am_lpe_stream_register will return failure to indicate fire-n-forget is not preferred, App should use decode-n-return mode. Lpe_stream_name is to indicate the name of the LPE fire-n-forget stream, AMStreamCreated signal will contain this information, so that LPE app could know which stream id refers to which LPE stream.
NOTE: though this method will directly return the am stream id, AM still will emit AMStreamCreated signal if the registration succeeded. Reason is: even MMF could get the am stream id directly, but app may not know the stream id, and we want LPE APP and None-LPE APP to be written as similar as possible (LPE app may not want to listen to gst bus), and we want apps only see am stream, rather than LPE stream or PA stream.
This method call will also trigger evaluation inside AM, and it may cause the APP/MMF that calls this API to receive StreamMuted signal.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “LPEStreamRegister”, &error, G_TYPE_UINT, lpe_stream_id, G_TYPE_STRING, media_role, G_TYPE_STRING, lpe_stream_name, G_TYPE_UINT, stream_type, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
lpe_stream_id LPE stream id from LPE driver perspective, AM will use LPE stream id to call LPE IOCTLs to control LPE stream. LPE stream id could be got using LPE IOCTL SNDRV_LPE_STREAM_SET_PARAMS
media_role Indicate the media role of this LPE stream, so that the LPE stream will be associated with some priority inside AM
lpe_stream_name The name of the LPE fire-n-forget stream, it will be contained inside AMStreamCreated signal. If App created two LPE fire-n-forget stream, app could use this name to know which am stream id refers to which LPE stream.
stream_type 0 indicates playback stream
1 indicates capture stream

Possible Return Values:
-1 Registration failed
-2 Registration failed
X Audio manager stream id. AM will create an audio manager stream structure inside AM, and will return the audio manager stream id

Error codes:
-1 Registration failed
-2 Fire-n-Forget not preferred, use Decode-n-Return

LPEStreamNotifyPause
int32 lpe_stream_notify_pause(uint32 stream_id)
This API is to notify AM that a LPE stream has paused. LPE APP/MMF is required to use this API to notify AM if the state of LPE stream has changed.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “LPEStreamNotifyPause”, &error, G_TYPE_UINT, stream_id, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
stream_id audio manager stream id that will be notified

Possible Return Values:
-1 Notification failed
0 Notification succeeded

Error codes:
-1 Notification failed

LPEStreamNotifyResume
int32 lpe_stream_notify_resume(uint32 stream_id)
This API is to notify AM that a LPE stream has resumed. LPE APP/MMF is required to use this API to notify AM if the state of LPE stream has changed.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “LPEStreamNotifyResume”, &error, G_TYPE_UINT, stream_id, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
stream_id audio manager stream id that will be notified

Possible Return Values:
-1 Notification failed
0 Notification succeeded

Error codes:
-1 Notification failed

LPEStreamUnregister
int32 lpe_stream_unregister(uint32 stream_id)
This API is to notify AM that a LPE stream has gone. LPE APP/MMF is expected to use this API to notify AM when LPE stream leaves, so that AM could perform clean up. If App accidentally died, AM could detect via Dbus mechanism (org.freedesktop.DBus.NameOwnerChanged signal) and then perform clean up.
If APP/MMF receives signal to transfer its mode from fire-n-forget to decode-n-return, it *must* call LPEStreamUnregister first before creating pa_stream.

GLIB invoke prototype:
dbus_g_proxy_call(proxy, “LPEStreamUnregister”, &error, G_TYPE_UINT, stream_id, G_TYPE_INVALID, G_TYPE_INT, &return_value, G_TYPE_INVALID)

Parameters:
stream_id audio manager stream id that will be unregistered

Possible Return Values:
-1 Unregistration failed
0 Unregistration succeeded

Error codes:
-1 Unregistration failed

Methods For MRST 3G Audio Apps

Not listed here

Signals

Signals For General Audio Apps

General signals are provided at:
Name: org.moblin.audiomanager
Path: /org/moblin/audiomanager
Interface: org.moblin.audiomanager
Signals are expected to be handled by audio APP/MMF, not central audio control APP. Central audio control app is actually kind of app that could control all audio streams/apps/devices on the system. It is a place that actually trigger signals.

StreamCreated
stream_created(char* app_binary, char* stream_name, uint32 stream_id, uint32 type)
APP doesn’t know when will its corresponding audio manager stream be created inside AM. So AM will use this signal to notify APP. APP could use the app_binary to determine whether this signal is sent to itself, then record its stream id, and type (capture or playback). App could use stream_name to bind the stream id to its pa_stream if it uses PA API to create audio streams. If app does not use PA API to create audio streams, it is hard for App to bind the stream id to its audio stream unless it only creates one audio stream.

Signal Name:
StreamCreated

Parameters:
app_binary The app binary info of that stream, application could use this parameter to determine whether this signal is sent to itself
stream_name The stream name of audio manager stream that has been created by AM. When application has multiple pa_streams. Application could set name for its individual pa_streams by setting the name argument of pa_stream_new/pa_stream_new_with_proplist.(key is am.stream.name, value is the stream name that user want to set) Then application could use this stream_name to bind the am_stream_id to its pa_stream
If application uses MMF like Gstreamer/Helix, setting the name of the pa_stream needs MMF’s support. Take Gstreamer for example, pulsesink may need to provide a property to set the name of the pa_stream which is created inside pulsesink.
stream_id Audio manager stream id of the AM stream that has been created inside AM
type Audio manager stream type, 0 indicates this is a playback stream, 1 indicates this is a capture stream

StreamDestroyed
stream_destroyed(uint32 stream_id)
APP doesn’t know when will its corresponding audio manager stream be destroyed inside AM. So AM will use this signal to notify APP.

Signal Name:
StreamDestroyed

Parameters:
stream_id Audio manager stream id of the AM stream that has been destroyed

StreamMuted
stream_muted(uint32 stream_id, gboolean pause)
This signal is to notify APP that the audio stream is muted, and app is advised to perform pause is pause is TRUE.
APP could use this signal to update its UI.

Signal Name:
StreamMuted

Parameters:
stream_id Audio manager stream id of the AM stream that has been muted and is advised to be paused.
pause TURE indicates the am stream is advised to be paused
FALSE indicates the am stream is not advised to be paused

StreamUnmuted
stream_unmuted(uint32 stream_id, gboolean resume)
This signal is to notify APP that the audio stream is unmated, and app is adviced to perform resume is resume is TRUE.

Signal Name:
StreamUnmuted

Parameters:
stream_id Audio manager stream id of the AM stream that has been un-muted and is advised to be resumed.
pause TURE indicates the am stream is advised to be resumed
FALSE indicates the am stream is not advised to be resumed

Signals For MRST LPE Audio Apps

MRST signals are provided at:
Name: org.moblin.audiomanager
Path: /org/moblin/audiomanager/lpe
Interface: org.moblin.audiomanager.lpe

StreamEnableLPEDirectRender
stream_enable_lpe_direct_render(uint32 stream_id)
This signal is to notify LPE APP/MMF to switch its mode from decode-n-return to fire-n-forget, LPE APP/MMF is required to handle this signal.

Signal Name:
StreamEnableLPEDirectRender

Parameters:
stream_id Audio manager stream id of the AM stream that is notified to switch its mode to fire-n-forget. NOTE: when LPE stream switched its mode from fire-n-forget to decode-n-return and created a pa_stream, it should specify a property in pa_stream structure to indicate that this pa_stream actually represents a LPE decode-n-return stream, so that AM could be aware which AM stream need to be notified by this signal

StreamDisableLPEDirectRender
stream_disable_lpe_direct_render(uint32 stream_id)
This signal is to notify LPE APP/MMF to switch its mode from fire-n-forget to decode-n-return, LPE APP/MMF is required to handle this signal. After receiving this signal, APP/MMF *must* first unregister its LPE stream use lpe_stream_unregister and then create pa_stream to receive the decode-n-return data. pa_stream_new_with_proplist should be used to create pa_stream, and there should be a pair [key:LPE, value:yes] inside pa_proplist.

Signal Name:
StreamDisableLPEDirectRender

Parameters:
stream_id Audio manager stream id of the AM stream that is notified to switch its mode to decode-n-return.

Signals For MRST 3G Audio Apps

Not listed here