RoarAudio/Programmieren/VS

Aus UUGRN

Die Very Simple API oder auch VS ist eine API die sich an die Simple APIs verschiedener anderer Sound Systeme anlehnt und einen leichten Umstieg ermöglichen soll. Im Sie ist recht stark limitiert. Ihr größtes Limit liegt darin das sie im Normalfall nur einen Stream pro Klient verwalten kann.

Die VS ist vollständig Objekt-Orientiert und kann auch einige der Funktionen die RoarAudio herausstellen bedienen. Sie hat weiterhin Schnittstellen-Funktionen um an die Internen Objekte heran zu kommen und ermöglicht somit mit der normalen API gemischt verwendet zu werden.

Grundsätzlicher Ablauf

Zu Beginn wird ein VS Objekt erzeugt. Dieses ist Bereits mit dem Server verbunden. Nun werden Stream Parameter gesetzt und ein Stream auf dem Server erzeugt. Dies Kann auch in Kombination mit dem erzeugen des Objektes geschehen. Nun können Operationen auf das Objekt angewendet werden. Zum Beispiel können Audio Daten geschrieben werden. Nach dem man fertig ist wird das Objekt wieder Freigegeben und die Verbindung zum Server voll automatisch getrennt.

Fehlerbehandlung

Alle Funktionen verwenden -1 oder NULL zur Fehlerrückgabe. Sie haben einen Parameter namens error welcher dazu genutzt werden kann um einen Fehler Code zu bekommen.

Die Funktion roar_vs_strerr() kann dazu verwendet werden um Lesbare Fehlermeldungen zu erzeugen.

Beispiel

int err;
int ret;

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

if ( ret == -1 ) {
 fprintf(stderr, "Fehler: %s\n", roar_vs_strerr(err));
}

Öffnen einer Verbindung zum Server und eines Streams

Es gibt mehre Arten eine Verbindung zu öffnen. Prinzipiell unterscheiden sich zwei Arten: Ob zu Beginn nur eine Verbindung zum Server hergestellt werden soll, oder bereits ein Stream erzeugt wird. Ersteres kann interessant sein, sollte man erst ein paar Daten mit dem Server mittels der Haupt API austauschen wollen, bevor man den Stream erzeugt.

In diesem Teil soll jedoch nur behandelt werden wie man eine Verbindung mit sofortigem erzeugen deines Streams herstellt. Das Andere verfahren wird später beschreiben.

Zum herstellen einer Verbindung mit sofortiger Erzeugung eines Streams wird die Funktion roar_vs_new_simple() verwendet. Diese erwartet folgende Parameter:

  • Name des Servers (kann NULL sein),
  • Name des Klients (kann NULL sein, sollte aber nicht),
  • Die Sample Rate für den Stream (Übliche werte Schliesen 44100, 48000 und andere ein),
  • Die Anzahl der Kanäle für den Stream (1 für Mono, 2 fuer Stereo, ...),
  • Den Verwendeten Codec (Siehe nachfolgende Tabelle),
  • Die Anzahl der Bits pro Sample (Üblicherweise 8 oder 16),
  • Die Stream Direction (ROAR_DIR_PLAY für Playback),
  • Die Fehlercode Variable.

Der Rückgabewert ist das neue Verbindungs-Objekt oder NULL im Fehlerfall.

Beispiel

roar_vs_t * vss;

vss = roar_vs_new_simple(NULL, "myClient", rate, channels, ROAR_CODEC_DEFAULT, bits, ROAR_DIR_PLAY, &err);

Codecs

RoarAudio kann mehre verschiedene Codecs verwenden. Welche genau unterstützt sind hängt vom Server ab. Die nachfolgende Tabelle zeigt eine Auswahl der möglichen Codecs.

Codec Konstante Codec Name Anmerkungen
ROAR_CODEC_DEFAULT Signed Native PCM
ROAR_CODEC_PCM_x_y PCM
ROAR_CODEC_OGG_VORBIS Ogg Vorbis
ROAR_CODEC_RIFF_WAVE RIFF/WAVE
ROAR_CODEC_AU AU
ROAR_CODEC_ALAW a-Law
ROAR_CODEC_MULAW μ-Law

Schließen der Verbindung

Zum Schließen der Verbindung wird kommt die Funktion roar_vs_close() zum Einsatz. Dieser wird das Verbindungs-Objekt, der Pointer zur Fehlercode Variable sowie der Parameter killit übergeben.

Der Parameter killit kann entweder ROAR_VS_TRUE oder ROAR_VS_FALSE sein. Ist er auf ROAR_VS_TRUE gesetzt wird die Wiedergabe sofort beendet. Ist er auf ROAR_VS_FALSE so wird der verbliebene Puffer (im Klient, Netzwerk und Server) erst zu ende abgespielt. Dies kann im besonderen dann einen Unterschied im Sekunden Bereich machen, sollte die Übertragung einen stark komprimierten Codec einsetzen.

Beispiel

int ret;

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

Schreiben und Lesen von Audio Daten

Zum Schreiben und Lesen von Audio Daten stehen die Funktionen roar_vs_write() und roar_vs_read() zur Verfügung. Diese erhalten folgende Parameter:

  • Das Verbindungs-Objekt,
  • Den Puffer zu den Daten,
  • Die Länge der Daten in Byte,
  • Den Pointer auf die Fehlercode Variable.

Der Rückgabewert ist die Anzahl der wirklich geschriebenen oder gelesenen Bytes oder -1 im Fehlerfalle. Die Anzahl kann kleiner sein als die vorgegebene Länge. Hierbei handelt es sich nicht um einen Fehler sondern nur darum das zum aktuellen Zeitpunkt nicht mehr Daten geschrieben oder gelesen werden können. Ein Programm muss es dann erneut versuchen.

Beispiele

Hier sei ein Programm gezeigt welches zwischen zwei Verbindungen kopiert. Dieses Programm Liest die Fehlercodes nicht aus. Ein reelles Programm sollte dies tun.

ssize_t ret;
char buf[1024];

while ((ret = roar_vs_read(vss0, buf, sizeof(buf), NULL)) != -1) {
 if ( roar_vs_write(vss1, buf, ret, NULL) != ret ) {
  // Short-Write handling.
 }
}

Andere Operationen

...

Interaktion mit der Haupt API

...

Siehe Auch

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/VS” weißt.