4. Config Files

There are two types of configuration files used in Asset Manager.

Main Asset Manager config file (am_config.txt)
Project configuration file.

am_config.txt file is used to set the global behaviors of Asset Manager, including I/O channels, default master level, and project list.

User specified project file is used to set I/O and panner configuration for a specific project or number projects. This file is reusable by any number of projects.

4.1 am_config.txt File

am_config.txt file is located inside the Configs folder. The syntax loosely resembles JSON, a lightweight data-interchange format. The configuration file allow inline // style comments and tab and spaces are ignored. Multi-line comments, /* */, are not supported. ,s and ;s are not necessary at the end of the line.

The file is broken up into two sections: Configs and Projects. Each section is indicated by its name and curly brackets {}. The opening bracket { should be specified on the same line as the section name.

Configs section:

Inputs, Outputs: Map hardware I/O to software I/O.

Example: Outputs = 1 3 5 7

This maps hardware outputs 1, 3, 5 and 7 to software outputs 1, 2, 3, and 4 respectively. In other words, specifying output 2 in Asset Manager (e.g. using am.dac~ object or in project configuration file) will actually send the audio to output 3 of the hardware.

A range of channels are specified using -. For example, 1-4 is equal to specifying 1 2 3 4. Channels are delimited with space and no commas should be used.

Example: Outputs = 1-4 9

Max/MSP's I/O Mapping: Since Asset Manager is built on top of Max/MSP, I/O mapping setup in Max will affect the I/O mapping in Asset Manager. The "hardware I/O" is technically the I/O setup in Max/MSP. Max/MSP's I/O mapping can be setup from the DSP Status window.

Using Aggregate devices: If you use aggregate devices, channel IDs depend on the order of the interfaces and how they were setup.
MaxActiveProjects: Specify the maximum number of projects that can be loaded at all time. Argument is an integer.
MasterLevel: Specify the default master level. Argument is a number in decibel.

Minimum is -inf dB and maximum is +9.6 dB Specifying the unit dB is optional. Not specifying the value will default to -inf dB.

Projects section:

This section lists all the projects that Asset Manager manages. Each line should specify a single project. The syntax is given as:

OSCAddressPattern = "Project Name" [config file] [autolaod]
- OSCAddressPattern: Specify the Open Sound Control address associated with the project. Each project is associated with a unique OSC address and the address is used for routing appropriate OSC messages to the projects and controlling its states.
- "Project Name": Name of Max patch that should be loaded from Asset Manager. This is typically the top level patch of the project. If the name contains spaces, the entire name must be surround by double quotes. Names without spaces do not need double quotes.
- [config file]: Optionally, a configuration file for the project can be specified. If a configuration file is not specified, Asset Manager will try to load a file with a filename {Project Name}_config.txt (without the curly brackets). For example, if the project is SimpleProject, Asset Manager will look for a file SimpeProject_config.txt.
- [autoload]: Optionally, a keyword autoload can be used to specify if the project should be automatically loaded on startup. When a project is set to autoload, it no longer responds to the /AM/Load and /AM/Unload network messages. Details on specific OSC messages can be found at the section 9. Open Sound Control.
- [mute]: Optionally, a keyword mute can be used to mute projects specified by autoload on load.
Note: conventionally, we have been including all projects inside _common/Projects folder and using the same name for the main project patch and the folder enclosing the patch.

The following is an example of am_config.txt:

// am_config.txt
//
// Updated v1.2.0
//
// This is the main configuration file for Asset Manager.

//------------------------------------------------------------------
// Configs
//------------------------------------------------------------------
// System level configurations.
//
// Syntax:
//  Variable = Values
//
Configs {
    // Specify hardware input and output channels
    // Hardware I/O are mapped to virtual I/O in ascending order. For
    // example, if hardware inputs are specified as "1 3 5 7", virtual 
    // inputs are mapped to "1 2 3 4".  
    Inputs = 1-2 4-5
    Outputs = 1-8

    // Maximum number of projects that can run concurrently
    MaxActiveProjects = 10

    // Set the master output level in dB. Max is +9.6dB. Default is -inf.
    MasterLevel = 0.0
    // Set the volume limiter for absolute maximum volume.
    // Currently the values are limited to -24dB to +24dB.
    LimiterLevel = 0.0
}

//------------------------------------------------------------------
// Projects
//------------------------------------------------------------------
// List all OSC Address Patterns and the associated projects.
// Project name and the folder name should be identical. 
//
// Syntax:
//     OSCAddressPattern = "ProjectName" [config file] [autoload]
//
// OSCAddressPattern    Should not include any spaces.
// ProjectName          Project name must be identical to the project's 
//                      folder and its main patch. The name can include 
//                      spaces as long as it is surrounded by double 
//                      quotes.
// [config file]    (Optional) Specify the config file that the project
//                      should load on start. If the config file is not 
//                      specified, Asset Manager will try to load 
//                      {ProjectName}_config.txt as the default.
// [autoload]           (Optional) Specify a keyword "autoload" to
//                      load the project on startup. Additionally, projects
//                      that are specified as autoload will not respond to
//                      remote network load and unload messages. i.e. the
//                      projects can only be loaded/unloaded using the main
//                      graphical user interface.
// [mute]               (Optional) Specify a keyword "mute" to set projects
//                      that are set to "autoload" to mute DSP when loaded.
Projects {
    /SampleProject = SampleProject autoload
}

4.2 Project Configuration File

Project configuration file specifies the I/O and panner setup for a project. The use of configuration file allows abstraction of hardware and specific panner implementation.

In 3.3 Signal Flow Overview we mentioned three signal paths: Project Outputs, Panner Outputs, and Auxiliary Outputs. In the project configuration file, we have three sections mapping to each signal output types.

SampleProject_config.txt has detail comments regarding the parameters for each sections.

// ProjectConfig 
// 
// Updated: v1.1.5
//
// This file specify configurations for individual projects.
//
//
// Config Sections:
//      1. Project
//      2. Panner
//        2a. Transform 
//      3. Aux
//        3a. Transform
//
//
// Project Signal Flow:
//
//      The top level object names ([project.out~], [project.panner~], 
//  [project.panner.out~] and [project.auxout~]) are actual patcher names 
//  used in the project. Other objects (in []) are symbolic name used for 
//  conveniently drawing the diagram.
//  
//  Figure 1.
//
//    1. Project            2. Panner               3. Aux
//
//                      [project.panner~]
//                              | 
//  [project.out~]    [project.panner.out~]     [project.aux.out~]
//         | A channels         | B channels            | D channels
//         |                    |                       | 
//         |                2a. |                   3a. | 
//         |               [transform]             [transform]
//         |                    | C channels            | E channels
//         |                    |                       | 
//         |--------------------+-----------------------|
//                              | channel sum
//                              | max(A,{B,C},{D,E}) <= F <= A+{B,C}+{D,E} 
//                              | channels 
//                              |
//                       [volume matrix]
//                              | max(A,{B,C},{D,E}) <= F <= A+{B,C}+{D,E} 
//                              | channels 
//                              |
//                       [system output]
//
//
//      A-F channels specify the number of channels at each signal point. 
//  Following list shows all the variables to set. ('.' represents 
//  indentation. For example, Project{ num_outputs } is represented 
//  as Project.num_outputs.)
//
//      A:  Project.num_outputs 
//      B:  Panner.num_outputs
//      C:  Panner.Transform.num_outputs
//      D:  Aux.num_outputs
//      E:  Aux.Transform.num_outputs
//
//

//------------------------------------------------------------------
// 1. Project (Required)
//------------------------------------------------------------------
// Specify the default project output volume and number of outputs to 
// the system's outputs.
//
// Variables:
//      volume = <value in dB>
//      num_outputs = <project output channel count>
//      output_channels = <list of channels to system out>
//
// Descriptions:
//      volume
//
//          Set initial volume (in dB) of the project. Default value 0.0
//          is used if volume is not set. This volume also controls the 
//          relative volume of signals from Panner and Aux 
//
//
//      num_outputs
//
//          Total number of outputs from [project.out~]. If num_outputs is
//          8, project outputs can be specified in range of 1-8. For example,
//          [project.out~ 1 2 3 4 5 6 7 8]. (Note: range specifier '-'
//          cannot be used for the argument of [project.out~] object.)
//          This value is implied by output_channels.
//
//
//      output_channels
//      Also see: Panner.output_channels (under 2. Panner)
//                Aux.output_channels (under 3. Aux)
//
//          These parameters specify a list of system output channels that 
//          are used to route audio from [project.out~], Panner (or its 
//          Transform if it's used), and Aux (or its Transform if its used) 
//          to system outputs. For example, all outputs may be routed to
//          different system outputs by specifying different channels.
//
//          Example diagram:
//
//          Figure 2.
//
//                     [Project]          [Panner]       [Aux]
//                         |                 |             |
//          output_        |---|     |---|---+---|---|     |
//          channels:     1|  2|    1|  2|  3|  5|  6|    4|
//                   [------------- system outputs -------------]
//
//          This is an example of setting up a 5.1 panner and use Aux as 
//          the LFE channel. Channel mapping uses SMPTE 5.1 format. Project 
//          output can feed stereo without going through the panner.
//
//          Furthermore, range of channels can be specified using '-' 
//          between the low and high range. (e.g. 2-4 = 2 3 4)
//
//
//      total_system_outputs (for reference)
//
//          Total number of output to the system outputs. This value is 
//          automatically calculated, and does not need to be set in this
//          config file. Using the A-F letters defined above, value 
//          the number of system output, F, can be represented using the 
//          following equation:
//
//                  max(A,{B,C},{D,E}) <= F <= A+{B,C}+{D,E} 
//
//          where {B,C} is B or C and {D,E} is D or E, depending on if
//          Transform is on or off.
//
Project {
    volume = 0.0
    // No need to set num_outputs because that is implied from 
    // output_channels
    // num_outputs = 2
    output_channels = 1 2   // or 1-2
}


//------------------------------------------------------------------
// 2. Panner (Optional)
//------------------------------------------------------------------
// Specify the panning method and its settings used for this project.
// The panner is a custom patcher using panner.3d.input and 
// project.panner.out~ abstractions.
//
// Variables:
//      num_outputs = <panner output channel count>
//      output_channels = <list of channels to system outputs>
//      patch = <Name of panner patcher>
//      msg = <message value>
//      use_transform = <1 or 0>
//      Transform {}
//
// Descriptions:
//      num_outputs
//
//          Number of outputs from the panner patcher. This depends on the 
//          actual patcher. Some generic panner patchers (e.g. vbap.3d)
//          require the number of outputs as an argument. In this case, the
//          value should be the same as the argument. In other cases, the
//          value must be known.
//
//
//      output_channels
//
//          output_channels list the indices of system output channels that
//          the Panner use to output the signal. The number of indices must
//          match Panner.num_outputs or Panner.Transform.num_outputs if 
//          Transform is used (see below for setting Transform). If 
//          num_outputs = 8 and Transform.num_outputs = 1, and 
//          use_transform = 1, output_channels must list 2 indices. If 
//          use_transform = 0, then output_channels must list 8 indices.
//
//          Example diagram:
//
//          Figure 3.
//
//                      use_transform = 0         use_transform = 1
//                          [panner]                  [panner]
//                             |                         |
//                             |                     [transform]
//                             |                         |
//          indices:   Panner.num_outputs    Panner.Transform.num_outputs
//
//
//      patch
//
//          Specify patcher name with (optional) arguments. If arguments 
//          are used, make sure they comply with the actual patcher. Some
//          patchers may not expect any arguments.  
//
//
//      msg
//
//          Optionally, messages can be sent to the patcher at instantiation.
//          This is useful if the patcher requires extra messages to 
//          initialize. 
//
//
//      use_transform
//
//          Set use_transform to 1 to enable the Transform. Setting it 0 
//          disables the Transform. If it's set to 1 but Transform.patch is
//          not specified, Transform is ignored. (See below, 2a.
//          Transform for details.)
//
//
//      Transform {}
//
//          An extra processing can be added by including a Transform block.
//          See below for more details.
//
Panner {
    num_outputs = 8

    // 8 channel panner using ICST’s Ambipanning~.
    patch = panner.3d.icstambipanning 8
    msg = active 1 // activate input
    msg = aed 1 90. 0. 1. 1 // initial source position
    msg = active_out 1 1 1 1 1 1 1 1 // activate outputs
    msg = speaker aed 1 -45 0. 1. 1
    msg = speaker aed 2 -0 0. 1. 1
    msg = speaker aed 3 45 0. 1. 1
    msg = speaker aed 4 90 0. 1. 1
    msg = speaker aed 5 135 0. 1. 1
    msg = speaker aed 6 180 0. 1. 1
    msg = speaker aed 7 -135 0. 1. 1
    msg = speaker aed 8 -90 0. 1. 1
    msg = distance_mode 2 // distance mode, 0 for no distance roll off
    msg = db_unit 1.5 // distance_mode = 1, exponential
    msg = dist_att 1. // distance_mode = 2, inverse proportional
    msg = center_size 1. // “head” size
    msg = center_curve 0.2 // curve factor when the source is in the center area
    msg = center_att_db 6. // compensate amplitude

    // Uncomment the following two lines for VBAP equivalent
    // patch = panner.3d.vbap 8
    // msg = define_loudspeakers 2 315 0 45 90 180 225 270

    use_transform = 1

    output_channels = 1-8

    //------------------------------------------------------------------
    // 2a. Transform (Optional)
    //------------------------------------------------------------------
    // Transform can be used to add an extra layer of processing after the 
    // panner patcher. This may be useful if an additional en/de-coding is 
    // necessary to match the signal that the system expects. For example, 
    // if a project has a VBAP panning implementation, Transform can 
    // encode it into an binaural format. Another example is down/up-mixing 
    // 5.1 project outputs to match system outputs. In most cases, 
    // Transform is not necessary and Panner is all that's needed.
    //
    // Variables:
    //      num_outputs = <transform output channel count>
    //      patch = <Name of transform patcher/external>
    //      msg = <message value>
    //
    // Descriptions:
    //      num_outputs
    //
    //          Number of outputs from the transform patcher/external. This
    //          depends on the actual transform patcher/external. If 
    //          Transform is used, make sure the number of indices in 
    //          Panner.output_channels matches this value.
    //
    //
    //      patch
    //
    //          Patcher/external name with (optional) arguments. As in 
    //          specifying Panner.patch, arguments can be used with proper 
    //          knowledge. Furthermore, number of inputs of the 
    //          patcher/external, must match with Panner.outputs, which is
    //          specified above.
    //
    //
    //      msg
    //
    //          Optionally, messages can be sent just like the panner 
    //          patcher.
    //
    //
    // Important Note:
    //      If patch is not specified, the Transform is bypassed.
    //
    Transform {

        // About the example:
        //      Example of using setting up matrix~ with one-to-one I/O 
        // mapping. Note that this is the default behavior when the 
        // transform is not used. Therefore, for real implementation, this 
        // is redundant and should not be used.

        num_outputs = 8

        patch = matrix~ 8 8 0.
        msg = 0 0 1.
        msg = 1 1 1.
        msg = 2 2 1.
        msg = 3 3 1.
        msg = 4 4 1.
        msg = 5 5 1.
        msg = 6 6 1.
        msg = 7 7 1.
    }
}

//------------------------------------------------------------------
// 3. Aux (Optional)
//------------------------------------------------------------------
// Specify the auxiliary outputs for the project. These outputs have
// their own signal chain separate from Panner and Project right up to
// the volume matrix, which is directly before system outputs, and
// have their own transform. (see Figure 1. for signal flow diagram.)
// This is useful for LFE out, which is typically not spatially rendered.
//
// Variables:
//      num_outputs = <auxiliary output channel count>
//      output_channels = <list of channels to system outputs>
//      Transform {}
//
// Descriptions:
//      Variables are set the same as Panner. See Descriptions for Panner 
//      for details. There is no equivalent for Panner.patch and Panner.msg
//      for Aux.
//
Aux {
    num_outputs = 1
    use_transform = 0

    output_channels = 4 

    //------------------------------------------------------------------
    // 3a. Transform (Optional)
    //------------------------------------------------------------------
    Transform {
        // patch = 
        // num_outputs = 
        // msg =
    }
}