AMaMP
Audio Mixing and Manipulation Project
SourceForge.net Logo
 
 
 

IPC Message Specification
This page describes the format of messages that may be exchanged with the core. 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.
  • effect - messages that are dispatched to effect modules to access any IPC functionality they offer.
  • placement - messages that relate to altering existing placements and adding new ones.

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.
  • 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. While it should release any open handles it holds, it will not be required to clear up any output files that have been created. 

core:
	request: stop
	id: request id

pause
This message causes the core to pause mixing and all outputs as soon as possible.

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

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 timeoffset sets the new position as a number of seconds.

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

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.

EFFECT MESSAGES
These messages will have the type identifier "effect". 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.

effect:
	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.

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.