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. |
The Mediabrowser
In other words, `dcop amarok mediabrowser`:
| void deviceConnect () | Connect the current media device. |
| void deviceDisconnect () | Disconnect the current media device. |
| void deviceSwitch ( QString name ) | Switch the current media device |
| QStringList deviceList () | List available media devices. |
| void queue ( KURL url ) | Add url to the transfer queue. |
| void queueList ( KURL::List url ) | Add list of urls to the transfer queue. |
| void transfer () | Transfer items in the queue to the current device. |
| void transcodingFinished ( QString src, QString dest ) | Announce that transcoding of job is finished. |
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.