The UCM2 master file
====================

The master file is the root config file for an UCM profile. It lists which usecases are available and what config
files those are located in. It also allows running sequences once at boot.

Here is an exhaustive example of the master file::

    Syntax 2

    # This is a file comment, they are stripped on parsing

    # This is not a comment, it's the name
    Comment "This is the display name of the profile"

    # The HiFi usecase is the normal audio profile for a soundcard
    SectionUseCase."HiFi" {
        # The file in the same directory that contains all the config
        File "my_hifi_config_file"
        # The display name for this profile, as shown in the distributions sound settings
        Comment "Play and record HiFi quality audio"
    }

    # A secondary profile for call audio routing
    SectionUseCase."Voice Call" {
        File "VoiceCall.conf"
        Comment "Make a voice call"
    }

    # Commands executed once on boot only, sequence format documented later
    BootSequence [
       cset "name='Master Playback Switch' on"
    ]

    # Commands executed before setting the first verb/usecase. Or when running
    # alsaucm set_defaults... I think
    SectionDefaults [
       cset ""
    ]

The first line in the master file is ``Syntax 2``. This is to make the parser parse
this configuration file in UCM v2 format. This field is required to be in the file and
has to be 2..5.

Setting the ``Syntax`` above 2 will enable additional parser features for the ucm file.

Usecases / verbs
----------------

The main purpose of the master file is to link together all the usecases. Every usecase
is a seperate config file which defines audio routing and is referred to by a verb.

In the example above there are two usecases defined with the verbs "HiFi" and "Voice Call".

The current valid verbs for usecases are:

* Inactive
* HiFi
* HiFi Low Power
* Voice
* Voice Low Power
* Voice Call
* Voice Call IP
* FM Analog Radio
* FM Digital Radio

The hardcoded verb list is to make userspace programs able to enable one of these verbs
for the predefined usecases. For example for a voice call the dialer might switch to the
Voice Call audio profile so the underlaying hardware audio routing could enable the sound
from and to the modem.

On top of the defined usecases there are also modifiers that can be passed to quickly
switch routing while the audio is streaming. This can be used to play a ringtone while
in the HiFi usecase or start voice recording while in a call.

The defined Use Case Modifiers are:

* Capture Voice
* Capture Music
* Play Music
* Play Voice
* Play Tone
* Echo Reference

The predefiend usecases and modifiers have no documentation beyond their name.

The usecase is defined in the master config file by creating an ``SectionUseCase`` block::

   SectionUseCase."HiFi" {
       File "configfilename"
       Comment "Play and record HiFi quality audio"
   }

The identifier after the ``SectionUseCase`` keyword is one of the predefined verbs from
the last above. The ``Comment`` is the name that will be shown to the end user in the
audio settings of the desktop environment. This will be the name for the PulseAudio
profile for example after PulseAudio maps the usecases to profiles.

Bootsequence
------------

The bootsequence is the sequence of commands that is only run once after booting the system
but before executing the first usecase.

SectionDefaults
---------------

This is honestly so undocumented that it's not even funny.