# Interface de programmation d'application (API) de &arts;

## Aperçu

aRts n'est pas seulement un logiciel, il fournit également tout un tas d'API pour tout un tas d'applications. Dans cette section, j'essaierai de dessiner les «grandes lignes», un brèf coup d'oeil ce que ces API sont supposées faire, et la façon dont elles interagissent.

Il y a une distinction importante à faire, la plupart des API sont indépendantes du langage et de l'endroit car elles sont spécifiées en tant que mcopidl. C'est-à-dire que vous pouvez utiliser les services qu'elles offrent avec n'importe quel langage, les implémenter dans n'importe quel langage, et vous n'aurez pas à vous préoccuper de savoir si vous vous adressez à des objets locaux ou distants. Voici tout d'abord une liste de ces API :

core.idl

  Définitions de base qui forment le coeur des fonctionnalités de MCOP, comme le protocole lui-même, les définitions des objets, le trader, le système de flux &etc;

artsflow.idl

  Il contient le système de flux que vous utiliserez pour connecter des flux audio, la définition de Arts::SynthModule qui est la basse de toute interface qui possède un flux, et enfin quelques objets audio utiles.

kmedia2.idl

  Ici, un objet qui peut lire un média, Arts::PlayObject est défini. Des lecteurs multimédia comme le lecteur de KDE noatun seront capables de lire n'importe quel média pour lequel un PlayObject peut être trouvé. Il est donc pertinent d'implémenter des PlayObject pour divers formats (comme mp3, vidéo mpg, midi, wav &etc;) à la base, et il y en a déjà beaucoup.

soundserver.idl

  Une interface pour le serveur sonore artsd est défini. L'interface est appelée Arts::SoundServer, qui implémente des fonctionnalités comme accepter des flux depuis le réseau, jouer des échantillons, créer des objets personnalisés non aRts &etc; La transparence réseau est implicite grâce à l'utilisation de MCOP (comme pour tout ici).

artsbuilder.idl

  Ce module défini les fonctionnalités graphiques des flux, c'est-à-dire, la combinaison d'objets simples avec des objets plus complexes, en définissant un graph de ceux-ci. Il défini l'interface de base Arts::StructureDesc, Arts::ModuleDesc et Arts::PortDesc qui contient une description d'une structure, d'un module et d'un port. Il y a également une façon d'obtenir un réseau d'objets vivants sur ces descriptions de connexions et valeurs, en utilisant un factory.

artsmidi.idl

  Ce module défini les fonctionnalités midi de base, comme les objets qui produisent des événements midi, ce qu'est un événement midi, un Arts::MidiManager pour connecter le producteur et le consommateur d'événements midi, &etc; Comme d'habitude, la transparence réseau est gérée.

artsmodules.idl

  Ici se trouvent divers filtres supplémentaires, oscilateurs, effets, délais &etc;, tous utiles pour un traitement du signal efficace, et pour construire des instruments complexes et des effets à partir de ces blocs de construction de base.

artsgui.idl

  Ceci s'occupe des objets visuels. Il définit le type de base Arts::Widget à partir duquel tous les modules de l'interface graphique dérivent. La boîte à outils sera donc indépendante, et nous aurons une édition visuelle de l'interface graphique ainsi que des interfaces graphiques sérialisables. Comme les éléments de l'interface ont des attributs normaux, leurs valeurs peuvent être connectées directement à des modules de traitement du signal (&cad; la valeur d'une glissière à la fréquence de coupure d'un filtre). Comme d'habitude, tout ceci avec la transparence réseau.

Lorsque c'est possible, aRts lui-même implémente en utilisant IDL. D'un autre côté, il y a quelques API spécifiques au langage, en utilisant soit du C++ pur ou du C pur. Il est souvent sage d'utiliser des interfaces IDL lorsque c'est possible, et les autres API lorsque c'est nécessaire. Voici une liste des API spécifiques au langage :

KNotify, KAudioPlayer (inclus dans libkdecore)

  Il y a des API KDE pratiques pour les cas simples et courants, où vous voulez juste jouer un échantillon. Les API sont en C++ pur, optimisés pour Qt/KDE, et aussi simples que possibles.

libartsc

  Interface en C pur pour le serveur sonore. Très utile pour porter des applications héritées

libmcop

  Ici, toute la magie de MCOP se produit. La librairie contient des choses de base que vous avez besoin de connaître pour écrire des applications MCOP simples, les répartisseurs (dispatcher), les temporisateurs, gestionnaires d'entrée/sortie, mais aussi les choses internes pour faire fonctionner le protocole MCOP lui-même.

libartsflow

  En plus de l'implémentation de artsflow.idl, des outils utiles comme la conversion du taux d'échantillonnage.

libqiomanager

  Intégration de MCOP dans la boucle d'événement Qt, lorsque vous écrivez des applications Qt utilisant MCOP.

## knotify

Pas encore rédigé

## kaudioplayer

Pas encore rédigé

## libkmid

Pas encore rédigé

## kmedia2

Pas encore rédigé

## serveur sonore

Pas encore rédigé

## artsflow

Pas encore rédigé

## API C

### Introduction

L'API C de &arts; a été conçue pour faciliter l'écriture et le port d'applications en C pur vers le serveur sonore &arts;. Elle fournit des fonctionnalités de gestion de flux (en envoyant les flux d'échantillons vers artsd), soit en bloquant ou en ne bloquant pas. Pour la plupart des applications, vous devez simplement enlever les quelques appels systèmes qui conversent avec votre matériel audio et les remplacer par les appels &arts; appropriés.

J'ai réalisé deux ports pour améliorer le concept : mpg123 et quake. Vous pouvez obtenir ces correctifs depuis ici. N'hésitez pas à soumettre vos propres correctifs au mainteneur de &arts;, ou au mainteneur des paquetages de logiciels multimédia pour qu'ils puissent intégrer la gestion de &arts; dans leur code.

### Aperçu rapide

Envoyer de l'audio au serveur sonore avec l'API est très simple :

1. ajoutez le fichier d'en-tête avec `#include <artsc.h>`

2. initialisez l'API avec `arts_init()`

3. créez un flux avec `arts_play_stream()`

4. configurez les paramètres spécifiques avec `arts_stream_set()`

5. écrivez des données d'échantillons dans le flux avec `arts_write()`

6. fermez le flux avec `arts_close_stream()`

7. libérez la mémoire de l'API avec `arts_free()`

Voici un petit exemple de programme qui illustre ceci :

    #include <stdio.h>
    #include <artsc.h>
    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;
    }

### Compilation et édition de liens : artsc-config

Pour compiler et lier facilement les programmes utilisant l'API C de &arts;, l'outil artsc-config connaît les librairies dont vous avez besoin pour lier et où se situent les fichiers d'en-tête. Vous pouvez appeler cet outil avec

    artsc-config --libs

pour trouver les librairies et

    artsc-config --cflags

pour trouver les drapeaux supplémentaires pour le compilateur C. L'exemple ci-dessus peut être compilé en utilisant la ligne de commande :

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

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

### Référence de la librairie

[A FAIRE : générer la documentation pour artsc.h en utilisant kdoc]