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

</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>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>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 functions that may be found in other KDE applications. This section is divided into two tables and is intended to describe the DCOP functions of the player and playlist. An example of the <quote>pause</quote> dcop function would look like:</para>

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

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

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

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

<row>
<entry>album</entry>
<entry>The <quote>album</quote> function returns the album of the currently playing track.</entry>
</row>

<row>
<entry>artist</entry>
<entry>The <quote>artist</quote> function returns the artist of the currently playing track.</entry>
</row>

<row>
<entry>bitrate</entry>
<entry>The <quote>bitrate</quote> function returns the bitrate of the currently playing track.</entry>
</row>

<row>
<entry>comment</entry>
<entry>The <quote>comment</quote> function returns the comment of the currently playing track.</entry>
</row>

<row>
<entry>coverImage</entry>
<entry>The <quote>coverImage</quote> function returns the URL to the current track's cover image.</entry>
</row>

<row>
<entry>currentTime</entry>
<entry>The <quote>currentTime</quote> function returns the position (mm:ss) of the currently playing track.</entry>
</row>

<row>
<entry>encodedURL</entry>
<entry>The <quote>encodedURL</quote> returns the URL for the current track with spaces encoded.</entry>
</row>

<row>
<entry>genre</entry>
<entry>The <quote>genre</quote> function returns the genre of the currently playing track.</entry>
</row>

<row>
<entry>nowPlaying</entry>
<entry>The <quote>nowPlaying</quote> function returns "Artist - Title" of the currently playing track. If one of both id3 tags is empty, only "Artist" or "Title" is shown (without the "-").</entry>
</row>

<row>
<entry>title</entry>
<entry>The <quote>title</quote> function returns the title of the currently playing track.</entry>
</row>

<row>
<entry>totalTime</entry>
<entry>The <quote>totalTime</quote> function returns the total time (mm:ss) of the currently playing track.</entry>
</row>

<row>
<entry>track</entry>
<entry>The <quote>track</quote> function returns the track number of the current track.</entry>
</row>

<row>
<entry>year</entry>
<entry>The <quote>year</quote> function returns the year of the currently playing track.</entry>
</row>

<row>
<entry>isPlaying</entry>
<entry>The <quote>isPlaying</quote> function returns a value of true or false to indicate if the player is playing or not.</entry>
</row>

<row>
<entry>randomModeStatus</entry>
<entry>The <quote>randomModeStatus</quote> function returns the status of Random Mode with a value of true or false.</entry>
</row>

<row>
<entry>repeatPlaylistStatus</entry>
<entry>The <quote>repeatPlaylistStatus</quote> function returns the status of Repeat Playlist with a value of true or false.</entry>
</row>

<row>
<entry>repeatTrackStatus</entry>
<entry>The <quote>repeatTrackStatus</quote> function returns the status of Repeat Track with a value of true or false.</entry>
</row>

<row>
<entry>getVolume</entry>
<entry>The <quote>getVolume</quote> function returns a value for the volume level specified by a value of 0-100.</entry>
</row>

<row>
<entry>sampleRate</entry>
<entry>The <quote>sampleRate</quote> function returns the sample rate of the current track.</entry>
</row>

<row>
<entry>score</entry>
<entry>The <quote>score</quote> function returns the current track's score.</entry>
</row>

<row>
<entry>status</entry>
<entry>The <quote>status</quote> function returns a value for the engine status, 2 for playing, 1 for paused, and 0 for idle.</entry>
</row>

<row>
<entry>trackCurrentTime</entry>
<entry>The <quote>trackCurrentTime</quote> function returns a value of the current elapsed track time in seconds.</entry>
</row>

<row>
<entry>trackPlayCounter</entry>
<entry>The <quote>trackPlayCounter</quote> function returns the number of times the current track has been played.</entry>
</row>

<row>
<entry>trackTotalTime</entry>
<entry>The <quote>trackTotalTime</quote> function returns a value of the current track's total time in seconds.</entry>
</row>

<row>
<entry>configEqualizer</entry>
<entry>The <quote>configEqualizer</quote> function raises the equalizer configuration window.</entry>
</row>

<row>
<entry>enableOSD</entry>
<entry>The <quote>enableOSD</quote> function allows you to toggle the On-Screen-Display with a true or false value</entry>
</row>

<row>
<entry>enableRandomMode</entry>
<entry>The <quote>enableRandomMode</quote> function is used to toggle the random mode with a value of 0 for disabled, and 1 for enabled.</entry>
</row>

<row>
<entry>mute</entry>
<entry>The <quote>mute</quote> function allows you to mute and unmute the playing track.</entry>
</row>

<row>
<entry>next</entry>
<entry>The <quote>next</quote> function advances the player one track.</entry>
</row>

<row>
<entry>pause</entry>
<entry>The <quote>pause</quote> function pauses the currently playing track.</entry>
</row>

<row>
<entry>play</entry>
<entry>The <quote>play</quote> function starts the player from where it was last stopped.</entry>
</row>

<row>
<entry>playPause</entry>
<entry>The <quote>playPause</quote> function starts the player if it is currently stopped or paused. This function also pauses the player if it is currently playing a track.</entry>
</row>

<row>
<entry>prev</entry>
<entry>The <quote>prev</quote> function moves the player back one track.</entry>
</row>

<row>
<entry>scanCollection</entry>
<entry>The <quote>scanCollection</quote> function performs a manual scan of your collection.</entry>
</row>

<row>
<entry>seek</entry>
<entry>The <quote>seek</quote> function is used to seek to a specific point in a track by a value specified in seconds.</entry>
</row>

<row>
<entry>seekRelative</entry>
<entry>The <quote>seekRelative</quote> function is used to seek to a position relative to the current track position by a value specified in seconds.</entry>
</row>

<row>
<entry>setContextStyle</entry>
<entry></entry>
</row>

<row>
<entry>setEqualizer</entry>
<entry>The <quote>setEqualizer</quote> function 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.</entry>
</row>

<row>
<entry>setEqualizerEnabled</entry>
<entry>The <quote>setEqualizerEnabled</quote> function is used to enable the equalizer using a true or false value.</entry>
</row>

<row>
<entry>setVolume</entry>
<entry>The <quote>setVolume</quote> function adjusts the volume to a level specified by a value of 0-100.</entry>
</row>

<row>
<entry>showOSD</entry>
<entry>The <quote>showOSD</quote> function raises the OSD to show the current track information.</entry>
</row>

<row>
<entry>stop</entry>
<entry>The <quote>stop</quote> function will stop the player if it is currently playing.</entry>
</row>

<row>
<entry>volumeDown</entry>
<entry>The <quote>volumeDown</quote> function adjusts the volume down one step.</entry>
</row>

<row>
<entry>volumeUp</entry>
<entry>The <quote>volumeUp</quote> function adjusts the volume up one step.</entry>
</row>

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

</sect2>

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

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

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

<row>
<entry>getActiveIndex</entry>
<entry>The <quote>getActiveIndex</quote> function returns an integer value for the current track's position in the playlist.</entry>
</row>

<row>
<entry>addMedia</entry>
<entry>The <quote>addMedia</quote> function is used to add single files to the playlist.</entry>
</row>

<row>
<entry>addMediaList</entry>
<entry>The <quote>addMediaList</quote> function is used to add multiple files to the playlist.</entry>
</row>

<row>
<entry>clearPlaylist</entry>
<entry>The <quote>clearPlaylist</quote> function is used to clear the entire playlist.</entry>
</row>

<row>
<entry>playByIndex</entry>
<entry>The <quote>playByIndex</quote> function starts playback of a track by it's position in the playlist. </entry>
</row>

<row>
<entry>playMedia</entry>
<entry>The <quote>playMEDIA</quote> function starts playback of a track specified by it's KURL.</entry>
</row>

<row>
<entry>saveCurrentPlaylist</entry>
<entry>The <quote>saveCurrentPlaylist</quote> function saves the current playlist as ~/.kde/share/apps/amarok/current.xml.</entry>
</row>

<row>
<entry>setStopAfterCurrent</entry>
<entry>The <quote>setStopAfterCurrent</quote> function stops playback of the playlist after the current track has completed.</entry>
</row>

<row>
<entry>shortStatusMessage</entry>
<entry>The <quote>shortStatusMessage</quote> function displays a string of text as a message in the status bar.</entry>
</row>

<row>
<entry>shufflePlaylist</entry>
<entry>The <quote>shufflePlaylist</quote> function randomizes the order of the tracks in the playlist.</entry>
</row>

<row>
<entry>togglePlaylist</entry>
<entry>The <quote>togglePlaylist</quote> function toggles the use of the playlist window either on or off.</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>

</chapter>
