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  arts_init ()

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

#include <artsc.h>

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

const char * arts_error_text (int errorcode)

#include <artsc.h>

converts an error code to a human readable error message

Parameters:
errorcodethe errorcode (from another arts function that failed)

Returns: a text string with the error message

arts_stream_t  arts_play_stream (int rate, int bits, int channels, char *name)

#include <artsc.h>

open a stream for playing

Parameters:
ratethe sampling rate (something like 44100)
bitshow many bits each sample has (8 or 16)
channelshow many channels, 1 is mono, 2 is stereo
namethe 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  arts_record_stream (int rate, int bits, int channels, char *name)

#include <artsc.h>

open a stream for recording

Parameters:
ratethe sampling rate (something like 44100)
bitshow many bits each sample has (8 or 16)
channelshow many channels, 1 is mono, 2 is stereo
namethe 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  arts_close_stream (arts_stream_t stream)

#include <artsc.h>

close a stream

int  arts_read (arts_stream_t stream, void *buffer, int count)

#include <artsc.h>

read samples from stream

Parameters:
streama previously opened record stream
buffera buffer with sample data
countthe number of bytes contained in the buffer

Returns: number of read bytes on success or error code

int  arts_write (arts_stream_t stream, void *buffer, int count)

#include <artsc.h>

write samples to to stream

Parameters:
streama previously opened play stream
buffera buffer with sample data
countthe number of bytes contained in the buffer

Returns: number of written bytes on success or error code

typedef enum {...} arts_parameter_t

#include <artsc.h>

parameters for streams

int  arts_stream_set (arts_stream_t stream, arts_parameter_t param, int value)

#include <artsc.h>

configure a parameter of a stream

Parameters:
streaman opened record or play stream
parameterthe parameter you want to modify
valuethe 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  arts_stream_get (arts_stream_t stream, arts_parameter_t param)

#include <artsc.h>

query a parameter of a stream

Parameters:
streaman opened record or play stream
parameterthe parameter you want to query

Returns: the value of the parameter, or an error code


back to index