Source: arts/soundserver.idl

#include "artsflow.idl"
#include "kmedia2.idl"

module Arts {
/**
 * Producer of byte sound
 *
 * This is used inside the sound server interface
 */
interface ByteSoundProducer : SynthModule
{
	readonly attribute long samplingRate;
	readonly attribute long channels;
	readonly attribute long bits;

	async out byte stream outdata;
};

/**
 * This is a very simple sound server interface
 *
 * WARNING: This currently inherits a KMedia2 PlayObjectFactory for test
 *          purposes, but don't rely on that
 */

interface SimpleSoundServer : PlayObjectFactory
{
	readonly attribute StereoEffectStack outstack;

	/**
	 * tries to play the sound in "filename"
	 *
	 * returns an ID when success 0 when it fails
	 */
	long play(string filename);

	/**
	 * returns true if the sound in ID is still playing
	 */
	//boolean isPlaying(long ID);

	/**
	 * stops a playing sound by ID
	 */
	//void stop(long ID);

	/**
	 * specifies the minimum amount of milliseconds that have to be buffered
	 * to allow safe streaming (without interruptions) from/to external apps
	 *
	 * this depends on the realtime parameters the sound server itself uses
	 * to talk to the hardware
	 */
	readonly attribute float minStreamBufferTime;

	/**
	 * specifies the amount of milliseconds the server itself spends with
	 * the hardware (buffering latency) - so if you stream into the server,
	 * you should have a yourStreamBufferTime >= minStreamBufferTime, and
	 * the total latency is
	 *
	 *  totalLatency = yourStreamBufferTime + serverBufferTime
	 */
	readonly attribute float serverBufferTime;

	/**
	 * attaches a byte sound producer (read: a client which produces/mixes
	 * an audio stream itself and just wants playback via the soundserver)
	 */
	void attach(ByteSoundProducer producer);

	/**
	 * detaches a previous attached byte sound producer
	 */
	void detach(ByteSoundProducer producer);

	object createObject(string name);
};

enum RealtimeStatus { rtRealtime, rtNoSupport, rtNoWrapper, rtNoRealtime };

/**
 * This is an enhanced sound server interface which can be used to
 * query status information or suspend the soundserver right away
 */
interface SoundServer : SimpleSoundServer
{
	readonly attribute RealtimeStatus realtimeStatus;

	/**
	 * Returns how many seconds you have to wait _now_ for the soundserver
	 * to suspend. A value of -1 signals that the sound server is busy and
	 * will not suspend automatically at the moment.
	 */
	readonly attribute long secondsUntilSuspend;

	/**
	 * Makes the soundserver suspend now _if_ it is not busy playing, that
	 * is, if it is "suspendable". Returns true if successful.
	 */
	boolean suspend();

	/**
	 * Permanently terminates the sound server - this is not intended to be
	 * widely used. However, it provides a way to "kill" the sound server,
	 * even if you don't reside on the same host with it, and even if you
	 * don't know the process id, and so on. In the future it also offers
	 * the possibility for interested apps to be informed before the server
	 * goes away, and for important apps to block termination.
	 *
	 * Returns true if successful.
	 */
	boolean terminate();
};

/**
 * A KMedia2 Wave PlayObject
 */
interface WavPlayObject : PlayObject, SynthModule
{
	out audio stream left,right;
};

};