1. Before doing anything with this Software, read the LICENCE at the
   end of this file.

2. The distribution directory MusicBox contains:

 a) This README file.

 b) mkmusicdb.tcl, a script that takes a directory "Music" containing a 
    directory hierarchy and puts in it a sqlite3 database "index.sqlite" 
    according to its contents.

 c) musicsh.tcl, a script that takes the directory Music above, helps 
    search wav and mp3 files in it by asking the database index.sqlite,
    and offer a player for playing them.

 d) play.tcl, it takes as arguments mp3 and wav files and plays them. It
    is the player offered by musicsh.tcl as standalone program.

 e) flute.tcl, it takes as arguments alternate time in seconds and note
    names, and plays them. It is also part of musicsh.tcl.

 f) readkbd.tcl, it shows the bytes (hex) generated by keys pressed. 
    It is included for porting musicsh to different systems.
    musicsh.tcl needs to know these bytes for processing the menus it offers.

3. For installing the scripts read the source. For FreeBSD, it should be 
   enough to adjust in the first line the path to the tcl interpreter and 
   to install the libraries snack and sqlite3 it uses. For other systems,
   it will be necessary to adapt the switch commands that process the menus.

4. How it works.

   Music contains wav/mp3 files, organized in subdirectories, where
   a subdirectory may contain a file "Desc" describing its contents.
   Original purpose was that a subdirectory contain the tracks of a CD.

   The script mkmusicdb.tcl generates a sqlite3 database index.sqlite
   with the tables:

   a) cd, containing one entry for each "Desc" file in Music. Fields:
      cdid - number of entry
      cdp  - path to the directory containing the "Desc" file
      cdtxt - contents of Desc file

   b) track, containing one entry for each .wav or .mp3 file. Fields:
      trid - number of field
      nid - path to the mp3/wav file, path elements are given by numbers
      trp - path to the mp3/file file, as in file system
      trtxt - field for description of the file, not filled jet
      cdid - reference to entry in cd, if the wav/mp3 file is in cdp.

   c) conc, joins tables track and cd using cdid. Hence, its fields are:
      trid, nid, trp, trtxt, cdid, cdp, cdtxt.

   The script musicsh.tcl offers first a menu for building a SQL query
   "SELECT trp FROM conc WHERE ...", the constraints that follow are
   built with parameters entered:

   Entered with  parameter    constraint:
   ---------------------------------------
   F1            $cdid        cdid=$cdid
   F2            $nid         nid regexp ^nid
   F3            $tr0         tr >= $tr0
   F4            $tr1         tr <= $tr1
   F5            $cdtxt       cdtxt like %$cdttxt%
   F6            $cdp         cdp regexp $cdp
   F7            $trtxt       trtxt like %$trtxt%
   F8            $trp         trp regexp $trp

   After entering parameters, pressing "o" queries the database,
   and pressing "p" plays the files found, offering a new menu.

   The program gives auditive signals, see meaning in source.
   The aim is to use musicsh.tcl without looking at a monitor. 

5. Background

   I backed up my old audio CDs with the program cdda2wav before they 
   get spoiled by the time. Then I discovered that a lot of CDs pass
   into a USB stick. I build a readonly, bootable USB stick with FreeBSD 10.4,
   put the program musicsh.tcl as login shell for a user "x" without 
   password, and a lot of CDs in a directory Music. I use this stick
   to boot a thin client (128 MB Ram) connected to an amplifier and 
   with a small wireless keyboard as remote control.

6. What can be done with it?

   It is only a prototype. There is sure a lot to improve. But it fullfils
   my needs.

/*
 * Copyright (c) 2021 Rodrigo Readi <hruodr@gmail.com>
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the "Software"),
 * to deal in the Software without restriction, including without limitation
 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
 * and/or sell copies of the Software, and to permit persons to whom the
 * Software is furnished to do so, subject to the following conditions:
 *
 * The above copyright notice and this permission notice (including the 
 * next item) shall be included in all copies or substantial portions of 
 * the Software;
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT;  IN NO EVENT SHALL
 * AN AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 * DEALINGS IN THE SOFTWARE.
 */
