shntool
What is it?
What does it do?
Len mode
Fix mode
Where can I get it?
How do I compile the source?
Command-line switches
How do I run it?
Len mode examples
Fix mode examples
Known bugs
Future improvements
Credits
Contact information
What is it?
shntool is a multi-purpose .wav/.shn processing utility. File formats are abstracted from the functions that perform the real work in shntool. Thus, .shn files and .wav files are structurally identical from its perspective.
As far as its functionality, shntool currently has several uses. shntool can:
- report size/length information about the WAVE data within .wav and/or .shn files
- write corrected files for input files that weren't cut on sector boundaries (in this respect, it's sort of a rudimentary CDWave for unix, except it can read and write .shn's as well as .wav's)
- write a concatenated .wav or .shn file from the given .wav and/or .shn files
- print all WAVE information contained in the header of .wav and/or .shn files
shntool has native support for .wav files. If you want to also work with .shn files, you must have
shorten somewhere in your default PATH.
shntool is currently beta software (though I run it with no problems). Keep this in mind! If you use shntool, be sure to double-check its results until you feel comfortable with it.
If you have a great idea for shntool, let me know! Or code it yourself - shntool is GPL'ed. ;-)
What does it do?
Depending upon the mode it is run in, shntool will perform certain actions. shntool currently has two modes, 'len' mode and 'fix' mode.
Note that any error messages are printed to stderr, so you can redirect them to /dev/null if you don't want to see them. (I suggest you don't do this while in fix mode, because error messages there are pretty important.)
Len mode
In len (length) mode, files are quickly scanned to determine their contents. Len mode takes the following arguments:
- an optional argument from the following list (if none is given, the default unit is bytes):
- "-kb" to specify that totals should be output in kilobytes
- "-mb" to specify that totals should be output in megabytes
- "-gb" to specify that totals should be output in gigabytes
- an optional argument, "-debug", to specify that all of the following information be printed for each file given, instead of the standard output line (described below):
- the file name
- length, in mm:ss format
- samples per second
- number of channels
- bits per sample
- average bytes per second
- rate (should equal average bytes per second)
- block align
- header size
- data size
- total size
- chunk size
- any errors associated with the file
If the file is a .wav file (not a .shn), then to aid in debugging 'hdr' errors, you will also see:
- header size + data size
- chunk size + 8
- actual size
All three of the above should match.
- finally, optional file names to process. If none are given, then file names are read from standard input.
If "-debug" is not specified, then for each valid file name given, shntool reports the following information:
- the length of the WAVE data within the .wav or .shn, in minutes:seconds format
- the exact size, in bytes, of the WAVE data within that .wav or .shn
- One of the following status indicators:
- the word "bound" if the WAVE data within that .wav or .shn is not cut on a sector boundary, or
- the word "short" if the WAVE data within that .wav or .shn is too short to be burned, or
- the word " hdr " if the WAVE header within that .wav contains incorrect information with respect to sizes (not applicable to .shn files), or
- the character " - " (dash, or minus sign) otherwise
- the file name of the .wav or .shn
After all files have been processed, it will report the total run length and disk space used and/or needed for the given files.
Fix mode
In fix mode, the given files are checked for .shn and/or .wav validity, and are processed only if (a) all files pass the check and (b) all files have identical headers (to prevent accidental mixing of different WAVE streams). Fix mode takes the following arguments:
- a required argument, "-wav" or "-shn", which specifies .wav or .shn output, respectively
- a required argument from the following list:
- "-b" to specify that track breaks be moved backward to the previous multiple of 2352 bytes, where necessary, or
- "-f" to specify that track breaks be moved forward to the next multiple of 2352 bytes, where necessary, or
- "-j" to specify that all WAVE data from the given files be joined together in one large output file (useful if you want to split the tracks with a more advanced .wav editor)
- an optional argument "-d", which indicates that the next argument is the name of an alternate output directory
- an optional argument "-pad" to force padding of the last file written in fix mode, if necessary
- an optional argument "-order" to edit the order that your files will be processed (see the important note below)
- finally, at least two filenames to process.
While running in fix mode, shntool displays which file it is currently processing. Output file names will be in the following format:
- prefix-fixed.ext (for forward- and backward-shifted files created with "-f" or "-b")
- joined.ext (for joined files created with "-j")
where 'prefix' is the basename of the input filename, and '.ext' is either '.shn' or '.wav', depending on what you specify. For example, assuming that the '-wav' command-line switch was given, 'th79-08-08d1t03.shn' would become 'th79-08-08d1t03-fixed.wav'.
If you use fix mode, make sure to listen to the resulting files to ensure that they came out alright. There is always the possibility of a bug lurking in the WAVE-splitting code.
IMPORTANT NOTE!
Because some shows contain files with non-etree-standardized names, simply running (for example) 'shntool -fix -shn -b *.shn' on those .shn's will produce unexpected (i.e.
wrong) results, because of the wildcard expansion. That's why I've included an optional switch, "-order", which allows you to edit the order that the files will be processed. Typing (for example) 'shntool -fix -shn -b -order *.shn' will bring up this editor. Below is a chart showing an example of how non-etree-standardized file names can screw up the file order:
File order from wildcard expansion -
Desired file order
track1.shn -- track1.shn
track10.shn - track2.shn
track11.shn - track3.shn
track12.shn - track4.shn
track13.shn - track5.shn
track2.shn -- track6.shn
track3.shn -- track7.shn
track4.shn -- track8.shn
track5.shn -- track9.shn
track6.shn -- track10.shn
track7.shn -- track11.shn
track8.shn -- track12.shn
track9.shn -- track13.shn
Where can I get it?
Right here. To see if you are using the most current version, type 'shntool -v'.
version 0.95, released 2000-10-19
+ Available as C source code (56711 bytes)
+ Now available for DOS/Windows: shntool.zip (316969 bytes) - thanks Caleb Epstein!
NOTE: Please consult the README file included in this zip file for installation instructions.
+ fixed bug where chunk size wasn't being updated for files that were altered in fix mode
+ added code to help determine whether shorten is in the default path
+ WAVE data for headers in .wav (not .shn) files are now verified
+ file names created in fix mode are now based on input filenames when -f or -b are given
version 0.94, released 2000-08-24
+ Available as C source code (53189 bytes)
+ added new fix mode switch "-pad" to force padding of the last file written with zeroed bytes up to the next multiple of the sector size, if necessary
version 0.93, released 2000-07-06
+ Available as C source code (51151 bytes)
+ I partially broke file reading from stdin in len mode in 0.92 - fixed.
+ did several other minor cleanups/corrections that did not affect the core functionality of shntool
version 0.92, released 2000-07-04
+ Available as C source code (49633 bytes)
+ added setlinebuf() support for architectures that don't have it (see the compiling section for more info)
+ added description of the len mode "-debug" flag to its help menu
version 0.91, released 2000-07-04
+ Available as C source code (49201 bytes)
+ WAVE headers are now processed correctly (this was the bug reported in version 0.9)
+ added "-debug" switch for len mode
+ fixed segfaults with headers > 64 bytes
version 0.9, released 2000-07-03
+ Available as C source code (45179 bytes)
+ Initial release
How do I compile the source?
Simple:
% gcc -Wall shntool.c -o shntool
%
NOTE: If you see the following error trying to compile shntool as above, try using the "-D_SETLINEBUF_HACK" compiler switch:
% gcc -Wall shntool.c -o shntool
shntool.c: In function `start_child':
shntool.c:311: warning: implicit declaration of function `setlinebuf'
% gcc -Wall -D_SETLINEBUF_HACK shntool.c -o shntool
%
Now stick 'shntool' somewhere in your PATH.
For ease of use, shntool recognizes when it is run as 'shnlen' and 'fixwav'. This way, by creating symbolic links to shntool with these names, you can avoid having to remember to specify which mode you want to run shntool in. Here's how to do this:
% cd /directory/where/shntool/is/installed
% ln -s shntool shnlen
% ln -s shntool fixwav
%
Thus, running 'shnlen' is equivalent to running 'shntool -len', and running 'fixwav' is equivalent to running 'shntool -fix'.
NOTE: If you previously installed the older program 'shnlen', make sure that you remove it before installing shntool. You can find out your shnlen version by typing 'shnlen -v'. If it's 0.5 or less, you need to remove the old shnlen executable.
The source is known to compile cleanly on the following platforms (given by 'uname -srm'):
- Linux 2.2.x i686
- Linux 2.2.x alpha
- Linux 2.0.x i686
- Linux 2.0.34 mips (Cobalt Qube)
- SunOS 5.7 sun4u
- SunOS 5.5.1 sun4u
- SunOS 4.1.4 sun4c
- FreeBSD 3.4-RELEASE i386
- IRIX64 6.5 IP27
- IRIX 6.5 IP22
- HP-UX B.10.20 9000/735
- add your platform here
Thanks to Steve B. for providing several of these entries.
If it does not compile on some other platform, but you successfully port it to that platform, please let me know!
Command-line switches
To see what command-line switches are supported, simply type 'shntool -h'.
% shntool -h
usage: shntool [ -len | -fix ] ...
For help with the -len switch, type 'shntool -len -h'.
For help with the -fix switch, type 'shntool -fix -h'.
%
How do I run it?
Here are some sample uses. How you use it is entirely up to you.
Len mode examples
Here's a file not cut properly on a sector boundary:
% shntool -len disc1/lc85-07-06d1t10.shn
4:45 50398704 bound disc1/lc85-07-06d1t10.shn
4:45 50398704 B (total for 1 file)
%
See exactly what information is contained within a troublesome file:
% shntool -len -debug lc85-07-06d1t10.shn
filename: lc85-07-06d1t10.shn
samples/sec: 44100
channels: 2
bits/sample: 16
avg. bytes/sec: 176400
rate: 176400
block align: 4
header size: 44
data size: 50398660
total size: 50398704
length: 4:45
errors: not cut on sector boundary
---------------------------------------------------------------
%
Get statistics for one disc of a show, and display totals in terms of megabytes:
% shntool -len -mb *.wav *.shn
29:12 309097532 gd78-10-22d1t1.shn
6:15 66288812 gd78-10-22d1t2.shn
4:33 48277196 gd78-10-22d1t3.wav
6:07 64891724 gd78-10-22d1t4.shn
9:49 104021948 gd78-10-22d1t5.wav
6:29 68749004 gd78-10-22d1t6.wav
10:29 111049724 gd78-10-22d1t7.shn
72:59 736.60 MB (totals for 7 files)
%
Find out how many gigabytes of WAVE data you have sitting within the .wav's and .shn's on your hard drive(s):
% find / -iname \*.shn -o -iname \*.wav | shntool -len -gb | tail -1
4966:56 48.96 GB (totals for 773 files)
%
Fix mode examples
Fix a disc of .shn's, where some files are not cut on sector boundaries, and write our fixed files as .shn's (note that the last file in a disc might still not be cut on a sector boundary, unless you specify the '-pad' option like I do below). I show the results of 'shntool -len' on these files, before and after fixing, for comparison:
% shntool -len ak98-08-21/disc1/*.shn
3:23 35911420 bound ak98-08-21/disc1/ak98-08-21t101.shn
4:23 46550828 - ak98-08-21/disc1/ak98-08-21t102.shn
3:57 41844476 - ak98-08-21/disc1/ak98-08-21t103.shn
4:27 47261132 - ak98-08-21/disc1/ak98-08-21t104.shn
4:16 45299560 bound ak98-08-21/disc1/ak98-08-21t105.shn
3:05 32803388 - ak98-08-21/disc1/ak98-08-21t106.shn
3:41 39113804 - ak98-08-21/disc1/ak98-08-21t107.shn
4:50 51193676 - ak98-08-21/disc1/ak98-08-21t108.shn
5:39 59804348 - ak98-08-21/disc1/ak98-08-21t109.shn
3:40 38979740 - ak98-08-21/disc1/ak98-08-21t110.shn
5:09 54547624 bound ak98-08-21/disc1/ak98-08-21t111.shn
5:00 53025872 bound ak98-08-21/disc1/ak98-08-21t112.shn
3:32 37455644 - ak98-08-21/disc1/ak98-08-21t113.shn
3:15 34503884 - ak98-08-21/disc1/ak98-08-21t114.shn
4:36 48780524 - ak98-08-21/disc1/ak98-08-21t115.shn
4:32 48110204 - ak98-08-21/disc1/ak98-08-21t116.shn
3:05 32681084 - ak98-08-21/disc1/ak98-08-21t117.shn
70:39 747867208 B (totals for 17 files)
% shntool -fix -shn -d /mnt/fixed -b -pad ak98-08-21/disc1/*.shn
ak98-08-21/disc1/ak98-08-21t101.shn --> /mnt/fixed/ak98-08-21t101-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t102.shn --> /mnt/fixed/ak98-08-21t102-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t103.shn --> /mnt/fixed/ak98-08-21t103-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t104.shn --> /mnt/fixed/ak98-08-21t104-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t105.shn --> /mnt/fixed/ak98-08-21t105-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t106.shn --> /mnt/fixed/ak98-08-21t106-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t107.shn --> /mnt/fixed/ak98-08-21t107-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t108.shn --> /mnt/fixed/ak98-08-21t108-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t109.shn --> /mnt/fixed/ak98-08-21t109-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t110.shn --> /mnt/fixed/ak98-08-21t110-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t111.shn --> /mnt/fixed/ak98-08-21t111-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t112.shn --> /mnt/fixed/ak98-08-21t112-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t113.shn --> /mnt/fixed/ak98-08-21t113-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t114.shn --> /mnt/fixed/ak98-08-21t114-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t115.shn --> /mnt/fixed/ak98-08-21t115-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t116.shn --> /mnt/fixed/ak98-08-21t116-fixed.shn ... done.
ak98-08-21/disc1/ak98-08-21t117.shn --> /mnt/fixed/ak98-08-21t117-fixed.shn ... done. Padded this file with 1332 zero bytes.
% shntool -len -pad /mnt/fixed/*fixed.shn
3:23 35910380 - /mnt/fixed/ak98-08-21t101-fixed.shn
4:23 46550828 - /mnt/fixed/ak98-08-21t102-fixed.shn
3:57 41844476 - /mnt/fixed/ak98-08-21t103-fixed.shn
4:27 47261132 - /mnt/fixed/ak98-08-21t104-fixed.shn
4:16 45299564 - /mnt/fixed/ak98-08-21t105-fixed.shn
3:05 32803388 - /mnt/fixed/ak98-08-21t106-fixed.shn
3:41 39113804 - /mnt/fixed/ak98-08-21t107-fixed.shn
4:50 51193676 - /mnt/fixed/ak98-08-21t108-fixed.shn
5:39 59804348 - /mnt/fixed/ak98-08-21t109-fixed.shn
3:40 38979740 - /mnt/fixed/ak98-08-21t110-fixed.shn
5:09 54547628 - /mnt/fixed/ak98-08-21t111-fixed.shn
5:00 53025884 - /mnt/fixed/ak98-08-21t112-fixed.shn
3:32 37455644 - /mnt/fixed/ak98-08-21t113-fixed.shn
3:15 34503884 - /mnt/fixed/ak98-08-21t114-fixed.shn
4:36 48780524 - /mnt/fixed/ak98-08-21t115-fixed.shn
4:32 48110204 - /mnt/fixed/ak98-08-21t116-fixed.shn
3:05 32683436 - /mnt/fixed/ak98-08-21t117-fixed.shn
70:39 747868540 B (totals for 17 files)
%
Create one large .wav file from a disc's worth of .shn's, without padding it. Again, I show the results of 'shntool -len' on the joined file for comparison. Note that the joined files size will be smaller than the sum of the split files - this is due to the header lengths of the split files being counted in the total file size.
% shntool -fix -wav -j ak*.shn
Adding contents of ak98-08-21t101.shn to joined.wav ... done.
Adding contents of ak98-08-21t102.shn to joined.wav ... done.
Adding contents of ak98-08-21t103.shn to joined.wav ... done.
Adding contents of ak98-08-21t104.shn to joined.wav ... done.
Adding contents of ak98-08-21t105.shn to joined.wav ... done.
Adding contents of ak98-08-21t106.shn to joined.wav ... done.
Adding contents of ak98-08-21t107.shn to joined.wav ... done.
Adding contents of ak98-08-21t108.shn to joined.wav ... done.
Adding contents of ak98-08-21t109.shn to joined.wav ... done.
Adding contents of ak98-08-21t110.shn to joined.wav ... done.
Adding contents of ak98-08-21t111.shn to joined.wav ... done.
Adding contents of ak98-08-21t112.shn to joined.wav ... done.
Adding contents of ak98-08-21t113.shn to joined.wav ... done.
Adding contents of ak98-08-21t114.shn to joined.wav ... done.
Adding contents of ak98-08-21t115.shn to joined.wav ... done.
Adding contents of ak98-08-21t116.shn to joined.wav ... done.
Adding contents of ak98-08-21t117.shn to joined.wav ... done.
% shntool -len joined.wav
70:39 747866504 bound joined.wav
70:39 747866504 B (total for 1 file)
%
Known bugs
shntool's WAVE header parsing algorithm is not comprehensive - it only recognizes canonical WAVE headers and certain variations of the canonical format. Multiple RIFF chunks and/or other chunk types may cause the file to be declared "not a .shn or a .wav file." If you run into this problem, please let me know, and try to provide a way for me to get a hold of the offending file(s) so I can improve shntool. (Thanks to Jeff Kempka for reporting this bug)
Future Improvements
- generalize the WAVE header parsing algorithm to support a wider range of headers
- possibly add an option to write canonical WAVE headers in fix mode
- possibly make shntool track-splitting more robust, so that it can split tracks according to user input, instead of just correcting the splits by jumping to the next (or previous) sector boundary
- when in fix mode, have shntool check whether any changes would be made before processing files (you can do this manually by running shntool in len mode on the files to be processed)
I'm open to suggestions, so let me know if you have an idea for an improvement.
Credits
Special thanks goes out to Tim [tmo], whose ideas prompted the creation of this program's predecessor (shnlen), and whose diligent testing helped iron out the bugs in that program.
Thanks also goes out to Herschel Gelman, who had the great suggestion that shnlen could check to see whether the .wav files inside the .shn's were properly cut on sector boundaries.
Both of these ideas/functionalities were carried over into shntool.
Who do I contact if I have any questions/comments/suggestions/patches/bugs/flames?
Send it all to jasonxxxx.xxxxxxxx.xxx.