1. Amarok Scripting Sven Krohlas sven@getamarok.com LinuxTag Berlin, 2009-06-24

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

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

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

5. D-Bus ● Media Player Remote Interfacing Specification ● Very basic interface ● http://wiki.xmms2.xmms.se/wiki/MPRIS ● Use QtScript for advanced and internal stuff!

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

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

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

9. 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-Email=sven@getamarok.com X-KDE-PluginInfo-Name=Free Music Charts X-KDE-PluginInfo-Version=1.3.0 X-KDE-PluginInfo-Category=Scriptable Service X-KDE-PluginInfo-Website=http://krohlas.de/ X-KDE-PluginInfo-Depends=Amarok2.0 X-KDE-PluginInfo-License=GPL X-KDE-PluginInfo-EnabledByDefault=false

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

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

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

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

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

15. 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"

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

17. Hints: Script Console ● Great for debugging :-)

18. 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 1.3.1 ● Bookmarks

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

20. Example: Free Music Charts

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

23. 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 );

24. Further reading ● Qt 4.4 documentation – http://doc.trolltech.com/4.4/ ● Amarok Scripting HowTo – http://amarok.kde.org/wiki/Development/Scripting_HowTo_2.0 ● Amarok Scripting API – http://amarok.kde.org/wiki/Development/Script_API ● Scripted Services Tutorial – http://amarok.kde.org/wiki/Development/Scripted_Services_Tutorial_2.0 ● Using.ui files – http://www.peterzl.net/en/?p=99

25. Questions?

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