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

Getting startet:
----------------

 Requirements:
  - Android 1.6? (Tested with 2.3.6)
  - Music files located in <DirRootExternal>/Music, which is most likely (?)
    /mnt/sdcard/Music
    Note the capital 'M'.

 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[, ...]).*

 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

 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.

Hidden features:
----------------

 - Widget. In case you haven't noticed.
 - 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 headset (wired only?) button click Calaym will pause/unpause
 - on headset (wired only?) 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

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

 - last played songs? (view after / right of search?)
 - better default app handling (for headset button)
 - add some more styles, also to make it easier to distinguish current view(s)
 - maybe add higher res images for additional controls
 - maybe downsample high res images to save space
 - 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 ()

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 libraries:
---------------

 - BroadcastReceiver 1.00 - Sends and receives Broadcasts in the Android
                            Operating System. (by XverhelstX - Tomas Verhelst)
 - Core              2.71 - Part of Basic4Android?
 - id                1.00 - inputlist without radio controls (by Maximus /
                            thedesolatesoul ?)
 - IME               1.05 - Part of Basic4Android?
 - Phone             2.10 - Part of Basic4Android?
 - Reflection        2.40 - Reflection library for runtime creation and
                            manipulation of Java classes and object instances.
                            (by Agraham - Andrew Graham)

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

 - Storage: modify/delete USB storage contents
   You can delete songs within Calaym.
 - 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
 - Basic4Android, the community etc

Recent changes:
---------------

 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.
