RoarAudio/Programmieren/VS
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 | Vorzeichenbehaftetes Integer PCM in nativer Byte-Reihenfolge. Dies ist ein Alias auf ROAR_CODEC_PCM_S_y mit y der Byte-Reihenfolge des Klients. |
| ROAR_CODEC_PCM_x_y | PCM | Integer PCM. x kann S oder U sein für Vorzeichen behaftung oder Unvorzeichen behaftung. y ist die Byte-Reihenfolge und kann die werte LE, BE und PDP haben. |
| ROAR_CODEC_OGG_VORBIS | Ogg Vorbis | Der Vorbis Codec in Ogg. Die Parameter rate, bits und channels sollten auf 0 gesetzt werden. |
| ROAR_CODEC_RIFF_WAVE | RIFF/WAVE | Micro$oft .wav-Dateien. Die Parameter rate, bits und channels sollten auf 0 gesetzt werden. |
| ROAR_CODEC_AU | AU | .au-Dateien. Die Parameter rate, bits und channels sollten auf 0 gesetzt werden. |
| ROAR_CODEC_ALAW | a-Law | Der a-Law Codec. Er wird im europäischen ISDN Standard eingesetzt. Der Parameter bits sollte auf 8 gesetzt werden. |
| ROAR_CODEC_MULAW | μ-Law | Der μ-Law Codec. Er wird im US-Amerikanischen ISDN Standard eingesetzt. Der Parameter bits sollte auf 8 gesetzt werden. |
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
Neben den Grundoperationen kann die VS API auch diverse Weitere Operationen durchführen. Diese sollen hier kurtz beschrieben werden.
Syncing
...
Blocking
...
Position und Latenz
...
Pause
...
Mute
...
Lautstärke
...
Meta Daten
Die Funktion roar_vs_meta() wird verwendet um Meta Daten zu setzen. Dies ist stark empfohlen.
Beispiel
int ret;
struct roar_keyval meta[] = {
{"TITLE", "Der Titel des Liedes..."},
{"ARTIST", "Ein Künstler"},
{"VERSION", "Radio Remix"}
};
size_t len = sizeof(meta)/sizeof(*meta); // Länge des meta[]-Arrays in Elementen
ret = roar_vs_meta(vss, meta, len, &err);
Stream Rolle
Die Stream Rolle ist eine logische Gruppierung von Streams die einen bestimmten Zweck erfüllen. Sie wird mittels roar_vs_role() gesetzt.
Beispiel
int ret; ret = roar_vs_role(vss, ROAR_ROLE_MUSIC, &err);
Liste möglicher Rollen
- ROAR_ROLE_UNKNOWN
- ROAR_ROLE_NONE
- ROAR_ROLE_MUSIC
- ROAR_ROLE_VIDEO
- ROAR_ROLE_GAME
- ROAR_ROLE_EVENT
- ROAR_ROLE_BEEP
- ROAR_ROLE_PHONE
- ROAR_ROLE_BACKGROUND_MUSIC
- ROAR_ROLE_VOICE
- ROAR_ROLE_INSTRUMENT
- ROAR_ROLE_RHYTHM
- ROAR_ROLE_CLICK
- ROAR_ROLE_MIXED
Noop
Die Funktion roar_vs_noop() sendet einen NOOP Befehl an den Server. Dieser wird diesen immer mit einem OK beantworten. Diese Funktion kann als Beispiel verwendet werden um den Server zu pingen oder um eine Art Keep Alive durch zu führen. Sie wird selten benötigt.
Beispiel
int ret; ret = roar_vs_noop(vss, &err);
Interaktion mit der Haupt API
...
Siehe Auch
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.
