Amarok/Archives/DCOPFunctions

The Amarok 1.4 DCOP Functions

The Player

In other words, `dcop amarok player`:

bool dynamicModeStatus()	Return dynamic mode status.
bool equalizerEnabled()	Return the equalizer status.
bool isPlaying()	Return true if something is playing now.
bool osdEnabled()	Returns true if the Onscreen Display is enabled
bool randomModeStatus()	Return random mode status.
bool repeatPlaylistStatus()	Return repeat playlist status.
bool repeatTrackStatus()	Return repeat track status.
int getVolume()	Return volume in range 0-100%.
int rating()	Return rating of current song
int sampleRate()	Return the sample rate of the currently playing track.
int score()	Return the score of the currently playing track.
int status()	Return playback status: 0 - stopped, 1 - paused, 2 - playing. < 0 - error
int trackCurrentTime()	Return current play position in seconds.
int trackPlayCounter()	Return play counter for current song.
int trackTotalTime()	Return track length in seconds.
QString album()	Return the album of the currently playing track.
QString artist()	Return the artist of the currently playing track.
QString bitrate()	Return the bitrate of the currently playing track (XX kbps).
QString comment()	Return the comment of the currently playing track.
QString coverImage()	Return the encoded URL of the current track's cover image
QString currentTime()	Return the position of the currently playing track ([h:]mm:ss format).
QString encodedURL()	Return the encoded URL of the currently playing track.
QString engine()	Return the current sound engine.
QString genre()	Return the genre of the currently playing track.
QString lyrics()	Return the lyrics of the currently playing track.
QString lyricsByPath(QString path)	Return the lyrics of a track by path.
QString nowPlaying()	The title of now playing media.
QString path()	Return the unencoded path of the currently playing track.
QString setContextStyle(QString)	Set the CSS style for the context browser
QString title()	Return the title of the currently playing track.
QString totalTime()	Return the total length of the currently playing track ([h:]mm:ss format).
QString track()	Return the track number.
QString type()	Return the file type.
QString version()	returns version of amaroK
QString year()	Return the year of the currently playing track.
QStringList labels()	Return the labels of the currently playing track.
void configEqualizer()	Toggle equalizer config dialog.
void enableOSD(bool enable)	Switch OSD display on or off.
void enableRandomMode(bool enable)	Switch Random Mode on or off.
void enableRepeatPlaylist(bool enable)	Switch Repeat Playlist on or off.
void enableRepeatTrack(bool enable)	Switch Repeat Track on or off.
void mediaDeviceMount()	Sets the command used for mounting media device.
void mediaDeviceUmount()	Sets the comment used for umounting media device.
void mute()	Toggle mute.
void next()	Equivalent to pressing "Next" button.
void pause()	Equivalent to pressing "Pause" button.
void play()	Equivalent to pressing "Play" button.
void playPause()	Toggle play/pause state (good for mm keyboard users)
void prev()	Equivalent to pressing "Prev" button.
void queueForTransfer(KURL url)	Queue file for transfer to Media Device.
void seek(int s)	Seek track to seconds position.
void seekRelative(int s)	Seek to a position relative to the current track position.
void setEqualizer(int, int, int, int, int, int, int, int, int, int, int)	Set the equalizer bands
void setEqualizerEnabled(bool active)	Toggle equalizer.
void setEqualizerPreset(QString name)	Set the equalizer preset
void setLyricsByPath(QString url, QString lyrics)	Set the lyrics of a track by it's path.
void setRating(int rating)	set the rating of the currently playing track.
void setRatingByPath(QString url, int rating)	Set rating of a track by it's path
void setScore(int score)	Set the score of the currently playing track.
void setScoreByPath(QString url, int score)	Set the score of a track by it's path.
void setVolume(int volume)	Set volume in range 0-100%.
void setVolumeRelative(int ticks)	Set volume relative to current volume
void showBrowser(QString browser)	Shows browsers in the playlist window.
void showOSD()	Show the OSD display on the screen.
void stop()	Equivalent to pressing "Stop" button.
void transferDeviceFiles()	Transfer files to media device.
void volumeDown()	Decrease volume by a reasonable step.
void volumeUp()	Increase volume by a reasonable step.

The Playlist

In other words, `dcop amarok playlist`:

int getActiveIndex()	Return the index of the currently active track. -1 if none.
int getTotalTrackCount()	Return number of tracks in playlist. 0 if none.
QString saveCurrentPlaylist()	Saves the current playlist to current.xml and returns its path.
void addMedia(KURL)	Add audio media specified by the url.
void addMediaList(KURL::List)	Add some audio media specified by the url.
void clearPlaylist()	Clears the playlist.
void playByIndex(int)	Starts playing the track at the specified index.
void playMedia(KURL)	Add audio media specified by the url.
void popupMessage(QString)	Shows a temporary popup message.
void removeCurrentTrack()	Removes the current-track item from the playlist.
void repopulate()	Repopulate the playlist with random tracks.
void saveM3u(QString path, bool relativePaths)	Saves the current playlist as m3u.
void setStopAfterCurrent(bool)	Enables/disables the "Stop After Current Track" feature.
void shortStatusMessage(QString)	Shows a temporary message on the statusbar.
void shufflePlaylist()	Shuffles the playlist.
void togglePlaylist()	Toggle the Playlist-window.

The Playlist Browser

In other words, `dcop amarok playlistbrowser`:

int loadPlaylist(QString)	Load a playlist at given QString
void addPlaylist(QString)	Add a playlist to the playlist browser.
void addPodcast(QString)	Add a podcast entry to the playlist browser.
void scanPodcasts()	Scan all podcasts for updates.

The Context Browser

In other words, `dcop amarok contextbrowser`:

void showCurrentTrack()	Show the current track in the context browser.
void showLyrics()	Show the lyrics tab in the context browser.
void showLyrics(QCString lyrics)	Show lyrics at given path.
void showWiki()	Show the wikipedia tab in the context browser.

The Collection

In other words, `dcop amarok collection`:

bool isDirInCollection(QString)	Returns true if the given directory exists in collection.
bool movefile(QString oldURL, QString newURL)	Moves file from oldURL to newURL, preserving statistics
int totalAlbums()	Returns the total of albums in the collection.
int totalArtists()	Returns the total of artists in the collection.
int totalCompilations()	Returns the total of compilations in the collection.
int totalGenres()	Returns the total of genres in the collection.
int totalTracks()	Returns the total of tracks in the collection.
int addLabels(QString url, QStringList labels)	Add user-defined labels to the song with the given url. Returns the number of labels which were not already assigned to the track.
void removeLabels(QString url, QStringList oldLabels)	Remove user-defined labels from the song with the given url.
QStringList query(QString sql)	Queries the database via SQL.
QStringList similarArtists(int artists)	Return similar artists of the current tracks, limit to int artists.
void migrateFile(QString oldURL, QString newURL)	Move a file in the collection, keeping stats intact.
void newUniqueIdForFile(QString path)	Generates a new unique id for file at path.
void newUniqueIdForFiles(QStringList list)	Generates a new id for files in list
void scanCollection()	Scan the collection.
void scanCollectionChanges()	Scan the collection for changes only.

The Scripts

In other words, `dcop amarok script`:

bool runScript(QString name)	Starts the script with the given name. Returns true on success.
bool stopScript(QString name)	Stops the script with the given name. Returns true on success.
QString readConfig(QString key)	returns a AmarokConfig configuration entry value from the given key
QStringList listRunningScripts()	Returns a list of all currently running scripts.
QStringList readListConfig(QString key)	AmarokConfig lists must use this function
void addCustomMenuItem(QString submenu, QString itemTitle)	Enables and sets custom menu item title.
void removeCustomMenuItem(QString submenu, QString itemTitle)	Removes the custom menu item.

Devices

In other words, `dcop amarok devices`:

void mediumAdded ()	Called when there is a mediumAdded event.
void mediumRemoved ()	Called when there is a mediumRemoved event.
void mediumChanged ()	Called when there is a mediumChanged event.
QStringList showDeviceList ()	Called to display the DeviceManager's current device list.

Tips for Using the DCOP CLI client

Giving a QStringList argument

The QStringList class needs to be delimited from the rest of the DCOP command with delimiters of your choosing: [], (), $$, etc.

E.g. To add labels to a file, issue:

dcop amarok collection addLabels /path/to/song.mp3 [ "Electronica" "Not Very Good" ]

DCOP should return 2 assuming both labels were new to the song. If your formatting is incorrect, you'll likely see an error like:

Not enough arguments (expected 2, got 2).

Check that you have a space between the delimiter and the quotation marks.