Input File Specification
This page describes the syntax that you can use in the instruction files you give the core. This syntax is valid as of release 0.3.1 of the core.

CONTENTS

• Overview
• About Chunks
• The Global Chunk
• Input Chunks
  • FileInput
  • StreamInput
  • GeneratorInput
• Output Chunks
  • FileOutput
  • StreamOutput
  • DataOutput
• Placement Chunks
• Effect Chunks

OVERVIEW
AMaMP input files are text based. The input file consists of a list of named chunks, which are in the format:-

chunktype name {
    ...
} 

Data detailing a particular chunk is contained between the { and }. While whitespace in terms of multiple tabs and spaces is not important (so long as there is at least some whitespace between things), line breaks are significant. A line break is the statement seperator for AMaMP input files. Both the name of the chunk and the chunk type and other "keywords" will be case sensitive. If the parser sees a keyword unexpectedly or encounters any other kind of syntactical error, it will exit immediately and display a message that will hopefully help you track down the error.

ABOUT CHUNKS
Chunks are used to define input sources (inputs), where data goes (outputs), where in the output the input sources feature (placements) and effects. It is not important to have all the outputs and inputs before the placements that use them, or all together at the start of the file. Doing so will have no effect on performance.

Each chunk must have a unique name, called an identifier. This identifier may contain alphanumerics and the underscore character, and is case sensitive. The uniqueness is not dependent on chunk type either - that is, you cannot have an input and an output with the same name.

CHUNK SYNTAX
The following documentation describes the various chunks that are available, what data you must associate with them and what data you can optionally associate with them.

The Global Chunk
This chunk allows global settings to be defined. It is optional as of AMaMP Core 0.3. If you choose to supply it then it must be the first chunk that appears in an instruction file.

A Global chunk might look like this:-

Global {
    BaseSamplingRate 44100
    BaseChannels 2
}

BaseSamplingRate defines the sampling rate that offsets will be specified in terms of and that the audio will me mixed at internally. Be aware that if this is not at least equal to the highest sampling rate of the outputs, you will not be making optimum use of the output's precision. Be equally aware that if you supply a value that is way above the highest sampling rate of the outputs, you're going to waste a lot of CPU cycles. If that doesn't scare you enough into working out a good value, take into account the small loss in placement precision if you use a value that isn't divisible by the sampling rates of the output files. The default is 44100.

BaseChannels defines the number of channels that audio will be represented as having when it is mixed. Inputs and outputs may provide or accept different numbers of channels.

The FileInput Chunk
This chunk allows you to define an input source that will take data from a file. An example file input chunk will look like this:-

FileInput drums {
    Format WAVEPCM
    Path "C:\Path\To\Sound.wav"
}

The optional Format keyword is to be followed by the name of the module that will handle the input file. A full list of these is available. You can use the keyword Module in place of Format. If you do not specify the format of the file, the core will attempt to guess based upon the extension and possibly other conditions, though this will slow down parsing.

The additional parameters of a FileInput chunk depend on the format in question; the majority of file formats only take a Path parameter, which is the path to the file. If the path contains spaces, it should be enclosed in double quotes. For more information on the required parameters for different formats, see the documentation for the module that handles that format.

The StreamInput Chunk
This chunk allows you to describe an input that will take data from a source that is continuously producing (real-time) data, e.g. data from line-in on a sound card. The simplest StreamInput chunk will not have any parameters:-

StreamInput voiceover {
}

This will usually do the right thing (e.g. use the default streaming input module to take input from the soundcard), however you may wish to be a little more specific.

StreamInput voiceover {
    Module Win32Wave
    SamplingRate 44100
    BitDepth 16
    Channels 1
}

The Module keyword allows you to choose to use a particular module. The remaining parameters depend on the module, however those collecting data from a soundcard will usually support the three named above.

The GeneratorInput Chunk
This chunk allows you to describe an input that will generate data as it is required. An example of a module of this type would be a synthesiser.

GeneratorInput squarewave {
    Module FourierSynthesis
    WaveForm Square
    Frequency 2000
}

The Module keyword is required for all GeneratorInput chunks and specifies the name of the module that will be used to generate the signal.

The parameters that a generator input will take vary widely between modules, so reference to the documentation will be essential.

The FileOutput Chunk
This chunk allows you to define an output that will write data to a file. A FileOutput chunk might look like this:-

FileOutput wavefileout {
    Format WAVEPCM
    Path "C:\Path\To\MixDown.wav"
    SamplingRate 44100
    BitDepth 16
    Channels 2
}             

The optional Format keyword is to be followed by the name of the module that will handle writing a file or the desired type. A full list of these is available. You can use the keyword Module in place of Format. If you do not specify the format of the file, the core will attempt to guess which format is wanted based upon the extension, though this will slow down parsing.

Path is a path to the output file, and an absoloute path is recommended. AMaMP will not ask if you really wish to overwrite an existing file of the same name.

The additional parameters of a FileOutput chunk depend on the format in question; many modules will have a set of defaults. See the documentation for the module you are interested in for more information.

The StreamOutput Chunk
This chunk allows you to defines an output that needs data to be passed to it in realtime. The usual example of this will be the soundcard. The simplest StreamOutput chunk will not have any parameters:-

StreamOutput speakers {
}

This will usually do the right thing (e.g. use the default streaming output module to send data to the soundcard), however you may wish to be a little more specific.

StreamOutput speakers {
    Module Win32Wave
    SamplingRate 44100
    BitDepth 16
    Channels 1
}

The Module keyword allows you to choose to use a particular module to handle the output. The remaining parameters depend on the module, however those playing sound through a soundcard will usually support the three named above.

The DataOutput Chunk
This chunk allows you to define an output that will generate some kind of data based upon the audio stream generated from the mix down. An example of this would be a module that sends data, via IPC messages, to a front end to enable it to render a VU (volume level) meter or a waveform plot. An DataOutput chunk might look like this:-

DataOutput vu {
    Module VUMeter
    ValueFrequncy 20
}

The Module keyword is required, and defines the name of the module that will handle the generation of the output data. The rest of the parameters vary widely between different modules and more details can be found the documentation for the module in question.

The Placement Chunk
This chunk allows you to place data from an input in an output stream at a certain sample offset. A placement chunk might looks like this:-

Placement drums1 {
    Input drums
    Output wavefileout
    Effects shortdelay, harshflange
    SampleOffset 110250 | TimeOffset 2.5
    StartSample 11025 | StartTime 0.25
    EndSample 220500 | EndTime 5.0
    Volume 1
    Pan 0
}             

Input is the name of the input source to place. What type of input it is does not matter.

Output is optional, and if omitted the placement will be routed to all outputs. To route the sound to multiple outputs, specify the identifiers of those outputs, seperated by commas (,) if there is more than one of them.

Effects is optional and allows you to provide a list of Effect chunk identifiers separated by commas. These effects will be applied to the placement before it is sent to the outputs. By default, no effects are applied.

You must supply one of SampleOffset or TimeOffset. These specify where in the output the input will be placed. It is specifed by giving an offset in terms of samples or seconds from the first sample in the output, where the first sample is numbered 0. The sampling rate used for these offsets is the one set in the Global chunk using the BaseSamplingRate keyword.

StartSample/StartTime and EndSample/EndTime are optional. They allow on-the-fly non-destructive trimming of an input, enabling you to set the sample (relative to the base sampling rate) or time that playback of the sample is from and to. Incorrect usage of these (e.g. using values too large or too small) will result in a warning being emitted and the start and end of the input being used in place of your StartSample and EndSample values respectively.

Volume is optional. A value of 1 will leave the placement at its default volume, 2 will double the volume, 0.5 will halve it, etc.

Pan is optional, and controls the left/right output balance. 0 routes output equally to both channels, -1 shifts the output entirely to the left channel and 1 shifts the output entirely to the right channel.

The Effect Chunk
This chunk allows you to create an instance of a particular effect module with a certain set of parameters. You will always need to pass a Module parameter, which is the name of the effect module that will be used for this effect chunk. The rest of the parameters depend on the effect module you are using, and you should see the documentation for an effect module to see what parameters it requires. An Effect chunk might look like this:-

Effect mydelay {
    Module Delay
    ... Other Prams Here ...
}             

You can create as many Effect chunks as you wish for a particular effect module. IPC messages sent to effect modules are sent on a per-chunk basis too. That means that you can tie many placements to one effect chunk and modify the parameters for all of these placements at once as the effect module allows.