RoarAudio PlayList Daemon/Protokoll

Aus UUGRN
< RoarAudio PlayList Daemon
Version vom 24. Mai 2012, 08:14 Uhr von Ph3-der-loewe (Diskussion | Beiträge) (→‎Fehler Codes: +NFPROERR)
(Unterschied) ← Nächstältere Version | Aktuelle Version (Unterschied) | Nächstjüngere Version → (Unterschied)

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

Befehle zur Verbindungs-Steuerung[Bearbeiten]

NOOP[Bearbeiten]

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

QUIT[Bearbeiten]

Dieser Befehl beendet die Verbindung.

HELP[Bearbeiten]

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

SETPLAYLIST[Bearbeiten]

Dieser Befehl Setzt die aktuelle Wiedergabeliste.

Syntax:

 SETPLAYLIST {"Name"|ID}

AUTH[Bearbeiten]

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

UNAUTH[Bearbeiten]

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[Bearbeiten]

PLAY[Bearbeiten]

Dieser Befehl startet den Abspielvorgang.

STOP[Bearbeiten]

Dieser Befehl beendet hält den Abspielvorgang an.

PAUSE[Bearbeiten]

Unterbricht das Abspielen oder setzt es fort.

Syntax:

 PAUSE {TRUE|FALSE|TOGGLE}

NEXT[Bearbeiten]

Dieser Befehl wechselt zum nächsten Titel.

PREV[Bearbeiten]

Dieser Befehl wechselt zum zuletzt gespielten Titel.

ISPLAYING[Bearbeiten]

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

SHOWPLYING[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

SETVOLUME[Bearbeiten]

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[Bearbeiten]

Zeigt die Aktuelle Lautstärke an.

Ausgabe Beispiel:

 VOLUME 65535/65535 100%

Befehle zur Steuerung der Haupt Wiedergabewarteschlagen-Spielliste[Bearbeiten]

LISTQ[Bearbeiten]

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

Syntax:

 LISTQ [{"Name"|ID}]

FLUSHQ[Bearbeiten]

Löscht den Inhalt der Haupt Wiedergabewarteschlagen-Spielliste.

SHOWCUR[Bearbeiten]

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[Bearbeiten]

LISTPLAYLISTS[Bearbeiten]

Listet alle Wiedergabelisten auf.

SHOWLIST[Bearbeiten]

Zeigt die Aktuelle oder eine andere Wiedergabeliste an.

Syntax:

 SHOWLIST [{"Name"|ID}]

ADDPLAYLIST[Bearbeiten]

Fügt eine neue Wiedergabeliste hinzu.

Syntax:

 ADDPLAYLIST "Name"

DELPLAYLIST[Bearbeiten]

Löcht eine Wiedergabeliste.

Syntax:

 DELPLAYLIST [{"Name"|ID}]

FLUSHPLAYLIST[Bearbeiten]

Leert den Inhalt einer Wiedergabeliste.

Syntax:

 FLUSHPLAYLIST [{"Name"|ID}]

SETPARENTLIST[Bearbeiten]

Setzt die Eltern Liste der Aktuellen oder einer anderen Wiedergabeliste.

Syntax:

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

IMPORT[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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

LISTPLE[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

SETPOINTER[Bearbeiten]

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[Bearbeiten]
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[Bearbeiten]

Zeigt alle oder nur den angebenden Wiedergabelistenzeiger an.

Syntax:

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

Befehle zur Permanent Speicherung[Bearbeiten]

STORE[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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[Bearbeiten]

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.