path: root/doc/en/advanced.docbook

<chapter id="advanced-features">
<title>Advanced Amarok features</title>


<sect1 id="keybd-shortcuts">
<title>Keyboard Shortcuts</title>

<para>&amarok; uses keyboard shortcuts like most other applications, below is a listing of those shortcuts and there respective actions. The global shortcuts can be configured by right clicking the Player window and selecting <guimenuitem>Configure Global Shortcuts...</guimenuitem> The &amarok; shortcuts can be configured by right clicking the Player window and selecting <guimenuitem>Configure Shortcuts...</guimenuitem></para>

<tip><para>You can assign you multimedia keys to work as &amarok; shortcuts making your keyboard an &amarok; control center.</para></tip>

<para>The global shortcuts are:</para>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>Key Combination</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>X</keycap></keycombo></entry>
<entry>Play</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>C</keycap></keycombo></entry>
<entry>Pause</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>V</keycap></keycombo></entry>
<entry>Stop</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>B</keycap></keycombo></entry>
<entry>Next Track</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>Z</keycap></keycombo></entry>
<entry>Previous Track</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>KP_Add</keycap></keycombo></entry>
<entry>Increase Volume</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>KP_Subtract</keycap></keycombo></entry>
<entry>Decrease Volume</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>Shift</keycap><keycap>KP_Add</keycap></keycombo></entry>
<entry>Seek Forward</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>Shift</keycap><keycap>KP_Subtract</keycap></keycombo></entry>
<entry>Seek Backward</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>A</keycap></keycombo></entry>
<entry>Add Media</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>P</keycap></keycombo></entry>
<entry>Toggle Playlist</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>O</keycap></keycombo></entry>
<entry>Show OSD</entry>
</row>

<row>
<entry><keycombo><keycap>Win</keycap><keycap>M</keycap></keycombo></entry>
<entry>Mute Volume</entry>
</row>

</tbody>
</tgroup>
</informaltable>

<para>The &amarok; shortcuts are:</para>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>Key Combination</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo></entry>
<entry>Copy</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>KP_Enter</keycap></keycombo></entry>
<entry>Goto Current</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>D</keycap></keycombo></entry>
<entry>Queue Selected Tracks</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>Q</keycap></keycombo></entry>
<entry>Quit</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>Shift</keycap><keycap>Z</keycap></keycombo></entry>
<entry>Redo</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>S</keycap></keycombo></entry>
<entry>Save Playlist</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>A</keycap></keycombo></entry>
<entry>Select All</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>M</keycap></keycombo></entry>
<entry>Show Menubar</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>H</keycap></keycombo></entry>
<entry>Shuffle</entry>
</row>

<row>
<entry><keycombo><keycap>Ctrl</keycap><keycap>Z</keycap></keycombo></entry>
<entry>Undo</entry>
</row>


</tbody>
</tgroup>
</informaltable>


<para>The Playlist Browser shortcuts are:</para>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>Key Combination</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry><keycap>Space</keycap></entry>
<entry>Load Playlist</entry>
</row>

<row>
<entry><keycap>F2</keycap></entry>
<entry>Rename Playlist</entry>
</row>

<row>
<entry><keycap>Backspace</keycap></entry>
<entry>Remove Playlist</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect1>

<sect1 id="the-dcop-interface">
<title>The DCOP Interface</title>

<para>The Amarok DCOP interface provides you with an easy way to control Amarok with your own custom scripts.</para>

<para>The DCOP interface for Amarok has many generic calls that may be found in other TDE applications. This section is divided into six tables and is intended to describe the DCOP calls of the collection, contextbrowser, player, playlist, playlistbrowser and scripts. An example of the <quote>pause</quote> dcop call would look like:</para>

<para><prompt>&percnt;</prompt>dcop amarok player pause</para>

<sect2 id="dcop-collection">
<title>dcop amarok collection</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>DCOP Call</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>int totalAlbums()</entry>
<entry>Returns the total of albums in the collection.</entry>
</row>

<row>
<entry>int totalArtists()</entry>
<entry>Returns the total of artists in the collection.</entry>
</row>

<row>
<entry>int totalCompilations()</entry>
<entry>Returns the total of compilations in the collection.</entry>
</row>

<row>
<entry>int totalGenres()</entry>
<entry>Returns the total of genres in the collection.</entry>
</row>

<row>
<entry>int totalTracks()</entry>
<entry>Returns the total of tracks in the collection.</entry>
</row>

<row>
<entry>TQString query( TQString sql)</entry>
<entry>Queries the database via SQL.</entry>
</row>

<row>
<entry>QStringList similarArtists( int artists )</entry>
<entry>Return similar artists of the current tracks, limit to int artists.</entry>
</row>

<row>
<entry>void migrateFile( TQString oldURL, TQString newURL )</entry>
<entry>Move a file in the collection, keeping stats intact.</entry>
</row>

<row>
<entry>void scanCollection()</entry>
<entry>Scan the collection.</entry>
</row>

<row>
<entry>void scanCollectionChanges()</entry>
<entry>Scan the collection for changes only.</entry>
</row>


</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-context">
<title>dcop amarok contextbrowser</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>DCOP Call</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>void showCurrentTrack()</entry>
<entry>Show the current track in the context browser.</entry>
</row>

<row>
<entry>void showLyrics()</entry>
<entry>Show the lyrics tab in the context browser.</entry>
</row>

<row>
<entry>void showWiki()</entry>
<entry>Show the wikipedia tab in the context browser.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-player">
<title>dcop amarok player</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>DCOP Call</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>bool dynamicModeStatus()</entry>
<entry>Return dynamic mode status.</entry>
</row>

<row>
<entry>bool equalizerEnabled()</entry>
<entry>Return the equalizer status.</entry>
</row>

<row>
<entry>bool isPlaying()</entry>
<entry>Return true if something is playing now.</entry>
</row>

<row>
<entry>bool randomModeStatus()</entry>
<entry>Return random mode status.</entry>
</row>

<row>
<entry>bool repeatPlaylistStatus()</entry>
<entry>Return repeat playlist status.</entry>
</row>

<row>
<entry>bool repeatTrackStatus()</entry>
<entry>Return repeat track status.</entry>
</row>

<row>
<entry>int getVolume()</entry>
<entry>Return volume in range 0-100%.</entry>
</row>

<row>
<entry>int sampleRate()</entry>
<entry>Return the sample rate of the currently playing track.</entry>
</row>

<row>
<entry>int score()</entry>
<entry>Return the score of the currently playing track.</entry>
</row>

<row>
<entry>int status()</entry>
<entry>Return playback status: 0 - stopped, 1 - paused, 2 - playing.</entry>
</row>

<row>
<entry>int trackCurrentTime()</entry>
<entry>Return current play position in seconds.</entry>
</row>

<row>
<entry>int trackPlayCounter()</entry>
<entry>Return play counter for current song.</entry>
</row>

<row>
<entry>int trackTotalTime()</entry>
<entry>Return track length in seconds.</entry>
</row>

<row>
<entry>TQString album()</entry>
<entry>Return the album of the currently playing track.</entry>
</row>

<row>
<entry>TQString artist()</entry>
<entry>Return the artist of the currently playing track.</entry>
</row>

<row>
<entry>TQString bitrate()</entry>
<entry>Return the bitrate of the currently playing track (XX kbps).</entry>
</row>

<row>
<entry>TQString comment()</entry>
<entry>Return the comment of the currently playing track.</entry>
</row>

<row>
<entry>TQString coverImage()</entry>
<entry>Return the encoded URL of the current track's cover image </entry>
</row>

<row>
<entry>TQString currentTime()</entry>
<entry>Return the position of the currently playing track ([h:]mm:ss format).</entry>
</row>

<row>
<entry>TQString encodedURL()</entry>
<entry>Return the encoded URL of the currently playing track.</entry>
</row>

<row>
<entry>TQString engine()</entry>
<entry>Return the current sound engine.</entry>
</row>

<row>
<entry>TQString genre()</entry>
<entry>Return the genre of the currently playing track.</entry>
</row>

<row>
<entry>TQString lyrics()</entry>
<entry>Return the lyrics of the currently playing track.</entry>
</row>

<row>
<entry>TQString lyricsByPath( TQString path )</entry>
<entry>Return the lyrics of a track by path.</entry>
</row>

<row>
<entry>TQString nowPlaying()</entry>
<entry>The title of now playing media.</entry>
</row>

<row>
<entry>TQString path()</entry>
<entry>Return the unencoded path of the currently playing track.</entry>
</row>

<row>
<entry>TQString setContextStyle( TQString )</entry>
<entry>Set the CSS style for the context browser.</entry>
</row>

<row>
<entry>TQString title()</entry>
<entry>Return the title of the currently playing track.</entry>
</row>

<row>
<entry>TQString totalTime()</entry>
<entry>Return the total length of the currently playing track ([h:]mm:ss format).</entry>
</row>

<row>
<entry>TQString track()</entry>
<entry>Return the track number.</entry>
</row>

<row>
<entry>TQString type()</entry>
<entry>Return the file type.</entry>
</row>

<row>
<entry>TQString year()</entry>
<entry>Return the year of the currently playing track.</entry>
</row>

<row>
<entry>void configEqualizer()</entry>
<entry>Toggle equalizer config dialog.</entry>
</row>

<row>
<entry>void enableDynamicMode(bool enable)</entry>
<entry>Switch Dynamic Mode on or off.</entry>
</row>

<row>
<entry>void enableOSD(bool enable)</entry>
<entry>Switch OSD display on or off.</entry>
</row>

<row>
<entry>void enableRandomMode(bool enable)</entry>
<entry>Switch Random Mode on or off.</entry>
</row>

<row>
<entry>void enableRepeatPlaylist(bool enable)</entry>
<entry>Switch Repeat Playlist on or off.</entry>
</row>

<row>
<entry>void enableRepeatTrack(bool enable)</entry>
<entry>Switch Repeat Track on or off.</entry>
</row>

<row>
<entry>void mediaDeviceMount()</entry>
<entry>Sets the command used for mounting media device.</entry>
</row>

<row>
<entry>void mediaDeviceUmount()</entry>
<entry>Sets the comment used for umounting media device.</entry>
</row>

<row>
<entry>void mute()</entry>
<entry>Toggle mute.</entry>
</row>

<row>
<entry>void next()</entry>
<entry>Equivalent to pressing "Next" button.</entry>
</row>

<row>
<entry>void pause()</entry>
<entry>Equivalent to pressing "Pause" button.</entry>
</row>

<row>
<entry>void play()</entry>
<entry>Equivalent to pressing "Play" button.</entry>
</row>

<row>
<entry>void playPause()</entry>
<entry>Toggle play/pause state (good for mm keyboard users) </entry>
</row>

<row>
<entry>void prev()</entry>
<entry>Equivalent to pressing "Prev" button.</entry>
</row>

<row>
<entry>void queueForTransfer( KURL url )</entry>
<entry>Queue file for transfer to Media Device.</entry>
</row>

<row>
<entry>void seek(int s)</entry>
<entry>Seek track to seconds position.</entry>
</row>

<row>
<entry>void seekRelative(int s)</entry>
<entry>Seek to a position relative to the current track position.</entry>
</row>

<row>
<entry>void setEqualizer(int, int, int, int, int, int, int, int, int, int, int)</entry>
<entry>Set the equalizer bands </entry>
</row>

<row>
<entry>void setEqualizerEnabled( bool active )</entry>
<entry>Toggle equalizer.</entry>
</row>

<row>
<entry>void setEqualizerPreset( TQString name )</entry>
<entry>Set the equalizer preset </entry>
</row>

<row>
<entry>void setLyricsByPath( TQString url, TQString lyrics )</entry>
<entry>Set the lyrics of a track by it's path.</entry>
</row>

<row>
<entry>void setScore( int score )</entry>
<entry>Set the score of the currently playing track.</entry>
</row>

<row>
<entry>void setScoreByPath( TQString url, int score )</entry>
<entry>Set the score of a track by it's path.</entry>
</row>

<row>
<entry>void setVolume(int volume)</entry>
<entry>Set volume in range 0-100%.</entry>
</row>

<row>
<entry>void showBrowser( TQString browser )</entry>
<entry>Shows browsers in the playlist window</entry>
</row>

<row>
<entry>void showOSD()</entry>
<entry>Show the OSD display on the screen.</entry>
</row>

<row>
<entry>void stop()</entry>
<entry>Equivalent to pressing "Stop" button.</entry>
</row>

<row>
<entry>void transferDeviceFiles()</entry>
<entry>Transfer files to media device.</entry>
</row>

<row>
<entry>void volumeDown()</entry>
<entry>Decrease volume by a reasonable step.</entry>
</row>

<row>
<entry>void volumeUp()</entry>
<entry>Increase volume by a reasonable step.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-playlist">
<title>dcop amarok playlist</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>DCOP Call</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>int getActiveIndex()</entry>
<entry>Return the index of the currently active track. -1 if none.</entry>
</row>

<row>
<entry>int getTotalTrackCount()</entry>
<entry>Return number of tracks in playlist. 0 if none.</entry>
</row>

<row>
<entry>TQString saveCurrentPlaylist()</entry>
<entry>Saves the current playlist to current.xml and returns its path.</entry>
</row>

<row>
<entry>void addMedia( KURL )</entry>
<entry>Add audio media specified by the url.</entry>
</row>

<row>
<entry>void addMediaList( KURL::List )</entry>
<entry>Add some audio media specified by the url.</entry>
</row>

<row>
<entry>void clearPlaylist()</entry>
<entry>Clears the playlist.</entry>
</row>

<row>
<entry>void playByIndex(int)</entry>
<entry>Starts playing the track at the specified index.</entry>
</row>

<row>
<entry>void playMedia( KURL )</entry>
<entry>Add audio media specified by the url.</entry>
</row>

<row>
<entry>void popupMessage( TQString)</entry>
<entry>Shows a temporary popup message.</entry>
</row>

<row>
<entry>void removeCurrentTrack()</entry>
<entry>Removes the current-track item from the playlist.</entry>
</row>

<row>
<entry>void repopulate()</entry>
<entry>Repopulate the playlist with random tracks.</entry>
</row>

<row>
<entry>void saveM3u( TQString path, bool relativePaths)</entry>
<entry>Saves the current playlist as m3u.</entry>
</row>

<row>
<entry>void setStopAfterCurrent( bool )</entry>
<entry>Enables/disables the "Stop After Current Track" feature.</entry>
</row>

<row>
<entry>void shortStatusMessage( TQString)</entry>
<entry>Shows a temporary message on the statusbar.</entry>
</row>

<row>
<entry>void shufflePlaylist()</entry>
<entry>Shuffles the playlist.</entry>
</row>

<row>
<entry>void togglePlaylist()</entry>
<entry>Toggle the Playlist-window.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-playlistbrowser">
<title>dcop amarok playlistbrowser</title>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>DCOP Call</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>void addPodcast( TQString )</entry>
<entry>Add a podcast entry to the playlist browser.</entry>
</row>

<row>
<entry>void scanPodcasts()</entry>
<entry>Scan all podcasts for updates.</entry>
</row>

<row>
<entry>void addPlaylist( TQString )</entry>
<entry>Add a playlist to the playlist browser.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect2>

<sect2 id="dcop-script">
<title>dcop amarok script</title>


<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>DCOP Call</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>bool runScript( TQString name)</entry>
<entry>Starts the script with the given name. Returns true on success.</entry>
</row>

<row>
<entry>bool stopScript( TQString name)</entry>
<entry>Stops the script with the given name. Returns true on success.</entry>
</row>

<row>
<entry>QStringList listRunningScripts()</entry>
<entry>Returns a list of all currently running scripts.</entry>
</row>

<row>
<entry>void addCustomMenuItem(TQString submenu, TQString itemTitle )</entry>
<entry>Enables and sets custom menu item title.</entry>
</row>

<row>
<entry>void removeCustomMenuItem(TQString submenu, TQString itemTitle )</entry>
<entry>Removes the custom menu item.</entry>
</row>

<row>
<entry>TQString readConfig( TQString key)</entry>
<entry>Returns a AmarokConfig configuration entry value from the given key.</entry>
</row>

</tbody>
</tgroup>
</informaltable>


</sect2>

</sect1>

<sect1 id="cmd-line-options">
<title>Command-line Options</title>

<para>Amarok supports the use of the standard Qt and kde command line options. Amarok also has it's own application specific options.</para>

<para>The Qt and kde options:</para>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>Option</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>--help</entry>
<entry>Show help about options.</entry>
</row>

<row>
<entry>--help-qt</entry>
<entry>Show Qt specific options.</entry>
</row>

<row>
<entry>--help-kde</entry>
<entry>Show KDE specific options.</entry>
</row>

<row>
<entry>--help-all</entry>
<entry>Show all options.</entry>
</row>

<row>
<entry>--author</entry>
<entry>Show author information.</entry>
</row>

<row>
<entry>-v, --version</entry>
<entry>Show version information.</entry>
</row>

<row>
<entry>--license</entry>
<entry>Show license information.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

<para>The Amarok options:</para>

<note><para>The &amarok; options are designed to be used while &amarok; is running.</para></note>

<informaltable>
<tgroup cols="2">
<thead>

<row>
<entry>Option</entry>
<entry>Action</entry>
</row>
</thead>
<tbody>

<row>
<entry>-r, --previous</entry>
<entry>Skip to the previous track in the playlist.</entry>
</row>

<row>
<entry>-p, --play</entry>
<entry>Start playing current playlist.</entry>
</row>

<row>
<entry>-s, --stop</entry>
<entry>Stop playback.</entry>
</row>

<row>
<entry>--pause</entry>
<entry>Pause playback.</entry>
</row>

<row>
<entry>-f, --next</entry>
<entry>Skip to the next track in the playlist.</entry>
</row>

<row>
<entry>-a, --append</entry>
<entry>Append Files/URLs into the playlist.</entry>
</row>

<row>
<entry>-e, --enqueue</entry>
<entry>See append, available for backwards compatability.</entry>
</row>

<row>
<entry>--queue</entry>
<entry>Queue Files/URLs after the currently playing track.</entry>
</row>

<row>
<entry>-m, --toggle-playlist-window</entry>
<entry>Toggle the playlist window.</entry>
</row>

<row>
<entry>--wizard</entry>
<entry>Launch the First-run wizard.</entry>
</row>

<row>
<entry>--engine "name"</entry>
<entry>Start &amarok; with the "name" engine.</entry>
</row>

</tbody>
</tgroup>
</informaltable>

</sect1>


<sect1 id="script-writing">
<title>Script Writing</title>

<para>Scripting allows you to extend &amarok; easily without changing the main codebase. Scripts are similar to plugins, but instead of a dedicated plugin API they use &amarok;'s DCOP interface for communication. This makes it possible to write scripts in almost any programming language, like Ruby, Python or PHP. Not only can you create scripts in classic scripting languages, but also in compiled languages like C++ or plain C. Additionally, &amarok; can notify the scripts on special events and make them react accordingly. This notification system will be explained later in this section.</para>

<sect2 id="script-bindings">
<title>Bindings</title>

<para>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).</para>

<para>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.</para>

<para>This example shows how to catch a missing dependency in Ruby:</para>

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

</sect2>

<sect2 id="script-templates">
<title>Getting Started: The Templates</title>

<para>&amarok; provides template scripts for several languages in the <filename class="directory">scripts/templates/</filename> 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.</para>

</sect2>

<sect2 id="script-controlling-amarok">
<title>Controlling &amarok; With DCOP</title>

<para>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.</para>

<para>Here is an example for increasing the master volume:</para>

<programlisting>dcop amarok player volumeUp</programlisting>

<para>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:</para>

<programlisting>
 import os
 os.system("dcop amarok player volumeDown")
</programlisting>

</sect2>

<sect2 id="script-notifications">
<title>Notifications</title>

<para>&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.</para>

<para>The following notifications are sent by &amarok;:</para>

<programlisting>
<cmdsynopsis><command>configure</command></cmdsynopsis>
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.
</programlisting>

<programlisting>
<cmdsynopsis><command>engineStateChange:</command><arg>empty|idle|paused|playing</arg></cmdsynopsis>
Signals a change in the engine's state.
</programlisting>

<programlisting>
<cmdsynopsis><command>trackChange</command></cmdsynopsis>
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.
</programlisting>

<programlisting>
<cmdsynopsis><command>volumeChange</command><arg>newVolume</arg></cmdsynopsis>
Signals a change of the master volume level. The volume is an integer with a
range of 0-100.
</programlisting>

<programlisting>
<cmdsynopsis><command>customMenuClicked:</command><arg>submenu itemTitle paths</arg></cmdsynopsis>
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 )'.
</programlisting>

</sect2>

<sect2 id="script-termination">
<title>Script Termination</title>

<para>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.</para>

</sect2>

<sect2 id="script-packaging">
<title>Packaging</title>

<para>&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.</para>

<note><para>&amarok; 1.3 will only accept script packages with the amarokscript extension, so it is better to use it right from the start.</para></note>

<para>The tarball's content must be organized as follows:</para>

<programlisting>
myscript/
   README
   myscript.py (executable)
   somemodule.py
   foo.data
   ...
</programlisting>

</sect2>

<sect2 id="script-permissions">
<title>File permissions</title>

<para>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:</para>

<programlisting>tar -cf myscript.amarokscript.tar -p myscript</programlisting>

<note><para>&amarok; will not be able to install the script if the permissions are not correctly set.</para></note>

</sect2>

<sect2 id="script-distributing">
<title>Distributing</title>

<para>When the package is finished, you can upload it to <ulink url="http://www.kde-apps.org">www.kde-apps.org</ulink>, and add the link to the &amarok; <ulink url="http://amarok.kde.org/amarokwiki/index.php/Scripts">Wiki Scripts Page</ulink>. For the kde-apps entry you should use the <ulink url="http://kde-apps.org/index.php?xcontentmode=56">&amarok; Scripts</ulink> category.</para>

</sect2>

</sect1>


</chapter>