# Advanced amaroK features

## Keyboard Shortcuts

&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 Configure Global Shortcuts... The &amarok; shortcuts can be configured by right clicking the Player window and selecting Configure Shortcuts...

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

The global shortcuts are:

Key Combination | Action
--- | ---
Win X | Play
Win C | Pause
Win V | Stop
Win B | Next Track
Win Z | Previous Track
Win KP_Add | Increase Volume
Win KP_Subtract | Decrease Volume
Win Shift KP_Add | Seek Forward
Win Shift KP_Subtract | Seek Backward
Win A | Add Media
Win P | Toggle Playlist
Win O | Show OSD
Win M | Mute Volume

The &amarok; shortcuts are:

Key Combination | Action
--- | ---
Ctrl C | Copy
Ctrl KP_Enter | Goto Current
Ctrl D | Queue Selected Tracks
Ctrl Q | Quit
Ctrl Shift Z | Redo
Ctrl S | Save Playlist
Ctrl A | Select All
Ctrl M | Show Menubar
Ctrl H | Shuffle
Ctrl Z | Undo

The Playlist Browser shortcuts are:

Key Combination | Action
--- | ---
Space | Load Playlist
F2 | Rename Playlist
Backspace | Remove Playlist

## The DCOP Interface

The amaroK DCOP interface provides you with an easy way to control amaroK with your own custom scripts.

The DCOP interface for amaroK has many generic calls that may be found in other KDE applications. This section is divided into four tables and is intended to describe the DCOP calls of the collection, player, playlist, and scripts. An example of the pause dcop call would look like:

&percnt;dcop amarok player pause

### dcop amarok collection

DCOP Call | Action
--- | ---
query | The query call allows you to send direct database queries to &amarok;'s collection.
scanCollection | The scanCollection call performs a manual scan of your collection.
scanCollectionChanges | The scanCollectionChanges call performs a manual scan for changes to your collection.
similarArtists | The similarArtists call returns the similar artists of the current track. Results are limited to an integer value of artists.
totalAlbums | The totalAlbums call returns the total number of albums in your collection.
totalArtists | The totalArtists call returns the total number of artists in your collection.
totalCompilations | The totalCompilations call returns the total number of compilations in your collection.
totalGenres | The totalGenres call returns the total number of genres in your collection.
totalTracks | The totalTracks call returns the total number of tracks in your collection.

### dcop amarok player

DCOP Call | Action
--- | ---
album | The album call returns the album of the currently playing track.
artist | The artist call returns the artist of the currently playing track.
bitrate | The bitrate call returns the bitrate of the currently playing track.
comment | The comment call returns the comment of the currently playing track.
coverImage | The coverImage call returns the URL to the current track's cover image.
currentTime | The currentTime call returns the position (mm:ss) of the currently playing track.
encodedURL | The encodedURL returns the URL for the current track with spaces encoded.
engine | The engine returns the current audio engine.
genre | The genre call returns the genre of the currently playing track.
lyrics | The lyrics call returns the cached lyrics of the currently playing track.
lyricsByPath | The lyricsByPath call returns the cached lyrics of a track specified by it's path.
nowPlaying | The nowPlaying call returns Artist - Title of the currently playing track. If one of both id3 tags is empty, only Artist or Title is shown (without the -).
path | The path call returns the filesystem path to the current track.
setContextStyle | The setContextStyle call sets the Context Browser's CSS theme specified by it's name.
title | The title call returns the title of the currently playing track.
totalTime | The totalTime call returns the total time (mm:ss) of the currently playing track.
track | The track call returns the track number of the current track.
year | The year call returns the year of the currently playing track.
dynamicModeStatus | The dynamicModeStatus call returns a value of true or false to indicate if the dynamic mode is enabled.
equalizerEnabled | The equalizerEnabled call returns a value of true or false to indicate if the equalizer is enabled.
isPlaying | The isPlaying call returns a value of true or false to indicate if the player is playing or not.
randomModeStatus | The randomModeStatus call returns the status of Random Mode with a value of true or false.
repeatPlaylistStatus | The repeatPlaylistStatus call returns the status of Repeat Playlist with a value of true or false.
repeatTrackStatus | The repeatTrackStatus call returns the status of Repeat Track with a value of true or false.
getVolume | The getVolume call returns a value for the volume level specified by a value of 0-100.
sampleRate | The sampleRate call returns the sample rate of the current track.
score | The score call returns the current track's score.
setLyricsByPath | The setLyricsByPath call sets the lyrics of a track specified by it's path. Use the lyrics call for viewing examples of proper html formatting.
status | The status call returns a value for the engine status, 2 for playing, 1 for paused, and 0 for idle.
trackCurrentTime | The trackCurrentTime call returns a value of the current elapsed track time in seconds.
trackPlayCounter | The trackPlayCounter call returns the number of times the current track has been played.
trackTotalTime | The trackTotalTime call returns a value of the current track's total time in seconds.
configEqualizer | The configEqualizer call raises the equalizer configuration window.
enableDynamicMode | The enableDynamicMode call is used to toggle the dynamic mode with a value of 0 for disabled, and 1 for enabled.
enableOSD | The enableOSD call allows you to toggle the On-Screen-Display with a true or false value
enableRandomMode | The enableRandomMode call is used to toggle the random mode with a value of 0 for disabled, and 1 for enabled.
enableRepeatPlaylist | The enableRepeatPlaylist call is used to toggle the repeat playlist mode with a value of 0 for disabled, and 1 for enabled.
enableRepeatTrack | The enableRepeatTrack call is used to toggle the repeat track mode with a value of 0 for disabled, and 1 for enabled.
mute | The mute call allows you to mute and unmute the playing track.
next | The next call advances the player one track.
pause | The pause call pauses the currently playing track.
play | The play call starts the player from where it was last stopped.
playPause | The playPause call starts the player if it is currently stopped or paused. This call also pauses the player if it is currently playing a track.
prev | The prev call moves the player back one track.
seek | The seek call is used to seek to a specific point in a track by a value specified in seconds.
seekRelative | The seekRelative call is used to seek to a position relative to the current track position by a value specified in seconds.
setEqualizer | The setEqualizer call uses eleven space delimited integers to set the equalizer slider values. The slider values range from -255 as the lowest value, and 255 as the highest. The first integer is used to set the pre-amp value, the remaining integers set the pre-amp response frequency values from 60Hz to 16kHz.
setEqualizerEnabled | The setEqualizerEnabled call is used to enable the equalizer using a true or false value.
setScore | The setScore call sets the score of the current track specified by a number from 0 to 100.
setScoreByPath | The setScoreByPath call sets the score of a track specified by it's path followed by it's score specified by a number from 0 to 100.
setVolume | The setVolume call adjusts the volume to a level specified by a value from 0 to 100.
showBrowser | The showBrowser calls shows a browser in the playlist window. Valid browser values are context, collection, playlist, media and file.
showOSD | The showOSD call raises the OSD to show the current track information.
stop | The stop call will stop the player if it is currently playing.
volumeDown | The volumeDown call adjusts the volume down one step.
volumeUp | The volumeUp call adjusts the volume up one step.

### dcop amarok playlist

DCOP Call | Action
--- | ---
saveCurrentPlaylist | The saveCurrentPlaylist call saves the current playlist as ~/.kde/share/apps/amarok/current.xml.
getActiveIndex | The getActiveIndex call returns an integer value for the current track's position in the playlist.
getTotalTrackCount | The getTotalTrackCount call returns the total number of tracks in the playlist.
addMedia | The addMedia call is used to add single files to the playlist.
addMediaList | The addMediaList call is used to add multiple files to the playlist.
clearPlaylist | The clearPlaylist call is used to clear the entire playlist.
playByIndex | The playByIndex call starts playback of a track by it's position in the playlist.
playMedia | The playMEDIA call starts playback of a track specified by it's KURL.
popupMessage | The popupMessage call starts a popup mesage in the playlist window. The popup message is specified with a QString.
repopulate | The repopulate call repopulates the playlist with tracks from dynamic mode.
removeCurrentTrack | The removeCurrentTrack call removes the current track from the playlist.
saveM3u | The saveM3u call saves the current playlist in the M3U format. You must specify the path to save the file as, and include a value of 0 or 1 to indicate whether or not to write relative paths.
setStopAfterCurrent | The setStopAfterCurrent call stops playback of the playlist after the current track has completed.
shortStatusMessage | The shortStatusMessage call displays a string of text as a message in the status bar.
shufflePlaylist | The shufflePlaylist call randomizes the order of the tracks in the playlist.
togglePlaylist | The togglePlaylist call toggles the use of the playlist window either on or off.

### dcop amarok script

DCOP Call | Action
--- | ---
listRunningScripts | The listRunningScripts call will list all running &amarok; scripts.
runScript | The runScript call will start an &amarok; script specified by it's name.
stopScript | The stopScript call will stop an &amarok; script specified by it's name.
addCustomMenuItem | The addCustomMenuItem call adds a menu item to the playlist context menu. This call takes two QStrings, the first for the submenu title, the second for the item's title in the submenu. Both QStrings are returned in the script manager notification system.
removeCustomMenuItem | The removeCustomMenuItem call removes menu items added to the playlist context menu using the addCustomMenuItem call. This call uses the same QStrings as addCustomMenuItem.

## Command-line Options

amaroK supports the use of the standard Qt and kde command line options. amaroK also has it's own application specific options.

The Qt and kde options:

Option | Action
--- | ---
--help | Show help about options.
--help-qt | Show Qt specific options.
--help-kde | Show KDE specific options.
--help-all | Show all options.
--author | Show author information.
-v, --version | Show version information.
--license | Show license information.

The amaroK options:

The &amarok; options are designed to be used while &amarok; is running.

Option | Action
--- | ---
-r, --previous | Skip to the previous track in the playlist.
-p, --play | Start playing current playlist.
-s, --stop | Stop playback.
--pause | Pause playback.
-f, --next | Skip to the next track in the playlist.
-a, --append | Append Files/URLs into the playlist.
-e, --enqueue | See append, available for backwards compatability.
--queue | Queue Files/URLs after the currently playing track.
-m, --toggle-playlist-window | Toggle the playlist window.
--wizard | Launch the First-run wizard.
--engine "name" | Start &amarok; with the "name" engine.

## Script Writing

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.

### Bindings

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

### Getting Started: The Templates

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

### Controlling &amarok; With DCOP

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")

### Notifications

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

    volumeChangenewVolume
    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 )'.

### Script Termination

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.

### Packaging

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

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

The tarball's content must be organized as follows:

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

### File permissions

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

&amarok; will not be able to install the script if the permissions are not correctly set.

### Distributing

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.