The K Desktop Environment

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]