The aRts Handbook
Prev | Chapter 7. aRts Application Programming Interfaces | Next

# 7.8. C API

## 7.8.1. Introduction

The aRts C API was designed to make it easy to writing and port plain C applications to the aRts sound server. It provides streaming functionality (sending sample streams to artsd), either blocking or non-blocking. For most applications 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 a proof of concept: mpg123 and quake. You can get the patches from here. Feel free to submit your own patches to the maintainer of aRts or of multimedia software packages so that they can integrate aRts support into their code.

## 7.8.2. Quick Walkthrough

Sending audio to the sound server with the API is very simple:

1. include the header file using `#include <artsc.h>`

2. initialize the API with `arts_init()`

3. create a stream with `arts_play_stream()`

4. 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()`

Here is a small example program that illustrates this:

       1 #include <stdio.h>
       2 #include <artsc.h>
       3
       4 int main()
       5 {
       6     arts_stream_t stream;
       7     char buffer[8192];
       8     int bytes;
       9     int errorcode;
      10
      11     errorcode = arts_init();
      12     if (errorcode < 0)
      13     {
      14         fprintf(stderr, "arts_init error: %s\n", arts_error_text(errorcode));
      15         return 1;
      16     }
      17
      18     stream = arts_play_stream(44100, 16, 2, "artsctest");
      19
      20     while((bytes = fread(buffer, 1, 8192, stdin)) > 0)
      21     {
      22         errorcode = arts_write(stream, buffer, bytes);
      23         if(errorcode < 0)
      24         {
      25             fprintf(stderr, "arts_write error: %s\n", arts_error_text(errorcode));
      26             return 1;
      27         }
      28     }
      29
      30     arts_close_stream(stream);
      31     arts_free();
      32
      33     return 0;
      34 }

## 7.8.3. Compiling and Linking: artsc-config

To easily compile and link programs using the aRts C API, the artsc-config utility is provided which knows which libraries you need to link and where the includes are. It is called using

     artsc-config --libs

to find out the libraries and

     artsc-config --cflags

to find out additional C compiler flags. The example above could have been compiled using the command line:

     cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

     cc -o artsctest artsctest.c `artsc-config --cflags` `artsc-config --libs`

## 7.8.4. Library Reference

[TODO: generate the documentation for artsc.h using kdoc]

Prev | Home | Next
artsflow | Up | aRts modules