### The aRts C API

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.

#### Quick walkthrough

Sending audio to the sound server with that API is very simple.

1. use a #include <artsc.h>
2. initialize the API with arts_init()
3. create a stream with arts_play_stream()
4. eventually configure specific parameters with arts_stream_set()
5. write sampling data to the stream with arts_write()
6. close the stream with arts_close_stream()
7. free the API with arts_free()

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,16,2,"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;
    }

#### Compiling & Linking: artsc-config

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 --libs

to find out the libraries, and like

    $ artsc-config --cflags

to 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`

#### Library Reference

int <underline>arts_init</underline> ()

`#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 <underline>arts_free</underline> ()

`#include <artsc.h>`

disconnects from the sound server and frees the aRts C API internals

const char * <underline>arts_error_text</underline> (int errorcode)

`#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 <underline>arts_play_stream</underline> (int rate, int bits, int channels, char *name)

`#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 <underline>arts_record_stream</underline> (int rate, int bits, int channels, char *name)

`#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 <underline>arts_close_stream</underline> (arts_stream_t stream)

`#include <artsc.h>`

close a stream

int <underline>arts_read</underline> (arts_stream_t stream, void *buffer, int count)

`#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 <underline>arts_write</underline> (arts_stream_t stream, void *buffer, int count)

`#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 {...} <underline>arts_parameter_t</underline>

`#include <artsc.h>`

parameters for streams

- ARTS_P_BUFFER_SIZE (rw) The size of the internal buffers used for streaming to the server - this directly affects the latency that will occur. If you never set it explicitely, this value defaults to at least 65536 (64kb). Generally, it is important to know that the server itself gives some constraints which makes buffer sizes below a certain value impossible. So setting this parameter will always result in either getting what you wanted, or a larger streaming buffer due to server limitations.

- ARTS_P_BUFFER_TIME (rw) The time the buffer used for streaming to the server takes to play in milliseconds. This is just a more human readable method to set the buffer size, so setting ARTS_P_BUFFER_SIZE affects this parameter and the other way round. As aRts chooses reasonable buffer sizes for streaming (rather 3*16kb than 40234 bytes), setting this parameter will often end up with a slightly larger value than you requested.

- ARTS_P_BUFFER_SPACE (r) The amount of bytes that can be read/written without blocking (depending whether this is a record or play stream). As requesting this parameter does a few system calls (but no remote invocation) to verify that it is up-to-date, don't overuse it.

- ARTS_P_SERVER_LATENCY (r) The amount of latency the server creates (due to hardware buffering) in milliseconds.

- ARTS_P_TOTAL_LATENCY (r) The overall latency in milliseconds it takes (at most), from the time when you write a byte into a stream, until it gets played on the soundcard. This is simply a shortcut to the sum of ARTS_P_BUFFER_TIME and ARTS_P_SERVER_LATENCY.

- ARTS_P_BLOCKING (rw) If this parameter is 1 (the default), arts_read/arts_write will block when not all data can be read/written successfully, and wait until it works. If this parameter is 0, arts_read/arts_write will return the number of successfully read/written bytes immediately.

int <underline>arts_stream_set</underline> (arts_stream_t stream, arts_parameter_t param, int value)

`#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 <underline>arts_stream_get</underline> (arts_stream_t stream, arts_parameter_t param)

`#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

back to index