The HAMA agent is configured through a JSON file that specifies the audio zones, the GAMA modules and the guests they support,
and the properties and audio types associated with each guest.
You can store your configuration file anywhere; /etc/hama.conf is a convenient location.
You must specify this file's path when starting the HAMA agent process, by using the -c option; otherwise,
the process won't start. The HAMA agent reads the configuration at startup and loads the required GAMA modules to communicate
with the Android Audio HAL or the GAMA agents in guests.
Any fields that aren't relevant for a given object are simply ignored. This allows comments to be included in a configuration
by using JSON items with such names. JSON doesn't support duplicate item names, so if you want to put more than one comment in a
section, each comment needs a unique name.
You can write a multiline comment, using as many array entries as you need, to describe an object.
The example configuration makes use of comments to describe the options and their use.
The top-level objects in the configuration file are:
- zones — an array of objects, each describing a zone that SWAM should monitor or otherwise interact with
- modules — an array of objects, each describing a GAMA module that SWAM should load to communicate with guests,
and any module-specific settings
The zones array
Each object in the
zones array contains the following fields:
| Name |
Type |
Content |
|---|
| name |
string |
The human-readable name for this zone |
| card |
number |
The number of the io-audio card containing
the audio device associated with this zone |
| devno |
number |
The io-audio device number for
the audio device associated with this zone |
| audiomgmt_id |
string |
The name of the audio-management profile to use.
This should match the audiomgmt_id field in the io-audio configuration file's
[ctrl] section for the specified device |
| ducking_vol_ramp_ms |
number |
The number of milliseconds that an expected
ramp down from full volume to mute will take. This should match the value in the io-audio audio-policy
configuration file's [vol_ramp], name=ducking entry |
The order in which the zones are defined in this object determines the indexes used to identify them in subsequent configuration
objects.
The modules array
Each
modules array entry is an object with at least the first two of the following fields:
| Name |
Type |
Content |
|---|
| dll |
string |
The name of the DLL to load |
| guests |
object array |
A set of objects describing characteristics of individual
guests |
| port |
number |
The port that the module will listen to for guest GAMA client
connections. This field is present only for the GAMA module used with guests that run a GAMA agent. |
The guests array
Each object in the
guests array contains at least the first three of the following fields, and one of the last two:
| Name |
Type |
Content |
|---|
| name |
string |
The name of the guest to connect with |
| class |
number |
The class of the guest, which is a number from 1 to 4.
The class tells SWAM which discrete audio channels and level of audio-management event messaging it can expect from the
guest. |
| connect_to_zones |
array of numbers |
A mapping from host zone indexes to
guest zone identifiers. This array must have the same number of entries as the zones array. Entries for host zones
that are NOT to be connected to a guest zone must be set to -1. |
| server_addr |
string |
The address and port to use when connecting to the
Android Audio HAL, in the format address:port. This field is present
only in guests objects defined for the GAMA module used with Android guests.
The address token is either an IP address if a standard socket is used, or the string vsock
if the virtual socket (virtio-vsock) is used. |
| host_channel_types |
object |
An object describing the
audio types of channels associated with a given guest's transient, non-transient, and ducking audio.
This object is present for class 1, 2, or 3 guests. |
| host_watch_channel_types |
object |
An object describing the
audio types that should cause messages to be sent to the guest when the associated channels become active or become
inactive again. This object is present for class 4 guests. |
The host_channel_types object
The
host_channel_types object contains the following fields:
| Name |
Type |
Content |
|---|
| pause_proxy |
string |
The audio type of the channel that SWAM should open just
to cause host or other guest media playback to pause.
This field is used only for class 2 guests, because these guests can't route transient and non-transient audio to different
audio busses (and thus, there's no non-transient audio type used by the guest's virtio-snd vdev
instances). |
| non-transient |
string |
The audio type used by the virtio-snd
vdev stream through which the guest plays non-transient audio (e.g., music) |
| transient |
string |
The audio type used by the virtio-snd
vdev stream through which the guest plays transient audio (e.g., navigation announcements) |
| duck |
string |
The audio type used by the virtio-snd
vdev stream through which the guest plays audio that should duck but otherwise not interfere with other audio
streams |
The host_watch_channel_types object
The
host_watch_channel_types object is used only by class 4 guests, and contains the following fields:
| Name |
Type |
Content |
|---|
| suspend_on |
string array |
An array of audio type names, as defined in the
audio policy configuration file (audio-policy.conf), that will cause suspend and resume notifications
to be sent to the guest when it transitions to or from actively playing audio |
| duck_on |
string array |
An array of audio type names, as defined in the
audio policy configuration file (audio-policy.conf), that will cause duck notifications
to be sent to the guest when it transitions to or from actively playing audio |
Guest classes
There are four classes of guests. These classes reflect their audio-management capabilities and the level of audio information
they provide to the host.
- Class 1
- These guests:
- Send audio streams of different purposes to different devices, each of which is implemented by its own vdev instance
and has a different audio type for its channel (i.e., connection to io-audio)
- Route transient and non-transient audio to different devices
- Don't inform the host of their audio-management activity.
The host derives the guest's audio-management state from the activity on the guest's audio channels.
- Class 2
- These guests:
- Send audio streams of different purposes to different devices, each of which is implemented by its own vdev instance
and has a different audio type for its channel (i.e., connection to io-audio)
- Route transient and non-transient audio to the same device
- Inform the host when they begin playing non-transient audio
- Don't inform the host of their activity for managing transient audio.
The host derives the guest's audio-management state from the activity on the guest's audio channels for transient audio.
- Class 3
- These guests:
- Mix all audio streams from local applications into a single stream that gets routed to a single vdev instance.
This means all of the guest's audio is streamed through that vdev's channel (i.e., connection to
io-audio), with the same audio type.
- Inform the host of their audio-management activity.
- In their vdev configuration, use an audio type that's lower priority than the multimedia type in the
audio policy configuration file of the host. The default audio type is a good choice.
- Class 4
- These guests:
- Mix all audio streams from local applications into a single stream that gets routed to a single vdev instance.
This means all of the guest's audio is streamed through that vdev's channel (i.e., connection to
io-audio), with the same audio type.
- Don't have a mechanism to inform the host of their audio-management activity or state.