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
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.
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.
It is important that any front end listening for messages on STDIN
considers blocking issues.
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.
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:-
message: invalid message
communicating with the AMaMP core should not respond to messages
they do not understand, but instead drop them.
The following are valid message types that may be sent by the AMaMP
- sent when something has gone wrong. The AMaMP core will always
terminate after sending one of these.
- 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.
- these will contain debugging info and will only be sent if the
AMaMP core is compiled with #define AMAMP_DEBUG 1
- sent when something happens in the I/O layer that you may be
interested in, for example audio output has started playing.
- 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.
- sent to confirm a request was completed successfully. Will contain
the id of the request as supplied by the requester and possibly
- sent to state that a request failed. Will contain the id of
the request as supplied by the requester and possibly other data.
are valid message types that may be sent to the AMaMP core:-
- sent to issue "top level" requests to the core, e.g.
to request it to immediately terminate.
- sent when the application wants the I/O layer to do something.
- this will allow new placements to be created and existing ones
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.