home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / arts / soundserver.idl < prev    next >
Encoding:
Text File  |  2005-09-10  |  7.4 KB  |  295 lines
  1. #include "artsflow.idl"
  2. #include "kmedia2.idl"
  3. #include "core.idl"
  4.  
  5. module Arts {
  6.  
  7. /**
  8.  * One entry of the sample storage - initially, you'll need to fill the entry.
  9.  *
  10.  * To do so, call write repeatedly to fill it with data, and finish() when
  11.  * you are done. After that you can use the filename attribute to get the
  12.  * name of the file on the server that has stored the data. You can use
  13.  * this filename for other things (i.e. SimpleSoundServer::play).
  14.  */
  15. interface SampleStorageEntry {
  16.     readonly attribute string name;
  17.     readonly attribute string filename;
  18.     readonly attribute boolean completed;
  19.  
  20.     void write(sequence<byte> data);
  21.     void finish();
  22. };
  23.  
  24. /**
  25.  * Interface for storing files on the sound server
  26.  */
  27. interface SampleStorage {
  28.     void constructor(string directory, boolean clearOnInit);
  29.  
  30.     /**
  31.      * creates a new entry which you can use to store a sample - if you just
  32.      * create an entry, it will be private to you, i.e. you can use it, and
  33.      * as soon as you don't need it any longer, it will be freed
  34.      *
  35.      * if you want that the entry stays in the storage, you need to add it,
  36.      * and it will stay then until you remove it
  37.      */
  38.     SampleStorageEntry createEntry(string name);
  39.  
  40.     /**
  41.      * add an entry (which will make it accessible via findEntry) - remember
  42.      * to eventually call removeEntry, or the entry will stay there forever
  43.      */
  44.     void addEntry(SampleStorageEntry entry);
  45.  
  46.     /**
  47.      * removes an entry, that is, the entry will only stay there until
  48.      * nobody needs it any more and then get freed
  49.      */
  50.     void removeEntry(SampleStorageEntry entry);
  51.  
  52.     /**
  53.      * finds an entry by name
  54.      */
  55.     SampleStorageEntry findEntry(string name);
  56. };
  57.  
  58. /**
  59.  * Producer of byte sound
  60.  *
  61.  * This is used inside the sound server interface
  62.  */
  63. interface ByteSoundProducer : SynthModule
  64. {
  65.     readonly attribute long samplingRate;
  66.     readonly attribute long channels;
  67.     readonly attribute long bits;
  68.  
  69.     async out byte stream outdata;
  70. };
  71.  
  72. /**
  73.  * V2 version of the ByteSoundProducer interface that implements the title
  74.  * attribute
  75.  */
  76. interface ByteSoundProducerV2 : ByteSoundProducer
  77. {
  78.     readonly attribute string title;
  79. };
  80.  
  81. /**
  82.  * Receiver of byte sound
  83.  */
  84. interface ByteSoundReceiver : SynthModule
  85. {
  86.     readonly attribute long samplingRate;
  87.     readonly attribute long channels;
  88.     readonly attribute long bits;
  89.     readonly attribute string title;
  90.  
  91.     async in byte stream indata;
  92. };
  93.  
  94. /**
  95.  * This is a very simple sound server interface
  96.  *
  97.  * WARNING: This currently inherits a KMedia2 PlayObjectFactory for test
  98.  *          purposes, but don't rely on that
  99.  */
  100.  
  101. interface SimpleSoundServer : PlayObjectFactory
  102. {
  103.     readonly attribute StereoEffectStack outstack;
  104.  
  105.     /**
  106.      * tries to play the sound in "filename"
  107.      *
  108.      * returns an ID when success 0 when it fails
  109.      */
  110.     long play(string filename);
  111.  
  112.     /**
  113.      * returns true if the sound in ID is still playing
  114.      */
  115.     //boolean isPlaying(long ID);
  116.  
  117.     /**
  118.      * stops a playing sound by ID
  119.      */
  120.     //void stop(long ID);
  121.  
  122.     /**
  123.      * specifies the minimum amount of milliseconds that have to be buffered
  124.      * to allow safe streaming (without interruptions) from/to external apps
  125.      *
  126.      * this depends on the realtime parameters the sound server itself uses
  127.      * to talk to the hardware
  128.      */
  129.     readonly attribute float minStreamBufferTime;
  130.  
  131.     /**
  132.      * specifies the amount of milliseconds the server itself spends with
  133.      * the hardware (buffering latency) - so if you stream into the server,
  134.      * you should have a yourStreamBufferTime >= minStreamBufferTime, and
  135.      * the total latency is
  136.      *
  137.      *  totalLatency = yourStreamBufferTime + serverBufferTime
  138.      */
  139.     readonly attribute float serverBufferTime;
  140.  
  141.     /**
  142.      * attaches a byte sound producer (read: a client which produces/mixes
  143.      * an audio stream itself and just wants playback via the soundserver)
  144.      */
  145.     void attach(ByteSoundProducer producer);
  146.  
  147.     /**
  148.      * detaches a previous attached byte sound producer
  149.      */
  150.     void detach(ByteSoundProducer producer);
  151.  
  152.     /**
  153.      * attaches a byte sound receiver (a client that records an
  154.      * audio stream from the soundserver)
  155.      */
  156.     void attachRecorder(ByteSoundReceiver receiver);
  157.  
  158.     /**
  159.      * detaches a previous attached byte sound receiver
  160.      */
  161.     void detachRecorder(ByteSoundReceiver receiver);
  162.  
  163.     object createObject(string name);
  164. };
  165.  
  166. enum RealtimeStatus { rtRealtime, rtNoSupport, rtNoWrapper, rtNoRealtime };
  167.  
  168. /**
  169.  * This is an enhanced sound server interface which can be used to
  170.  * query status information or suspend the soundserver right away
  171.  */
  172. interface SoundServer : SimpleSoundServer
  173. {
  174.     readonly attribute RealtimeStatus realtimeStatus;
  175.  
  176.     /**
  177.      * Returns how many seconds you have to wait _now_ for the soundserver
  178.      * to suspend. A value of -1 signals that the sound server is busy and
  179.      * will not suspend automatically at the moment.
  180.      */
  181.     readonly attribute long secondsUntilSuspend;
  182.  
  183.     /**
  184.      * Makes the soundserver suspend now _if_ it is not busy playing, that
  185.      * is, if it is "suspendable". Returns true if successful.
  186.      */
  187.     boolean suspend();
  188.  
  189.     /**
  190.      * Asks the soundserver if it is suspended.  Returns true if so.
  191.      */
  192.     boolean suspended();
  193.  
  194.     /**
  195.      * Permanently terminates the sound server - this is not intended to be
  196.      * widely used. However, it provides a way to "kill" the sound server,
  197.      * even if you don't reside on the same host with it, and even if you
  198.      * don't know the process id, and so on. In the future it also offers
  199.      * the possibility for interested apps to be informed before the server
  200.      * goes away, and for important apps to block termination.
  201.      *
  202.      * Returns true if successful.
  203.      */
  204.     boolean terminate();
  205. };
  206.  
  207. /**
  208.  * This is an even more enhanced sound server interface that supports changing
  209.  * the autosuspend time, and returning more information about the server
  210.  * settings.
  211.  */
  212. interface SoundServerV2 : SoundServer, PlayObjectFactoryV2
  213. {
  214.     /**
  215.      * Time in seconds after which server will suspend if idle.
  216.      */
  217.     attribute long autoSuspendSeconds;
  218.  
  219.     /**
  220.      * Multiplier for size of network buffers. Default is 1,
  221.      * which is fragment size * fragment count. (expressed
  222.      * as milliseconds).
  223.      */
  224.     attribute long bufferSizeMultiplier;
  225.  
  226.     /**
  227.      * Current CPU usage in percent
  228.      */
  229.     readonly attribute float cpuUsage;
  230.  
  231.     /**
  232.      * AudioSubSystem parameters
  233.      */
  234.     readonly attribute string audioMethod;
  235.     readonly attribute long samplingRate;
  236.     readonly attribute long channels;
  237.     readonly attribute long bits;
  238.     readonly attribute boolean fullDuplex;
  239.     readonly attribute string audioDevice;
  240.     readonly attribute long fragments;
  241.     readonly attribute long fragmentSize;
  242.  
  243.     /**
  244.      * version
  245.      */
  246.     readonly attribute string version;
  247.  
  248.     /**
  249.      * global output volume for the sound server
  250.      */
  251.     readonly attribute StereoVolumeControl outVolume;
  252.  
  253.     /**
  254.      * for storing samples on the sound server
  255.      */
  256.     readonly attribute SampleStorage sampleStorage;
  257.  
  258.     /**
  259.      * this method checks for new object implementations (you can call this
  260.      * if you have implemented and installed new components in C++ or with
  261.      * artsbuilder, to make the soundserver use them without restart)
  262.      */
  263.     void checkNewObjects();
  264. };
  265.  
  266. /**
  267.  * A KMedia2 Wave PlayObject
  268.  */
  269. interface WavPlayObject : PlayObject, SynthModule
  270. {
  271.     out audio stream left,right;
  272. };
  273.  
  274. /**
  275.  * An advanced KMedia2 PlayObject based on GSL datahandles
  276.  */
  277. interface GSLPlayObject : PlayObject, PitchablePlayObject, SynthModule
  278. {
  279.     attribute boolean done;
  280.  
  281.     out audio stream left,right;
  282. };
  283.  
  284. /**
  285.  * Helper interface to ensure that artsd gets initialized properly when
  286.  * multiple artsd processes are started at the same time.
  287.  */
  288. interface SoundServerStartup
  289. {
  290.     void lock();
  291.     void unlock();
  292. };
  293.  
  294. };
  295.