GSoC Application Review
Anmol Ahuja
darthcodus at gmail.com
Mon Apr 29 18:37:08 UTC 2013
Is this going right? Is the implementation detail really needed?
And for classes like CollectionLocation, should I create wrappers like
CollectionLocationTypeExporter or simple modify the existing class,
changing script evokable functions to public slots/ Q_INVOKABLE? I think
the former would help keep the scripting logic in one place.
*
Short description : My proposal aims at revamping the Amarok scripting
interface, and adding an intuitive Script Creator graphical application
allowing easy script creation by non-coders and coders alike. This involves
getting rid of dangerous and obsolete methods, and adding accessors for all
the new features added to Amarok over the years. Every major type will have
a QtScript object representation, allowing unparalleled scripting
flexibility. I also plan on writing unit tests to allow automated testing
of the Amarok scripting API. The third part involves documentation of the
entire scripting API in-source and automating the generation of Amarok
Scripting API documentation from the in-source documentation. All of this
will lead to a cleaner and more feature rich well-documented scripting API
hopefully generating new interest in Amarok script. Other features I plan
to work upon, if time permits, are allowing users to terminate long running
or stuck scripts instead of forcing a restart, adding GUI handling to the
script creation utility and porting popular Amarok 1.4 scripts, if
possible, to the newer QtScript based interface.
Name : Anmol Ahuja
Email Address : darthcodus at gmail.com
Freenode IRC Nick : darthcodus
IM Service and Username : Gtalk, darthcodus
Location (City, Country and/or Time Zone) : New Delhi, India ( GMT +5:30 )
Proposal Title :
Revamping Amarok’s Scripting Interface
Motivation for Proposal:
Amarok has a thriving scripting community, but the existing scripting API
is:
-
Undocumented
-
Currently, Amarok script functions must be documented manually on the
wiki, and the documentation in its current state only includes only names
of Global objects and methods, with no description or example to clarify
their purpose or usage. [BR
313283<https://bugs.kde.org/show_bug.cgi?id=313283>
]
-
Untested
-
No tests for Amarok’s scripting interface exist as of this writing
-
Unreliable
-
Inconsistent signals [BR
299218<https://bugs.kde.org/show_bug.cgi?id=299218>
]
-
Incomplete
-
No scripting interface for new features added to Amarok over the
years, like saved playlists and playlist object,
CollectionManager, Dynamic
Playlists, etc.
-
Dangerous
-
Allows direct access to the underlying SQL database
-
Obsolete
-
Uses deprecated methods and calls, for instance, the Collection
methods called in AmarokCollectionScript.
Project Goals:
My proposal involves four main parts :
-
Part I : Revamping the Scripting API
-
Clean up existing scripting API and add accessors for the other Amarok
features to the Amarok scripting API ( I will be documenting code as I
write it ) :
-
Add global CollectionManager object
-
Remove AmarokCollectionScript and re-implement as QScriptObject
-
Remove direct SQL access
-
CollectionLocation
-
Transcoding
-
QueryMaker
-
Playlists
-
Dynamic Playlists
-
Automatic Playlist Generator
-
Bookmarks
-
Implement Equalizer support in the AmarokEngineScript
-
Synchronization Job
-
Podcast Management
-
Others
-
Add suspend inhibition to AmarokScript
-
-
Add other requested features/ wishes and fix bugs
-
Bug 213376 <https://bugs.kde.org/show_bug.cgi?id=213376> - Implement
setter for Amarok.Engine.currentTrack().imageURL
- Bug 183497 <https://bugs.kde.org/show_bug.cgi?id=176663> -
Scripting API to add a context menu to everything representing a song or
file
- Bug 187957 <https://bugs.kde.org/show_bug.cgi?id=187957> - Create
submenus from the Scripting interface
- Bug 176663 <https://bugs.kde.org/show_bug.cgi?id=176663> -
Installing a new script requires a restart of amarok
- Bug 23271 <https://bugs.kde.org/show_bug.cgi?id=232711>: - Provide
scripting interface to customize collection display (filter, sort, group,
displayed tags, etc.)
- Bug 205509 <https://bugs.kde.org/show_bug.cgi?id=205509> : Add
dbus functions to update podcasts and download podcast tracks
-
Bug 176663 <https://bugs.kde.org/show_bug.cgi?id=176663> -
Installing a new script requires restart of Amarok
-
Others ( Covered earlier/ later ):
- Bug 299218 <https://bugs.kde.org/show_bug.cgi?id=299218> - Amarok
script API track signals are unreliable, undocumented (
Covered by Step 3 )
- Bug 150610 <https://bugs.kde.org/show_bug.cgi?id=150610> - Add
Dynamic Playlist API for scripts
-
Bug 279701 <https://bugs.kde.org/show_bug.cgi?id=279701> -
Scripting support for the equalizer
-
Bug 243096 <https://bugs.kde.org/show_bug.cgi?id=243096> - Load
a saved playlist in database from script
-
Bug 313283 <https://bugs.kde.org/show_bug.cgi?id=313283> -
Amarok Scripting API lacks documentation
-
Bug 245647 <https://bugs.kde.org/show_bug.cgi?id=245647> -
Programmatic access to data objects in QtScript
-
Add new scripts demonstrating the new scripting API ( and adding cool
new features )
-
A generic full-fledged synchronization framework like iTunes written
in Amarok Script for media devices
- Link to Google Music Search for currently playing artist (also Bug
136502 <https://bugs.kde.org/show_bug.cgi?id=136502>)
-
Automatic adjust equalizer according to genre (also Bug
129374<https://bugs.kde.org/show_bug.cgi?id=129374>
)
-
Part II : Design a graphical Script Creator utility
Create a user-friendly script creation GUI allowing everybody, coders and
non-coders alike to write scripts for Amarok. The utility will be generic
enough to allow easy porting to other KDE apps.
-
Part III : Automated Testing Scripts
Write scripts for unit-testing the scripting interface. Look into existing
solutions like QSTestLib (
http://blog.qt.digia.com/blog/2007/11/05/unit-testing-with-qt-script/ ) to
see if they’re viable for
-
Part IV: Automating Documentation
-
Document any undocumented scripting API code
-
Use Doxygen for generating the wiki Scripting API Documentation content
from in source documentation. [Or should I write my own scripts for that?]
-
Others ( if time permits, can be continued after GSoC )
-
Add GUI Handling to the Script Creator utility
Add support for handling GUIs to the Script Creator utility. GUIs can be
made
in QtCreator and the .ui files loaded in script. The Script Creator will
allow
handling UI elements both for input and output.
-
Allow abortion of long running scripts
The scripting engine is blocking, and poorly written scripts freeze the UI.
Popup a dialog box (popup delay user configurable) allowing users to
terminate long running scripts.
-
Port popular Amarok 1.4 scripts to the newer QtScript based scripting
API if possible, and more scripts!
Implementation Details //incomplete, is all this really needed?
*Enums will be handled as strings in Amarok Scipt, converted to and fro
using static enum to string maps*
*
1. AmarokScript
public signals:
configured (I’m actually uncertain when it’s supposed to be emitted, when
the Amarok configuration changes? )
Write script errors to error log
2. AmarokEngineScript
Q_PROPERTY( int trackLength READ trackLength )
Q_PROPERTY( bool replayGain READ replayGain WRITE setReplayGain )
slots:
isMuted
isPaused
isPlaying
isStopped
isSeekable
prettyNowPlaying
replay
supportsGainAdjustments
supportsFadeout
supportedMimeTypes
setFadeoutLength
setDynamicMode
public signals:
capabilitiesChanged
playbackStateChanged
stopped(); paused(); //needed? can be inferred from playbackStateChanged();
trackPositionChanged
muteStateChanged
seekableChanged
3. AmarokEqualizerScript
Q_PROPERTY( bool isSupported READ isSupported )
Q_PROPERTY( double maxGain READ maxGain)
public slots:
bandsFreq
getGains
setGains
defaultPresetsList
defaultTranslatedPresetsList
userPresetList
globalPresetList
setDefaultPreset
deletePreset
setPresetVal
getPresetVal
selectedPresetName
4. AmarokNetworkScript
Check if 0th parameter of Context passed to Downloader::init is a QUrl
5. AmarokScriptableServiceScript
StreamItem and ScriptableServiceScript in same header file, not in
AmarokScript namespace where they should be
6. AmarokWindowScript
public slots:
showtrayIcon
showSplashScreen
addContextMenuAction
addContextMenuActionByFileType
addSubmenu
getSelectedIndicesMetaQueryMaker
isSelection
7. Handling collections, copying between collections ,transcoding and
querying
Implement in a more object oriented way.
a. class AmarokCollectionManagerScript
[ global CollectionManager object - Amarok.CollectionManager ]
public:
enum Type
{
UmsCollection,
IpodCollection,
AudioCdCollection,
DaapCollection,
DatabaseCollection,
MediaDeviceCollection,
MtpCollection,
NepomukCollection,
PlaydarCollection,
ProxyCollection,
PlaylistCollection,
}
Q_PROPERTY
public slots:
getCollectionByType
viewableCollections
queryMaker
**
b. class CollectionTypeExporter
[ exporter for Collection type objects ]
Q_PROPERTY( QString type READ type )
Q_PROPERTY(hasCapacity READ)
Q_PROPERTY(usedCapacity READ)
*
Q_PROPERTY(totalCapacity READ)
*
**
public slots:
queryMaker
location
hasCapacity
usedCapacity
localCapacity
c. TranscodingConfigurationTypeExporter
Q_PROPERTY( QString encoder READ encoder WRITE setEncoder );
Q_PROPERTY( QString trackSelection READ trackSelection WRITE trackSelection)
public slots:
setEncoder
getPropertiesForEncoder
addProperty
d. CollectionLocationTypeExporter
Q_PROPERTY( isOrganizable READ)
Q_PROPERTY( isWritable READ)
Q_PROPERTY( actualLocation READ)
public signals:*
* finishCopy();
public slots:
prepareCopy //accept TranscodingConfiguration Object
prepareMove
prepareRemove
Tentative Timeline:
May 27 - May 30 : Familiarize myself with members of the Amarok team.
Discuss proposal with team-members and fine-tune implementation details
based on the feedback.
May 31 - June 5 : Finalize all implementation details and the work plan,
resolving any ambiguities.
June 6 - June 17 : Unavailable due to my exams
<-----Coding Period Starts----->
June 17 - June 23 : Work on cleaning up existing API, implement
CollectionManager and write QtScriptObject accessor for for Collections and
CollectionLocations
June 24 - June 30 : Implement file copying and moving among
CollectionLocations, with script configurable transcoding support
June 31 - July 6 : Write QtScriptObject for Querymaker and Bookmarks.
Add accessor for QueryMaker to Collections object
July 7 - July 13 : Podcast Management. Synchronization Jobs.
July 14 - July 20 : Dynamic playlists and automatic playlist generators
July 21 - July 27 : Other requested features and bug-fixes
July 27 - July 31 : Other features, like suspend inhibition.
<--------August 2----------> Midterm Evaluations Deadline
August 3 - August 9 : Write the new scripts
August 10 - August 16 : Design a UI for Amarok Script Creator
August 17 - August 23 : Write code for Script Creator
August 24 - August 30 : Test script creator, add new features based on
community feedback
<----- All components of the scripting interface ready at this point----->
August 31 - September 9 : Write unit tests for the Amarok scripting
interface
September 10 - September 16 : Write missing documentation, set up automatic
documentation generation
<-----September 16-----> Suggested Pencils Down
September 17 - September 23 : (Buffer Time) Finish any pending tasks,
implement miscellaneous features (GUI handling in Script Creator, abortion
of long running scripts, porting Amarok 1.4 scripts)
<----- September 23----->Firm Pencils Down
September 23 and on - tweaking, bug fixing, polishing interface based on
community feedback
About Me:
I’m Anmol, a 20 year old engineering student studying Computer Science and
Engineering in New Delhi, India.
I was introduced to KDE by my college senior Rishab (spacetime) as a
solution to my session management problem, and I was hooked. Being an avid
music fan, I was naturally drawn to Amarok as my music player of choice,
and eventually the first open source project I decided to contribute to.
The Amarok community has been very welcoming, especially Matěj
(strohel)and Myriam (Mamarok),
guiding me through my open source journey, and it’s been a lot of fun
working with them. Even more exciting has been adding features from my
wishlist to Amarok myself and watching them being accepted upstream,
knowing they’ll eventually reach the entire Amarok user-base [ waiting for
2.8 ;) ].
I am a rapid learner and a proficient C++ developer, it being the first
language I started coding in four years ago in high school. I have worked
in several other languages over the years, including Python, Java,
Javascript and Dart . I have made some projects in college, and an Android
app B’Wished <https://play.google.com/store/apps/details?id=com.anm.bwished>(now
defunct), and have been an active member of the Amarok community.
After GSoC, I will continue contributing to Amarok as I have been, and
hopefully contribute to some other KDE software too!
My contributions to Amarok include the following patches:
Contributions to Amarok:
Description
Reviewboard Link
Commit
Added power management options to Amarok-
allow pausing playback on suspend and inhibiting automatic suspend if
playing
https://git.reviewboard.kde.org/r/109846/
71e55e7bdd9b31642d09145a5801777c0e120454
Added fine-tuning transcode control options while copying and moving tracks
https://git.reviewboard.kde.org/r/109781/
e84b44ebbb6c470af1272852ba8afd258aa858d0
Added tooltips describing why a track doesn’t play
https://git.reviewboard.kde.org/r/109817/
0b1391318ae98c5f077b301ccb76a23b7efd1c3f
Handle Data CDs in Amarok
https://git.reviewboard.kde.org/r/109752/
6dd3e1e190118dd079c7c414a44f22eaecffc5d5
Added 3 different seek options to Amarok
https://git.reviewboard.kde.org/r/108964/
265696b694559e09cad34f4b5e06077b92f91dce
SIGNAL SLOT Normalization patch
https://git.reviewboard.kde.org/r/109794/
7a72f13d7f57e83efdae66b5078b7f1aa0131b2d
Added a prepareToQuit() signal to amarokWindowScript
https://git.reviewboard.kde.org/r/109695/
b0c79900429e8987c018112f875e09e565126408
Other Obligations:
I have my current semester’s final exams from June 4 to June 17, during
which I will unavailable. I have no other obligations for the rest of my
summer vacations and will be fully available for my GSoC work.
*
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/amarok-devel/attachments/20130430/597e23c7/attachment-0001.html>
More information about the Amarok-devel
mailing list