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

{| class="wikitable"
 ! 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
 |-
 |}

== 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:
<pre>
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)
</pre>

{| class="wikitable"
 ! 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 =====
{| class="wikitable"
 ! 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 ==
{{Homepage|roaraudio.keep-cool.org}}

[[Kategorie:RoarAudio]]
[[Kategorie:Software]]
[[Kategorie:Sound]]
{{Stub}}