GSoC Application Review
Anmol Ahuja
darthcodus at gmail.com
Wed May 1 21:31:52 UTC 2013
Here's a new version of the proposal. Some things like suspend inhibition
and transcoding are still tentative, since I am awaiting a response to my
previous email. Also, the version of my proposal on the melange page is a
major formatting mess. Can I link to a pdf or external webpage
instead?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 scripting. 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 at gmail.com
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 : Setting up Automating Documentation
**
-
Setup Doxygen for automatically generating the Scripting API
Documentation wiki content from in-source documentation.
-
Document any undocumented scripting API code in-source.
*
***
-
Part II : Clean up, document and write unit tests for the existing
Scripting API
-
Deprecate AmarokCollectionScript
-
Some features will be moved to the new
AmarokScript::CollectionManager class.
-
Others, like direct SQL access, will be deprecated without
replacement
-
Set up notification for scripts calling deprecated methods and objects
-
Write scripts for unit-testing the existing 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 unit testing Amarok Scripting API, and write
custom unit tests if they’re not.
*
***
-
Part III : Revamping the Scripting API
**
-
Add accessors for the other Amarok features to the Amarok scripting API
*
( Documentation and unit tests will be written as soon as an API class/
method is implemented )
*
-
CollectionManager
-
Collection
-
CollectionLocation
-
Transcoding [Uncertain, awaiting Matěj’s response]
-
QueryMaker( exposed indirectly via QueryFilter )
-
Playlists
-
Dynamic Playlists
-
Automatic Playlist Generator
-
Bookmarks
-
Equalizer [Uncertain, awaiting Matěj’s response]
-
Podcast Management
-
MatchTracksJob
-
Others
-
Add suspend inhibition to AmarokScript [Uncertain, awaiting
Matěj’s response]
*
*
-
Add other requested features/ wishes and fix bugs
- Bug 183497 <https://bugs.kde.org/show_bug.cgi?id=183497> - 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
- 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
*
***
-
Others ( if time permits, can be continued after GSoC )
**
-
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>
)
**
-
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.
Implementation Details
**
QObjects can easily be accessed in QtScript, an ECMAScript based language,
thanks to the Qt meta-object system. This can be achieved by passing them
to QScriptEngine::newQObject(), resulting in a QtScript accessible
QScriptValue with all of the QObject's public slots and signals, functions
with the Q_INVOKABLE macro, named child objects, and Q_PROPERTY parameters
(with SCRIPTABLE true) accessible in the script environment.
**
In Amarok script, only selected methods are exposed to the QtScript
environment by creating QObject( and for prototypes, QScriptable ) -
derived wrappers for the classes to be accessed via Amarok script, to avoid
cluttering the scripting API and customizing behavior of Amarok classes to
be script friendly. This gives complete control over functionality made
available via the scripting API. These wrappers simply call the functions
of the actual class they link to, which do the real work. So, instead of
having to design Javascript equivalents of every class, only the wrapper
QObjects must be made and exported.
**
I will be using the following QtScript classes in this GSoC project:
***
-
QScriptable - For exposing Amarok classes like Collection,
CollectionLocation to the scripting environment. They will be exposed using
QScriptable and QObject derived classes registered as protoypes via
QScriptEngine::setDefaultPrototype(). The
**
-
QScriptable derivation allows accessing the scriptable environment's
context from within the C++ code, allowing access to the calling object and
more.
-
QScriptEngine - Provides the environment for QtScript evaluation. Used
for setting custom protoypes of objects, setting global objects in the
scripting environment, etc.
*
***
-
Other basic classes, like:
-
QScriptContext for Javascript to C++ interaction, like accessing
function arguments, accessing the this pointer, etc.
-
QScriptValue : for translating objects back and forth between
QtScript and Qt/ C++.
*
**
Qt Script uses garbage collection to reclaim memory used by script objects
when they are no longer needed, with this need being determined on the
basis of the ownership parameter passed as the second argument to
QScriptEngine::newQObject():
1. Qt Ownership (default) - QObject owned by the C++ code, not the script
engine. That is, it managed according to Qt's object ownership.
2. Script ownership - Script engine fully owns the QObject, deleting it
when there are no references to it in the script code.
3. Auto-Ownership - Behaves like Script ownership when no parent, Qt
Ownership otherwise.
**
**
Here are class diagrams for some of the classes I plan on implementing, as
detailed in the project goals:
1. Collection Management and Manipulation
**
Handling collections, copying between collections, transcoding and querying
in an object oriented way.
( Names of other scripting classes will also be changed to reflect this
naming scheme, like AmarokScript::Engine instead of
AmarokScript::AmarokEngineScript )
**
The QueryMaker will be exposed in a simplified form via the QueryFilter
class, which will use Collections::addTextualFilter and addDateFilter to
allow the CollectionBrowser search widget like queries. For example:
title:"carry" AND artist:"Fun."
Besides being much simpler, it’s also easy to test directly from the Amarok
collection browser.
**
2. AmarokScript::EngineController
( only lists properties and methods which do not already exist )
**
**
3. AmarokScript::Equalizer
**
Other changes/ refactoring ( part of the initial cleanup ):
***
-
AmarokScript
-
Write script errors to the error log
-
AmarokNetworkScript
-
Check if 0th parameter of Context passed to Downloader::init is a QUrl
-
Move all Amarok Scripting classes to the AmarokScript namespace, if they
aren’t already there, like StreamItem and ScriptableServiceScript.
-
Move classes StreamItem and ScriptableServiceScript to different files.
-
Rename classes in the AmarokScripting namespace, like
AmarokScript::AmarokEngineScript to AmarokScript::Engine. Rename
MetaTypeExporter
to TrackExporter.
*
**
**
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
ex<https://bugs.kde.org/show_bug.cgi?id=313283>
ams
<-----Coding Period Starts----->
June 17 - June 23 : Set up automatic scripting API documentation on the Amarok
Scrip <https://bugs.kde.org/show_bug.cgi?id=299218>t wiki page using
Doxygen. Document the existing scripting API
June 24 - June 30 : Clean up existing API. Deprecate redundant, obsolete,
soon to be replaced objects and calls. Add deprecation notifier for scripts
using deprecated API calls.
June 31 - July 6 : Continue with cleanup. Write unit tests for the
existing API
( For the rest of the API, documentation will be written along with the
code, and unit tests for every component of the scripting API written as
soon as it is complete )
July 7 - July 13 : Implement CollectionManager and write QtScriptObject
accessors for Collection and CollectionLocation.
July 14 - July 20 : Implement file copying and moving among
CollectionLocations, with script configurable transcoding support using
TranscodingConfiguration objects.
July 21 - July 27 : Implement EqualizerController class. Implement
AmarokScript::Equalizer.
July 28 - July 31 : Write QtScriptObject for QueryFilter ( Querymaker ) and
Bookmarks. Add accessors for QueryFilter to CollectionTypeExporter.
<--------August 2----------> Midterm
Evaluati<http://blog.qt.digia.com/blog/2007/11/05/unit-testing-with-qt-script/>ons
Deadline
August 3 - August 9 : Podcast Management. MatchTracksJobs.
August 10 - August 16 : Dynamic playlists and automatic playlist generators
August 17 - August 23 : Add missing features to AmarokScript::Engine as
detailed in the class diagram above. Other features, like suspend
inhibition.
August 24 - September 9 : : Other requested features and bug-fixes.
<----- All components of the scripting interface ready at this point----->
September 10 - September 16 : Write the new scripts. Implement script
execution control.
<-----September 16-----> Suggested Pencils Down
September 17 - September 23 :
(Buffe<https://bugs.kde.org/show_bug.cgi?id=183497>r
Time) Finish any pending tasks.
<----- September 23----->Firm Pencils Down
September 23 <https://bugs.kde.org/show_bug.cgi?id=187957>and on -
tweaking, bug fixing, polishing interface based
o<https://bugs.kde.org/show_bug.cgi?id=176663>n
community feedback
About Me:
I’m Anmol, a 20 year old
engineer<https://bugs.kde.org/show_bug.cgi?id=232711>ing
student, studying Computer Science and Engineering in New Delhi, India.
**
I was introduced to KDE by my college
se<https://bugs.kde.org/show_bug.cgi?id=205509>nior
Rishab (spacetime) as a solution to my session management problem, and
I w<https://bugs.kde.org/show_bug.cgi?id=176663>as
hooked. Being an avid music fan, I was naturally drawn to Amarok as my
music player of choice, an <https://bugs.kde.org/show_bug.cgi?id=299218>d
eventually the first open source project I decided to contribute
to.<https://bugs.kde.org/show_bug.cgi?id=150610>
<https://bugs.kde.org/show_bug.cgi?id=150610>
T <https://bugs.kde.org/show_bug.cgi?id=150610>he Amarok community has been
very welcoming, espec <https://bugs.kde.org/show_bug.cgi?id=279701>ially Matěj
(strohel) and Myriam (Mamarok),
guidi<https://bugs.kde.org/show_bug.cgi?id=243096>ng
me through my open source journey, and it’s been a lot
o<https://bugs.kde.org/show_bug.cgi?id=313283>f
fun working with them. Even more exciting has been
<https://bugs.kde.org/show_bug.cgi?id=245647>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,
in<https://bugs.kde.org/show_bug.cgi?id=136502>cluding
Python, Java, Javascript and Dart . I have made some
pro<https://bugs.kde.org/show_bug.cgi?id=129374>jects
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/20130502/60b96d2d/attachment-0001.html>
More information about the Amarok-devel
mailing list