IPC Specification
This page describes the way an external program can exchange instructions and data with AMaMP while it is in the mixdown process. Details of the messages that can be exchanged are details elsewhere in the documentation.

OVERVIEW
AMaMP uses pipes to communicate with external programs. This means that instead of just invoking AMaMP by running it at the command line (or doing the equivalent programatically), you open at least STDIN or STDOUT (e.g. open both for bidirectional communication). AMaMP will regularly poll it's STDIN for instructions and data, parse it and act upon it. It will send data on STDOUT as required. It is up to the external program to interpret this data and act upon it as required.

LATENCY
Discussions about latency and response time are being put off until an appropriate time. At the moment AMaMP will aim to offer a reasonable response time to data sent on STDIN.

BLOCKING
It is important that any front end listening for messages on STDIN considers blocking issues.

FORMAT
Data will be sent as part of a message. A message will start with a message type, which will be a lowercase word stating what kind of message it is, followed by a colon. Any data sent as part of that message will be placed on lines after that, each line starting with a tab character (\t). A piece of data on a line is called a parameter. It should have an identifier no more than 30 characters in length immediately after the tab, followed by a colon. This can be followed by data of any length. After a message, an extra \n (newline character) must be printed (e.g. so there is a blank line).

This is well suited to ASCII data, however binary data may also need to be sent. In these cases, a data length must be sent with the data, and the AMaMP core will read that many bytes. This will be defined in the specification for a particular type of message.

PROCEDURE FOR MESSAGES NOT UNDERSTOOD
If the AMaMP core recieves a message that it cannot understand, it will send back a warning message, which will look like this:-

warning:
	module: ipc
	message: invalid message

Applications communicating with the AMaMP core should not respond to messages they do not understand, but instead drop them.

STANDARD MESSAGE TYPES
The following are valid message types that may be sent by the AMaMP core:-

• error - sent when something has gone wrong. The AMaMP core will always terminate after sending one of these.
• warning - sent to alert the "client" application of a recoverable problem in the AMaMP core. It may be caused by out-of-bounds errors on input files, or if an invliad message is recieved.
• debug - these will contain debugging info and will only be sent if the AMaMP core is compiled with #define AMAMP_DEBUG 1
• event_io - sent when something happens in the I/O layer that you may be interested in, for example audio output has started playing.
• output - contains data sent from something named as an Output in the instruction file. An example may be a VU meter, which sends data about volume at certain points in time.
• request_confirmation - sent to confirm a request was completed successfully. Will contain the id of the request as supplied by the requester and possibly other data.
• request_failed - sent to state that a request failed. Will contain the id of the request as supplied by the requester and possibly other data.

The following are valid message types that may be sent to the AMaMP core:-

• core - sent to issue "top level" requests to the core, e.g. to request it to immediately terminate.
• io - sent when the application wants the I/O layer to do something.
• placement - this will allow new placements to be created and existing ones removed on-the-fly.

All requests issued to the core will have an id: field which will be used to send a confirmation or failure message. It is up to the requesting program to supply a "unique enough" identifier. Every request will be followed up by a confirmation.