Working IPC Message Specification
This page describes the format of messages that may be exchanged with the core, both planned and current. They are exchanged using the method described in the IPC Specification.

MESSAGE TYPES
Messages that can be sent to the core:-

• core - messages that control what the core is doing as a whole.
  • stop
  • pause
  • resume
  • get_position
  • set_position
  • io_list
  • effect_list
• input - messages that relate to working with inputs
  • add
  • length
  • check
• output - messages that relate to working with outputs
  • add
• effect - messages that relate to working with effects
  • add
• placement - messages that relate to altering existing placements and adding new ones.
  • add
  • edit
  • delete
• io - messages that are dispatched to I/O modules to access any IPC functionality they offer.
• fx - messages that are dispatched to effect modules to access any IPC functionality they offer.

Messages that may be recieved from the core:-

• debug - messages that will be emitted if the core is compiled to send debug messages.
• error - error messages; the core will terminate after emitting one of these.
• request_confirmation - messages sent to confirm a request was successful. Extra information may be included.
• request_failed - messages sent when a request fails.
• warning - warnings; the core will not terminate, but the client program may like to pay attention to these.

CORE MESSAGES
These messages will have the type identifier "core" and are handled by a core module. They will all take the format:-

core:
	request: request type
	id: request id
	[additional parameters]

Where the request type describes the action to be taken, and request id is a unique id provided by the front end to identify the request.

stop
This message causes the core to immediately stop what it is doing, finish writing any files, close all open files and devices and exit.

core:
	request: stop
	id: request id

pause
This message causes the core to pause mixing and all outputs as soon as possible. Invalid if we have already paused.

core:
	request: pause
	id: request id

resume
This message causes the core to resume mixing after a pause. Invalid unless a pause message has been sent prior to this one.

core:
	request: resume
	id: request id

get_position
This message requests that the core give its current position. The request confirmation message will have two extra fields: "sampleposition", which defines the position in samples (from 0), and "timepositon" which defines the position in seconds (from 0).

core:
	request: get_position
	id: request id

set_position
This message allows the current position of output to be set. Either sampleposition or timeposition should be specified, but not both. sampleposition sets the new position in samples from the start (first sample = 0), and timeposition sets the new position as a number of seconds.

core:
	request: set_position
	id: request id
	sampleposition: position

io_list
This message requests that the core provides a list of all the I/O modules that are available. The request confirmation message will have the extra field modules, which contains a comma seperated list of all I/O modules.

core:
	request: io_list
	id: request id

effect_list
This message requests that the core provides a list of all the effect modules that are available. The request confirmation message will have the extra field modules, which contains a comma seperated list of all effect modules.

core:
	request: effect_list
	id: request id

DEBUG MESSAGES
AMaMP can optionally be compiled to emit debug messages. These provide useful information for tracing problems with the core. They take the following format:-

debug:
	module: parser | engine | ipc | io | effect | dll
	message: message text

The module section states where the debug message came from, which allows you to just track messages related to your problem. The message text contains the debug message itself.

FX MESSAGES
These messages will have the type identifier "fx". They always require an ID and an effect identifier, and are handled by the effects module that supports the effect with that identifier. The parameters you use are defined by effect modules themselves; see their documentation for more information.

fx:
	identifier: identifier
	id: request id
	[additional parameters]

ERROR MESSAGES
When things go badly wrong in the core and it cannot continue, it will send an error message stating what went wrong and then exit. The messages will take the following format:-

error:
	module: parser | engine | ipc | io | effect | dll
	message: message text

The module parameter specifies where the error occurred. If it's in the parser, you probably had an invalid input file. The message parameter supplies a textual description of the problem.

I/O MESSAGES
These messages will have the type identifier "io". They always require an ID and an identifier, and are handled by the input/output module that supports the input or output with that identifier. The parameters you use are defined by I/O modules themselves; see their documentation for more information.

io:
	identifier: identifier
	id: request id
	[additional parameters]

INPUT MESSAGES
These messages relate to operations that can be performed on input chunks and/or relating to modules that do input. These types of messages are handled within the core; they are not handled by an I/O module's IPC handler. Use the "io" message type for that.

add
This type of request will add a new input.

input:
	request: add
	id: request id
	identifier: new identifier
	type: file | stream | generator
	module: module_name
	[additional parameters]

Identifier is the identifier of the new input chunk. The type is the type of input it is; these correspond to the FileInput, StreamInput and GeneratorInput chunks in the instruction file. module, which can also be spelt format, is the name of the input module to use. Any additional parameters, e.g. Path, should be put afterwords, using colon notation, e.g. "Path: /path/to/file.wav", and preceded by a tab. Remember that case matters on parameter names, and parameters for I/O modules by convention have the first letter capitalized.

check
This request checks if a particular (file) input module is able to read a particular file. Pass in the module and path to the file in question. The request confirmation message will contain an extra field named valid, which will contain a 1 if the file can be read by that value and a 0 if it cannot be.

input:
	request: check
	id: request id
	module: module_name
	path: path

length
This request takes a path to a file and the name of a file input module that should be able to read the file, and attempts to get the length of the data in the file. If it is valid, the request confirmation message will contain two extra fields named time and samples: time is the length in seconds, samples is the length in samples at the base sampling rate. If the file could not be read, a request failed message will be sent back.

input:
	request: length
	id: request id
	module: module_name
	path: path

OUTPUT MESSAGES
These messages relate to operations that can be performed on output chunks and/or relating to modules that do output. These types of messages are handled within the core; they are not handled by an I/O module's IPC handler. Use the "io" message type for that.

add
This type of request will add a new output.

output:
	request: add
	id: request id
	identifier: new identifier
	type: file | stream | data
	module: module_name
	[additional parameters]

Identifier is the identifier of the new output chunk. The type is the type of output it is; these correspond to the FileOutput, StreamOutput and DataOutput chunks in the instruction file. module, which can also be spelt format, is the name of the output module to use. Any additional parameters, e.g. Path, should be put afterwords, using colon notation, e.g. "Path: /path/to/file.wav", and preceded by a tab. Remember that case matters on parameter names, and parameters for I/O modules by convention have the first letter capitalized.

EFFECT MESSAGES
These messages relate to operations that can be performed on effect chunks and/or relating to modules that do effects. These types of messages are handled within the core; they are not handled by an effect module's IPC handler. Use the "fx" message type for that.

add
This type of request will add a new effect.

effect:
	request: add
	id: request id
	identifier: new identifier
	module: module_name
	[additional parameters]

Identifier is the identifier of the new effect chunk. module is the name of the input module to use. Any additional parameters should be put afterwords, using colon notation, e.g. "DelayLength: 0.5", and preceded by a tab. Remember that case matters on parameter names, and parameters for effect modules by convention have the first letter capitalized.

PLACEMENT MESSAGES
These methods allow you to create new placements on the fly, edit the parameters of old existing ones and delete existing ones. They will take the following format:-

placement:
	request: request type
	id: request id
	[additional parameters]

Where the request type describes the action to be taken, and request id is a unique id provided by the front end to identify the request.

add
This type of request will allows a new placement to be created on-the-fly. It looks like this:-

placement:
	request: add
	id: request id
	identifier: new identifier
	input: input identifier
	sampleoffset: offset
	timeoffset: offset
	outputs: output identifier 1, output identifier 2, ...
	effects: effect identifier 1, effect identifier 2, ...
	[startsample: sample to start playing from]
	[endsample: sample to stop playing at]
	[starttime: time to start playing from]
	[endtime: time to stop playing at]

Identifier is the identifier of the new sample placement. The other fields beneath this are defined in the same way those in the input file are - note that the names here are in lowercase and followed by a colon. Adding a placement that would currently be playing is allowed and the placement will play from the correct position, however effect state may not be the same.

delete
This type of request will allow a sample placement to be removed from the list of sample placements.

placement:
	request: delete
	id: request id
	identifier: identifier

Identifier specifies the identifier given to the placement to be removed. Rmoving a placement that is currently playing is allowed.

edit
The edit message allows the parameters of a sample placement to be changed.

placement:
	request: edit
	id: request id
	identifier:  identifier of sample to edit
	[volume: volume]
	[pan: pan]

Anything that is not specified will retain its current value.

REQUEST CONFIRMATION MESSAGES
When you send a request to the core and the request is fulfilled, a message containing the id of the message will be returned. The message will look like this:-

request_confirmation:
	id: request id

Where request id is the id you passed with your request.

REQUEST FAILURE MESSAGES
When you send a request to the core and the request fails, a message containing the id of the request will be returned. The message will look like this:-

request_failed:
	id: request id

Where request id is the id you passed with your request.

WARNING MESSAGES
If the core recieves input that is not quite right but correctable or some other recoverable event occurs, a warning message will be sent. It will take the format:-

warning:
	module: parser | engine | ipc | io | effect | dll
	message: message text

The module parameter specifies the type of the warning. The message parameter provides a textual description of the warning. Warnings are ignorable, but front end developers may wish to collect them to help with bug tracking.