TeaCup Music Widget
Contact: Matthew Hague ([email protected])
(Or use the issue tracker on github -- please send any errors, players you want
supporting, working configurations for other players, and so on and so forth.)

A desktop music widget for Android works with stock player by default but allows
configuration for (hopefully) any player.  Can interact with Last FM: getting
album art and scrobbling (choose when to connect, can cache when offline).

Play, prev, next buttons.  Press album art to open the music player.

Configurable album art options: get embedded art, images in the same directory
as the music file, or fetch album art from Last FM.  Can also pre-fetch album
art from Last FM.

Scrobbling to Last FM: when on wifi and/or phone network.  Can store scrobbles
in a cache when no connection (will be sent when connection returns).

Written and tested for Android 2.3.3 (Android 10) on a Samsung Galaxy Mini 2,
but seems to compile and work in emulators for 4.2 (Android 17).


CHANGES
    v1.7

        Changed layout to meet recommended standards for 4x1 widgets.

    v1.6:
        
        Added support for CyanogenMod's Eleven player.

    v1.5:
        
        Replaced some inefficient scrobbling code.

    v1.4:

        Re-orders incorrectly ordered SSL Certificates (code borrowed from
        Chariot Solutions:
        http://blog.chariotsolutions.com/2013/01/https-with-client-certificates-on.html)

        When storing album art in a separate directory, .nomedia is created to
        keep the gallery clean.

    v1.3:

        Bug fix when fetching album art.

    v1.2:
        
        Last FM pays attention to track ID now, not just name (as e.g. Bjork's
        Bastards album is 12 tracks with the same name...)

    v1.1:

        Better concurrency handling, buttons don't stop working after changing
        language.  Basically less crashy...
        
        Test Last FM authentication button.


PERMISSIONS:

    The widget needs permission to know when your phone has just booted up.
    This is so it can start a service (if there's a widget on the home screen)
    that listens for changes to the media state and does the updating
    asynchronously.

    It also needs network access for downloading from Last FM (if enabled) and
    to be able to write files (to store cached album art).


CONFIGURATION:

    The configuration utility starts when adding a widget and can also be
    accessed via an icon in the launcher menu.  Note, all instances of widgets
    share a configuration.

    If you want to customise the widget to work with any media player, press
    "choose player" then select "custom player".  You'll get a long list of
    options.  

    To launch the player, the package name is needed.  The default is
    "com.android.music".  I think HTC use a different stock player, so you'll
    need to find out the config options to use this with HTC... (on my todo
    list).

    To keep up-to-date with the player, TeaCup needs to know what to listen for.
    You can specify the "metachanged" action, that is fired when the track changes,
    and the "playstatechanged" action, that is fired when the player changes
    between play and pause.  From the metachanged action, TeaCup needs to know
    how to get the android media "id" of the song playing.  In the stock player,
    this is the "id" field of the "com.android.music.metadatachanged" action.
    Similarly, TeaCup needs to know how to tell whether the current song is
    playing or paused.  This is the "playing" field of the
    "com.android.music.playstatechanged" action.

    Next, to control the player, TeaCup needs to know what requests to send to
    the player and how.  E.g. to jump to the next track, it must send a
    "com.android.music.musicservicecommand" action, with the field "command" set
    to "next".  Hence, for the default player we set

        Jump next action: com.android.music.musicservicecommand
        Jump next command field: command
        Jump next command: next

    And similarly for play/pause and jump previous.


ICONS:

    Teacup Logo is free clipart:
    http://www.wpclipart.com/food/beverages/tea/teacup.png.html

    Last FM Logo came from them: www.last.fm (uh, powered by AudioScrobbler).

    Everything else i self-gimped.


BUILDING:

    Hopefully all the files you need to compile are here...

    ... except a build system...

    Linux-wise, you should be able to run

        android update project --path . --target android-10

    assuming you've set-up the android-sdk with android-10 (probably compiles for
    other targets).  (Run simply "android" to start setting up targets.)

    And that will generate build.xml and local.properties, then you should be able
    to do

        ant debug

    and an .apk will be built and put in bin/.

    I've included build.xml.generated and local.properties.generated which are the
    files generated on my machine.  Rename to build.xml and local.properties, maybe
    they'll work for you (if you edit local properties to tell it where the android
    sdk is installed).

    For more on building, see here

        https://developer.android.com/tools/building/building-cmdline.html

    and here

        http://www.androidengineer.com/2010/06/using-ant-to-automate-building-android.html

    Then, once it's built, copy the .apk to your phone, open it up and let it
    install.  (Or use adb or whatever you prefer.)