Requirements:
-------------

  - Android 1.6? (Tested with 2.3.6)
  - Music files located in external storage / memory card in folder /Music
    Note the capital 'M'.

Getting started:
----------------

 Layout:
 The layout changes as you interact. However, at the bottom are some buttons
 that are always available, which currently are:
  - Play/Pause;  Click to toggle
  - Repeat mode; Click to toggle repeat mode
                 Long click to toggle folder based repeat
  - Skip;        Click to skip to next song (if playing)
  - Back/Quit;   Switches to player layout, or quits if you already are in
                 player interface

 You may switch layouts by slinding the display left or right (not working at
 the bottom area) between
   folders <-> current folder <-> player <-> search
 In landscape mode on large screen devices, two of the layouts are shown:
   folders + current folder <-> current folder + player <-> player + search
 You can also enable classic click interface in the settings.

 Folders:
   Shows any folder containing music (music in subfolders)
   Click to switch to current folder view

 Current folder:
   Shows the content of the current folder
   Click on the folder item on top of the list to switch to Folder view
   Click on any song to play item. This will automatically switch to player view
   Long click on any song to invoke a popup menu with additional options.

 Player:
  Shows
   - The folder containing the current song. Click to switch to that folder.
   - The current song; Click to switch to the folder containing that song;
                       Long click to invoke a popup menu with additional options
   - Settings button; Click to opens setup popup dialog
   - Position/duration; Long click to toggle between elapsed and remaining time
   - Info button
   - Position bar; Click to seek to certain position.

 Search:
   Allowes you to search the playlist
   Click on folders to open them in current folder view
   Click on any song to play item. This will automatically switch to player view
   Long click on any song to invoke a popup menu with additional options.

 Widget:
  Shows a compact player interface.
  Note that widgets don't support long clicks, therefore you cannot toggle time
  display; Clicking repeat will toggle within some repeat modes only.

Launcher Edition:
-----------------

  Differences to the standard version:
   - There is no quit function
   - Adds another layout/page with a (very compact) launcher; On the bottom,
     you can launch camera / (alarm) clock / flash-light.
   - Long click on apps to invoke application details (e.g. to uninstall)
   - In fullscreen-Launcher-Edition, current time and battery status is shown on
     the player view, near the top right corner. The battery status indicator is
     a small bar which changes color (green->yellow->orange->red if on battery,
     pulsing blue if charging) and size accordingly.

More features:
--------------

 - 'Play next' option if you long-click on a song
 - Widget.
 - Install on sd-card. This makes partly sense, as Calaym relies on the music on
   the sd card. However, if installed on phone, you can start Calaym even if
   android's media scanner hasn't scanned apps on sd card yet. Calaym does not
   rely on the media library.
 - Calaym detects 'ogg', 'mp3', 'mid'/'midi' and 'flac' (flac files playback
   requires at least Android 3.1, otherwise flac files will be ignored)
 - when connecting (wired only?) headset during playback, Calaym will fade in
   volume
 - when disconnecting (wired only?) headset during playback, Calaym will pause
 - on media button (headset) click Calaym will pause/unpause
 - on media button (headset) longer button press during playback, Calaym will
   switch songs (fast crossfade)
 - on incoming/outgoing calls, Calaym will fade out, pause and resume afterwards
 - long clicking songs (in current directory, search list, or current song) will
   invoke a popup menu with additional options.
 - Multilanguage support (english / german currently included)
 - 'Last.fm Scrobbler' and 'Simple Last.fm Scrobbler' intent support, which can
   be used to update Last.fm and/or Libre.fm with the proper app installed
 - Lyric support. Be sure the lyric files are UTF-8 lrc files placed next to
   your music files.

Pending features / To-do list:
------------------------------

 - last played songs? (view after / right of search?)
 - add some more styles, also to make it easier to distinguish current view(s)
 - ignore activity pause/unpause when opening popups (context menu, info
   message, empty playlist message)?
 - Multithreading? (so playback continues when showing messages/popups)
 - Seek with Zero Volume to avoid 'clippings'
 - Seems sometimes unpauses after calls even if was paused (stopped?) before
   call
 - Detect false play button press due connecting wired headset?
 - filename to tag splitter:
     * skip '(' artist infos if text after ')'; (last ()?);
     * Ignore () artist tags starting with 'from ', or ending with
       ' rmx'/' mix'/' remix' or equal with former; strip 'by ' from artists
       when ()
 - Better saving
 - sleep timer
 - 'on listen' (speach recognition)
 - Help 'How do I...?'
 - Play next as global option?
 - popup menu for current info/settings, and other features here instead
 - In single-repeat mode, Calaym sometimes skips to the next song. Reason
   unknown. maybe if paused during crossfade, no crossfade (due dialog),
   and/or with last item in folder only?
 - Add rescan / restart function in launcher mode (quit button long-press...?)
   

File / Folder naming guidlines:
-------------------------------

 The following naming schemes are supported when splitting filename for
 'Last.fm Scrobbler' / 'Simple Last.fm Scrobbler':
   *\Artist - Album\Title[ (...)].*
   *\Album (Artist[; ...)\Title.*    (Recommend)
   *\Album (Artist[, ...])\Title.*
   *\.....\Artist - Album - Title.*
   *\Album\Artist - Title.*
   *\Album\Title (Artist[; ...]).*   (Recommend)
   *\Album\Title (Artist[, ...]).*

Legal stuff:
------------

 - You can use this software under the terms of the User-friendly Open source
   License Version 1.00, published by Jan Vorel;
 - You can redistribute the official software packages under the terms of the
   User-friendly Distribution License Version 2.00, published by Jan Vorel.
 - Folder icons are from the 'Tango Desktop Project' icon theme;
   http://tango.freedesktop.org/

Used Version/libraries:
-----------------------

 - Basic4Android     4.00
 - BroadcastReceiver ?.00 - Sends and receives Broadcasts in the Android
                            Operating System. (by XverhelstX - Tomas Verhelst)
                            "NOTE: I FORGOT TO CHANGE THE VERSION OF
                            BROADCASTRECEIVER TO 2.0 IN THE IDE. SO THE IDE
                            MIGHT SAY VERSION 1.0 IN THE LIBRARY TAB"
 - Core              4.01 - Part of Basic4Android
 - id                1.00 - inputlist without radio controls (by Maximus /
                            thedesolatesoul ?)
 - IME               1.05 - Part of Basic4Android
 - Phone             2.26 - Part of Basic4Android
 - Reflection        2.40 - Part of Basic4Android
 - SVG               1.50 - Scalable Vector Graphics renderer (by Agraham -
                            Andrew Graham)

Permissions:
------------

 - Storage: modify/delete USB storage contents
   Allowes to delete songs, creation of .nomedia file for the music folder...
 - Phone calls: Read phone status and ID
   Calaym will fade in/out on incoming/outgoing calls
 - Hardware controls: control vibrator
   Because Calaym does not use vibration when setting/updating notification
   icon/text?

By default some libraries want additional privileges, but these were disabled as
they should not be needed by Calaym.

Thanks:
-------

 - Marlene Vorel for letting me test on her tablet
 - Christian Falk for fixing some issues / testing on additional devices
 - Basic4Android, the community etc

Changelog:
----------

 1.07 (beta)
  - Fix: Song position control not visible on larges devices mode in portrait
         mode in slide interface mode
  - Fix: Positioning in dual-view classic click interface mode
  - Fix: Interface height after rotation change with keyboard open
  - Add: Warning when activating 'Hide music from media scanner'
  - Chg: Conditional code and other minor improvements
  - Chg: SVGs now saved under drawables, and loaded accordingly. That way,
         Resources can be conditionally included.
  - Fix: Resuming playlist position when re-starting.
  - Chg: Searching optimations, no longer listing subdirectories of a matching
         directory. Optimized directories displayed in the result list.
  - Add: 'Play next' option if you long-click on a song anywhere in the interface
  - Chg: Improved code for current song interaction handling
  - Chg: Faster GUI buildup (rotation / when already running)
  - Chg: Reworked launcher applist and related. Also you can now long-click to
         invoke application details (e.g. to uninstall)
  - Add: Now always saving settings when closing the setup dialog
  - Fix: Hopefully fixed rotation issues
  - Add: Lyric support. Be sure the lyric files are UTF-8 lrc files placed next
         to your music files.

 1.06 (beta)
  - Chg: For publishing compatibility, the package version is changed to a very
         simple x.xx format, and increased. See the info dialog for full version
         info details.
  - Add: Small dedicated service for media button and phone call intents
          - Faster processing of the intents
          - Additional workarounds to catch phone state intents that cause the
            service to start, but are not recieved with the reciever.
         All in all, it should no longer interfere with accepting phone calls
         using the media button.
  - Add: Calaym icon shown on top info bar startup (e.g. when launching using
         media button / widget)
  - Add: Launcher Edition code (experimental)
  - Add: SVG images (mostly)
  - Chg: Due a bug with transparent gifs in recent android versions, all
         (remaining) graphics are now png. Those few graphics are slightly
         bigger and match the new SVGs.
  - Add: Scrolling on song position control will no longer scroll views
  - Fix: Songs already fading out now shorten fadeout time if required, e.g.
         pausing shortly after crossfade - remaining fadeout time up to about
         15 seconds - will now shorten to 2 seconds.
  - Add: Click/touch sound on media button (headset) click if Calaym is not
         running / starting up; (You now have an audio response feedback)

 1.00 beta 5:
  - Add: Current state broadcasting
  - Fix: Startup error with widget on some conditions (devices?)
  - Add: Better support for external external sd cards
  - Add: Keyboard pops up when scrolling to search and scroll list is empty
  - Add: Search result list adjusts height so it no longer overlaps keyboard
  - Fix: Better widget updating
  - Chg: Little bit more spacing between position bar and controls above/below
  - Chg: More orientation options on larger devices
  - Chg: Setup controls arrangements

 1.00 beta 4:
  - Chg: "Fixed volume" option renamed "Lock media volume"
  - Add: Last.fm Scrobbler support (via Last.fm app)
  - Add: "Simple Last.fm Scrobbler" intent support (App required), which can be
         used to update Last.fm and/or Libre.fm
  - Chg: Tweaked headset (un)plug/on call pausing / soft fade-in (again)
  - Fix: File reading progress bar calculation
  - Chg: Setup view more compact
  - Add: Smarter volume handling if setup is cancelled
  - Add: Widget shows file reading progress on startup
  - Fix: Widget size issue, plus display refresh workaround
  - Fix: Initial settings (Volume!) set properly on first start / missing config
         file
  - Chg: Now you need to long click on time (label) to switch between elapsed
         and remaining time
  - Fix: Song loading fail issue when current song is last song in folder and is
         deleted (single-repeat / repeat all mode)
  - Fix: Several startup / empty playlist handling issues, esp. with active
         widget
  - Add: Folder based repeats. Long click the repeat button will use songs in
         same folder only. One of those features always considered for the PC
         version, and as the android version has no playlist management, a
         rather essential feature
  - Add: Pattern based randomizing
  - Add: 'Old style click interface' setting, disables vertical sliding and adds
         an fixed bottom bar to the left of the screen.
  - Chg: Several interface changes / fixes
  - Fix: Workaround for clipped thumbs on seekbars
  - Fix: Workaround for settings to handle reversed landscape orientation
  - Del: Suppressed 'ACCESS_COARSE_UPDATES' permission

 1.00 beta 3:
  - Add: Long-pressing songs will show a popup menu, instead of just deleting
         that song (already added in beta 2?)
  - Add: Check if no music is found on startup / show message;
  - Del: Suppressed some permissions from libraries
  - Chg: Larger listitem height
  - Chg: Smaller search text box (height)
  - Add: Click on time (label) to switch between elapsed and remaining time;
         Default is now remaining time
  - Fix: Restoring last viewed directory properly
  - Chg: Fast crossfade when deleting
  - Fix: No skipping one song when deleting and repeat-all is set
  - Chg: flac support only if supported (android version 3.1 / newer).
  - Add: Support for .mid (and .midi) playback
  - Chg: Skip button now also on bottom bar
  - Chg: Tweaked headset (un)plug pausing / soft fade-in
  - Add: Settings button, plus setup dialog (not much in here, but it will grow
         eventually)
  - Add: Fixed volume option
  - Fix: When deleting paused songs, next song is loaded, but paused
  - Fix: When fading out to pause, and song end is reached while fading, next
         song is loaded, but paused.
  - Fix: Current song actions only available if only one song is active.
  - Add: Current song actions disabled if there was a song change was withing
         four seconds, other songs are still active (fading out), and some
         other extra checking.
  - Add: Some extra scroll checking when resuming activity
  - Fix: Quit icon shown instead of back icon
  - Add: Widget
  - Add: 'Enable rotation' option
  - Chg: Folder icon from tango theme
  - Add: Option to prevent media scanner from parsing music folders (.nomedia
         file)
  - Add: Media scanner updated when quitting if files were deleted
  - Add: Fading/crossfade indicator (icon)

 1.00 beta 2:
  - Fix: SEVERAL internal and minor visual BUGS
  - Add: Dual-views in landscape mode on large displays;
         (folders+files <-> files+player <-> player+search)
  - Add: Main 'buttons' now on panel with gray background
  - Add: Support for dual storage (sdcard/Music + sdcard/external_sd/Music)
         (As encountered on the Galaxy S Advance I9070P...)
  - Add: Search results are sorted

 1.00 beta 1:
   Almost everything I wanted the player to be, working and fully functional.
   Or so it appears. It has all features I considered essential, like fading,
   crossfading, search and some automatic playback features. Plus the mobile
   device related features.
