RoarAudio PlayList Daemon/Protokoll

Auf dieser Seite wird auf das simple Protokoll des RoarAudio PlayList Daemon eingegangen. Andere durch den rpld unterstützte Protokolle werden hier ignoriert. Die Spezifikationen zu diesen sind bei den entsprechenden Herstellern zu finden beziehungsweise zu erfragen.

Rahmen Protokoll

Das Protokoll besteht aus einer Sequenz von Befehl-Antwort-Paaren. Dabei Sendet der Klient einen Befehl als abgeschlossene Zeile (Terminiert mit line feed, 0x0A, '\n') an den Server und dieser Beantwortet dies dann mit einem Datenbereich gefolgt von einer Status Zeile. Der Datenbereich wird durch eine Zeile die ausschließlich aus einem Punkt besteht Beendet. Sollte eine Zeile im Datenbereich vorkommen die ausschließlich aus einem oder Mehren Punkten besteht so wird ein Punkt vor gehängt um Eindeutigkeit der Ende Sequenz zu garantieren.

Die Statuszeile besteht aus drei oder vier Teilen:

* Dem Vorsatz '>',
* dem Fehler Code,
* dem Fehler Text
* und optional einer Fehlerbeschreibung in Klammern ('(...)').

Die Felder sind jeweils dusch Leerzeichen getrennt.

Beispiel:

C: NOOP
S: .
S: > 0 OK

C: HELP
S: Commands:
S:   HELP
S:   NOOP
S:   PLAY
...
S: .
S: > 0 OK

Implementierungen dürfen nur die obigen Zeilenenden senden solten aber auch anderen gängige Zeilenumbrüche Akzeptieren.

Fehler Codes

Folgende Tabelle zeigt die definierten Fehler Codes:

Symbolischer Name	Numerischer Wert	Versionen	Fehler Text	Fehler beschreibung
OK	0	ab 0.1beta0	OK	Der Befehl wurde erfolgreich abgearbeitet.
ERROR	1	ab 0.1beta0	Error	Bei der Abarbeitung des Befehls ist ein Fehler aufgetreten.
INPROC	2	ab 0.1beta0	In Process	Die Abarbeitung wurde wird im Hintergrund fortgesetzt.
YES	3	ab 0.1beta0	Yes	Die Antwort auf die Anfrage ist: Wahr
NO	4	ab 0.1beta0	No	Die Antwort auf die Anfrage ist: Falsch
PROERR	5	ab 0.1beta0	Protocol Error	Es ist ein Protokollfehler aufgetreten. Die Verbindung kann vom Server zurück gesetzt werden.
GOODBYE	6	ab 0.1beta0	GoodBye	Antwort auf den QUIT Befehl. Die Verbindung wird vom Server zurück gesetzt.
NOTPERM	7	ab 0.1rc0	Not Permitted	Die Operation wird verweigert da sie nicht erlaubt ist mit den Rechten des Klienten
NFPROERR	8	ab 0.1rc8	Nicht Fataler Protokollfehler. Normalerweise syntaktischer Fehler.

Befehle

Befehle zur Verbindungs-Steuerung

NOOP

Dieser Befehl führt keine Aktion aus sondern bestätigt nur das die Verbindung noch besteht.

QUIT

Dieser Befehl beendet die Verbindung.

HELP

Dieser Befehl gibt einen Hilfe-Text zu den Befehlen aus.

SETPLAYLIST

Dieser Befehl Setzt die aktuelle Wiedergabeliste.

Syntax:

 SETPLAYLIST {"Name"|ID}

AUTH

 AUTH [TO AUTHLEV {n|"name"}] USING authtype...

UNAUTH

Dieser Befehl setzt das AccessLevel (ACCLEV) auf einen gewünschten Wert herunter.

Syntax:

 UNAUTH [ACCLEV] {BY n|TO {n|"name"}}

Beispiel:

 UNAUTH TO "guest"

Befehle zur Steuerung des Abspielvorgangs

PLAY

Dieser Befehl startet den Abspielvorgang.

STOP

Dieser Befehl beendet hält den Abspielvorgang an.

PAUSE

Unterbricht das Abspielen oder setzt es fort.

Syntax:

 PAUSE {TRUE|FALSE|TOGGLE}

NEXT

Dieser Befehl wechselt zum nächsten Titel.

PREV

Dieser Befehl wechselt zum zuletzt gespielten Titel.

ISPLAYING

Dieser Befehl kann verwendet werden um in Erfahrung zu bringen ob gerade etwas abgespielt wird.

SHOWPLYING

Dieser Befehl zeigt den aktuellen zustand an. Sollte etwas abgespielt werden so werden weitere Daten zurückgegeben:

Beispiel Ausgabe:

STATE RUNNING
LONGGTN long:0xE1D9000000000067
SHORTGTN short:0xE10000BE
UUID uuid:0eafd00b-0b06-4805-a61f-66dc6427b181
META TITLE "Kuschel.FM - Das Kuschelradio!"
MDUC 1
RATE 44100
CHANNELS 2
BITS 16
TIME 196090280 S (2223.246s)

Feldname	Feldbedeutung	Mögliche Werte
STATE	Der aktuelle Abspielstatus.	STOPPED, PAUSE, RUNNING
LONGGTN	Lange Globale Titel Nummer	GTN
SHORTGTN	Kurtze Globale Titel Nummer	GTN
UUID	Eindeutiger Identifikator für den Titel	UUID
META n	Meta Datum des Types n	Zeichenkette
MDUC	Meta Daten Aktualisierungs Zähler	Zahl
RATE	Abtastrate	Zahl
CHANNELS	Kanal Anzahl	Zahl
BITS	Abtastbreite	Zahl
TIME	Zeit	Zahl in Abtastwerten und in Sekunden

SHOWIDENTIFIER

Zeigt eine Zeichenkette an welche den aktuell abgespielten Titel auf der nächst tieferen Ebene repräsentierte. Dabei kann es sich um eine RoarAudio StreamID, eine Geräte Datei, eine UUID oder ein beliebig geformte andere Zeichenkette handeln. Es ist nicht Garantiert das diese keine Stimmbrüche beinhaltet oder 7-Bit Sauber ist. Die Bedeutung ist nicht weiter im Protokoll Spezifiziert und wird ausschließlich vom Daemon weitergereicht.

Syntax:

 SHOWIDENTIFIER

Befehle der Lautstärke Steuerung

SETVOLUME

Setzt die Lautstärke.

Syntax:

 SETVOLUME new-volume

new-volume kann entweder im Format 'n%' mit n einem Prozentualen Wert von 0..100 sein, oder ein planer Integer im Bereich 0..65535.

SHOWVOLUME

Zeigt die Aktuelle Lautstärke an.

Ausgabe Beispiel:

 VOLUME 65535/65535 100%

Befehle zur Steuerung der Haupt Wiedergabewarteschlagen-Spielliste

LISTQ

Zeigt den Inhalt der Haupt Wiedergabewarteschlagen-Spielliste oder einer anderen Wiedergabeliste an.

Syntax:

 LISTQ [{"Name"|ID}]

FLUSHQ

Löscht den Inhalt der Haupt Wiedergabewarteschlagen-Spielliste.

SHOWCUR

Dieser Befehlt Zeigt den obersten Eintrag in der Haupt Wiedergabewarteschlagen-Spielliste an. Zur Anzeige was gerade gespielt wird ist dieser Befehl nicht geeignet. Dazu muss SHOWPLYING verwendet werden.

Befehle zur Wiedergabelisten Verwaltung

LISTPLAYLISTS

Listet alle Wiedergabelisten auf.

SHOWLIST

Zeigt die Aktuelle oder eine andere Wiedergabeliste an.

Syntax:

 SHOWLIST [{"Name"|ID}]

ADDPLAYLIST

Fügt eine neue Wiedergabeliste hinzu.

Syntax:

 ADDPLAYLIST "Name"

DELPLAYLIST

Löcht eine Wiedergabeliste.

Syntax:

 DELPLAYLIST [{"Name"|ID}]

FLUSHPLAYLIST

Leert den Inhalt einer Wiedergabeliste.

Syntax:

 FLUSHPLAYLIST [{"Name"|ID}]

SETPARENTLIST

Setzt die Eltern Liste der Aktuellen oder einer anderen Wiedergabeliste.

Syntax:

 SETPARENTLIST [OF {"Name"|ID}] [TO] {"Name"|ID}

IMPORT

Importiert eine Wiedergabeliste aus einer Datei oder vom Aktuellen Datenstrom in die Aktuelle oder eine andere Wiedergabeliste.

Syntax:

 IMPORT [{"Name"|ID}] FROM {STDIN|"Filename"} [AS {RPLD|PLS|M3U|VCLT|PLAIN}]

EXPORT

Exportiert die Aktuelle oder eine andere Wiedergabeliste in eine Datei oder gibt sie über den aktuellen Datenstrom aus.

Syntax:

 EXPORT [{"Name"|ID}] TO {STDOUT|"Filename"} [AS {RPLD|PLS|M3U|VCLT|PLAIN}]

Befehle zur Wiedergabelisten Eintrags Verwaltung

Bei den folgenden Befehlen steht PLE immer für "PlayList Entry" (Wiedergabelisten Eintrag).

LISTPLE

Zeigt alle Einträge in einer Wiedergabeliste an. Es werden entweder wie Einträge der aktuellen Liste oder der angegebenen Angezeigt.

Syntax:

 LISTPLE [{"Name"|ID}]

SHOWPLE

Dieser Befehl zeigt einen bestimmten Eintrag an. Es wird entweder in der aktuellen Liste, in der angegebenen oder in allen Listen gesucht.

Syntax:

 SHOWPLE {long:0xLongID|0xLongID|short:0xShortID|uuid:UUID|pointer:name} [FROM {"Name"|ID|ANY}]

COPYPLE

Dieser Befehl kopiert einen Eintrag aus der aktuellen, einer angegebenen Liste oder einen aus allen Listen gesuchten Eintrag in eine andere Liste. Eine Position an welcher er in der neuen Liste stehen soll kann optional angegeben werden. Der neue Eintrag erhält eine neue Global Track Number sowie Short Global Track Number.

Syntax:

 COPYPLE {long:0xLongID|0xLongID|short:0xShortID|uuid:UUID|pointer:name} [FROM {"Name"|ID|ANY}] TO {"Name"|ID} [AT POSITION]

MOVEPLE

Gleich der Funktion COPYPLE nur das diese Funktion den Eintrag nicht kopiert sondern verschiebt. Die Global Track Number sowie Short Global Track Number bleibt erhalten.

Syntax:

 MOVEPLE {long:0xLongID|0xLongID|short:0xShortID|uuid:UUID|pointer:name} [FROM {"Name"|ID|ANY}] TO {"Name"|ID} [AT POSITION]

DELPLE

Diese Funktion löscht einen Eintrag aus der aktuellen oder einer angegebenen Liste.

Syntax:

 DELPLE {long:0xLongID|0xLongID|short:0xShortID|uuid:UUID|pointer:name} [FROM {"Name"|ID}]

QUEUEPLE

Dieser Befehl ist eine Kurzform des COPYPLE Befehls bei dem die Ziehlliste immer die Haupt Wiedergabewarteschlagen-Spielliste.

Syntax:

 QUEUEPLE {long:0xLongID|0xLongID|short:0xShortID|uuid:UUID|pointer:name} [FROM {"Name"|ID|ANY}] [AT POSITION]

Befehle zur Zeigerverwaltung

SETPOINTER

Setzt den angegebenen Wiedergabelistenzeiger auf einen angegebenen Wiedergabelisten Eintrag.

Syntax:

 SETPOINTER {CURRENT|DEFAULT|STARTUP|TEMP} {long:0xLongID|0xLongID|short:0xShortID|uuid:UUID|pointer:name} [FROM {"Name"|ID|ANY}]

Bedeutungen der Einzelnen Zeiger

Zeigername	Gültigkeit	Zeiger Beschreibung
CURRENT	Global	Sollte die Haupt Wiedergabewarteschlagen-Spielliste leer laufen so wird der Titel auf den dieser Zeiger verweist automatisch in die Spielliste kopiert und dieser Zeiger einen Eintrag weiter geschoben in der Wiedergabeliste in der sich der Eintrag auf den er Zeigt befindet. Auf diese Weise kann eine Spiele alles ab hier Funktion implementiert werden wie sie viele andere Wiedergabe-Programme besitzen.
DEFAULT	Global	Sollte der CURRENT-Zeiger bei einer Weiterschiebe-Operation an das Ende der Wiedergabeliste stoßen so wird er erneut mit dem Inhalt dieses Zeigers initialisiert. Auf diese weise kann ein Wenn am Ende dann beginn vom Neuen Funktion wie es viele Wiedergabe-Programme besitzen implementiert werden. Diese Zeiger Logik kann aber auch zur Implementierung höheren Funktionen verwendet werden, wie dem automatischen Wechsel zwischen verschiedenen Listen.
STARTUP	Global	Der Wiedergabelisten Eintrag auf den dieser Zeiger verweist wird beim Starten des Daemons automatisch abgespielt. Dies gescheit bevor die normale Abarbeitung der restlichen Titel in der Haupt Wiedergabewarteschlagen-Spielliste beginnt.
TEMP	Klient Verbindung	Dieser Zeiger ist rein für die Benutzung in einer Klient Applikation bestimmt. Diese könnte ihn zum Beispiel auf den Aktuell in einem GUI ausgewählten Listeneintrag verwiesen lassen.

SHOWPOINTER

Zeigt alle oder nur den angebenden Wiedergabelistenzeiger an.

Syntax:

 SHOWPOINTER [{CURRENT|DEFAULT|STARTUP|TEMP}]

Befehle zur Permanent Speicherung

STORE

Dieser Befehl lässt den Daemon seinen Aktuellen Zustand Speichern. Dieser kann zum Beispiel vor dem Beenden genutzt werden um den zustand dann wiederherstellen zu können beim nächsten Start. Je nach Parameter wird dieser Befehl vom Daemon beim Beenden eigenständig durchgeführt.

Syntax:

 STORE

RESTORE

Stellt den Zustand wie er mit STORE gespeichert wurde wieder her. Dies kann als Beispiel beim Starten des Daemons verwendet werden um den Zustand wieder her zu stellen der beim beenden herrschte. Je nach Parameter wird dieser Befehl vom Daemon selbstständig beim Starten ausgeführt.

Wichtig: Ein mehrfaches verwenden dieses Befehls kann zu Duplikaten führen.

Syntax:

 RESTORE

Veraltete Befehle

Die folgenden Befehle sind veraltet. Sie werden mit Version 0.1.0 voraussichtlich entfernt werden. Sie sollten auf keinen Fall Verwendung finden.

Syntax:

 ADD2Q entry
 DELFQ identifier

Andere Befehle und geplante Befehle

Die folgenden Befehle sind in diesem Dokument nicht beschreiben, oder noch in Planung. Sie sollten aktuell nicht verwendet werden.

 SEARCHPLE {"search string"|0xdiscid|uuid} [{AS|IN} {ALL|TITLE|ARTIST|VERSION|FILENAME|DISCID|UUID|TAG:"Tagname"}] [FROM {"Name"|ID|ANY}]
 UPDATE [{"Name"|ID|ANY}] {TO|FROM} {STDIN|STDOUT|"Filename"} [AS {RPLD|PLS|M3U|VCLT|XSPF|PLAIN}] USING {ALL|TITLE|ARTIST|VERSION|FILENAME|DISCID|UUID|TAG:"Tagname"} [AND ...] [POLICY {DEFAULT|OLD|NEW} {KEEP|DELETE}]

Weblinks

Offizielle Webpräsenz „RoarAudio PlayList Daemon/Protokoll”

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 PlayList Daemon/Protokoll” weißt.