This is a collection of tools for users of the MobileSheetsPro, the
Android Music Reader.

WARNING: THIS IS 'WORK IN PROGRESS' AND 'WORKS FOR ME'. I CANNOT GIVE
ANY GUARANTEE THAT IT WILL WORK FOR YOU.

Requirements:

 * A system with a command line tool, e.g. Linux Shell, Windows
   Command.
 * Perl 5.10 or newer.
 * Perl modules for DBI, SQLite, PDF::API2.
 * Experience with running command line tools (yes, really).

Tools:

Note: All tools support a --help command line option for more
information.

msb_unpack.pl

This tool verifies and/or unpacks an MSPro backup set into the current
directory.

Usage:

  Copy the backup set from the tablet onto the PC.

  perl script/msb_unpack.pl MobileSheetsProBackup.msb

  (Note: You may need to adjust the path to perl, the script and the
  backup set if they are not accessible from the current directory.)

  The contents of the backup set will be extracted. All files will be
  extracted into the current directory, folder information will not be
  included. 

msb_relocate.pl

This tool copies an MSPro backup set, changing path prefixes,
effectively relocating the backup set to be restored to a new
location.

Usage:

  Copy the backup set from the tablet onto the PC.

  perl script/msb_reloc.pl MobileSheetsProBackup.msb

  (Note: You may need to adjust the path to perl, the script and the
  backup set if they are not accessible from the current directory.)

  The new backup set will be called MobileSheetsProBackup_reloc.msb.
  You can verify its contents with msb_unpack.
  If the relocation is okay, copy the new backup set to the (new)
  tablet and restore it.

flatten.pl

This tool processes an unpacked MSPRo backup set and creates PDF files
that include the MSPro annotations.

** This tool no longer works with recent MSPro versions **

Usage:

  Unpack the backup set into the current directory.

  perl script/flatten.pl

  (Note: You may need to adjust the path to perl and the script if
  they are not accessible from the current directory.)

  PDF documents are created for each file that has annotations. For
  PDF sources the original document is included, so the new PDF
  document contains the original plus the annotations. For other
  source files, the PDF document will contain empty pages containing
  the annotations.

  Supported annotations:

  - drawing annotations (line, rectangle, circle, free)
  - highlight annotations (line, rectangle, circle, free)
  - text annotations, but no fancy font stuff

get_meta.pl

This program will retrieve the metadata for all songs from the
MobileSheetsPro database and write it out in JSON format.

Usage

  perl script/get_meta.pl

  (Note: You may need to adjust the path to perl and the script if
  they are not accessible from the current directory.)

  The output will be similar to

       {
	  "title"       : "13. The Old Triangle"
	  "sorttitle"   : "013 The Old Triangle",
	  "artists"     : [ "Luke Kelly & the Dubliners" ],
	  "collections" : [ "HowsaGoin!" ],
	  "tempo"       : [ 92 ],
	  "keys"        : [ "C" ],
	  "signatures"  : [ "3/4" ],
	  "songid"	: 621,
	  "paths"       : [
	     {
		"path"   : "/storage/sdcard1/Music/013_The_Old_Triangle.pdf"
		"fileid" : 1412,
		"type"   : "PDF",
		"source" : "Sheet Music",
	     }
	  ],
       },

upd_meta.pl

This program updates the metadata for all songs from the
MobileSheetsPro database according to JSON input data, as generated by
get_meta.

Usage

  perl script/upd_meta.pl metadata.json

  (Note: You may need to adjust the path to perl and the script if
  they are not accessible from the current directory.)

  Songs are identified by the SongId and paths by the FileId. If
  either is missing, songs are searched for using the filename without
  the leading path, e.g. a path
  "/storage/sdcard1/Music/013_The_Old_Triangle.pdf" will search the
  database for a file entry ending in "013_The_Old_Triangle.pdf".

  NOTE: You can extract the metadata using get_meta, and selectivily
  extract portions that you want to update. For example, this snippet
  will only change the title of song 621:

       {
	  "songid"   : 621,
	  "title"    : "The Old Triangle (Instrumental)",
       }

  NOTE: When a new value is given to a list-valued item (key,
  collection, artist, etc.) the value is overwritten and the old content is
  lost.

  WARNING: You need to copy the MobileSheetsPro database from the
  tablet to the PC, run this program, and then copy the (modified)
  database back to the tablet. This is a risky process that can blow
  up your music collection, MobileSheetsPro, the tablet, and your cat.
  See https://www.youtube.com/watch?v=MgxgYL5P4z4 .

WARNING: See WARNING above.

chordpro_meta.

Usage

  perl script/chordpro_meta

  This program extracts ChordPro metadata from the MobileSheetsPro
  database.

  The metadata is written to standard output in the form of a series of
  ChordPro directives, preceeded by the file name, e.g.

      === HowsaGoin/051_As_I_Roved_Out.cho === [2497/14472]
      {title: As I Roved Out}
      {artist: The High Kings}
      {capo: 3}
      {tempo: 105}
      {meta: collection HowsaGoin!}
      {meta: source Lead Sheet}
      {meta: custom2 51}

  You can cut/paste this into your ChordPro files, or use it
  for visual inspection.
  
  The numbers between C<[ ]> are the internal song and file id. These
  can be used for subsequent searches with B<--songid> and B<--fileid>
  command line options.

  If no songs are selected, the information for all songs in the
  database is returned.