It is possible to write simple scripts that do not need user interaction, and it's also possible to make scripts with comfortable GUIs that act like little applications of their own. For GUI programming one of the many bindings which KDE provides can be used, for instance RubyQt, a Qt library binding for Ruby. However, it is worth noting that not every user has all available bindings installed. If you decide to use a binding, try to use one of the relatively wide spread ones (e.g. RubyQt or PyQt).

In order to provide some feedback when a script fails to run due to a missing dependency, please check in your script if the module you want to include really exists. If the dependency is missing, you should catch the error and show an information dialog using the "kdialog" command line tool, so that the user learns why the script fails to run.

This example shows how to catch a missing dependency in Ruby:

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

Amarok provides template scripts for several languages in the scripts/templates/ directory. You can use these scripts as a basis for your own scripts, and extend them with the functionality you need. You'll notice that scripting is actually quite straightforward; For instance if you know to program a bit in Python, making your own script won't take you long.

Scripts can control Amarok by calling some of its DCOP functions. The easiest way to invoke a DCOP function is by using the "dcop" command line utility, which is part of every KDE distribution.

Here is an example for increasing the master volume:

dcop amarok player volumeUp

Most scripting languages allow to execute external programs, with a function like exec(). This way the "dcop" utility can be invoked easily. Here is a simple Python example:

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

Amarok sends notifications to all running scripts by writing strings to their stdin channel. The script should therefore constantly monitor stdin, and react accordingly to each of the possible events. Scripts may also choose to ignore any event they don't have a use for.

The following notifications are sent by Amarok:

configure
Tells the script to show its configuration dialog. The script must handle the
storing and loading of configuration options by itself. When a script is
started, Amarok sets its working directory to the folder where all data
should be stored.

engineStateChange: [empty|idle|paused|playing]
Signals a change in the engine's state.

trackChange
Signals the start of a new track. The script may then use DCOP functions to
query further information about the track, e.g. metadata and the length.

volumeChange [newVolume]
Signals a change of the master volume level. The volume is an integer with a
range of 0-100.

customMenuClicked: [submenu itemTitle paths]
Returns the paths to selected files in the playlist when the custom playlist
context menu item is clicked. The submenu and itemTitle are also returned for
identification purposes in case a script is listening for multiple notifications.
To insert an item into the context menu use the DCOP call
'dcop amarok script addCustomMenuItem( submenu itemTitle )'. To remove an
item from the context menu use the DCOP call
'dcop amarok script removeCustomMenuItem( submenu itemTitle )'.

Before Amarok exits, or when the user stops a script with the Script Manager, Amarok sends the SIGTERM signal to the script. This signal can be caught in order to do cleanup work, like saving data or configuration settings.

Amarok's Script Manager is able to install script packages that the user has downloaded from a web server. Packages are just normal tarballs (.tar), optionally compressed with bzip2 (.bz2). We strongly recommend using a filename like myscript.amarokscript.tar.bz2, so the user can easily identify the package as an Amarok script.

The tarball's content must be organized as follows:

myscript/
   README
   myscript.py (executable)
   somemodule.py
   foo.data
   ...

The main script must have executable (+x) permissions set, while additional modules which the script loads should not be executable. To preserve the file permissions in the tarball, you should use tar with the -p flag:

tar -cf myscript.amarokscript.tar -p myscript

When the package is finished, you can upload it to www.kde-apps.org, and add the link to the Amarok Wiki Scripts Page. For the kde-apps entry you should use the Amarok Scripts category.