Audio Manager Compliant App Writer's Guide

Introduction

Moblin Audio Manager is a core component of Moblin, and it is used to manage all audio apps/streams/devices of the system with regards to the configuration file. If an audio application is not compliant with AM, what AM can do with this kind of App is basically limited to volume control, mute or unmute, and for LPE applications, AM will not be able to control the LPE stream. If an audio application is compliant with AM, AM will be able to pause the application with the cooperation of the application, and AM will be able to control the LPE stream that is created by LPE application.
AM provides a set DBUS methods and signals for user to write AM compliant applications, please refer to “Moblin Audio Manager API”.
This doc is a guide for developers to write AM compliant applications with the API spec. Readers of this doc should have the pre-knowledge of Moblin Audio Manager API spec.

Pre-Knowledge

Do Not Use ALSA API

AM compliant applications should not use ALSA API directly, and for applications that use MMF like Helix/Gstreamer should not use the ALSA plug-in of the MMF. Instead, they should use PA API . The reason is as following: In Helix, if user choose to use ALSA audio device, from code perspective, it will use Class CAudioOutLinuxAlsa, and if user pauses Helix, the _Reset function will be called, and inside the _Reset function, snd_pcm_drop and snd_pcm_prepare will be invoked.
The problem occurs inside snd_pcm_prepare. Because ALSA is configured to use PA, then the snd_pcm_prepare will finally go into ALSA plug-in for PA, and call pulse_prepare which will first pa_stream_disconnect, and then pa_stream_new.
The result is that if Helix uses ALSA audio device, Helix will execute pause of a pa_stream as “destroy pa_stream then create new pa_stream”, the semantic is fundamentally wrong for AM. So does Gstreamer, if Gstreamer uses alsasink, the issue is the same.
But if Gstreamer uses pulsesink, the issue does not exist. The pause of pipeline will call gstaudiosink’s gst_audioringbuffer_pause which in turns calls the pulsesink’s gst_pulsesink_reset, and inside that reset function, there’s no pa_stream disconnect/new operation, it’s just some PA function calls to pause that pa_stream.
So, conclusion is if user wants to write an AM compliant app, do not use ALSA anymore, instead, use PA APIs. For non-compliant apps, no restriction.

PA Stream Creation Notes

Stream Name

As written in API spec, after the AM stream is created inside AM (as soon as the pcm data is written into the pa_stream), AM will emit a signal StreamCreated which contains 4 arguments: binary name of the application, stream name of the created stream, AM stream id of the created stream, type of the created stream. Then application is supposed to use the AM stream id to execute commands from AM.
Pay attention to the stream name and AM stream id pair. If application created multiple audio streams, there must be a way for application to know which AM stream id refers to which audio stream; that’s what stream name does. When application creates pa_stream with pa_stream_new, application could specify the name of the pa_stream(set the proplist of pa_stream, key is am.stream.name, value is the stream name user specifies), so that after application receives the StreamCreated signal, application could know which AM stream id refers to which pa_stream; hence application could know which pa_stream to operate on when receives commands from AM, e.g. pause a stream of stream id xx. If application only creates on audio stream, then stream name is not important.
If application uses MMF and wants to create multiple audio streams. For Gstreamer, which means creating multiple pipelines, then pulsesink may need to be added a property stream_name which is to specify the name of the pa_stream that is created inside pulsesink. For Helix, TODO.

Stream Property

There are two properties of pa_stream that need to be pay attention to. One is “am.media.role”, the other is “LPE”. Media role actually specifies the priority of the audio stream; LPE specifies whether the audio stream is a LPE Decode-N-Return stream or not.
If application wants to specify the priority of the audio stream that is going to be created, application could set the “am.media.role” property of the pa_stream when creating the pa_stream using API pa_stream_new_with_proplist. If application does not specify am.media.role property, the media role of the audio stream will be gotten from configuration file if it is configured there, or be set with a default value.
If LPE application receives signal StreamDisableLPEDirectRender, it will shift from Fire-N-Forget to Decode-N-Return mode, and will create a pa_stream to receive the decoded data, it SHOULD specify the “LPE” property of the pa_stream to “yes”, so that AM could know that this a LPE Decode-N-Return stream.

LPE Stream Creation Notes

It should be noted that the LPE stream registration LPEStreamRegister will trigger evaluation inside Audio Manager if it succeeds, and one possible consequence is that the LPE APP/MMF may receive a StreamMuted signal right after registration (StreamCreated signal will be received first of course). Will this have impact on MMF implementation?
When invoking LPEStreamRegister, user could specify the name of the LPE stream if user want to create multiple LPE streams, so that user could distinguish the AM stream id between different LPE streams. And user could also specify the media role of the LPE stream

Programming Guide

None-LPE Application

Single Stream

It is simple to write applications of single stream, and this is the most common case. To write applications of single stream, user doesn’t even need to specify the stream name of the pa_stream; and it’s optional to set the am.media.role property. If am.media.role property is not set, AM will try to use configure info from configuration file, if there’s no info inside configuration file, default value will be applied.

Multiple Streams

The difference between writing application of multiple streams and writing application of single stream is that developer should pay attention to the AM stream id binding to pa_stream.

LPE Application

Single Stream

Writing a LPE application should be very similar to writing a non-LPE application. From application perspective, what it creates is AM stream, not LPE stream or PA stream. Below work flows assume MMF will call LPEStreamRegister during initial phase.

Code snippet

The attached seek.c is modified from gst-plugins-base/tests/examples/seek.c, it is added with AM related code thus become AM compliant, you can put it under gst-plugins-base folder and compile.