RoarAudio/Vortrag/Programmieren mit RoarAudio VS

Was ist RoarAudio?

Ziel

ein Vortrag über RoarAudios VS API vor einem Unixpublikum mit geringem Vorwissen zum Thema. Nach ende des Vortags sollen die Hörer in der Lage sein einfache Programme mit der VS API zu schreiben.

RoarAudio Logo

Abstrakt

Der Vortrag soll eine Einführung in die Programmierung mit der VS API aus libroar liefern. Im laufe des Vortrags werden die grundlegenden API Funktionen vorgestellt und mit Code Beispielen erläutert. Am Ende des Vortrags sollten die Zuhörer in der Lage sein einfache Programme mit der VS API zu schreiben.

Als Vorwissen empfiehlt es sich einen der Einführenden Vorträge besucht zu haben.

Über den Referent

Philipp 'ph3-der-loewe' Schafft schreibt seit etwa 10 Jahren Software (primär in C und Perl). Im Moment studiert er Elektrotechnik/Automatisierungstechnik.

Besondere Interessen liegen in dem Bereich der Netzwerke und Bus Systeme, Mikrocontrollern, Kryptographie und Digitaler Audio Verarbeitung sowie Entwicklung kreativer Lösungen für Mathematik und Logik Rätseln und Übungen.

In seiner Freizeit beschäftigt er sich außerdem intensiv mit Großkatzen.

Vortrag

Was ist die VS API?

Die VS API (von engl. "Very Simple API") ist eine Schnittstelle auf hoher Ebene welche durch libroar angeboten wird. Sie ist stark an OpenBSD's sndio, aRtsc (KDE 2.x und 3.x) und pulsesimple angelehnt. Sie ist entwikelt worden um neuen Entwicklern und Entwicklern die mit den anderen Systemen zu tun hatten den Umstieg zu erleichtern.

Die VS API bedient nur einen sehr kleinen Bereich von RoarAudios Fähigkeiten. Sie ist auch nur für das Abspielen und Aufnehmen von Streams geeignet und hat keine allgemeinen Steuer Funktionen. Sie kann aber, anders als bei ähnlichen ähnlichen Implementierungen der anderen Sound Systeme, beliebig mit der Haupt API kombiniert werden.

Theorie

Schichten

Die VS API ist die im Moment höchste Schicht in libroar. Sie Abstrahiert mehre darunter liegenden Schichten wie die Simple API und VIO/DSTR.

OOP

Die VS API ist wie fast alles rund um RoarAudio Objekt Orientiert. Sie verwendet primär das so genannte VSS (von engl. "VS State") Objekt das sowohl Steuer-, Daten-, Datei-Verbindung Objekte sowie alle Puffer und Speicher Objekte die intern verwendet werden enthält.

Streaming Modus

Der Streaming Mode ist der native Modus. Hier wird das VS Objeckt (VSS) geöffnet und dann mittels Schreibe- und Lese-Befehlen die Audio Daten zum Server geschickt beziehungsweise von dort abgeholt. Ist man Fertig so wird das VS Objekt wieder geschlossen.

Zum öffnen gibt es zwei Funktionen: roar_vs_new_simple() und roar_vs_new_playback(). Letztere ist lediglich ein Aufruf auf die erstere und übergibt beim Richtungs und Subsystem Parameter (engl. "stream direction") den wert ROAR_DIR_PLAY. Da oft nur Wiedergabe gewünscht ist, ist diese Funktion viel zu finden.

Im zweiten Schritt werden Audio Daten gelesen oder geschrieben. Dies geschieht mittels roar_vs_read() beziehungsweise roar_vs_write().

Im letzten Schritt wird das Objekt wieder freigegeben und die Verbindungen geschlossen. Dies gescheit mittels roar_vs_close().

Sollten Meta Daten oder andere Steuerinformationen (Siehe weiter am Ende des Vortrags) gesetzt werden sollten diese vor dem ersten Aufruf von roar_vs_read() beziehungsweise roar_vs_write() gesetzt werden.

Beispiel:

roar_vs_t * vss = roar_vs_new_simple(server, "MyApp", rate, channels, codec, bits, ROAR_DIR_PLAY, &err);

while (alive) { // main loop...
 // ...
 ret = roar_vs_write(vss, buf, len, &err);
}

ret = roar_vs_close(vss, ROAR_VS_FALSE, &err);

In diesem Beispiel wurde ein Stream zum Server server aufgebaut, Die Audio Parameter finden sich in rate, channels, codec und bits. Er ist zur Wiedergabe (ROAR_DIR_PLAY). Die Variablen ret und err' werden im nächsten Kapitel erläutert.

Der Parameter server kann (und sollte meistens auch) den Wert NULL haben. Dies steht für das verbinden zum Default Server.

Auch ist der Applikationsname (hier: "MyApp") angegeben. Dieser sollte einen Sprechenden Namen für das Produkt beinhalten. Normalerweise das was man auf der Packung oder der CD Hülle in großen Lettern erwartet.

Folgendes sollte nicht verwendet werden:

• Versionen (ggf. noch major releases),
• Datei Namen ("myapp.bin", "myapp.exe"),
• Pfad Namen ("/usr/bin/player").

Auf die Audio Parameter soll hier nicht weiter eingegangen werden als diese Grundlagen Wissen sind den Zeitrahmen sprengen würden.

Der Richtungs und Subsystem Parameter hat im oberen Beispiel den Wert ROAR_DIR_PLAY. Andere Werte sind als Beispiel ROAR_DIR_RECORD, ROAR_DIR_MONITOR oder auch ROAR_DIR_MIDI_IN. Genaueres sollte aus passenden Tabellen entnommen werden.

Der zweite Parameter bei der Funktion roar_vs_close() (hier ROAR_VS_FALSE) gibt an ob beim Schließen des Objekts auch auf Server Seite der Stream direkt beendet werden soll (ROAR_VS_TRUE) oder nicht (ROAR_VS_FALSE). Im Falle das er nicht direkt beendet werden soll (Normalfall) wird noch zu Ende gespielt bis alle Puffer leer sind. Dies macht vor allem bei komprimierten Codecs wie Ogg Vorbis (ROAR_CODEC_OGG_VORBIS) einen unterschied der Teilweise im Sekunden Bereich liegt.

Fehler Behandlung

• Die meisten Aufraufe werfen -1 zurück im Fehlerfall. Ausnahmen sind beispielsweise Funktionen welche einen Pointer zurückgeben. Diese werfen NULL.
• IO Funktionen können "short reads" bzw. "short writes" erzeugen.
• Die Fehlervariable (&err) beinhaltet im Fehlerfall einen Fehler Code. Dieser kann mittels roar_vs_strerr(err) in eine Zeichenkette gewandelt werden.

int err;
ssize_t ret = roar_vs_write(vss, buf, len, &err);
if ( ret == -1 ) {
 fprintf(stderr, "Fehler beim schreiben: %s\n", roar_vs_strerr(err));
} else if ( ret < (ssize_t)len) {
 fprintf(stderr, "\"Short write\", nur %zi von %zu Bytes geschieben\n", ret, len);
}

Datei Modus

Die VS API besitzt einen Datei Modus (engl. "file mode") in dem sie direkt Dateien aber auch Streams abspielen kann. Dazu wird die Verbindung mittels roar_vs_new_from_file() geöffnet. Anschließend wird mittels roar_vs_run() oder roar_vs_iterate() der Datenstrom zum Server geschrieben. Am Schluss wird das Objekt normal mittels roar_vs_close() geschlossen.

Sollten Meta Daten, Lautstärke oder ähnliches gesetzt werden so sollte dies vor dem Aufruf von roar_vs_run() beziehungsweise vor dem ersten Aufruf von roar_vs_iterate() gesehen.

Beispiel:

roar_vs_t * vss = roar_vs_new_from_file(server, "MyApp", filename, &err);
ret = roar_vs_run(vss, &err);
ret = roar_vs_close(vss, ROAR_VS_FALSE, &err);

Im obigen Beispiel wird zum Server server (sollte normalerweise NULL sein) verbunden. Der Klient Name ist "MyApp". Als Dateiname wird filename verwendet. Danach wird roar_vs_run() aufgerufen was bis zum Dateiende (EOF) die Datei abspielt. Am ende wird ganz normal mittels roar_vs_close() die Verbindung geschlossen.

Da roar_vs_run() so lange läuft bis es das Dateiende erreicht oder ein Fehler auftritt ist blockt ist es nicht (trivial) möglich im selben Kontext weitere Dinge parallel aus zu führen. Da viele Programme aber ohne hin einen eigenen Thread für die Tonausgabe verwenden ist dies eine geringe Einschränkung. Für alle anderen Felle gibt es roar_vs_iterate() wie das folgende Beispiel zeigt:

roar_vs_t * vss = roar_vs_new_from_file(server, "MyApp", filename, &err);

while (alive) { /* main loop */
 // ...
 ret = roar_vs_iterate(vss, ROAR_VS_WAIT, &err);
}

ret = roar_vs_close(vss, ROAR_VS_FALSE, &err);

Gepufferter Modus

Viele Applikationen erwarten einen Gepufferten Modus vor zu finden in dem sie einen Ring Puffer mit sehr definiertem zustand vor finden in den sie Arbeiten können. Dieses Vorgehen ist nur mit einem Lokalen Ringpuffer möglich der recht groß ist und viele Nachteile in sich birgt. Aus diesem Grunde wird dieser Modus nicht Empfohlen.

An dieser Stelle soll auch nur Kurz erwähnt sein das dieser Existiert und mit der Funktion roar_vs_buffer() zu steuern ist. Weitere Informationen finden sich in der Dokumentation.

Um nicht weiter zu Verwirren direkt zum Nächsten Kapitel...

Meta Daten

Derzeit stellt die VS API zwei Meta Daten Schnittstellen zur Verfügung: Titel Meta Daten und Stream Rolle.

Titel Meta Daten

Die Titel Meta Daten (Normalerweise nur "Meta Daten) sind Informationen über den Aktuellen Titel: Künstler, Titel, Album, Genre, Version, Titelnummer, RPG, und viele mehr.

Diese werden mit der Funktion roar_vs_meta() gesetzt

struct roar_keyval kv[3] = {
 {"TITEL", "Test Titel"},
 {"ARTIST", "Irgendwer"},
 {"VERSION", "Vortrags Remix"}
};
ret = roar_vs_meta(vss, kv, 3 /* Anzahl der Datensätze */, &err);

Stream Rolle

Die Stream Rolle (engl. "stream role") gibt die Funktion des Streams an: Musik, Video, Ereignisse (z.B. Fehlermeldungs Töne), Spiel, Hintergrund Musik, Telephon,...

Diese wird mit der Funktion roar_vs_role() gesetzt:

ret = roar_vs_role(vss, ROAR_ROLE_MUSIC, &err);

Lautstärkesteuerung

Zur Lautstärkesteuerung stehen in der VS API drei Funktionen zur Verfügung: roar_vs_volume_mono(), roar_vs_volume_stereo() und roar_vs_volume_get().

Die beiden Ersetzen setzen die Lautstärke, jeweils im Mono oder im Stereo Modus. Das heißt sollte eine Datenstrom eine andere Anzahl von Kanälen haben so rechnen diese Funktionen automatisch um.

Die Lautstärke Skala geht vom 0 bis 1 (inklusive).

Im folgenden Beispiel wird die Lautstärke auf 50% (-6dB) eingestellt:

float c = 0.5; /* 50% */
ret = roar_vs_volume_mono(vss, c, &err);

Im zweiten Beispiel wird der Linke Kanal auf 50% (-6dB) und der Rechte Kanal auf 25% (-12dB) eingestellt:

float l = 0.5, r = 0.25;
ret = roar_vs_volume_stereo(vss, l, r, &err);

Die Lautstärke lässt sich mittels roar_vs_volume_get() wie folgt auslesen:

float l, r;
ret = roar_vs_volume_get(vss, &l, &r, &err);

Sollte die Mono-Lautstärke und nicht die L/R-Lautstärke gewünscht sein:

float c = (l + r)/2.0;

Zum Stumm schalten sollte die Lautstärke nicht geändert werden sondern das Mute-Flag verwendet werden (Nächste Folie).

Flags

Aktuell unterstützt die VS die beiden Flags "Mute" und "Pause".

Das Mute Flag schaltet die Ausgabe des Tons ab, der Stream läuft aber weiterhin. Das Flag Pause hält den Stream an so das er später fortgesetzt werden kann.

Die Flags werden mit den Funktionen roar_vs_pause() und roar_vs_mute() gesetzt:

ret = roar_vs_mute(vss, ROAR_VS_TRUE, &err);

Beziehungsweise:

ret = roar_vs_pause(vss, ROAR_VS_TRUE, &err);

Anstatt ROAR_VS_TRUE (zum setzen) kann natuerlich auch ROAR_VS_FALSE (zum rücksetzen) und ROAR_VS_TOGGLE (zum kippen) verwendet werden.

Mittels ROAR_VS_ASK kann der zustand angefragt werden.

Optionales

Nicht Blockender Zugriffsmodus

Wie auf normalen Filehandles in der UNIX Welt kann auch auf VS Objekten ein Nicht-Blockender Modus verwendet werden. Das heißt das Lese- und Schreibbefehle nicht blockieren sondern nur im internen Puffer operieren und somit schneller zurückkehren. Der Nachteil ist das dabei so genannte "short reads" beziehungsweise "short writes" häufiger passieren.

Der Nicht Blockierende Modus kann mittels der Funktion roar_vs_blocking() verwendet werden wie im folgenden Beispiel gezeigt:

ret = roar_vs_blocking(vss, ROAR_VS_TRUE, &err);

Der zweite Parameter gibt dabei an ob der Modus gesetzt werden soll (ROAR_VS_TRUE) oder zurückgesetzt (ROAR_VS_FALSE). Natürlich kann er auch gekippt (ROAR_VS_TOGGLE) oder Abgefragt werden (ROAR_VS_ASK).

Warten auf Stream Ende

Mit der Funktion roar_vs_sync() kann man auf das Ende des Streams warten.

Beispiel:

ret = roar_vs_write(vss, buf, len, &err); // letzter Schreibzugriff
ret = roar_vs_sync(vss, ROAR_VS_WAIT, &err);
// am Stream-Ende
ret = roar_vs_close(vss, ROAR_VS_FALSE, &err);

Es sollte nach dem Aufruf von roar_vs_sync() entweder direkt der Stream geschlossen werden oder erneut geschrieben. In letzterem Fall wird ein Knacken oder ähnliches zu hören sein durch die Unterlaufs bedingte Unterbrechung (engl. "underrun").

Interface zur Haupt API

...