Summary of Features
Detailed Features
What's New?
Download
Installation & Getting Started
License & acknowledgements
Project Info
User's Guide
Library Window
Playlist Window
Track Editor Window
Customization
Advanced Topics
Regular Expressions
Trouble Shooting
Tables
ID3 Frame Descriptions
Utilities
mp3 Management Scripts
Tag Backup
Tag Update
Text to Speech
Speech XML Format
Speech Phonemes
Author
Peter Bennett
My Other Projects
Peter's Backup
Proxy and debug tool
Jampal includes a management system that will organize and automate many tasks related to a large mp3 library. These programs are written as bash shell scripts and make heavy use of awk. Familiarity with shell scripts is essential for use of these scripts
The following is a summary of what these scripts do and how to run them. I have been using them for years. I have made many changes over the years and I continue to make modifications and enhancements.
System Requirements
This requires either windows with Cygwin or a Linux or Unix operating system or similar. If you are running Linux you are all set. If you have Windows, download and install Cygwin. If you have a dual boot system with Linux and Windows you can run this on both.
Linux / Cygwin components
Certain optional components are required. Many installations will already have these, if you do not you should obtain and install them.
| Product name | Used by | Where to get it |
|---|---|---|
| Open Office | mp3cover.sh | Free Download from openoffice.org. For CYGWIN get the Windows version. |
| FreeTTS | playlist.sh, playlistcd.sh, ptts.sh. | Free Download from freetts.sourceforge.net |
| Mbrola | playlist.sh, playlistcd.sh, ptts.sh. | Free Download from the MBROLA Project |
| Cepstral | playlist.sh, playlistcd.sh, ptts.sh. | Purchase from Cepstral. Free Trial is available. |
| sox | playlist.sh, playlistcd.sh, ptts.sh. | Free download from sourceforge.net |
Setup
Scripts are installed in a "scripts" directory under the jampal directory. For ease of operation you can add this to your path.
Your Jampal library or libraries must be set up with the option "use Unix style paths" if you are running windows / cygwin. See the jampal documentation for details and restrictions.
If using CYGWIN, all paths must be set up so that the path is compatible with Windows. This means creating links for example ln -s C:/Music /Music makes the /Music directory compatible. Use this for "Program Files" ln -s "C:/Program Files" "/Program Files".
Create a profile file. Copy the file mp3_base.profile to mp3.profile. Edit this file and insert your own values for each parameter. This contains directory names and options that will be used by the scripts. The profile caters for a dual boot Windows and Linux system if you have one, by checking the operating system and supplying different parameters as required. If you do not have a dual boot system you can ignore the parts that do not apply to you.
The scripts work best if you organize your library as follows.
Your library of mp3 files should be backed up on to CDs or DVDs. Name each CD or DVD with a serial number of the form YYMMDD_HHMM_X, using the date and time you created it and any character you please instead of X (e.g. you may want to identify the CDs with one character representing music type).
If you are starting out and they are not yet on CDs or DVDs, create a directory named as described, and put your files in subdirectories under that directory. Put up to 700 MB per CD directory or 4.2 GB per DVD directory. You can name the subdirectories anything you want, or just put them in one subdirectory.
Load the music files into jampal and make sure that they all have titles, artists, track numbers and album names. Without these filled in none of the scripts will work.
You can use the mp3lib.sh script to rename your files with the track number, title and artist and move them around into directories named according to the album title. After this you can burn them to CD or DVD.
mp3lib.sh
This script renames files and organizes them in directories. It has a safety feature built in which allows you to review all of the changes before anything is renamed.
A directory is created for each album. See below for how to handle tracks without an album name. It is named with a 3 digit number and the album name. Each track in the directory is named with a three digit number. They are ordered within directory by album name and track number.
If your mp3.profile has an entry for OLDISKFORMATBEFORE with a date YYMMDD, any CD or DVD with a date before that will be formatted differently. Albums will have a prefix A to Z and tracks will have a prefix of the album prefix and 2 digit track number (e.g. A01 for the first track of album A). This was an old scheme I used before DVDs and it restricts you to 26 albums per disk. This is fine for CDs but insufficient for DVDs.
Make sure all of your files are loaded into a jampal library that is located in the LIBDIR specified in mp3.profile. Make sure they all have titles, artists, track numbers and (where applicable) album names. A directory will be created for each album.
If you have some tracks without an album or you only have one or two tracks from some albums, You may want to group them in a directory together rather than creating a separate directory for each one. To do this, customize your library and add a field called Directory. This must be a "user defined text information frame" with description Directory. Also add this field to the tag editor, and select it in the Display Columns. Now you can enter values in the Directory field and those tracks will be placed in a directory named after that field instead of named after the album. I generally type Misc into that column and all of the tracks without an album are put in the Misc directory.
Save the library in jampal (File, Save Library). Run mp3lib.sh followed by your library name. There may be some error messages displayed, and then it will give you the option to view the list of renames, run it or ignore it. The first time you will probably want to look at it very carefully. If you press enter it will not run the renames, and you can try again at any time. If you type yes as prompted it will run the renames. After renaming and moving the files it updates your jampal library. If jampal is still open you must use the File, Reload library menu at this time.
Note - If you forget to reload no harm will result, the only effect is that jampal will report an error if you try to play or update a track that was renamed. The next time you start up jampal the library would be reloaded anyway. Even if you update in jampal some tracks that were not renamed, all will be sorted out next time you start jampal.
In the mp3.profile is an entry DELETEFRAME. This is set up as a text frame ID3V2TAGTXXXPeter. You can change this to another frame if you prefer. Which ever frame is specified here is used for removing unwanted songs. If you use this feature, this frame must be selected as part of your library and should be displayed in the library window. You can customize this within Jampal. If this frame is set to R or D, that song will be removed. It is not physically deleted, it is moved to another directory and the entry is removed from the library. Periodically you can clean up that other directory. The directory where the reject files go is identified in mp3.profile by the entry export REJECTPATH="$basedir/reject", by default it is directory "reject" under your music base directory. You can change it to any other directory if you prefer.
Sometimes it is necessary to run mp3lib.sh and the renames twice. If songs are being moved from one directory to another (i.e. you renamed their album or Directory, or you added new songs that are being moved to an existing directory), you will need to run mp3lib.sh and the renames twice. If a second rename is not necessary, when viewing the results you will see no songs being moved.
Usage
mp3lib.sh [-reorder] library-name [moved-file-dir]
The -reorder option can be used to reorder album directories within a CD directory. Each time you run p3lib.sh it creates a file called ZZAlbums.txt in each CD directory. If you edit one of these files you will se a list of album names. You can change the order by moving some entries with an editor and saving the file. After doing that run mp3lib.sh with the -reorder option. There is an important requirement: Before editing any ZZFiles.txt file run mp3lib.sh against the library and make sure that the renames have been done. If there are any renames outstanding the reorder will not run. If you run mp3lib.sh and it performs renames, run it a second time to make sure there is no second set of renames.
The optional parameter moved-file-dir is a directory name to which album directories have been moved.
In order for the library to be correct, you should not move or rename song files on the hard drive (except for the automatic moving and renaming done by mp3lib.sh). There is an exception to this rule. If you need to move one or more directories (albums) from one place to another, you can use this feature. You can move directories to a single new directory, then use mp3lib.sh with the destination directory specified as the moved-file-dir parameter. mp3lib.sh will adjust the library and rename all the other directories accordingly. This is most useful when you are trying to split albums up into groups of 700 MB for burning to CD.
mp3cover.sh
This script makes an envelope for an mp3 cd and a track listing to be inserted in the envelope with the cd.
mp3cover.sh [-artist] library-name diskser "desc"
On the cover album names will be listed. If you prefer you can use
the -artist option and then artist names will be listed. Enter the
cd serial number directory name as "diskser" and any title you
would like as "desc". The program will create an openoffice text
document and open it in openoffice. After reviewing it you can
print it.
The first pages of the document are an insert listing of tracks. The last page is an envelope. If you are making a DVD cover you probably have so many albums that the last page does not hold all the names and actually produces several pages. In that case, use openoffice to insert columns in the last page, sufficient so that it all fits, as follows.
- Select menu format, page, columns tab. Select 2 or 3 columns. Then use menu format, table. Reduce the column sizes and reduce the left spacing. After this you may still need to select the whoile table and reduce the font size. You can use fractions, such as 6.6 to achieve the correct size so that it fits on one page.
Making the envelope
These instructions are designed for USA letter sized paper (8.5
inches x 11 inches). If you are using A4 they may need some
modification.
Cut the index pages along the lines as shown below.
Turn the envelope page (last page) over and make marks as shown below in red. The printing on the example below will not be visible, it will be on the underside of the paper.
Place a ruler on the page along the red lines marked fold 1, fold 2, fold 3. In each case pull the paper up against the ruler to make a crease. Finally fold the right edge over to meet fold 1. This makes fold 4 (marked in blue).
Cut corners off as shown below.
Fold down the right hand flap.
Fold in the middle.
Fold over the tabs and tape them down.
Fold the index pages in half with the writing on the outside. Slide them into the envelope. Slide in the CD or DVD. The view from the front is shown below.
Fold down the top tab to close the envelope.
mp3dup.sh
This script helps you identify and remove duplicate songs. In order to save space on your hard drive, if a song exists on multiple albums you can remove some of the duplicates.
The script is used in conjunction with the mp3lib.sh script. Any songs you identify as duplicates are removed when you run mp3lib.sh.
A customized text field (ID3V2TAGTXXXDup) is used, as well as the frame that you designate in mp3.profile as DELETEFRAME. The DELETEFRAME is the name if the frame (usually a user text frame) that is used by mp3lib.sh to identify songs to remove. See the description under "mp3lib.sh" above. These frames must be selected as library fields in your main library.
To run it use mp3dup.sh. It does not take any parameters. The script creates a library called "duplicate" with possible duplicate songs identified, and opens it in Jampal. It uses transformations of the title and artist to identify possible duplicates even if they are not typed exactly the same. The duplicate library is created in your library directory the first time you run mp3dup.sh. You can customize the duplicate library and from then on it will use the customized version.
The first column of the library contains a DUMMY column with two numbers. First is a numeric sequence of the song number identified as a possible duplicate. Second is a number identifying which duplicate it is. This makes up the sort sequence, so if you change the order of songs in the duplicate library you can click on this column header and get it back to the initial sequence.
Look at the library and decide if the songs are real duplicates or not. If they are duplicates and you do not want to keep both copies, mark one as rejected. If you want to keep two or more copies mark each with a number in the Dup column. Then in future these will not be shown as duplicates.
Mark a song as rejected by putting R or D in the column identified by DELETEFRAME in your mp3.profile. Then running mp3lib.sh will move those files to your rejected directory and remove them from the library.
Tip - you can first mark them with another value (e.g. X) in the delete frame. Once you are sure and have double checked you can easily use jampal to change all songs with X in that column to R or D. (sort on the column, select all songs with X, edit tags, check off the delete frame, enter R or D for the value, click the Update button). Only songs with R or D in that column are removed.
mp3lame.sh
Usage: mp3lame.sh [-recode|-recode-even]
Converts files in a directory to mp3 using lame.
If you use no input option, it encodes all wave files in the current directory that have extension wav. It encodes to 128K mp3.
If you use option -recode, it re-encodes mp3 files in the current directory, but only if they have higher than 128K bit settings. It puts the re-encoded files in a subdirectory called recode.
If you use option -recode-even, it re-encodes all mp3 files in the current directory, regardless of their bit settings. It puts the re-encoded files in a subdirectory called recode.
When either of the recode options is used, the ID3V2 tag is copied to the new file after the recoding is done.
playlist.sh and playlistcd.sh
Creates a playlist with songs chosen and ordered by parameters you supply. You can choose using any values of combinations on values in the library, and order randomly or according to any values in the library. There are many iptions, which are shown if you enter the command with no parameters. The conditions are entered as expressions in the awk programming language.
playlistcd.sh takes the playlist that was generated and stores them in directories of the appropriate size for burning to CD. Alternatively stores them in directories of appropriate size for loading to an mp3 player. Also can load the songs directly to an mp3 player.
There are some examples in the examples subdirectory under scripts.
playlist.sh
| condition list |
An awk language expression which is used to select which songs
to include in the playlist. You can use field names from the
library in the format that is used for customization. Look in
your temp directory (from environment variable TEMPDIR) for a
file called xxxx.awkset, where xxxx is the library name. That
file contains a list of field names that can be used here.
Create an awk expression and enclose in single quotes. To
select all songs you can use something like '1==1'. You can use
awk functions like tolower in the expression. For example to
select songs by Loreena Mckennitt or Qntal you could use ' ( match(tolower(ARTIST),/loreena mckennitt/) || match(tolower(ARTIST),/qntal/) ) ' |
| sort field | Awk expression for fields that will be used to sort the playlist. You can use 'random' for a random sequence, or else expressions using the fields in xxxx.awkset. For example to sort by track within album you can use 'ALBUM " |" TRACK'. This concatenates album name , a blank, a pipe character, track number into a string for sorting. |
| sort option -r for reverse | Use a blank field '' to sort in ascending order or '-r' to sort in reverse order. |
| announce Y or N | Indicate whether you want synthesized voice announcements to be added to the mp3 files. |
| Tracks per directory | Maximum number of tracks per directory (default 100) |
| Start directory Number | Each directory will be numbered with a three digit number. Normally the first is numbered 002. You can change the first number here. (The default is 002 because my Kenwood car mp3 changer assigns 001 to the root directory and therefore displays 002 when playing the first directory). |
| library-name | Name of library to use for generating the playlist. This defaults to your main library. In some cases it is helpful to create a temporary library and drag songs to it from the main library, then use the temporary library name here. This wasy you can manually pick and choose what to include and exclude. |
| Announcements merge Y or N default Y | Y will add the announcements into the front of the mp3 music files. N will create separate small mp3 files with the announcements. |
| Speak. Default is TITLE " by " ARTIST | You can customize the announcement by using an awk expression. Note that you can only use fields that are in the library, unlike the Jampal accouncement customization which can use any field from the tag. |
| separator default ", followed by " | Where you have used the Jampal "Follow" option (See Playlist Window), the program will always add the following track in the playlist, even if it was not selected in the condition list and even if the sort sequence out it elsewhere. If you are using announcements it announces both tracks before playing the first one, and here you can customize what it says between track names. |
| directory change condition, default blank | If you leave this blank '' then each directory will have 100 songs or the maximum specified above. If you want a new directory for every album use ALBUM here. This only makes sense if you have sorted by album, otherwise you could end up with a new directory for each song. |
| Append sequence number to song name in tag, Y or N. Default N | Some mp3 playes (e.g. Sansa) ignore file names and sort songs by name. This is irritating. Here you can update the tag, appending a sequence number to each title to force the Sansa player to play songs in the order you have selected. |
| Maximum size per CD in MB. Default 690 | If you are loading an mp3 player, change this to the capacity of the player. You should subtract about 10 MB from the player capacity because the calculation is not always exact. If you prefer you can use 50% of the player capacity and create two directories on the player. Note that the actual capacity may be less that advertized or expected, a 512 MB player may only be 490 MB. The value you use here assumes 1 KB = 1024 bytes and 1 MB = 1048576 bytes. |
| Staging Directory. | The output is written here. If you leave it out it takes the value from mp3.profile (normally /Music/temp/playlist-cd). If you are writing to an mp3 player put its location here. Mount it under a directory e.g. /disks/PLAYER and enter that name here. In Windows this can be done by creating that directory then using "Disk Management". With Linux that is a mount command. |
tagbkup.sh and related scripts
Back up your mp3 tags so that if you lose your hard drive you can restore your songs from CD and then replace the latest version of your tags from the backup. Also keep track of which songs are saved to CD / DVD and report on any songs that were not saved.
Full instructions coming ...