===== Configuring Input and Outputs and DSP parameters =====

This section describe the I/O configuration system of jMax Phoenix.
The configuration of jMax Phoenix is quite different than the original jMax.
It is based on XML files instead of tcl scripts, and adopt a quite simpler,
yet powerfull, model.

==== I/O Configurations ====

I/O configurations are described in the XML configuration file, using an io-configuration tag.
Multiple configuration can be described. Each of them have a unique name.

An I/O configuration is a list of device descriptions and of mapping commands, mapping device names
to the names used for i/o within a patch.

A specific i/o configuration is selected and installed by specifying it in the preferences section
of the configuration file (site or user).

The following XML excerpt is an example of configuration for portaudio devices.

<code xml>
<jmax>
  .......
  <io-configuration name="portaudio">

    <device name="portAudioStereoOut"
	    type="portdev_dac"
	    deviceName="portaudio_default"
	    out_channels="2"/>

    <map>
      <logical-device type="out~" name="main"/>
      <device name="portAudioStereoOut" />
    </map>
  </io-configuration>
  ......
</jmax>
</code>

The ''io-configuration'' element can include a number of ''device'' elements and a number of ''map'' elements. 

The ''device'' element declare a jMax device to be used by this configuration. A jMax device is an abstraction
of an actual device or library to access audio or midi devices. It is a way for jMax to adapt to the different
choices available on the different platforms.

Currently, jMax support I/O thru the portaudio/portmidi library (that can map to ALSA, Jack in some case, and OSS),
and a native OSS interface. The source tree include also old interfaces for SGI and Solaris audio interfaces,
that may be resurrected once a version for these platforms will be made available.

The ''device'' element have a ''name'' attribute, that is used to identify the device in the ''map'' element,
a ''type'' attribute that identify the actual device type to use (portaudio audio output, in this case), and
a number of attributes that depends on the device itself, typically including at least the number of channels and
other configuration parameter for the device. You'll find a detailed list of supported devices for all the platforms
and their parameters [[DeviceDocumentation| here]].

The ''map'' element declare a mapping from a name or port number used in the patch objects (in the //in~// and ''out~'' objects for
audio, or in midi input/output objects) and the declared devices. This level of indirections allows to write patches that
do not depends on a specific machine configuration, but that can be run on any machine by just adapting the configuration,
without  editing the patch itself.

The first audio device mapped is also associated to the //dac~// or //adc~// object, objects that do not take the device name
argument. As long as the audio library used support it, jMax can use multiple audio and midi devices.

The ''map'' element need two subelement, ''logical-device'' and ''device''.
''logical-device'' specify which device name (and of which kind) we are mapping to the device identified by the ''device'' element.
''logical-device'' take a ''type'' attribute, that currently can be:
  * //in~// for audio input devices 
  * //out~// for audio output devices
  * //midi// for midi devices

//in~// and //out~// logical devices have a ''name'' attribute, that is the name of the device used in the corresponding
objects, while //midi// logical devices have a ''port'' attribute, that is the midi port number mapped to the specified device.
The ''device'' tag specify the device by name, and have a single ''device'' attribute.

Please note that since the mapping is at the device, and not channel, level, it is a lot less useful than expected.
The objective is to be able to write a patch using a ideal input/output configuration (for example Stereo PA output, 
4 mono stage return, stereo recording output) using symbolic name for each input/output connection,
and then to map these logical inputs and outputs to existing audio interfaces (for example, to channels 1 .. 8 or
your Motu or Focusrite interface).

This is not possible today, because the mapping is done at the whole device level. We plan to introduce this
feature later, as a consequence of a new DSP compiling strategy (so, no, do not expect it in a few weeks).

Once defined, a specific i/o configuration is selected and installed by specifying something like:

<code xml>
<jmax>
  .....
  <preferences>
    ....
    <io-configuration name="portaudio"/>
    ....
  </preferences>
  .....
</jmax>
</code>

in the user configuration file.

The jMax distributions contains a small number of ready to use configurations,
defined in the jmax/config/jmax.xml file, that can be used as they are or
copied and modified as needed.

The defined configurations are documented [[ConfigurationDocumentation | here ]].




==== DSP Parameters ====

Using the preferences in a configuration file (either the site ''jmax.xml'' file or the personal
configuration file at ''~/.jmax.xml'') you can set the basic DSP parameters, i.e. the sampling frequency
used in DSP, the computation vector size (in the original jMax was fixed at 64, in jMax Phoenix can be
any 2 power between 32 and 2048), and the default output fifo length.

The syntax to be used is the following :

<code xml>
<jmax>
  <preferences>
    ....
    <fts>
      <param name="sampling_rate" type="int" value="44100"/>
      <param name="vector_size"  type="int" value="256"/>
      <param name="fifo_size"    type="int" value="256"/>
    </fts>
    ....
  </preferences>
</jmax>
</code>

Declaring the above in the personal configuration file ( ~/.jmax.xml ) will overwrite the 
default parameter value defined in the installation configuration file.