From Amarok Wiki
Contents |
Einführung
Scripting erlaubt es, amaroK auf einfache Art und Weise zu erweitern, ohne den Hauptcode ändern zu müssen.
Skripte sind ähnlich wie Plugins, aber anstatt einer bestimmten Plugin API nutzen sie amaroKs DCOP Schnittstelle zur Kommunikation. Dies ermöglicht das Schreiben von Skripten in fast jeder Programmiersprache wie Ruby, Python, PHP oder der Bash. Die empfohlene Programmiersprache ist Ruby. Sie ist einfach zu lernen und ist ideal für amaroK-Skripting. Das amaroK-Team wird Dich bei Fragen zur Ruby-Programmierung gerne unterstützen.
Zusätzlich kann amaroK den Skripten spezielle Ereignisse mitteilen, so das diese entsprechend darauf reagieren können.
Verbindungen zu Skriptsprachen(Bindings)
Es ist möglich einfache Skripte zu schreiben, die keine Nutzerinteraktionen benötigen und es ist genauso gut möglich Skripte mit komfortablen grafischen Oberflächen zu schreiben, die sich wie kleine eigenständige Anwendungen verhalten. Für das Programmieren von grafischen Oberflächen kann eine der vielen Verbindungen benutzt werden, welche KDE zur Verfügung stellt, zum Beispiel RubyQt, eine Verbindung zwischen den Qt-Bibliotheken und der Sprache Ruby. Jedoch hat nicht jeder Nutzer alle verfügbaren Bindungen installiert. Wenn sie sich für eine Bindung entscheiden, versuchen sie eine der weit verbreiteten zu nehmen (Bspw.: RubyQt oder PyQt).
Um eine Rückmeldung zu erhalten wenn ein Skript auf Grund von fehlenden Bindungen nicht funktioniert, überprüfe bitte in deinen Skripten, ob das Modul welches du nutzen willst auch wirklich existiert. Falls dies nicht der Fall ist, solltest du den Fehler abfangen und dem Nutzer mitteilen, warum das Skript bei ihm nicht funktioniert. Nutze dafür am besten das Kommandozeilenwerkzeug "kdialog".
Hinweis: Tutorial für kdialog
Dieses Beispiel zeigt, wie man in Ruby das Vorhandensein einer Bindung überprüft und im Fehlerfall eine Bildschirmmeldung ausgibt:
begin
require 'Korundum'
rescue LoadError
error = 'Korundum (KDE-Bindung für ruby) aus kdebindings v3.4 wird für dieses Skript benötigt.'
`kdialog --sorry '#{error}'`
exit
end
Editieren und Testen
Das erstellte Skript kann nach dem Installieren durch einen Rechts-Klick auf den Namen bearbeitet werden. Ein wiederholtes Installieren der geänderten Version ist daher nicht nötig. Die Ausgabe des Skripts erscheint nicht auf der Konsole von der Amarok gestartet wurde, sondern kann ebenfalls im Kontextmenü abgerufen werden.
SVN (Subversion) Server
Das amaroK-Projekt bietet Skript-Entwicklern ein kostenlosen SVN-Konto auf unserem Projektserver. SVN ist ein Versionsverwaltungssystem, das sehr bei der Entwicklung von Programmen hilft. Es erlaubt jederzeit Fehler wieder rückgängig zu machen und die Zusammenarbeit von vielen Entwicklern an einem Projekt. Wenn Du ein Benutzerkonto (Account) haben möchtest, so schicke eine E-Mail an unsere Mailingliste amarok@kde.org.
Los gehts: Die Vorlagen
amaroK stellt im Verzeichnis scripts/templates/ Vorlagen für verschiedene Sprachen zur Verfügung. Du kannst diese Skripte gut als Basis für ihre eigenen Skripte benutzen und sie mit den gewünschten Funktionen erweitern. Du wirst feststellen das Skripte schreiben sehr effektiv ist. Wenn bereits ein wenig Erfahrung mit Ruby vorhanden ist, dauert es nicht lange bis ein Skript funktioniert :)
TODO: Wir benötigen mehr Vorlagen! Falls du eine erstellt hast schicke uns diese doch bitte einfach an unsere Mail-Liste amarok@kde.org.
amaroK über DCOP steuern
Skripte können amaroK über einige seiner DCOP-Funktionen steuern. Der einfachste Weg eine DCOP-Funktion zu nutzen ist das Kommandozeilenwerkzeug "dcop", welches Teil jeder KDE-Distribution ist. Hier ein kleines Beispiel um das Master-Volume zu erhöhen:
"dcop amarok player volumeUp"
Die meisten Skriptsprachen erlauben das Benutzen von externen Programmen mit einer Funktion wie exec(). Auf diese Weise kann "dcop" sehr einfach aufgerufen werden.
In Ruby ist das sehr einfach. Setze einfach den Befehl in schräge Hochkommata:
artist = `dcop amarok player artist`
Hier ein einfaches Beispiel in Python:
import os
os.system("dcop amarok player volumeDown")
Für Python gibt es noch einen anderen Weg DCOP-Aufrufe abzusetzen. Du kannst pyKDEs dcop oder dcopext-Modul nutzen. Wegen einigen Limitierungen (z.B. kann man amarok.contextbrowser.showLyrics() aufrufen, aber nicht amarok.contextbrowser.showLyrics(QString)) empfehle ich eine modifizierte Version von dcopext zu nutzen. Siehe http://kde-apps.org/content/show.php?content=37981
from dcop import DCOPClient
from dcopext import DCOPApp
import sys
# create a new DCOP-Client:
client = DCOPClient()
# connect the client to the local DCOP-server:
client.attach()
# create a DCOP-Application-Object to talk to amarok:
amarok = DCOPApp('amarok', client)
# call a DCOP-function:
ok, artist = amarok.player.artist()
# amaroK 1.4 and the modified version of dcopext:
ok, void = amarok.contextbrowser.showLyrics(
'<lyric artist="Foo" title="Bar" page_url="http://foobar.org">text</lyric>')
Wenn ok == True ist, war der Aufruf erfolgreich.
Einträge im Kontextmenü
Mit einem einfachen dcop-Aufruf können eigene Einträge in das Kontextmenü der Playliste eingefügt werden:
dcop amarok script addCustomMenuItem "MyScript" "MyAction"
Der Eintrag kann auch einfach wieder entfernt werden:
dcop amarok script removeCustomMenuItem "MyScript" "MyAction"
Stelle sicher, dass das Skript nach einer Benachrichtigung schaut, ob der Menüeintrag angeklickt worden ist. Andernfalls wird nichts passieren. Siehe dazu "customMenuClicked"-Benachrichtigung weiter unten.
Benachrichtigungen
amaroK sendet an alle laufen Skripte Benachrichtigungen indem es Strings in deren stdin Kanal schreibt. Die Skripte sollten deshalb stdin ständig überwachen und entsprechend auf die möglichen Ereignisse reagieren. Skripte können ebenso alle Ereignisse ignorieren für die sie keine Verwendung haben.
Hier ist ein Beispiel in Ruby für eine Hauptschleife, die auf Benachrichtigungen von amaroK wartet und diese verarbeitet:
loop do
message = gets().chomp() #Read message from stdin
command = /[A-Za-z]*/.match( message ).to_s()
case command
when "configure"
msg = '"This script does not have configuration options."'
`dcop amarok playlist popupMessage "#{msg}"`
when "fetchLyrics"
args = message.split()
artist = args[1]
title = args[2]
lyrics = fetchLyrics( artist, title )
`dcop amarok script showLyrics "#{lyrics}"`
end
end
Die folgenden Benachrichtigungen werden von amaroK gesendet:
- configure
- Teilt dem Skript mit, seinen Konfigurationsdialog zu zeigen. Das Skript muss das Laden und Speichern seiner Konfiguration allerdings selbst erledigen. Wenn ein Skript gestartet wird setzt amaroK sein Arbeitsverzeichnis in den Ordner wo alle Daten gespeichert werden sollen.
- TIP: Wenn Dein Skript vor der ersten Benutzung eingerichtet werden muss, dann zeige den grafischen Einrichtungsdialog beim ersten Start.
- engineStateChange: {empty|idle|paused|playing}
- Signalisiert eine Veränderung des Engine-Status.
- trackChange
- Zeigt den Start eines neuen Stückes an. Das Skript kann dann DCOP-Funktionen benutzen um beispielsweise Meta-Daten und die Länge des Stücks abzufragen.
- volumeChange: {newVolume}
- Signalisiert eine Veränderung des Master-Volume-Levels. Die Lautstärke ist ein Integer-Wert im Bereich 0-100.
Anmerkung: Die Benachrichtigung wurde der amaroK 1.3 Serie hinzugefügt.
- customMenuClicked: {submenu itemTitle paths}
- Gibt den Pfad zu den in der Playliste ausgewählten Dateien zurück, wenn der vom Benutzer hinzugefügte Eintrag im Kontextmenü angeklickt wurde. Das Untermenü (submenu) und Eintragsbezeichnung (itemTitle) werden für Erkennungszwecke auch zurückgegeben. Ein Skript kann auf verschiedene Benachrichtigungen warten. Um einen Eintrag in das Kontextmenü einzufügen, wird folgender dcop-Aufruf 'dcop amarok script addCustomMenuItem( submenu itemTitle )' genutzt. Um den Eintrag wieder zu entfernen, hilft folgender dcop-Aufruf 'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.
Anmerkung: Die Benachrichtigung wurde der amaroK 1.3 Serie hinzugefügt.
- fetchLyrics {artist title}
- Signalisiert die Anfrage nach den Lyrics für das im Moment gespielte Lied. Die Benachrichtigung wird nur an ein Lyrics-Modul gesendet. Um ein Modul (plugin) als ein Lyrics-Modul zu kennzeichnen, muss ein spec-file des Typs type=lyrics vorhanden sein. Siehe The Spec File.
- Die Strings für "artist" und "title" sind CGI-kodiert. Dies bedeutet, das spezielle Zeichen wie Leerzeichen, '?', '&', '=', '%' und andere Zeichen, die nicht in einem CGI-query-string vorkommen können, als "%xx" dargestellt werden. Wobei "xx" eine zweistellige Hexadezimale Nummer ist, die den Wert des Zeichen repräsentiert. Die Strings für "artist" und "title" können auch leer sein. Daher ist es auch möglich das nur ein String oder gar keiner an das Modul weitergegeben werden.
- Empfangene Lyrics werden per dcop-Aufruf an amaroK weitergereicht: amarok.contextbrowser.showLyrics(QString). Der Parameter für diese Funktion muss im folgenden XML-format vorliegen:
<lyric artist="artist name" title="song title" page_url="http://provided.by"> text text text text text text ... </lyric>
- Nicht vergessen alle Zeichen richtig zu "maskieren" (escape)! Nutze eine XML-API um dies ohne Fehler zu erledigen(z.B. mit dem Python-Modul xml.dom).
- Wenn keine exakten Treffer vorliegen, aber einige Vorschläge, dann nutze folgendes Format:
<suggestions page_url="http://provided.by"> <suggestion artist="artist name" title="song title" url="http://url.to/the/specific/lyrics" /> ... </suggestions>
- Wenn kein Treffer vorliegt:
<suggestions page_url="http://provided.by"> </suggestions>
- Wenn ein Verbindungsfehler mit dem Lyrics-Server auftrat, dann sende einen leeren String.
Anmerkung: Die Benachrichtigung wurde der amaroK 1.4 Serie hinzugefügt.
- fetchLyricsByUrl {url}
- Diese Benachrichtigung wird bei einem Klick auf einen Liedtext-Vorschlag gesendet. Die URL ist das URL-Attribut des ausgewählten Vorschlags und ebenfalls CGI-kodiert. Zuletzt noch etwas zu Zeichen wie 'ä'. Du musst diese Zeichen zurück konvertieren, wenn diese nicht nicht kodiert werden sollen.
Anmerkung: Die Benachrichtigung wurde der amaroK 1.4 Serie hinzugefügt.
Zugriff auf Skriptdaten
Das Ausführungsverzeichnis für amaroK-Skripte ist "~/.kde/share/apps/amarok/scripts-data/" und dort sollten auch die Konfigurationsdateien gespeichert werden. Soll aber wie in obigem Beispiel eine Datei wie z.B. "somemodule.rb" einbezogen werden, so muss für Ruby folgendes getan werden:
SAVEDIR = Dir.pwd Dir.chdir(File.dirname( File.expand_path(__FILE__) )) require 'somemodule.rb'
SAVEDIR enthält das "scripts-data"-Verzeichnis und wird verwendet wenn eine Datei geschrieben werden soll. Der Schlüssel in Code oben die Ruby-Konstante "__FILE__". Diese gibt den Dateinamen des aktuell ausgeführten Skripts zurück. Andere Programmiersprachen sollten ähnliche Funktionen besitzen.
In Python kann jedes Modul importiert werden, dass sich im gleichen Ordner wie das Skript befindet. Python durchsucht diesen Ordner, nicht den aktuellen. Wenn nun doch der Ordner gelesen werden soll, um z.B. einige mit Deinem Skript gelieferten Dateien zu lesen (wie Bilder), kann das folgende Beispiel verwendet werden:
import os, sys scriptfolder, scriptfile = os.path.split( sys.argv[0] )
Skript beenden
Bevor sich amaroK beendet, oder der Benutzer ein Skript durch den Skript-Manager beendet, sendet amaroK dass SIGTERM Signal an den Skriptprozess. Dieses Signal kann für Aufräumarbeiten, wie das entfernen von Kontextmenüeinträgen, verwendet werden oder zum Speichern von Daten und Konfigurationseinstellungen.
Hier ein Beispiel in Ruby:
def cleanup()
puts( "Script was terminated." )
`dcop amarok script removeCustomMenuItem #{scriptName} #{actionName}`
end
trap( "SIGTERM" ) { cleanup() }
Oder in Python:
import signal
def cleanup(signum, frame):
print 'Script was terminated.'
amarok.script.removeCustomMenuItem(scriptName, actionName)
signal.signal(signale.SIGTERM, cleanup)
Verpackung
amaroKs Skript-Manager ist in der Lage Skript-Pakete zu installieren, welche der Nutzer aus dem Internet geladen hat. Diese Pakete sind normale Tar-Archive (.tar), optional noch mit bzip2 komprimiert (.bz2). Die Dateien müssen nach dem folgendem Muster benannt werden: .amarokscript.*'. Beispiel: meinscript.amarokscript.tar.bz2.
Der Tarball-Inhalt muss folgendermaßen organisiert sein:
myscript/ README COPYING myscript.rb (executable) myscript.spec (amaroK 1.4 feature) somemodule.rb foo.png ...
Anmerkung: Seit amarok Version 1.3.4 können in Datei README einfache HTML-Tags verwendet werden und dadurch das Erscheinungsbild verbessert werden. Die Anzeige erfolgt in einem KAboutDialog-Widget. Wenn die COPYING vorhanden ist, wird dem KAboutDialog das zusätzliche Register "License" hinzugefügt. Das Lizenzregister unterstützt keine HTML-Syntax.
Die Spec-Datei
(This is a new feature in amaroK 1.4)
Eine Spezifikationsdatei (spec(ification) file) kann dem Skriptordner hinzugefügt werden. Diese bietet zusätzliche Informationen zu dem Skript. Die Datei ist eigentlich eine einfache INI-Textdatei, wie die meisten UNIX-Konfigurationsdateien. Die folgenden Schlüssel/Werte-Paare werden im Moment unterstützt:
name = <Name des Skripts>
type = {generic|lyrics|transcode}
Wenn keine Spec-Datei vorhanden ist oder das "name"-Attribut nicht angegeben ist, wird der Dateiname des Skripts als Name verwendet. Die Spec-Datei muss den gleichen Basisnamen als die ausführbare Skriptdatei haben, jedoch mit der Erweiterung ".spec". Beispiel: "myscript.spec".
Lyrics-Module haben meist noch zusätzliche Eigenschaften definiert. Lese die [Lyrics]-Sektion hierzu:
[Lyrics] add_url = <http://url.to/add/lyrics/page/of/the/lyrics/service> site = <name of the lyrics-service> site_url = <http://url.of/the/lyrics/service>
Dateiberechtigungen
Das Hauptskript muss ausführbar sein (+x), während zusätzliche Module welche das Script lädt nicht ausführbar sein sollten. Um die Dateiberechtigungen im Archiv zu erhalten sollten sie "tar" mit der Option -p aufrufen:
tar -cf meinscript.amarokscript.tar -p meinscript
Bitte beachte das amaroK nicht in der Lage sein wird das Skript korrekt zu installieren, wenn die Berechtigungen nicht richtig gesetzt sind.
Veröffentlichen
Wenn das Skript fertig ist, kannst du es auf kde-apps.org hochladen und eine Verknüpfung ins Wiki setzen (Scripts). Für den Eintrag auf kde-apps solltest Du die amaroK Scripts-Kategorie nutzen. Wähle diese Kategorie nicht, wenn Dein Skript nicht mit amaroK's Skript-Manager installierbar ist.