RoarAudio/Programmieren/Intro

Dies ist eine minimale Einleitung zur Programmierung mittels der RoarAudio Standard Bibliotheken.

Diese Anleitung setzt grundlegendes Verständnis zur Funktionsweise von RoarAudio voraus.

Dieses Dokument beschreibt die Standard API. Für sehr einfache Programme mag es angebracht sein die Simple API oder die Very Simple API zu verwenden.

Header Dateien

Um die RoarAudio API verwenden zu können müssen als erstes die richtigen Header eingebunden werden. In aller Regel reicht es den Standard Header ein zu binden, welcher die meisten nötigen Header wiederum selbst einbindet:

#include <roaraudio.h>

Zur Verwendung von libroardsp, libroarlight, libroarmidi und libroareio müssen weiterhin folgende Header entsprechend eingebunden werden:

#include <libroardsp/libroardsp.h>
#include <libroarlight/libroarlight.h>
#include <libroarmidi/libroarmidi.h>
#include <libroareio/libroareio.h>

Weiterhin gibt es noch einen speziellen Header zur Verwendung von Einheiten:

#include <roaraudio/units.h>

Verbindung zum Server

In aller Regel muss zu Beginn eine Verbindung zum Server aufgenommen werden. Dazu wird ein Objekt für die Verbindung angelegt und dies dann mit dem Server verbunden. Ist die Arbeit getan so wird die Verbindung wieder Beendet. Die Verbindung sollte aber offen gehalten werden sofern in absehbarer Zeit sonst eine neue Verbindung aufgebaut werden müsste. (Etwa sollte sie nicht bei einem Lied Wechsel in einem Player erst abgebaut und dann erneut Aufgebaut werden, sondern bestehen bleiben solange der Player nicht beendet wird durch den Benutzer).

Öffnen eines Steuerkanals:

struct roar_connection con; // Steuer Verbindung

if ( roar_simple_connect(&con, NULL, "Klient Name")) == -1 ) {
 return -1;
}

In diesem Beispiel wird ein Objekt names con erzeugt und mit dem Standard Server (NULL) verbunden. Wird anstatt NULL ein String übergeben so wird dieser als Server Name/Adresse verwendet. Das letzte Argument ist der Name des neuen Klienten. Dieser wird beispielsweise durch roarctl angezeigt.

Ist die Arbeit getan so kann die Verbindung einfach durch roar_disconnect() wieder geschlossen werden:

roar_disconnect(&con);

Erstellen eines Streams

Ist die Verbindung zum Server aufgebaut so wird in aller Regel eine Datenverbindung Stream aufgebaut. Der der Einfachkeit wegen werden in diesem Dokument nur Streams behandelt die direkt durch die Bibliothek verbunden werden.

Um einen Stream zu öffnen benötigt man nun zwei weitere Objekte: Das Stream Objekt welches die Informationen über den Stream selbst beinhaltet und das VIO Objekt welches uns die Möglichkeit bietet Daten mit dem Stream aus zu tauchen.

struct roar_stream stream;  // Stream Objekt
struct roar_vio_calls vio;  // VIO Objekt

Nachdem beide Objekte erstellt sind öffnen wir nun eine Daten Verbindung zum Abspielen von Waveform Daten. Dies sind Streams zum abspielen von normaler Musik (PCM und PCM ähnliche Formate, kein MIDI).

if ( roar_vio_simple_new_stream_obj(&vio,
                                    &con,
                                    &stream,
                                     rate, channels, bits,
                                     ROAR_CODEC_DEFAULT, ROAR_DIR_PLAY
                                   ) == -1 ) {
 return -1;
}

Hierbei expandiert ROAR_CODEC_DEFAULT zu dem nativen PCM Format der aktuellen Maschine. ROAR_DIR_PLAY gibt an das wir Audio Daten abspielen möchten. rate, channels, bits sind entsprechend von der Applikation zu setzen entsprechend der aktuellen Daten. Übliche werte sind hier als Beispiel rate=44100Hz, channels=2, bits=16.

Sollen keine weiteren Informationen auf dem Stream gesetzt werden (Mixer Einstellungen, Meta Daten oder ähnliches) so kann das Stream Objekt ignoriert werden. Diese Einleitung tut dies, anderen Anleitungen mögen auf dieses Objekt detahierter eingehen.

Wollen wir nun Daten an den Server schicken so verwenden wir die VIO API. In unserem falle die Funktion roar_vio_write():

ret = roar_vio_write(&vio, buffer, len);

Die Funktion erwartet einen Datenpuffer sowie dessen Größe. Sie liefert die Anzahl der geschriebenen Byte zurück. Siehe auch write(2).

Erreicht unsere Applikation das Ende der Daten (zum Beispiel das Dateiende der Quell-Datei) so schließen wir das VIO Objeckt mittels roar_vio_close():

roar_vio_close(&vio);

Der Stream wird auf Seite des Servers beendet sobald dieser einen internen Puffer vollständig geleert hat. Dies kann je nach verwendetem Codec durchaus mehre Sekunden dauern. bei PCM Daten sollte dies allerdings im Milisekunden Bereich liegen und kann ignoriert werden.

Das Stream Objekt (stream) das wir oben angelegt haben verliert mit diesem Ereignis seine Gültigkeit. Aus diesem Grunde kann es ab dem Zeitpunkt zu dem wir das VIO Objekt geschlossen haben als ungültig angesehen werden.

Themen Liste

libroar

Simple API

API um simple Streams auf zu bauen.

Stream API

API zur Steuerung von Streams.

Control API

API zur Steuerung des Servers.

Virtuelle IO (VIO)

API für IO Handling.

VIO DSTR API

API für das öffnen von VIO Objekten anhand von Beschreibenden Strings (z.B. URLs)

VIO Typen Liste

Liste von möglichen VIO Typen.

Memory Puffer

API zur komfortablen Verwaltung von Memory Puffern.

Memory Management API

API zur Memory Verwaltung.

RoarAudio Dynamic Library API

API zum dynamischen Laden von Bibliotheken (z.B. Plugins)

libroardsp

Filter

Verwenden von Signal Filtern.

Fader

Überblend-Efeckte.

Transcode

Signal En-/De-/Transcoder.

Andere DSP Funktionen

Andere Signalverarbeitungs Funktionen.

libroarlight

RoarDMX

RoarDMX Licht Steuerungs Codec

libroarmidi

MIDI

Umgang mit MIDI Signalen.

libroareio

CDriver

Klient seitige Treiber.

Siehe Auch

• RoarAudio

Weblinks

Offizielle Webpräsenz „RoarAudio/Programmieren/Intro”

UUGRN-Wiki verbessern („Stub”)

Dieser Artikel ist leider sehr kurz. Also: Sei mutig und mache aus ihm bitte einen guten Artikel, wenn du mehr zum Thema „RoarAudio/Programmieren/Intro” weißt.