Copy of aRts for Trinity modifications

git-svn-id: svn://anonsvn.kde.org/home/kde/branches/trinity/dependencies/arts@1070145 283d02a7-25f6-0310-bc7c-ecb5cbfe19da

1 files changed, 566 insertions, 0 deletions

diff --git a/flow/artsflow.idl b/flow/artsflow.idl
new file mode 100644
index 0000000..44424e0
--- /dev/null
+++ b/flow/artsflow.idl
@@ -0,0 +1,566 @@
+    /*
+
+    Copyright (C) 2000 Stefan Westerfeld
+                       [email protected]
+
+    This library is free software; you can redistribute it and/or
+    modify it under the terms of the GNU Library General Public
+    License as published by the Free Software Foundation; either
+    version 2 of the License, or (at your option) any later version.
+  
+    This library is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+    Library General Public License for more details.
+
+    You should have received a copy of the GNU Library General Public License
+    along with this library; see the file COPYING.LIB.  If not, write to
+    the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+    Boston, MA 02111-1307, USA.
+
+    */
+
+/*
+ * arts.idl - MCOP port. What's missing currently in MCOP?
+ *
+ * -   namespaces (module)
+ */
+
+module Arts {  // analog real time synthesizer
+
+enum AutoSuspendState { asNoSuspend, asSuspend, asSuspendStop, asSuspendMask = 0x3,
+                        asProducer = 0x10, asConsumer = 0x20, asDirectionMask = 0x30 };
+
+/**
+ * The SynthModule interface is the base for all modules containing streams.
+ *
+ * There are two goals achieved by this interface. On one side, there is
+ * functionality which users of stream carrying modules want to use (which
+ * is: start streaming, stop streaming).
+ *
+ * On the other hand, there is functionality which the flow system will use
+ * to achieve these goals.
+ */
+interface SynthModule {
+	// interface for users of this module
+
+	/**
+	 * This function starts the streaming (e.g. the module will start
+	 * producing samples) - if you write a module, do not reimplement this,
+	 * instead reimplement streamInit/streamStart
+	 */
+	void start();
+
+	/**
+	 * This function stops the streaming - if you write a plugin, do not
+	 * reimplement this, instead reimplement streamEnd
+	 */
+	void stop();
+
+	// interface for people implementing modules
+
+	/**
+	 * this is supposed to be the initialization every module passes after
+	 * all attributes have been set up (e.g. you can see which file to open,
+	 * how to initialize your filter coefficients or whatever)
+	 */
+	void streamInit();
+
+	/**
+	 * starts the I/O of the module
+	 */
+	void streamStart();
+
+	/**
+	 * stop the thing again, and free data possibly allocated in streamInit
+	 */
+	void streamEnd();
+
+	/**
+	 * If you run a mixer desk (without anything connected), no calculations
+	 * need to be done - since the output is silent anyway. For this reason,
+	 * there exists this autosuspend attribute. It allows the flow system
+	 * to detect the idle condition, and start suspending the calculations,
+	 * until something "important" happens again.
+	 *
+	 * There are three possible values:
+	 *
+	 * @li  asNoSuspend - this one is appropriate when you have a module that
+	 *                    is active by itself
+	 * @li  asSuspend   - this one is appropriate for modules that "do nothing"
+	 *                    by themselves
+	 * @li  asSuspendStop - this one is for modules that should be stopped, when
+	 *                    the system gets suspended, and restarted when the
+	 *                    system will start again - an example for this is
+	 *                    soundcard output
+	 *
+	 * A module should choose asSuspend (or asSuspendStop) only if the
+	 * following conditions are true:
+	 *
+	 * @li given constant inputs (like 3.0 on all ports), the module will
+	 *     give constant output after some time
+	 * @li given only 0.0 inputs, the module will give only 0.0 outputs
+	 *     after some time
+	 * @li the module does not synchronize itself through signal flow (i.e.
+	 *     a midi sequence which "knows" when a second has passed through
+	 *     the signal flow breaks when suspension happens)
+	 * @li the module can't be brought to do something with a method
+	 *     invocation (i.e. a module which starts generating noise for
+	 *     a second whenever the noise() method is called is not suspendable)
+	 * @li the module has no internal state that changes over time when only
+	 *     constant inputs are given
+	 *
+	 * Typical examples for suspendable modules are arithmetic operations,
+	 * filters, delay/hall/reverb.
+	 *
+	 * Typical examples for non-suspendable modules are sequences, midi stuff,
+	 * oscillators, sample players,...
+	 *
+	 * To deal with modules which either input data from some external source
+	 * (i.e. soundcard input) or output data to some external destination,
+	 * (i.e. soundcard output) the following flags are available:
+	 *
+	 * @li	asProducer  - set this flag for modules which fulfill the conditions
+	 *                    for a suspendable module, but produce non-zero output
+	 *                    even when left alone
+	 * @li	asConsumer  - set this flag for modules which write the data to
+	 *                    some external destination - that is - definitely
+	 *                    require constant input to be suspended
+	 *
+	 * The suspension algorithm will first divide the graph of modules into
+	 * subgraphs of interconnected modules. A subgraph is suspendable if
+	 * all of its modules are suspendable and the subgraph does not contain
+	 * producer(s) and consumer(s) at the same time.
+	 *
+	 * Finally, our module graph is suspendable if all its subgraphs are.
+	 */
+	readonly attribute AutoSuspendState autoSuspend;
+};
+
+/**
+ * Plays a stream of audio data to the soundcard
+ */
+interface Synth_PLAY : SynthModule {
+	// attribute string channels;
+	default in audio stream invalue_left,invalue_right;
+};
+
+/**
+ * Records a stream of audio data from the soundcard
+ */
+interface Synth_RECORD : SynthModule {
+	// attribute string channels;
+	default out audio stream left,right;
+};
+
+/**
+ * A frequency generator
+ *
+ * This kind of object is used to create frequencies. Oscillators are connected
+ * at the output of this object
+ */
+interface Synth_FREQUENCY : SynthModule {
+	in audio stream frequency;
+	out audio stream pos;
+};
+
+/**
+ * A sine wave
+ */
+interface Synth_WAVE_SIN : SynthModule {
+	in audio stream pos;
+	out audio stream outvalue;
+};
+
+/**
+ * A module which mixes an arbitary number of audio streams
+ */
+interface Synth_MULTI_ADD : SynthModule {
+	in multi audio stream invalue;
+	out audio stream outvalue;
+};
+
+/**
+ * A module which adds two audio streams
+ */
+interface Synth_ADD : SynthModule {
+	default in audio stream invalue1,invalue2;
+	out audio stream outvalue;
+};
+
+/**
+ * Multiplies two audio streams
+ */
+interface Synth_MUL : SynthModule {
+	in audio stream invalue1,invalue2;
+	out audio stream outvalue;
+	default invalue1, invalue2;
+};
+
+/**
+ * This plays a wave file
+ */
+interface Synth_PLAY_WAV : SynthModule {
+	/**
+	 * How fast should it be played? 1.0 = normal speed
+	 */
+	attribute float speed;
+	/**
+	 * Which file should be played
+	 */
+	attribute string filename;
+	/**
+	 * Is true as soon as the file is finished
+	 */
+	readonly attribute boolean finished;
+
+	out audio stream left, right;
+	default left, right;
+};
+
+/**
+ * sends data to a bus - busses are dynamic N:M connections - all signals
+ * from all uplinks are mixed together, and sent to all downlinks
+ */
+interface Synth_BUS_UPLINK : SynthModule {
+	/**
+	 * the name of the bus to use
+	 */
+	attribute string busname;
+
+	default in audio stream left,right;
+};
+
+/**
+ * receives data from a bus - busses are dynamic N:M connections - all signals
+ * from all uplinks are mixed together, and sent to all downlinks
+ */
+interface Synth_BUS_DOWNLINK : SynthModule {
+	/**
+	 * the name of the bus to use
+	 */
+	attribute string busname;
+
+	default out audio stream left,right;
+};
+
+
+/**
+ * Byte stream to audio conversion object
+ *
+ * Converts an asynchronous byte stream to a synchronous audio stream
+ */
+interface ByteStreamToAudio : SynthModule {
+	attribute long samplingRate;
+	attribute long channels;
+	attribute long bits;
+
+	/**
+	 * is conversion currently running, or is it stalled due to the fact
+	 * that there is not enough input input?
+	 */
+	readonly attribute boolean running;
+
+	async in byte stream indata;
+
+	out audio stream left,right;
+	default left;
+	default right;
+};
+
+/**
+ * Audio to Byte stream conversion object
+ *
+ * Converts a synchronous audio stream to an asynchronous byte stream
+ */
+interface AudioToByteStream : SynthModule {
+	attribute long samplingRate;
+	attribute long channels;
+	attribute long bits;
+
+	async out byte stream outdata;
+
+	in audio stream left,right;
+	default left;
+	default right;
+};
+
+/**
+ * Base interface for all stereo effects
+ */
+interface StereoEffect : SynthModule {
+	default in audio stream inleft, inright;
+	default out audio stream outleft, outright;
+};
+
+/**
+ * this is a simple clipping stereo volume control
+ */
+interface StereoVolumeControl : StereoEffect {
+	attribute float scaleFactor;
+	readonly attribute float currentVolumeLeft;
+	readonly attribute float currentVolumeRight;
+};
+
+/**
+ * A funny FFT scope
+ */
+interface StereoFFTScope : StereoEffect {
+	readonly attribute sequence<float> scope;
+};
+
+/**
+ * A stack of stereo effects
+ */
+interface StereoEffectStack : StereoEffect {
+	/**
+	 * inserts an effect at the top side (= directly after the input)
+	 *
+	 * @returns an ID which can be used to remove the effect again
+	 */
+	long insertTop(StereoEffect effect, string name);
+
+	/**
+	 * inserts an effect at the bottom (= close to the output) side
+	 *
+	 * @returns an ID which can be used to remove the effect again
+	 */
+	long insertBottom(StereoEffect effect, string name);
+
+	/**
+	 * removes an effect again
+	 */
+	void remove(long ID);
+};
+
+/*
+ * Audio Manager stuff
+ */
+
+enum AudioManagerDirection { amPlay, amRecord };
+
+/**
+ * Information structure for audio manager clients
+ */
+struct AudioManagerInfo {
+	long ID;
+	string destination;
+
+	AudioManagerDirection direction;
+	string title, autoRestoreID;
+};
+
+/**
+ * an audio manager client
+ */
+interface AudioManagerClient {
+	readonly attribute long ID;
+	attribute AudioManagerDirection direction;
+	attribute string title, autoRestoreID;
+
+	void constructor(AudioManagerDirection direction, string title,
+					 string autoRestoreID);
+};
+
+/**
+ * The audio manager interface
+ */
+interface AudioManager {
+	/**
+	 * a list of destinations, where you can play/record data to/from
+	 */
+	readonly attribute sequence<string> destinations;
+
+	/**
+	 * a list of clients
+	 */
+	readonly attribute sequence<AudioManagerInfo> clients;
+
+	/**
+	 * this is incremented each time a change is made (i.e. new client attached)
+	 * TODO: SHOULD GO AWAY WITH ATTRIBUTE WATCHING
+	 */
+	readonly attribute long changes;
+
+	/**
+	 * this is used to route a client to another destination
+	 */
+	void setDestination(long ID, string destination);
+};
+/**
+ * This is a virtual output port, which you use to play data. Where exactly
+ * this data gets played is managed by the audiomanager.
+ *
+ * Creation: there are two ways to initialize a Synth_AMAN_PLAY - one is
+ * to set title and autoRestoreID to sensible (non empty) values. The other
+ * is to pass an already initialized AudioManagerClient on the constructor.
+ */
+interface Synth_AMAN_PLAY : SynthModule {
+	attribute string title, autoRestoreID;
+	void constructor(AudioManagerClient client);
+
+	default in audio stream left, right;
+};
+
+/**
+ * This is a virtual input port, which you use to record data. Where this
+ * data comes from is in turn managed by the audiomanager.
+ *
+ * Creation: there are two ways to initialize a Synth_AMAN_RECORD - one is
+ * to set title and autoRestoreID to sensible (non empty) values. The other
+ * is to pass an already initialized AudioManagerClient on the constructor.
+ */
+interface Synth_AMAN_RECORD : SynthModule {
+	attribute string title, autoRestoreID;
+	void constructor(AudioManagerClient client);
+
+	default out audio stream left, right;
+};
+
+/* --------------------------------------------------------------------- */
+
+/**
+ * Wraps a datahandle. That is an abstraction for a float value array
+ * which can be directly loaded data from a file or have some
+ * processing stages in between (caching, reversing, cropping...)
+ * which are hidden to this interface.
+ * In contrast to the underlying C++ API, this datahandle is already
+ * open()ed after creation, so you can access its information (like
+ * channelCount) without further action.
+ * A datahandle normally has one more important function: read() which
+ * is not wrapped in MCOP because of the overhead of the data
+ * transfer. (If there is need for sth. like that in the future,
+ * one could maybe find a solution.)
+ */
+interface DataHandle {
+	readonly attribute long bitDepth;
+	readonly attribute long channelCount;
+	readonly attribute long valueCount;
+	/**
+	 * error code open() returned
+	 */
+	readonly attribute long errorNo;
+};
+
+/**
+ * Represents a datahandle which delivers the data from the underlying
+ * sourceDatahandle in reverse order.
+ */
+interface ReversedDataHandle : DataHandle {
+	void init(DataHandle sourceHandle);
+};
+
+/**
+ * Represents a datahandle which delivers an "inner" part of the data
+ * from the underlying sourceDatahandle. You can cut away parts at the
+ * start and/or the end with this.
+ */
+interface CroppedDataHandle : DataHandle {
+	void init(DataHandle sourceHandle,
+			  long headCutValueCount,
+			  long tailCutValueCount);
+};
+
+/**
+ * Represents a datahandle which delivers the data from the underlying
+ * sourceDatahandle without the "inner" part containing the values
+ * [cutOffset..cutOffset+cutValueCount-1], which will be cut away.
+ */
+interface CutDataHandle : DataHandle {
+	void init(DataHandle sourceHandle,
+			  long cutOffset,
+			  long cutValueCount);
+};
+
+/**
+ * DataHandlePlay uses a gsl_wave_osc to play back data from a
+ * DataHandle using sophisticated anti-aliasing filtering and caching
+ * techniques. (Though not implemented at the time of writing this, it
+ * will be optimized for cases where the anti-aliasing is not needed
+ * because the mixerFrequency equals the current soundserver's.)
+ */
+interface DataHandlePlay : SynthModule {
+	/**
+	 * Which data should be played?
+	 */
+	attribute DataHandle handle;
+	/**
+	 * What is the normal mixer frequency the data from the handle
+	 * should be played back at? (default: current mixing frequency
+	 * of the soundserver, e.g. 44100)
+	 */
+	attribute float mixerFrequency;
+	/**
+	 * Which channel of the datahandle should by played?
+	 * (defaults to 0 = the first channel)
+	 */
+	attribute long channelIndex;
+	/**
+	 * How fast should the data be played?
+	 * (defaults to 1.0 = normal speed, see mixerFrequency)
+	 */
+	attribute float speed;
+	/**
+	 * Current position while playing, in fact it's the index in the
+	 * datahandle, so 0 <= pos < handle.valueCount
+	 */
+	attribute long pos;
+	/**
+	 * Is true as soon as the file is finished
+	 */
+	readonly attribute boolean finished;
+	/**
+	 * Can be used to pause and/or continue playing
+	 */
+	attribute boolean paused;
+
+	default out audio stream outvalue;
+
+	DataHandlePlay clone();
+};
+
+/**
+ * DataHandle which represents sample data loaded from a file. Note
+ * that the samples from all channels are interleaved, that is, the
+ * samples of the first channel in a stereo file are found at offsets
+ * 0,2,4,6,.. etc.
+ */
+interface WaveDataHandle : DataHandle {
+	/**
+	 * Properties of the loaded sample data. Note that those
+	 * properties are only available from a WaveDataHandle, but may be
+	 * available from a DataHandle in the future.
+	 */
+	readonly attribute float mixerFrequency;
+	readonly attribute float oscillatorFrequency;
+
+	/**
+	 * Load the first wavechunk from a file and return true on
+	 * success. A more specific error code is not available at the
+	 * moment.
+	 */
+	boolean load(string filename);
+
+	/**
+	 * Load a specific wavechunk from a file and return true on
+	 * success. A more specific error code is not available at the
+	 * moment.
+	 */
+	boolean load(string filename,
+				 long waveIndex, long chunkIndex);
+
+	/**
+	 * Return true if and only if a wavechunk was successfully loaded
+	 * from a file.
+	 */
+	readonly attribute boolean isLoaded;
+
+	/**
+	 * Creates a DataHandlePlay object with the important attributes
+	 * handle, mixerFrequency and channelCount already set to play
+	 * this WaveDataHandle.
+	 */
+	DataHandlePlay createPlayer();
+};
+
+};