Amarok/Development/Script API

Tools

• Simple Object Inspector - shows Amarok JS objects
• Amarok Script Console

Amarok

methods:

• void quitAmarok()
• void debug( String text )

- To print debug output to the shell. Only works when Amarok was started with --debug option.

• int alert( String text, String type = "information" )

- To invoke a KDE messagebox, this function is provided for convenience. The type should be one of the following: "error", "sorry", "information", "questionYesNo", "questionYesNoCancel", "warningYesNo", "warningContinueCancel", "warningYesNoCancel". The function will return -1 if no user choice is involved.

Amarok.alert( "hey, this is an alert" );

• void end()

- Signals Amarok that the script has ended.

• bool runScript( String name )
• bool stopScript( String name )
• String[] listRunningScripts()

Amarok.CollectionManager

methods:

• int totalAlbums()
• int totalArtists()
• int totalComposers()
• int totalGenres()
• int totalTracks()
• String[] collectionLocation()
• String[] query( String sql )
• String[] escape( String sql )
• void scanCollection()
• void scanCollectionChanges()
• bool isDirInCollection( String path )

Amarok.Engine

methods:

• void Play()
• void Stop( bool forceInstant = false )
• void Pause()
• void Next()
• void Prev()
• void PlayPause()
• void PlayAudioCD()
• void Seek( int ms )
• void SeekRelative( int ms )
• void SeekForward( int ms = 10000 )
• void SeekBackward( int ms = 10000 )
• int IncreaseVolume( int ticks = 100/25 )
• int DecreaseVolume( int ticks = 100/25 )
• void Mute()
• int trackPosition()
• int trackPositionMs()
• int engineState()
• QVariant currentTrack()

properties:

• bool randomMode
• bool dynamicMode
• bool repeatPlaylist
• bool repeatTrack
• int volume
• int fadeoutLength

signals:

• void trackFinished()
• void trackChanged()
• void trackSeeked( int )
• void volumeChanged( int )
• void trackPlayPause( int )

Amarok.Info

methods:

• String scriptPath()
• String scriptConfigPath( String name )
• String iconPath( String name, int size )
• String version()

Amarok.Lyrics

methods:

• void showLyrics( String lyrics )
• void showLyricsHtml( String lyrics )
• void setLyricsForTrack( String trackUrl , String lyrics )
• String toUtf8( QByteArray& lyrics, String encoding = "UTF-8" )
• String StringtoUtf8( String lyrics, String encoding = "UTF-8" )
• QByteArray fromUtf8( String str, String encoding )

signals:

• void fetchLyrics( String artist, String title, String )

Amarok.Playlist

methods:

• int activeIndex()
• int totalTrackCount()
• String saveCurrentPlaylist()
• void addMedia( QUrl &url )
• void addMediaList( QList<QUrl> &urls )
• void clearPlaylist()
• void playByIndex( int index )
• void playMedia( QUrl &url )
• void removeCurrentTrack()
• void removeByIndex( int index )
• void savePlaylist( String path )
• void setStopAfterCurrent( bool on )
• bool stopAfterCurrent()
• void togglePlaylist()
• String[] filenames()
• Track trackAt( int row )
• int[] selectedIndexes()
• String[] selectedFilenames()

signals:

• void trackRemoved(int start, int end)
• void trackInserted(int start, int end)

Amarok.Script

methods:

• QVariant readConfig( String name, QVariant defaultValue )
• String readConfig( String name, String defaultValue )
• void writeConfig( String name, QVariant content )
• void writeConfig( String name, String content )

Amarok.Window

methods:

• bool addToolsMenu( String id, String MenuTitle, String icon = "amarok" )
• void addToolsSeparator()
• bool addSettingsMenu( String id, String MenuTitle, String icon = "amarok" )
• void addSettingsSeparator()
• void showBrowser( String browser )

signals:

• void prepareToQuit()

Amarok.Window.OSD

methods:

• void showCurrentTrack()
• void show()
• void setDuration( int ms )
• void setTextColor( QColor &color )
• void setOffset( int y )
• void setImage( QImage &image )
• void setScreen( int screen )
• void setText( String &text )
• void setRating( short rating )

Amarok.Window.Statusbar

methods:

• void shortMessage( String &text )
• void longMessage( String &text )

Importer

methods:

• void loadExtension( String src )

See [1].

• void loadQtBinding( String binding )

Choices include:

• qt.core
• qt.gui
• qt.network
• qt.xml
• qt.sql
• qt.uitools

• bool include( String relativeFile )

Includes and executes a JavaScript file. The file location given relative to the currently executing file.

Scriptable Service

methods:

• int insertItem( StreamItem* item )
• int donePopulating()
• void setIcon( QPixmap &icon ) (since Amarok 2.0.1)
• void setEmblem( QPixmap &icon ) (since Amarok 2.0.1)

signals:

• void customize( ) (since Amarok 2.0.1)
• void populate( int, String, String )

ScriptableService.StreamItem

• String itemName()
• String infoHtml()
• String playableUrl()
• String callbackData()
• int level()

• String album()
• String artist()
• String genre()
• String composer()
• int year()

• void setItemName( String name )
• void setInfoHtml( String infoHtml )
• void setPlayableUrl( String playableUrl )
• void setCallbackData( String callbackData )
• void setLevel( int level )

• void setAlbum( String album )
• void setArtist( String artist )
• void setGenre( String genre )
• void setComposer( String composer )
• void setYear( int year )

Network

Downloader

Also aliased as 'StringDownloader' since Amarok 2.1.

 function somefunction(reply){ //do something with the reply, returned as a String }
 new Downloader( "url", somefunction, "encoding" );

The encoding argument is optional, it defaults to utf8.

DataDownloader

Since Amarok 2.1

DataDownloader works essentially just like StringDownloader except the result is a QByteArray instead of a String. The QByteArray requires that Importer.loadQtBinding("qt.core") to be run prior to using it. DataDownloader should be used for fetching files such as images.

 function showImage(reply){ 
     pix = new QPixmap();
     pix.loadFromData( reply );
     label = new QLabel();
     label.pixmap = pix;
     label.show();
 }
 new DataDownloader( "", showImage );

Examples

CurrentTrack

 Amarok.alert(Amarok.Engine.currentTrack().artist)
 Amarok.alert(Amarok.Engine.currentTrack().title)

Timer

A timer event will occur every interval milliseconds until killTimer() is called. If interval is 0, then the timer event occurs once every time there are no more window system events to process.

function timedAlert(interval) {
   var qo = new QObject();    
   qo.event = function(qevent) {           
     Amarok.alert("Timer triggered!");
     this.killTimer(qo.timerID);
   }
   qo.timerID = qo.startTimer(interval);
}

• int interval

Documentation:

• Qt 4.5: QObject Class Reference: startTimer