You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
arts/soundserver/soundserver.idl

295 lines
7.4 KiB

#include "artsflow.idl"
#include "kmedia2.idl"
#include "core.idl"
module Arts {
/**
* One entry of the sample storage - initially, you'll need to fill the entry.
*
* To do so, call write repeatedly to fill it with data, and finish() when
* you are done. After that you can use the filename attribute to get the
* name of the file on the server that has stored the data. You can use
* this filename for other things (i.e. SimpleSoundServer::play).
*/
interface SampleStorageEntry {
readonly attribute string name;
readonly attribute string filename;
readonly attribute boolean completed;
void write(sequence<byte> data);
void finish();
};
/**
* Interface for storing files on the sound server
*/
interface SampleStorage {
void constructor(string directory, boolean clearOnInit);
/**
* creates a new entry which you can use to store a sample - if you just
* create an entry, it will be private to you, i.e. you can use it, and
* as soon as you don't need it any longer, it will be freed
*
* if you want that the entry stays in the storage, you need to add it,
* and it will stay then until you remove it
*/
SampleStorageEntry createEntry(string name);
/**
* add an entry (which will make it accessible via findEntry) - remember
* to eventually call removeEntry, or the entry will stay there forever
*/
void addEntry(SampleStorageEntry entry);
/**
* removes an entry, that is, the entry will only stay there until
* nobody needs it any more and then get freed
*/
void removeEntry(SampleStorageEntry entry);
/**
* finds an entry by name
*/
SampleStorageEntry findEntry(string name);
};
/**
* 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;
};
/**
* V2 version of the ByteSoundProducer interface that implements the title
* attribute
*/
interface ByteSoundProducerV2 : ByteSoundProducer
{
readonly attribute string title;
};
/**
* Receiver of byte sound
*/
interface ByteSoundReceiver : SynthModule
{
readonly attribute long samplingRate;
readonly attribute long channels;
readonly attribute long bits;
readonly attribute string title;
async in byte stream indata;
};
/**
* 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);
/**
* attaches a byte sound receiver (a client that records an
* audio stream from the soundserver)
*/
void attachRecorder(ByteSoundReceiver receiver);
/**
* detaches a previous attached byte sound receiver
*/
void detachRecorder(ByteSoundReceiver receiver);
object createObject(string name);
};
enum RealtimetqStatus { 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 RealtimetqStatus realtimetqStatus;
/**
* 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();
/**
* Asks the soundserver if it is suspended. Returns true if so.
*/
boolean suspended();
/**
* 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();
};
/**
* This is an even more enhanced sound server interface that supports changing
* the autosuspend time, and returning more information about the server
* settings.
*/
interface SoundServerV2 : SoundServer, PlayObjectFactoryV2
{
/**
* Time in seconds after which server will suspend if idle.
*/
attribute long autoSuspendSeconds;
/**
* Multiplier for size of network buffers. Default is 1,
* which is fragment size * fragment count. (expressed
* as milliseconds).
*/
attribute long bufferSizeMultiplier;
/**
* Current CPU usage in percent
*/
readonly attribute float cpuUsage;
/**
* AudioSubSystem parameters
*/
readonly attribute string audioMethod;
readonly attribute long samplingRate;
readonly attribute long channels;
readonly attribute long bits;
readonly attribute boolean fullDuplex;
readonly attribute string audioDevice;
readonly attribute long fragments;
readonly attribute long fragmentSize;
/**
* version
*/
readonly attribute string version;
/**
* global output volume for the sound server
*/
readonly attribute StereoVolumeControl outVolume;
/**
* for storing samples on the sound server
*/
readonly attribute SampleStorage sampleStorage;
/**
* this method checks for new object implementations (you can call this
* if you have implemented and installed new components in C++ or with
* artsbuilder, to make the soundserver use them without restart)
*/
void checkNewObjects();
};
/**
* A KMedia2 Wave PlayObject
*/
interface WavPlayObject : PlayObject, SynthModule
{
out audio stream left,right;
};
/**
* An advanced KMedia2 PlayObject based on GSL datahandles
*/
interface GSLPlayObject : PlayObject, PitchablePlayObject, SynthModule
{
attribute boolean done;
out audio stream left,right;
};
/**
* Helper interface to ensure that artsd gets initialized properly when
* multiple artsd processes are started at the same time.
*/
interface SoundServerStartup
{
void lock();
void unlock();
};
};