The aRts plain C API aims at easily writing/porting plain C apps to the aRts sound server. What is provided is streaming functionality (sending sample streams to artsd), either blocking or non-blocking. So for most apps, you simply remove the few system calls that deal with your audio device, and replace them with the appropriate aRts calls.
I did two ports as proof of concept, that is mpg123 and quake. You can get the patches here. Of course feel free to submit your own patches either to me and/or to maintainers of software packages so that they can integrate aRts support in their code.
Sending audio to the sound server with that API is very simple.
And here is a small example that illustrates this:
int main() { arts_stream_t stream; char buffer[8192]; int bytes; int errorcode; errorcode = arts_init(); if(errorcode < 0) { fprintf(stderr,"arts_init error: %s\n", arts_error_text(errorcode)); return 1; } stream = arts_play_stream(44100,2,16,"artsctest"); while((bytes = fread(buffer,1,8192,stdin)) > 0) { errorcode = arts_write(stream,buffer,bytes); if(errorcode < 0) { fprintf(stderr,"arts_write error: %s\n",arts_error_text(errorcode)); return 1; } } arts_close_stream(stream); arts_free(); return 0; }
To easily compile and link programs using the aRts C API, there is the artsc-config tool which knows which libraries you need to link and where the includes are.
It is called like
$ artsc-config --libsto find out the libraries, and like
$ artsc-config --cflagsto find out additional cflags. This means, that the example above could be compiled like
$ cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`
int |
#include <artsc.h>
initializes the aRts C API, and connects to the sound server
Returns: 0 if everything is all right, an error code otherwise
void |
#include <artsc.h>
disconnects from the sound server and frees the aRts C API internals
const char * |
#include <artsc.h>
converts an error code to a human readable error message
Parameters:
errorcode | the errorcode (from another arts function that failed) |
Returns: a text string with the error message
arts_stream_t |
#include <artsc.h>
open a stream for playing
Parameters:
rate | the sampling rate (something like 44100) |
bits | how many bits each sample has (8 or 16) |
channels | how many channels, 1 is mono, 2 is stereo |
name | the name of the stream (these will be used so that the user can assign streams to effects/mixer channels and similar) |
Returns: a stream
arts_stream_t |
#include <artsc.h>
open a stream for recording
Parameters:
rate | the sampling rate (something like 44100) |
bits | how many bits each sample has (8 or 16) |
channels | how many channels, 1 is mono, 2 is stereo |
name | the name of the stream (these will be used so that the user can assign streams to effects/mixer channels and similar) |
Returns: a stream
void |
#include <artsc.h>
close a stream
int |
#include <artsc.h>
read samples from stream
Parameters:
stream | a previously opened record stream |
buffer | a buffer with sample data |
count | the number of bytes contained in the buffer |
Returns: number of read bytes on success or error code
int |
#include <artsc.h>
write samples to to stream
Parameters:
stream | a previously opened play stream |
buffer | a buffer with sample data |
count | the number of bytes contained in the buffer |
Returns: number of written bytes on success or error code
typedef enum {...} |
#include <artsc.h>
parameters for streams
int |
#include <artsc.h>
configure a parameter of a stream
Parameters:
stream | an opened record or play stream |
parameter | the parameter you want to modify |
value | the new value |
Returns: the new value of the parameter (which may or may not be the value you wanted to have), or an error code if something went wrong
int |
#include <artsc.h>
query a parameter of a stream
Parameters:
stream | an opened record or play stream |
parameter | the parameter you want to query |
Returns: the value of the parameter, or an error code