# Interfacce di programmazione dell'applicazione &arts;

## Panoramica

aRts non è solamente un software, ma fornisce anche una varietà di API per vari scopi. In questa sezione, cercherò di descriverti la "grande immagine", un breve accenno su che cosa si pensa che facciano quelle API, e come interagiscano.

C'è una distinzione importante da fare: la maggior parte delle API sono indipendenti dalla lingua e dalla posizione perché sono specificate come mcopidl. In questo modo puoi sostanzialmente usare i servizi che offrono da qualsiasi lingua, implementarli in qualsiasi lingua, e non dovrai preoccuparti di parlare con oggetti remoti o locali. Ecco una lista di questi primi:

core.idl

- Definizioni di base che formano il nucleo della funzionalità MCOP, come il protocollo stesso, definizioni dell'oggetto, il trader, il sistema flow e così via.

artsflow.idl

- Questi contengono il sistema flow che userai per connettere flussi audio, la definizione di Arts::SynthModule che è la base per qualsiasi interfaccia che ha flussi e infine alcuni oggetti audio interessanti

kmedia2.idl

- Qua viene definito un oggetto che può eseguire un oggetto multimediale, Arts::PlayObject. I riproduttori multimediali come il KDE multimedia player noatun sarà capace di eseguire qualsiasi oggetto multimediale per il quale può essere trovato un PlayObject. Così ha senso implementare PlayObject per vari formati (come mp3, mpg video, midi, wav, ...) su quella base, e ce ne sono già molti.

soundserver.idl

- Qui è definita un'interfaccia per l'ampio sistema server sonoro artsd. L'interfaccia è chiamata Arts::SoundServer, la quale implementa funzionalità come accettare i flussi dalla rete, suonare campioni, creare oggetti aRts o personalizzati e così via. La trasparenza di rete è implicitamente dovuta all'uso di MCOP (come per qualsiasi altra cosa qui).

artsbuilder.idl

- Questo modulo definisce la funzionalità di base del grafico del flusso, cioè, come combinare semplici oggetti con altri più complessi, definendo un loro grafico. Esso definisce l'interfaccia di base Arts::StructureDesc, Arts::ModuleDesc e Arts::PortDesc, che contengono una descrizione della struttura, del modulo e della porta. C'è anche un modo per far uscire una "rete live di oggetti" da queste connessioni e descrizioni, usando una factory.

artsmidi.idl

- Questo modulo definisce la funzionalità midi di base, come oggetti che producono eventi midi, cioè un Arts::MidiManager per connettere i produttori e i consumatori di eventi midi, e così via. Come sempre è sottintesa la trasparenza di rete.

artsmodules.idl

- Qua ci sono vari filtri aggiuntivi, oscillatori, effetti, ritardi e così via, qualsiasi cosa richiesta per un'esecuzione del segnale in modo reale, e per compilare strumenti complessi ed effetti da questi semplici blocchi di compilazione di base.

artsgui.idl

- Questo si occupa di oggetti visuali. Definisce il carattere tipo Arts::Widget dal quale derivano tutti i moduli GUI. Questo produrrà l'indipendenza dell'insieme degli strumenti, la modifica visuale delle GUI, e la serializzazione delle GUI. Inoltre, dato che gli elementi GUI hanno attributi normali, il loro valore può essere strettamente connesso ad alcuni moduli di elaborazione del segnale (come il valore di uno cursore al limite di taglio del filtro). Come sempre: trasparenza di rete.

Dove possibile, aRts stesso è implementato usando IDL. D'altra parte, ci sono alcune API con un linguaggio specifico, che usano sia il semplice C++ o C. È solitamente saggio usare le interfacce IDL dove è possibile, e le altre API dove necessario. Qui c'è una lista del linguaggio specifico delle API:

KNotify, KAudioPlayer (inclusi in libkdecore)

- Ci sono API KDE convenienti per i casi più semplici e comuni, nei quali vuoi eseguire un campione. Gli API sono ottimizzati per il semplice C++, Qt/KDE, e sono semplici come recuperarli.

libartsc

- Interfaccia del semplice C per il server sonoro. Molto utile per fare il porting di applicazioni vecchio stile.

libmcop

- Qua si svolge tutta la magia per MCOP. La libreria contiene le cose di base che devi conoscere per scrivere una semplice applicazione MCOP, il mittente, gli orari, la gestione i/o, ma anche gli interni per far lavorare il protocollo MCOP stesso.

libartsflow

- In aggiunta all'implementazione di artsflow.idl, qualche strumento interessante come la conversione rate dei campioni.

libqiomanager

- Integrazione di MCOP nell'evento loop Qt, quando scrivi applicazioni Qt usando MCOP.

## knotify

Non ancora scritto

## kaudioplayer

Non ancora scritto

## libkmid

Non ancora scritto

## kmedia2

Non ancora scritto

## server sonoro

Non ancora scritto

## artsflow

Non ancora scritto

## API C

### Introduzione

L' API &arts; C fu progettata per rendere più semplice scrivere e fare il port di semplici applicazioni C al server sonoro &arts;. Fornisce funzionalità di streaming (inviando flussi di campioni a artsd), sia a blocco o non blocco. Per la maggior parte delle applicazioni rimuovi semplicemente le poche chiamate del sistema che si occupano del tuo dispositivo audio e le rimpiazzi con appropriate chiamate &arts;.

Ho fatto due port come esempio del concetto: mpg123 e quake. Puoi scaricare le patch da here. Sentiti libero di proporre le tue proprie patch al responsabile di &arts; o dei pacchetti software multimediali in modo che possano integrare il supporto &arts; nel loro codice.

### In pochi passi

Inviare l'audio al server sonoro con l' API è molto semplice:

1. includi il file di intestazione usando `#include <artsc.h>`

2. inizializza l' API con `arts_init()`

3. crea un flusso con `arts_play_stream()`

4. configura i parametri specifici con `arts_stream_set()`

5. scrivi un campionamento dei dati al flusso con `arts_write()`

6. chiudi il flusso con `arts_close_stream()`

7. libera l' API con `arts_free()`

Ecco qua un piccolo programma di esempio che lo illustra:

    #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;
    }

### Compilare e fare il link: artsc-config

Per compilare e fare il link dei programmi usando le API C di &arts;, l'utility artsc-config fornisce conoscenze di quali librerie hai bisogno per fare il link e dove sono incluse. È chiamata usando

    artsc-config --libs

trovare le librerie e

    artsc-config --cflags

scoprire flag del compilatore C aggiuntivi. L'esempio sopra potrebbe essere compilato usando la riga di comando:

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

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

### Riferimento alla libreria

[TODO: generare la documentazione per artsc.h usando kdoc]