Bearbeiten von „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.

{| class="wikitable"
 ! 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
 | &mu;-Law
 | Der &mu;-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 ===
Die normale Betriebsart für das Schreiben und Lesen von Streams ist ''Blocking''. Das heißt, dass wenn man zu schnell schreibt oder liest der Schreib- oder Lesebefehl ''blockiert'' bis wieder genug Puffer oder Daten verfügbar ist. Dies dient dazu eine einfache Flusskontrolle zu haben. Für viele einfache Applikationen ist dies ausreichend. Mansche Applikationen benötigen es aber dass sie nicht an solchen Operationen Zwangs-Pausiert werden. Um dies zu unterbinden kann man in den so genannten ''Non-Blocking'' Modus gehen. In diesem Fall kehren die Ein-/Ausgabefunktionen unmittelbar zurück, auch wenn kein Puffer oder keine Daten verfügbar sind.

Die Funktion ''roar_vs_blocking()'' Kann verwendet werden um den Modus zu setzen. Die Funktion erwartet, neben Verbindungs-Objekt und Fehlercode Pointer, einen Wahrheitswert der den neuen Zustand angibt. Dieser kann entweder ROAR_VS_TRUE, ROAR_VS_FALSE, ROAR_VS_TOGGLE oder ROAR_VS_ASK sein.

Als Rückgabewert erhält man den alten Modus (ROAR_VS_TRUE für Blockend, ROAR_VS_FALSE für nicht blockend) oder -1 im Fehlerfall zurück.

==== Beispiel ====
 int old;
 
 old = roar_vs_blocking(vss, ROAR_VS_FALSE, &err);

=== Position und Latenz ===
...

=== Pause ===
Mit der Funktion ''roar_vs_pause()'' Kann man den Pause Status des Streams ändern. Diese Funktion erwartet folgende Parameter:

* Verbinungs-Objekt,
* Neuer Wert,
* Pointer auf Fehlercode Variable.

Als Rückgabewert bekommt man den Alten Wert oder -1 im Fehlerfall.

Als neuer Wert kommen folgende mögliche Werte in Frage:
; ROAR_VS_TRUE
: Setzt das Pause Flag.
; ROAR_VS_FALSE
: Rücksetzt das Pause Flag.
; ROAR_VS_TOGGLE
: Wirft das Pause Flag um. Dies ist die empfohlene Verwendung.
; ROAR_VS_ASK
: Fragt nur den Aktuellen wert an.

==== Beispiel ====
 int old;
 
 old = roar_vs_pause(vss, ROAR_VS_TOGGLE, &err);

=== Mute ===
Bei RoarAudio gibt es neben der Lautstärkeregelung ein getrenntes Mute Flag. Dies kann mit der Funktion ''roar_vs_mute()'' Beeinflusst werden. Die Funktion ''roar_vs_mute()'' funktioniert exakt wie die Funktion ''roar_vs_pause()'' mit der Ausnahme das sie auf dem Mute Flag operiert.

==== Beispiel ====
 int old;
 
 old = roar_vs_mute(vss, ROAR_VS_TOGGLE, &err);

=== Lautstärke ===
Die Lautstärke des Streams kann sowohl gelesen als auch gesetzt werden. Hier soll beides Behandelt werden.

die VS API verwendet native floats zur darstellung der Lautstärke. Der Wertebereich ist 0 (Signal wird komplett ausgeblendet. Sollte jedoch nicht verwendet werden um eine Mute Funktion zu implementieren) bis 1 (Volle Signalstärke).

Gesetzt werden kann die Lautstärke entweder als Einkanal Wert oder als Stereo Wert. Die Funktion ''roar_vs_volume_mono()'' kann verwendet werden um sie als Einkanal Wert zu setzen. Diese Funktion erwartet neben dem Verbindungs-Objekt und dem Fehlerocode Pointer nur noch die neue Lautstärke.

Die Funktion ''roar_vs_volume_stereo()'' kann dazu verwendet werden den Wert als Stereo Wert zu setzen. Sie verwendet zwei Lautstärke Parameter. Einen für den linken und einen für den rechten Kanal.

Zum lesen kommt die Funktion ''roar_vs_volume_get()'' zum Einsatz. Diese erwartet, neben Verbindungs-Objekt und Fehlerocode Pointer, zwei Pointer, einen für den linken und einen für den rechten Kanal.

Möchte man nur eine Einkanal Information über die Lautstärke erfahren so kann man folgende Formel benutzen:
<math>c = \frac{l + r}{2}</math>

==== Beispiele ====
 float c, l, r;
 int ret;
 
 c   = 0.5;
 ret = roar_vs_volume_mono(vss, c, &err);
 
 l = 0.8;
 r = 0.2;
 ret = roar_vs_volume_stereo(vss, l, r, &err);
 
 ret = roar_vs_volume_get(vss, &l, &r, &err);
 c = (l + r)/2;

=== 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
: Die Funktion des Streams ist unbekannt. Dies ist der default.
; ROAR_ROLE_NONE
: (Sollte nicht verwendet werden)
; ROAR_ROLE_MUSIC
: Es handelt sich um Musik
; ROAR_ROLE_VIDEO
: Es handelt sich um die Audio Spur zu einem Video
; ROAR_ROLE_GAME
: Es Handelt sich um die Audio Spur eines Spiels
; ROAR_ROLE_EVENT
: Es handelt sich um ein Geräusch das zum Beispiel durch eine Fehler- oder Warnmeldung erzeugt wird.  
; ROAR_ROLE_BEEP
: Es Handelt sich um ein Notify Beep (Sollte ehr nicht verwendet werden).
; ROAR_ROLE_PHONE
: Es Handelt sich um eine Echtzeit Sparchübertragung wie etwa einem Telephon.
; ROAR_ROLE_BACKGROUND_MUSIC
: Es Handelt sich um Hintergrund Musik. Man denke etwa an Kaufhäuser in denen leise Radio läuft.
; ROAR_ROLE_VOICE
: Es handelt sich um eine Sprach Spur. Zum Beispiel eine Ansage oder ein Sänger.
; ROAR_ROLE_INSTRUMENT
: Es Handelt sich um ein Instrument.
; ROAR_ROLE_RHYTHM
: Es Handelt sich um ein Rhythmus-Instrument.
; ROAR_ROLE_CLICK
: Es handelt sich um einen ''Click-Track''.
; ROAR_ROLE_MIXED
: Es Handelt sich um bereits aus mehren Quellen vorgemischtes. (Dies wird in aller Regel nur verwendet wenn mehre Sound System mit einander Verbunden werden).

=== 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 ''[[ping|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 ==
Dieser Teil soll nur die Grundlagen der Interaktion mit der Haupt API erläutern. Die Verwendung dieser soll hier nicht beschreiben werden da dies viel zu umfangreich für dieses Dokument währe.

=== Zugriff auf das Connection-, das Stream- und das VIO-Objekt ===
Wie auch unter Verwendung der Haupt API befindet sich im inneren des VS Verbindungs-Objekts eine Connection-, ein Stream- und ein VIO-Objekt. Auf diese kann man wie im folgenden Beispiel gezeigt mittels der Funktionen ''roar_vs_connection_obj()'', ''roar_vs_stream_obj()'' und ''roar_vs_vio_obj()'' zugreifen.

==== Beispiele ====
 struct roar_connection * con;
 struct roar_stream     * stream;
 struct roar_vio_calls  * vio;
 
 con    = roar_vs_connection_obj(vss, &err);
 stream = roar_vs_stream_obj(vss, &err);
 vio    = roar_vs_vio_obj(vss, &err);

=== Verwenden einer bereits offenen Verbindung zu einem Server ===
Sollte bereits eine Verbindung bestehen kann das vorhandene Connection-Objekt verwendet werden um VS Verbindungs-Objekte davon zu erzeugen. Wichtig hierbei ist das bei trennen der Verbindung zu erst alle VS Verbindungs-Objekte getrennt werden müssen und danach erst das Connection-Objekt.

Das Vorgehen ein Connection-Objekt kann als Beispiel dann sinnvoll sein, sollten vielen VS Verbindungs-Objekte benötigt werden um das ständige Neu verbinden zu unterdrücken. Dies reduziert auch deutlich die möglichen Fehler.

Zur Verwendung einer externen Verbindung wird die Funktion ''roar_vs_new_from_con()'' verwendet. Diese benötigt als Parameter lediglich das Connection-Objekt und den Fehlercode pointer.

Es wird das neue Verbindungs-Objekt oder NULL zurück gegeben.

Ein Stream muss anschließend wie im folgenden gezeigt mittels ''roar_vs_stream()'' erzeugt werden.

==== Beispiel ====
 roar_vs_t * vss;
 
 vss = roar_vs_new_from_con(con, &err);

=== Verwendung von VS Verbindungs-Objekts mit nachträglicher Stream Erzeugung ===
...

== Siehe Auch ==
* [[RoarAudio]]

[[Kategorie:RoarAudio]]
[[Kategorie:Software]]
[[Kategorie:Sound]]
[[Kategorie:Programmierung]]
{{Stub}}
@@ Zeile 287: / Zeile 287: @@
 === Verwendung von VS Verbindungs-Objekts mit nachträglicher Stream Erzeugung ===
-Ein VS Verbindungs-Objekt muss nicht von Anfang an mit einem Stream verbunden sein. Dies kann als Beispiel dann interessant sein sollte man mittels Haupt API weitere Parameter mit dem Server ab prüfen wollen bevor man den Stream erzeugt. Auch kann man so einen zweiten Versuch starten einen Stream zu öffnen (mit anderen Parametern) sollte der Server den Stream mit den gewünschten Parametern nicht annehmen ohne neu Verbinden zu müssen.
+...
-Zu erst muss dazu ein Nicht mit einem Stream verbundenes Verbinungs-Objekt erzeugt werden. Dies kann entweder mittels der oben beschriebenen Funktion ''roar_vs_new_from_con()'' oder mittels der Funktion ''roar_vs_new()'' geschehen.
-Im Gegensatz zu ''roar_vs_new_from_con()'' erzeugt ''roar_vs_new()'' selbstständig eine Verbindung zum Server. ''roar_vs_new()'' erwartet um dies zu tun drei Parameter: Die Adresse des Servers (oder NULL um Defaults zu verwenden), den Namen unseres Klienten und den Fehlercode Pointer. Siehe hierzu auch das Beispiel am ende dieses Teils.
-Um nun einen Stream zu erzeugen und zu Verbinden wird die Funktion ''roar_vs_stream()'' verwendet. Diese benötigt, neben dem Verbindungs-Objekt und dem Fehlercode Pointer, das Audio-Informations Struct und die Angabe der Stream Direction. Sollte diese Funktion Fehlschlagen ist es möglich erneut zu versuchen einen Stream (mit anderen Parametern) zu verbinden. Ausgenommen hiervon ist der Fall, dass das Objekt bereits verbunden ist da in diesem Fall es nicht sinnvoll ist diese Funktion auf zu rufen.
-==== Beispiele ====
- roar_vs_t * vss;
- struct roar_audio_info info;
- int ret;
- info.bits     = 16;
- info.rate     = 44100;
- info.channels = 2;
- info.codec    = ROAR_CODEC_DEFAULT;
- vss = roar_vs_new(NULL, "MyApp", &err);
- // Fehler hier Behandeln.
- ret = roar_vs_stream(vss, &info, ROAR_DIR_PLAY, &err);
 == Siehe Auch ==