# &arts; programmeringsgrænseflade

## Oversigt

aRts er ikke kun et program, den sørger for også et antal forskellige programmeringsgrænseflader (API) til forskellige formål. I dette afsnit, forsøger jeg at beskrive "helhedsbilledet", et hurtigt overblik over hvad disse grænseflader er tænkte at bruges til, og hvordan de hænger sammen.

Der er en vigtig distinktion som skal gøres: De fleste grænseflader er sprog- og pladsuafhængige eftersom de er specificerede som mcopidl. Dette betyder at man egentlig kan bruge den tjeneste de sørger for fra et hvilket som helst sprog, implementere dem i et hvilket som helst sprog, og man behøver ikke tage sig af om man taler med lokal- eller fjernobjekter. Her er først en liste af dem:

core.idl

- Grundlæggende definitioner som danner kernen i MCOP-funktionen, såsom selve protokollen, definitioner af objekter, handleren, flowsystemet og så videre.

artsflow.idl

- Disse indeholder flowsystemet som man bruger til at forbinde lydstrømmene, definitionen af Arts::SynthModule som er grundlaget for alle grænseflade som har strømme, og til slut nogle nyttige lydobjekter.

kmedia2.idl

- Her defineres Arts::PlayObject, et objekt som kan spille en mediatype. Mediaspillere såsom KDE's mediespiller noatun vil kunne afspille hvilket som helst medie som har et PlayObject. Derfor giver det mening at implementere PlayObject for forskellige formater (såsom mp3, mpg video, midi, wav, ...) med dette som grundlag, og der findes allerede mange.

soundserver.idl

- Her defineres en grænseflade for systemets lydserver artsd. Grænsefladen benævnes Arts::SoundServer, og implementerer funktioner såsom at tage imod strømme fra netværket, spille samplinger, oprette andre egne aRts-objekter og så videre. Netværkstransparens er underforstået eftersom MCOP bruges (som for alt øvrigt her).

artsbuilder.idl

- Dette modul definerer grundlæggende flowfunktioner, dvs. kombinerer enklere objekter til mere komplekse ved at definere en graf som binder dem sammen. Den definerer den grundlæggende grænseflade Arts::StructureDesc, Arts::ModuleDesc og Arts::PortDesc som indeholder en beskrivelse af en struktur, modul og port. Der er også en måde at oprette et "levende netværk af objekter" fra disse forbindelser og værdibeskrivelserne ved brug af en fabrik.

artsmidi.idl

- Dette modulet definerer grundlæggende midi-funktioner, såsom objekter som laver midi-begivenheder, hvad en midi-begivenhed er, og Arts::MidiManager til at forbinde producenter og konsumenter af midi-begivenheder, og så videre. Som altid er netværkstransparens underforstået.

artsmodules.idl

- Her er der diverse yderligere filtre, oscillatorer, lydeffekter, forsinkelser og så videre, alt som behøves for rigtig nyttig signalbehandling, og for at opbygge komplekse instrumenter og effekter fra disse grundlæggende byggeblokke.

artsgui.idl

- Denne tager sig af synlige objekter. Den definerer den grundlæggende type Arts::Widget som alle moduler med en grafisk grænseflade udgår fra. Dette giver uafhængighed af værktøjskasse, og ... visuel redigering af den grafiske grænseflade, og mulighed for at serialisere den grafiske grænseflade. Desuden, eftersom de grafiske komponenter har normale egenskaber, kan deres værdier på en ligetil måde forbindes til visse signalbehandlingsmoduler. (dvs. værdien af en skyder til klipning for et filter). Som altid, netværkstransparent.

Hvor det er muligt implementeres aRts selv med IDL. På den anden side er der nogle sprogspecifikke programmeringsgrænseflader, som enten bruger enkel C++ eller C. Det er ofte fornuftigt at bruge IDL-grænseflade hvis muligt, og de øvrige grænseflader når det er nødvendigt. Her er en liste over sprogspecifikke programmeringsgrænseflade:

KNotify, KAudioPlayer (indgår i libkdecore)

- Disse er KDE's programmeringsgrænseflader for bekvemmelighed med de enkle og vældigt almindelige tilfælde, hvor man kun vil afspille en sampling. Grænsefladen er enkel C++, Qt/KDE-optimerede, og så enkle som de kan være.

libartsc

- Enkel C-grænseflade for lydserveren. Meget nyttig for at tilrette gamle programmer.

libmcop

- Her sker al magi som har med MCOP at gøre. Biblioteket indeholder de grundlæggende ting som behøves for at skrive et enkelt MCOP-program, afsenderen, tidtagning, I/O-håndtering, men også de interne funktioner som behøves for at selve MCOP-protokollen skal fungere.

libartsflow

- Foruden implementeringen af artsflow.idl, nogle nyttige værktøjer for konvertering af samplingsrater.

libqiomanager

- Integration af MCOP i Qt's begivenhedsløkke, når man skriver Qt-programmer som bruger MCOP.

## knotify

Endnu ikke skrevet

## kaudioplayer

Endnu ikke skrevet

## libkmid

Endnu ikke skrevet

## kmedia2

Endnu ikke skrevet

## lydserver

Endnu ikke skrevet

## artsflow

Endnu ikke skrevet

## C API

### Indledning

C-grænsefladen for &arts; oprettedes for at gøre det let at skrive og overføre enkle C-programmer til &arts; lydserver. Den sørger for strømningsfunktioner (at sende samplingsstrømme til artsd), enten med eller uden blokering. For de fleste programmer tager man helt enkelt de få systemkald væk som håndterer lydenheden og skifter dem ud mod passende kald til &arts;.

Jeg lavede to overførsler for at verificere idéen: mpg123 og quake. Du kan skaffe programrettelserne herfra. Bidrag gerne med dine egne programrettelser til vedligeholderen af &arts; eller til programmelpakken for multimedia så de kan integrere understøttelsen for &arts; i deres kode.

### Hurtig gennemgang

At sende lyd til lydserveren med grænsefladen er meget enkelt:

1. indsæt deklarationsfilen med `#include <artsc.h>`

2. initiér grænsefladen med `arts_init()`

3. opret en strøm med `arts_play_stream()`

4. indstil særlige parametre med `arts_stream_set()`

5. skriv samplingsdata til strømmen med `arts_write()`

6. luk strømmen med `arts_close_stream()`

7. frigør grænsefladen med `arts_free()`

Her er et eksempel på et lille program som viser dette:

    #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 fejl: %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 fejl: %s\n", arts_error_text(errorcode));
                return 1;
            }
        }

        arts_close_stream(stream);
        arts_free();

        return 0;
    }

### Kompilere og linke: artsc-config

For let at kunne kompilere og linke programmer med &arts; C-grænseflade, findes værktøjet artsc-config som kender til hvilke biblioteker som man skal linke med og hvor deklarationsfilerne findes. Det kaldes med

    artsc-config --libs

for at finde ud af bibliotekerne og

    artsc-config --cflags

for at finde ud af yderligere C-oversætterflag. Eksemplet ovenfor ville være kunnet kompileres med kommandolinjen:

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

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

### Biblioteksreference

[HUSK: opret dokumentation for artsc.h med kdoc]