Amarok Scripting Sven Krohlas LinuxTag Berlin,

Overview Scripting? D-Bus QtScript Hints Example: Free Music Charts script NEW: Scripted Context Applets Further reading Questions?

Scripting? ● Communication with external apps ● Specialized Features ● Easy upgradeable – Lyrics ● Examples: BBC, NPR, LibriVox.org, Alarm, Free Music Charts, etc

Scripting? ● D-Bus interface for external apps – Similar to DCOP in Amarok 1.4 – MPRIS 1.0 compliant ● QtScript for internal enhancements – New in Amarok 2

D-Bus ● Media Player Remote Interfacing Specification ● Very basic interface ● ● Use QtScript for advanced and internal stuff!

D-Bus examples ● Who's here? – qdbus org.kde.amarok / Identity ● Start playback – qdbus org.kde.amarok /Player Play ● Pause playback – qdbus org.kde.amarok /Player Pause ● Change volume – qdbus org.kde.amarok /Player VolumeSet 50

QtScript ● ECMA Script with Qt bindings ● Three kinds of Amarok scripts: – Generic – Scriptable Service – Lyrics ● Type defined in script.spec file

QtScript: Why? ● No extra dependencies ● Works out of the box ● On all supported platforms ● Use QtScript whereever possible!

QtScript: script.spec [Desktop Entry] Icon=amarok Type=script ServiceTypes=KPluginInfo Name=Free Music Charts Comment=Listen to the Darkerradio.com Free Music Charts X-KDE-PluginInfo-Author=Sven Krohlas X-KDE-PluginInfo-Name=Free Music Charts X-KDE-PluginInfo-Version=1.3.0 X-KDE-PluginInfo-Category=Scriptable Service X-KDE-PluginInfo-Website= X-KDE-PluginInfo-Depends=Amarok2.0 X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=false

QtScript: Qt bindings ● Access to nearly all Qt modules: – qt.core – qt.gui – qt.network – qt.xml – qt.sql – qt.uitools

QtScript: Amarok API (1) ● Controlling Amarok: – Amarok.Collection – Amarok.Engine – Amarok.Info – Amarok.Lyrics – Amarok.Playlist – Amarok.Script – Amarok.Window ● Amarok.Window.OSD ● Amarok.Window.Statusbar

QtScript: Amarok API (2) ● “Tools & Utilities”: – Importer ● Importer.loadQtBinding( “qt.foo” ); – Scriptable Services – Downloader ● Downloader: text ● DataDownloader: Binary data

Hints: SVN ● Use our public SVN – amarok/playground/ – Get code reviews – Get help – New maintainers – Fast adoption of API changes – etc.

Hints: Linux/Windows/Mac ● Differences in the QtScript interpreter on different plattforms! ● Example: ● doc=new QDomDocument( "doc" ); ● Amarok.debug( doc ); ● Linux, Qt 4.4: OK - Windows: fail

Hints: Qt 4.4 vs. Qt 4.5 ● Amarok.Window.ToolsMenu.votingGui.trigg ered.connect( onVote ); ● Qt 4.4: OK - Qt 4.5: fail: ● amarok: [ScriptManager] [ERROR!] Script Error: "01:46:50 Error: Function.prototype.connect: ambiguous connect to KAction::triggered(); candidates are ● triggered(), triggered(bool), triggered(Qt::MouseButtons,Qt::KeyboardModifiers) ● Use e.g. object['triggered(Qt::MouseButtons,Qt::KeyboardModifiers)'].connect () to connect to a particular overload on Line: 177"

Hints ● → Test on different platforms with different Qt versions! ● Detailled debug output: – Call amarok -d from a shell (*nix) – Plus DebugView (Windows)

Hints: Script Console ● Great for debugging :-)

Hints: Amarok URLs ● New in Amarok 2.1 ● amarok:/ ● Can be used e.g. in the service info – amarok://navigate/service/Librivox.org/”Jules Verne” – Example: Free Music Charts ● Bookmarks

Hints ● Use our public SVN (again!) ● kde-apps.org – Lots of examples – Release there to show up in our Script Manager

Example: Free Music Charts

Scripted Applets (NEW in 2.2) ● Context Applets written in scripting languages ● Please use QtScript only! – amarok.kde.org /blog/archives/1017-time-to-take-it-away.html

Scripted Applets plasmoid.drawAppletBackground = function() { return true; } plasmoid.dataUpdate = function(a, b) { if ( b.current ) label.text = "Playing " + b.current[ "xesam:title" ] + " from " + b.current[ "xesam:author" ] + " on " + b.current[ "xesam:album" ]; } layout = new LinearLayout( plasmoid ); layout.setAlignment( 2 ); label1 = new Label( ); label1.text = "This is a javascript applet. Just to show off that we can get data from c++ dataengines, here's info on the currently playing track:"; layout.addItem( label1 ); label = new Label(); layout.addItem( label ); label.text = "This is a Javascript Applet"; plasmoid.dataEngine("amarok-current").connectSource( "current", plasmoid );

Further reading ● Qt 4.4 documentation – ● Amarok Scripting HowTo – ● Amarok Scripting API – ● Scripted Services Tutorial – ● Using.ui files –

Questions?

Easy Workshop Tasks ● Small, minimal UI ● GUI to change playlist mode – In Context View or as external app ● Tool to add missing XING headers ● Now Playing Plugin(s) ● Discogs Scripted Applet ●...or whatever comes to your mind