# &amarok;'s fortgeschrittene Funktionen

## Tastenkürzel

&amarok; benutzt wie alle anderen Programme Tastenkürzel. Unten finden Sie eine Liste dieser Kürzel und ihre Funktion. Die globalen Tastenkürzel können Sie einrichten, indem Sie mit der rechten Maustaste in das Player-Fenster klicken und Globale Tastenkürzel einrichten... auswählen. Die &amarok;-spezifischen Tastenkürzel können Sie einrichten, indem Sie mit der rechten Maustaste in das Player-Fenster klicken und Kurzbefehle festlegen... auswählen.

Sie können eventuell vorhandene Multimedia-Tasten so einrichten, dass sie als &amarok;-Kurzbefehle funktionieren. Dadurch machen Sie Ihre Tastatur zum &amarok;-Kontrollzentrum.

Die globalen Tastenkürzel sind:

Tastenkombination | Funktion
--- | ---
WinX | Wiedergabe
WinC | Pause
WinV | Stopp
WinB | Nächstes Stück
WinZ | Voriges Stück
WinNum_Plus | Lautstärke erhöhen
WinNum_Minus | Lautstärke senken
WinShiftNum_Plus | Vorwärts suchen
WinShiftNum_Minus | Rückwärts suchen
WinA | Hinzufügen
WinP | Wiedergabeliste anzeigen/ausblenden
WinO | OSD anzeigen
WinM | Stumm schalten

Die &amarok;-spezifischen Kurzbefehle sind:

Tastenkombination | Funktion
--- | ---
StrgC | Kopieren
StrgNum_Eingabe | Zum aktuellen Stück springen
StrgD | Ausgewählte Stücke in die Warteschlange einstellen
StrgQ | Beenden
StrgShiftZ | Wiederholen
StrgS | Wiedergabeliste speichern
StrgA | Alles auswählen
StrgM | Blendet die Menüleiste ein/aus.
StrgH | Zufallsmodus
StrgZ | Rückgängig

Die Kurzbefehle für den Wiedergabelisten-Browser sind:

Tastenkombination | Funktion
--- | ---
Leertaste | Wiedergabeliste laden
F2 | Wiedergabeliste umbenennen
Rücktaste | Wiedergabeliste entfernen

## Die DCOP-Schnittstelle

Mit der DCOP-Schnittstelle steht Ihnen ein einfacher Weg zur Verfügung, &amarok; mit eigenen Skripten anzupassen.

Die DCOP-Schnittstelle von amaroK hat einige generische Funktionen, die zumeist auch in anderen KDE-Programmen zu finden sind. Dieser Abschnitt besteht aus zwei Teilen und soll nur die nicht-generischen DCOP-Funktionen des Players und der Wiedergabeliste beschreiben. Ein Beispielaufruf für die DCOP-Funktion Pause wäre:

&percnt;dcop amarok player pause

### dcop amarok collection

DCOP-Aufruf | Funktion
--- | ---
query | Die Funktion query ermöglicht eine direkte Abfrage von amaroKs Musik-Datenbank.
scanCollection | Die Funktion scanCollection führt ein manuelles Erfassen der Sammlung durch.
scanCollectionChanges | Die Funktion scanCollectionChanges führt ein manuelles Erfassen der Änderungen an Ihrer Sammlung durch.
similarArtists | Die Funktion similarArtists gibt ähnliche Interpreten des aktuell laufenden Stücks zurück.
totalAlbums | Die Funktion totalAlbums gibt die Gesamtzahl der Alben in der Sammlung zurück.
totalArtists | Die Funktion totalArtists gibt die Gesamtzahl der Interpreten in der Sammlung zurück.
totalCompilations | Die Funktion totalCompilations gibt die Gesamtzahl der Zusammenstellungen in der Sammlung zurück.
totalGenres | Die Funktion totalGenres gibt die Gesamtzahl der Genre in der Sammlung zurück.
totalTracks | Die Funktion totalTracks gibt die Gesamtzahl der Stücke in der Sammlung zurück.

### dcop amarok player

DCOP-Aufruf | Funktion
--- | ---
album | Die Funktion album gibt das Album des aktuell laufenden Stücks zurück.
artist | Die Funktion artist gibt den Interpret des aktuell laufenden Stücks zurück.
bitrate | Die Funktion bitrate gibt die Bitrate des aktuell laufenden Stücks zurück.
comment | Die Funktion comment gibt den Kommentar zum aktuell laufenden Stück zurück.
coverImage | Die Funktion coverImage gibt die Adresse zu dem Cover-Bild des aktuell laufenden Stücks zurück.
currentTime | Die Funktion currentTime gibt die Abspiel-Position (mm:ss) des aktuell laufenden Stücks zurück.
encodedURL | Die Funktion encodedURL gibt die URL des aktuell laufenden Stücks zurück. Leerzeichen werden kodiert.
engine | Die Funktion engine gibt das derzeit verwendete Modul für die Audio-Ausgabe zurück.
genre | Die Funktion genre gibt das Genre des aktuell laufenden Stücks zurück.
lyrics | Die Funktion lyrics gibt den zwischengespeicherten Text des aktuell laufenden Stücks zurück.
lyricsByPath | Die Funktion lyricsByPath gibt den zwischengespeicherten Text des Stücks mit dem angegebenen Pfad zurück.
nowPlaying | Die Funktion nowPlaying gibt Interpret - Titel des aktuell laufenden Stücks zurück. Falls eines der beiden id3-Tags fehlt, wird nur Interpret bzw. Titel zurückgegeben (ohne den Bindestrich -).
path | Die Funktion path gibt den Dateisystempfad des aktuell laufenden Stücks zurück.
setContextStyle | Die Funktion setContextStyle stellt den Stil des Kontext-Browsers um. Übergeben Sie als Parameter den Namen des gewünschten Stils.
title | Die Funktion title gibt den Titel des aktuell laufenden Stücks zurück.
totalTime | Die Funktion totalTime gibt die Länge des aktuell laufenden Stücks zurück (mm:ss).
track | Die Funktion track gibt die Stücknummer des aktuell laufenden Stücks zurück.
year | Die Funktion year gibt das Jahr des aktuell laufenden Stücks zurück.
dynamicModeStatus | Die Funktion dynamicModeStatus gibt true zurück, wenn der dynamische Modus aktiviert ist. Ansonsten wird false zurückgegeben.
equalizerEnabled | Die Funktion equalizerEnabled gibt true zurück, wenn der Equalizer aktiviert ist. Ansonsten wird false zurückgegeben.
isPlaying | Die Funktion isPlaying gibt true zurück, wenn die Wiedergabe gerade läuft. Ansonsten wird false zurückgegeben.
randomModeStatus | Die Funktion randomModeStatus gibt den Status des Zufallsmodus zurück. Der Rückgabewert ist true oder false.
repeatPlaylistStatus | Die Funktion repeatPlaylistStatus gibt true zurück, wenn Wiedergabeliste wiederholen aktiviert ist. Ansonsten wird false zurückgegeben.
repeatTrackStatus | Die Funktion repeatTrackStatus gibt den Status der Funktion Stück wiederholen zurück. Der Wert ist true oder false.
getVolume | Die Funktion getVolume gibt die aktuelle Lautstärke zurück (ein Wert zwischen 0 und 100).
sampleRate | Die Funktion sampleRate gibt die Abtastrate des aktuell laufenden Stücks zurück.
score | Die Funktion score gibt die Bewertung zu dem aktuellen Stück zurück.
setLyricsByPath | Die Funktion setLyricsByPath legt den Text des Stücks mit dem angegebenen Pfad fest. Verwenden Sie den Aufruf lyrics, um ein paar Beispiele für korrekte HTML-Formatierung zu sehen.
status | Die Funktion status gibt den Status des Modules für Audio-Ausgabe zurück. 2 steht für Wiedergabe, 1 für Pause und 0 für Ruhezustand.
trackCurrentTime | Die Funktion trackCurrentTime gibt die abgelaufene Spielzeit des aktuellen Stücks in Sekunden zurück.
trackPlayCounter | Die Funktion trackPlayCounter gibt zurück, wie oft das aktuelle Stück bereits abgespielt wurde.
trackTotalTime | Die Funktion trackTotalTime gibt die Gesamtspielzeit des aktuell laufenden Stücks in Sekunden zurück.
configEqualizer | Die Funktion configEqualizer öffnet den Einrichtungsdialog des Equalizers.
enableDynamicMode | Die Funktion enableDynamicMode wird benutzt, um den dynamischen Modus ein-/auszuschalten. 0 bedeutet "ausschalten" und 1 bedeutet "einschalten".
enableOSD | Die Funktion enableOSD kann zum Aktivieren und Deaktivieren des On-Screen-Display benutzt werden.
enableRandomMode | Die Funktion enableRandomMode wird benutzt, um den Zufallsmodus ein-/auszuschalten. 0 bedeutet "ausschalten" und 1 bedeutet "einschalten".
enableRepeatPlaylist | Die Funktion enableRepeatPlaylist wird benutzt, um Wiedergabeliste wiederholen ein-/auszuschalten. 0 bedeutet "ausschalten" und 1 bedeutet "einschalten".
enableRepeatTrack | Die Funktion enableRepeatTrack wird benutzt, um Stück wiederholen ein-/auszuschalten. 0 bedeutet "ausschalten" und 1 bedeutet "einschalten".
mute | Die Funktion mute wird benutzt, um das aktuell laufende Stück Stumm zu schalten bzw. die Stummschaltung wieder aufzuheben.
next | Die Funktion next bewirkt einen Sprung zum nächsten Stück.
pause | Die Funktion pause hält die Wiedergabe des aktuell laufenden Stücks an.
play | Die Funktion play startet die Wiedergabe an der Stelle, wo sie zuletzt gestoppt wurde.
playPause | Die Funktion playPause startet die Wiedergabe, falls sie gestoppt ist, oder hält die Wiedergabe an, falls sie gerade läuft.
prev | Die Funktion prev bewirkt einen Sprung zum vorigen Stück.
seek | Die Funktin seek wird zum Anspielen einer bestimmten Position in einem Stück verwendet. Geben Sie die Position in Sekunden an.
seekRelative | Die Funktin seekRelative wird zum Abspielen einer zur aktuellen Spielzeit relativen Position in einem Stück verwendet. Geben Sie die Position in Sekunden an.
setEqualizer | Die Funktion setEqualizer verwendet elf durch Leerzeichen getrennte Integerzahlen um die Werte des Equalizers einzustellen. Für jeden Regler können Sie einen Wert zwischen -255 als kleinsten und 255 als höchsten Wert angeben. Die erste Zahl stellt den Regler für Vorverstärkung ein, die verbleibenden 10 stellen die Frequenzregler von 60Hz bis 16KHz ein.
setEqualizerEnabled | Die Funktion setEqualizerEnabled kann zum Aktivieren und Deaktivieren des Equalizer benutzt werden. Als Argument muss true oder false übergeben werden.
setScore | Die Funktion setScore stellt die Bewertung des aktuellen Stücks auf den angegebenen Wert ein (0-100).
setScoreByPath | Die Funktion setScoreByPath stellt die Bewertung des angegebenen Stücks auf den angegebenen Wert ein (0-100).
setVolume | Die Funktion setVolume stellt die Lautstärke auf den angegebenen Wert ein (0-100).
showBrowser | Die Funktion showBrowser zeigt einen Browser im Wiedergabelisten-Fenster an. Gültige Browsertypen sind context, collection, playlist, media und file.
showOSD | Die Funktion showOSD zeigt das On-Screen-Display mit den Informationen zum aktuellen Stück an.
stop | Die Funktion stop stoppt die Wiedergabe, falls sie gerade läuft.
volumeDown | Die Funktion volumeDown senkt die Lautstärke um einen Schritt.
volumeUp | Die Funktion volumeUp erhöht die Lautstärke um einen Schritt.

### dcop amarok playlist

DCOP-Aufruf | Funktion
--- | ---
saveCurrentPlaylist | Die Funktion saveCurrentPlaylist speicher die aktuelle Wiedergabeliste unter ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | Die Funktion getActiveIndex gibt einen Integerwert für die Position des aktuellen Stücks in der Wiedergabeliste zurück.
getTotalTrackCount | Die Funktion getTotalTrackCount gibt die Gesamtzahl der Stücke in der Wiedergabeliste zurück.
addMedia | Die Funktion addMedia wird benutzt, um der Wiedergabeliste einzelne Dateien hinzuzufügen.
addMediaList | Die Funktion addMediaList wird benutzt, um der Wiedergabeliste mehrere Dateien hinzuzufügen.
clearPlaylist | Die Funktion clearPlaylist wird benutzt, um die gesamte Wiedergabeliste zu leeren.
playByIndex | Die Funktion playByIndex startet die Wiedergabe eines Stückes mit der Angabe der Position in der Wiedergabeliste.
playMedia | Die Funktion playMedia startet die Wiedergabe eines über eine KURL angegebenen Stückes.
popupMessage | Die Funktion popupMessage öffnet eine Kurzinfo in der Wiedergabeliste. Die Kurzinfo wird der Funktion als QString übergeben.
repopulate | Die Funktion repopulate füllt die Wiedergabeliste mit Stücken aus dem dynamischen Modus.
removeCurrentTrack | Die Funktion removeCurrentTrack entfernt das aktuelle Stück aus der Wiedergabeliste.
saveM3u | Die Funktion saveM3u speichert die aktuelle Wiedergabeliste im Format *.m3u. Sie müssen den Pfad angeben, unter dem die Wiedergabeliste gepeichert werden soll. Außerdem müssen Sie 1 oder 0 übergeben, womit Sie festlegen, ob die Wiedergabeliste mit relativen Pfaden gespeichert werden soll.
setStopAfterCurrent | Die Funktion setStopAfterCurrent stoppt die Wiedergabe nach dem aktuell laufenden Stück.
shortStatusMessage | Die Funktion shortStatusMessage zeigt einen kurzen Text als Nachricht in der Statusleiste an.
shufflePlaylist | Die Funktion shufflePlaylist mischt die Stücke in der Wiedergabeliste in eine zufällige Reihenfolge.
togglePlaylist | Die Funktion togglePlaylist schaltet die Anzeige des Wiedergabelisten-Fenster ein oder aus.

### dcop amarok script

DCOP-Aufruf | Funktion
--- | ---
listRunningScripts | Die Funktion listRunningScripts listet alle laufenden &amarok;-Skripte auf.
runScript | Die Funktion runScript führt das &amarok;-Skript mit dem übergebenen Namen aus.
stopScript | Die Funktion stopScript stoppt das &amarok;-Skript mit dem übergebenen Namen.
addCustomMenuItem | Die Funktion addCustomMenuItem fügt dem Kontext-Menü der Wiedergabeliste einen Menü-Eintrag hinzu. Die Funktion benötigt zwei Parameter. Der erste ist der Titel des Unter-Menüs und der zweite der Titel des Menü-Eintrags. Beide QStrings werden im Benachrichtigungs-System der Skript-Verwaltung zurückgegeben.
removeCustomMenuItem | Die Funktion removeCustomMenuItem entfernt Menü-Einträge die mit addCustomMenuItem hinzugefügt wurden. Die Funktion verwendet die gleichen Parameter wie addCustomMenuItem.

## Optionen auf der Kommandozeile

&amarok; unterstützt die Kommandozeilen-Optionen von Qt und &kde;. Zusätzlich hat &amarok; noch einige eigene Kommandozeilen-Optionen.

Die Qt- und &kde;-Optionen:

Option | Funktion
--- | ---
--help | Hilfe zu den Optionen anzeigen.
--help-qt | Qt-Optionen anzeigen
--help-kde | &kde;-Optionen anzeigen.
--help-all | Alle Optionen anzeigen.
--author | Informationen über den Autor anzeigen.
-v, --version | Versionsinformationen anzeigen.
--license | Lizenzinformationen anzeigen.

Die &amarok;-Optionen:

Die &amarok;-Optionen sollten verwendet werden, während &amarok; läuft.

Option | Funktion
--- | ---
-r, --previous | Zum vorigen Stück in der Wiedergabeliste springen.
-p, --play | Die Wiedergabe der aktuellen Wiedergabeliste starten.
-s, --stop | Die Wiedergabe stoppen.
--pause | Die Wiedergabe anhalten (Pause).
-f, --next | Zum nächsten Stück in der Wiedergabeliste springen.
-a, --append | Dateien/URLs and die Wiedergabeliste anhängen.
-e, --enqueue | Siehe "append", nur für Rückwärtskompatibilität vorhanden.
--queue | Dateien/URLs nach dem aktuellen Stück zur Wiedergabe einreihen.
-m, --toggle-playlist-window | Die Anzeige des Wiedergabelisten-Fensters ein/ausschalten.
--wizard | Den Einrichtungsassistent starten.
--engine "Name" | Startet &amarok; mit dem Audio-Ausgabe-Modul "Name".

## Schreiben von Skripten

Mit Skripten kann &amarok; leicht erweitert werden, ohne die Codebasis von &amarok; ändern zu müssen. Skripte funktionieren ähnlich wie Module (Plugins), sie verwenden aber keine dedizierte Modul-API, sondern die DCOP-Schnittstelle. Auf diese Weise können &amarok;-Skripte in nahezu jeder Sprache programmiert werden (z. B. Ruby, Python oder PHP). Sie sind nichtmal auf Skriptsprachen beschränkt sondern können auch kompilierte Programme in C oder C++ verwenden. &amarok; kann Ihre Skripte über bestimmte Ereignisse informieren, sodass Ihre Skripte entsprechend reagieren können. Das Benachrichtigungs-System wird weiter hinten in diesem Abschnitt erklärt.

### Bindungen

Man kann natürlich einfache Skripte ohne jegliche Benutzer-Interaktion programmieren. Aber es ist auch möglich, Skripte mit einer komfortablen Oberfläche zu programmieren, die sich wie eine eigene Anwendung verhalten. Zum Programmieren der Oberfläche können Sie eine der vielen KDE-Bindungen verwenden, zum Beispiel RubyQt. Bedenken Sie dabei aber bitte, dass nicht jeder Benutzer alle verfügbaren Bindungen installiert hat. Wenn Sie sich für eine Bindung entscheiden, dann verwenden Sie am besten eine der weit verbreiteten wie z. B. RubyQt oder PyQt.

Sie sollten dem Anwender eine Rückmeldung geben, wenn das Skript wegen einer fehlenden Abhängigkeit nicht ausgeführt werden kann. Bitte prüfen Sie in Ihrem Skript, ob alle benötigten Module vorhanden sind und nutzen Sie kdialog, damit der Anwender weis, warum ein Skript nicht läuft.

Dieses Beispiel soll zeigen, wie man in Ruby eine fehlende Abhängigkeit abfängt:

    begin
           require 'Korundum'
    rescue LoadError
           error = 'Korundum (KDE bindings for ruby) from kdebindings v3.4 is required for this script.'
           `kdialog --sorry '#{error}'`
           exit
    end

### Erste Schritte: Die Vorlagen

Im Ordner `scripts/templates` finden Sie eine Menge Vorlage-Skripte in vielen verschiedenen Sprachen. Sie können sie als Basis für Ihre eigenen Skripte verwenden oder sie einfach um die benötigten Funktionen erweitern. Sie werden schnell feststellen, dass das Schreiben von Skripten relativ einfach ist.

### DCOP zur Steuerung von &amarok; verwenden

Skripte können DCOP verwenden, um mit &amarok; Daten auszutauschen oder um &amarok; zu steuern. Der einfachste Weg ist die Verwendung des Kommandos dcop; es liegt jedem KDE bei.

So können Sie beispielsweise die Lautstärke erhöhen:

    dcop amarok player volumeUp

Die meisten Skriptsprachen ermöglichen das Ausführen von externen Programmen und Befehlen. Dazu wird meist die Funktion exec() verwendet. Auf diese Weise kann dcop > relativ einfach aufgerufen werden. Hier ein Beispiel in Python:

    import os
     os.system("dcop amarok player volumeDown")

### Benachrichtigungen

&amarok; sendet Benachrichtigungen an alle laufenden Skripte. Dazu werden Strings an die Standardeingabe des Skripts geschrieben. Aus diesem Grund sollten Skripte ihre Standardeingabe laufend überwachen und entsprechend auf Ereignisse reagieren. Natürlich kann ein Skript die Ereignisse auch ignorieren wenn es keine Verwendung dafür hat.

Die folgenden Benachrichtigungen werden von &amarok; gesendet:

    configure
    Weist das Skript an, seinen Einrichtungsdialog anzuzeigen.
    Um das Speichern und Laden der Konfiguraion muss sich jedes Skript
    selbst kümmern. Wenn ein Skript gestartet wird, setzt &amarok; seinen
    Arbeitsordner auf den Ordner, wo alle Daten gespeichert werden sollten.

    engineStateChange:empty|idle|paused|playing
    Signalisiert eine Änderung im Modul für Audio-Ausgabe.

    trackChange
    Signalisiert, dass ein neues Stück angespielt wird. Das Skript könnte nun
    z. B. mit DCOP weitere Informationen zu dem neuen Stück abfragen (Metadaten
    oder die Stücklänge zum Beispiel).

    volumeChangenewVolume
    Signalisiert eine Änderung der Lautstärke. Die neue Lautstärke ist ein
    Integerwert zwischen 0 und 100.

    customMenuClicked:submenu itemTitle paths
    Enthält den Pfad zu den ausgewählten Dateien der Wiedergabeliste, wenn ein
    benutzerdefinierter Menüeintrag angeklickt wurde. submenu und itemTitle
    werden ebenfalls übergeben, damit das Skript den geklickten
    Eintrag identifizieren kann. Um dem Menü einen eigenen Eintrag
    hinzuzufügen, kann man die DCOP-Funktion dcop amarok script
    addCustomMenuItem( submenu itemTitle ) verwenden. Um einen
    Eintrag wieder zu entfernen verwendet man
    dcop amarok script removeCustomMenuItem( submenu itemTitle ).

### Beenden von Skripten

Bevor &amarok; sich beendet, oder wenn der Benutzer ein Skript stoppt, sendet &amarok; das Signal SIGTERM an das Skript. Dieses Signal sollte verarbeitet werden, um z. B. Aufräumarbeiten zu erledigen. Dazu gehört z. B. das Speichern von Daten oder Konfigurationseinstellungen.

### Skript-Pakete

&amarok;s Skript-Verwaltung kann auch Skript-Pakete installieren, die der Anwender z. B. von einem Webserver heruntergeladen hat. Solche Pakete sind im Grunde normale Tar-Archive (.tar), die optional auch mit bzip2 (.bz2) komprimiert sein können. Wir empfehlen einen Archivnamen wie z. B. meinskript.amarokscript.tar.bz2, damit der Benutzer das Archiv eindeutig als &amarok; Skript-Paket erkennen kann.

&amarok; 1.3 wird nur Skript-Pakete mit der Erweitungerung amarokscript akzeptieren. Aus diesem Grund sollten Sie Ihre Skript-Pakete gleich richtig benennen.

Der Inhalt des Skript-Pakets muss so organisiert sein:

    meinskript/
       README
       meinskript.py (ausführbar)
       einmodul.py
       foo.data
       ...

### Dateirechte

Das Hauptskript muss ausführbar sein (+x), die restlichen zu ladenden Module sollte nicht ausführbar sein. Verwenden Sie den Tar-Parameter -p um die Dateirechte zu erhalten:

    tar -cf meinskript.amarokscript.tar -p meinskript

&amarok; wird das Skript nicht installieren, wenn die Dateirechte nicht korrekt eingestellt sind!

### Veröffentlichung

Wenn Ihr Skript-Paket fertig ist, können Sie es auf www.kde-apps.org hinaufladen und den Link an die Wiki Scripts Seite von &amarok; anhängen. Für Ihren Eintrag auf kde-apps sollten Sie die Kategorie &amarok; Scripts verwenden.