shntool performs various functions on WAVE data through the use of mode modules. The core of shntool is simply a wrapper around the mode modules. In fact, when shntool is run with a valid mode as its first argument, it essentially runs the main procedure for the specified mode, and quits. shntool comes with several built-in modes, described below:

len

Shows size, length, and properties of PCM WAVE data within files

fix

Fixes sector-boundary problems with CD-quality PCM WAVE data

md5

Computes the MD5 fingerprint of PCM WAVE data

pad

Pads CD-quality files not aligned on sector boundaries with silence

join

Joins PCM WAVE data from multiple files into one large file

split

Splits PCM WAVE data from one file into multiple files

cat

Writes (catenates) PCM WAVE data from one or more files to stdout

cmp

Compares PCM WAVE data in two files

cue

Generates a CUE sheet or split points from a set of files

conv

Converts files from one format to another

info

Shows detailed information about WAVE data and other properties for each file given

strip

Strips extra RIFF chunks and/or writes canonical headers

For more information on the meaning of the various command-line arguments for each mode, see the OPTIONS section below.

For convenience, each mode can specify an alternate name or alias that will invoke it (this feature is currently only available on systems that support symbolic or hard linking). In particular, each mode is aliased to 'shn<mode>'. For instance, running shnlen is equivalent to running shntool len - thus saving a few keystrokes.

File formats are abstracted from shntool through the use of format modules. They provide a means for shntool to tranparently read and/or write different file formats. This abstraction allows shntool to concentrate on its job without worrying about the details of each file format.

The following formats are currently supported:

wav

RIFF WAVE file format

aiff

Audio Interchange File Format (AIFF and uncompressed/sowt AIFF-C only) (via sox [1])

shn

Shorten low complexity waveform coder (via shorten [2])

flac

Free Lossless Audio Codec (via flac [3])

ape

Monkey's Audio Compressor (via mac [4])

ofr

OptimFROG Lossless WAVE Audio Coder (via ofr [5])

lpac

Lossless Predictive Audio Compression (via lpac [6])

wv

WavPack Hybrid Lossless Audio Compression (via wavpack/wvunpack [7])

cust

Custom output format module (output only, useful for specifying non-standard arguments to encoders for existing output formats, or encoding to a format that shntool does not yet support)

null

sends output to /dev/null (output only, useful for dry-runs in several modes, such as fix mode or strip mode)

When reading files for input, shntool automatically discovers which, if any, format module handles each file. In modes where files are created as output, you can specify what the output format should be - otherwise, shntool decides for you by selecting the first format module it finds that supports output (in a default installation, this will be the wav format).

NOTE: after all files have been processed, a summary line will be shown displaying the total time, size, number of files processed, and the overall compression ratio (i.e. the total size of the actual files on disk divided by the total size of WAVE data (header, audio, extra RIFF chunks) contained in the files).

-u unit

Specifies the unit in which totals will be printed. Valid values are b (bytes), kb (kilobytes), mb (megabytes), or gb (gigabytes). The default is bytes.

The output of len mode may seem cryptic at first, because it attempts to convey a lot of information in just a little bit of space. But it is quite easy to read once you know what the columns represent; and in certain columns, what each character in the column means. Each column is explained below.

length

Shows the length of the WAVE data, in m:ss.nnn (millisecond) format. If the data is CD-quality, then m:ss.ff is shown instead, where ff is a number from 00 to 74 that best approximates the number of frames (2352-byte blocks) remaining after m:ss. If all files are CD-quality, the total length will be shown in m:ss.ff format; otherwise it will be in m:ss.nnn format. NOTE: CD-quality files are rounded to the nearest frame; all other files are rounded to the nearest second.

expanded size

Shows the total size of all WAVE chunks within the file (header, data and any extra RIFF chunks). Essentially this is the size that the file would be if it were converted to .wav format, e.g. with shntool conv

NOTE: Do not rely on this field for audio size! If you simply want to know how many bytes of audio are in a file, run it through info mode, and look at the "data size" field in its output.

cdr

Shows properties related to CD-quality files. A 'c' in the first slot indicates that the WAVE data is not [C]D-quality. A 'b' in the second slot indicates that the CD-quality WAVE data is not cut on a sector [b]oundary. An 's' in the third slot indicates that the CD-quality WAVE data is too [s]hort to be burned.

A '-' in any of these slots indicates that the particular property is OK or normal. An 'x' in any of these slots indicates that the particular property does not apply to this file, or cannot be determined.

WAVE

Shows properties of the WAVE data. An 'h' in the first slot indicates that the WAVE [h]eader is not canonical. An 'e' in the second slot indicates that the WAVE file contains [e]xtra RIFF chunks.

A '-' in any of these slots indicates that the particular property is OK or normal. An 'x' in any of these slots indicates that the particular property does not apply to this file, or cannot be determined.

problems

Shows problems detected with the WAVE header, WAVE data, or the file itself. A '3' in the first slot indicates that the file contains an ID[3]v2 header. An 'a' in the second slot indicates that the audio data is not block-[a]ligned. An 'i' in the third slot indicates that the WAVE header is [i]nconsistent about data size and/or file size. A 't' in the fourth slot indicates that the WAVE file seems to be [t]runcated. A 'j' in the fifth slot indicates that the WAVE file seems to have [j]unk appended to it.

A '-' in any of these slots indicates that the particular problem was not detected. An 'x' in any of these slots indicates that the particular problem does not apply to this file, or cannot be determined.

filename

Shows the name of the file that's being inspected.

NOTE: file names for files created in fix mode will be based on the input file name with the string '-fixed' appended to it, and the extension will be the default extension of the output file format. For example, with an output file format of shn the file 'foo.wav' would become 'foo-fixed.shn'.

-o format

Specifies the output file format. If not given, this defaults to the first file format it can find that supports output.

-O action

Specifies whether output files should be overwritten if they exist. Valid values for action are ask (ask before overwriting), always (always overwrite - this is the default), or never (never overwrite). NOTE: This option has no effect when using the cust output format module.

-d dir

Specifies an alternate directory where output files will be created. The default is the current directory.

-s type

Specifies the shift type. Valid values are b (shift track breaks Backward to previous multiple of 2352 bytes when necessary), f (shift track breaks Forward to next multiple of 2352 bytes when necessary), and r (Round track breaks to the nearest multiple of 2352 bytes when necessary). The default is to shift track breaks backward.

-nopad

Specifies that the last file created should not be padded with zero-bytes to make its WAVE data size a multiple of 2352 bytes. The default is to pad the last file.

-noskip

Specifies that all files should be processed, even if the first several of them wouldn't be altered (aside from a possible file format change). The default is to skip the first N files that wouldn't be changed (from a WAVE data perspective) in order to avoid unnecessary work.

-order

Allows you to edit the order of the files given on the command line. This is useful for situations where *.shn might give file1.shn, file10.shn, file11.shn, file2.shn, file3.shn, etc.

-p

Preview what changes would be made, without actually making them.

-c

Specifies that the composite MD5 fingerprint for all input files should be calculated, instead of the default of one MD5 fingerprint per file. The composite MD5 fingerprint is simply the MD5 fingerprint of the WAVE data from all input files taken as a whole in the order given, and is identical to the one that would be calculated from the joined file if the same files were joined into one large file, with no padding added. This option can be used to fingerprint file sets, or to identify file sets in which track breaks have been moved around, but no audio has been modified in any way (e.g. no padding added, no resampling done, etc.).

NOTE: file names for files created in pad mode will be based on the input file name with the string '-prepadded' or '-postpadded' appended to it, and the extension will be the default extension of the output file format. For example, with an output file format of shn and pre-padding specified on the command line, the file 'foo.wav' would become 'foo-prepadded.shn'.

Be aware that some output format encoder programs (e.g. flac, ape) automatically strip headers and/or extra RIFF chunks.

-o format

Specifies the output file format. If not given, this defaults to the first file format it can find that supports output.

-O action

Specifies whether output files should be overwritten if they exist. Valid values for action are ask (ask before overwriting), always (always overwrite - this is the default), or never (never overwrite). NOTE: This option has no effect when using the cust output format module.

-d dir

Specifies an alternate directory where output files will be created. The default is the same directory as the associated input file.

-prepad

Specifies that the file created should be padded at the beginning with zero-bytes to make its WAVE data size a multiple of 2352 bytes.

-postpad

Specifies that the file created should be padded at the end with zero-bytes to make its WAVE data size a multiple of 2352 bytes. This is the default action.

-p

Preview what changes would be made, without actually making them.

NOTE: file names for files created in join mode will be prefixed with 'joined.', and the extension will be the default extension of the output file format. For example, with an output file format of wav the files 'files*.wav' would become 'joined.wav'. Disregard this if you are using the -stdout option.

-o format

Specifies the output file format. If not given, this defaults to the first file format it can find that supports output.

-O action

Specifies whether output files should be overwritten if they exist. Valid values for action are ask (ask before overwriting), always (always overwrite - this is the default), or never (never overwrite). NOTE: This option has no effect when using the cust output format module.

-d dir

Specifies an alternate directory where the output file will be created. The default is the current directory.

-nopad

Specifies that the file created should not be padded with zero-bytes to make its WAVE data size a multiple of 2352 bytes. Note that this option does not apply if the input files are not CD-quality, since padding is undefined in that case.

-prepad

Specifies that the file created should be padded at the beginning with zero-bytes to make its WAVE data size a multiple of 2352 bytes. Note that this option does not apply if the input files are not CD-quality, since padding is undefined in that case.

-postpad

Specifies that the file created should be padded at the end with zero-bytes to make its WAVE data size a multiple of 2352 bytes. This is the default action. Note that this option does not apply if the input files are not CD-quality, since padding is undefined in that case.

-stdout

Specifies that data should be written to stdout, not a file. This option can only be used with the 'wav' file format.

-order

Allows you to edit the order of the files given on the command line. This is useful for situations where *.shn might give file1.shn, file10.shn, file11.shn, file2.shn, file3.shn, etc.

-p

Preview what changes would be made, without actually making them.

NOTE: file names for files created in split mode are of the form prefixNNN.ext, where NNN is the output file number, and 'ext' is the default extension of the output file format. If an output file format of 'wav' is used, and the prefix is not altered via the -n switch described below, then the output file names will be "split-track01.wav", "split-track02.wav", etc.

For information on specifying split points, see the "Specifying split points" section below.

-o format

Specifies the output file format. If not given, this defaults to the first file format it can find that supports output.

-O action

Specifies whether output files should be overwritten if they exist. Valid values for action are ask (ask before overwriting), always (always overwrite - this is the default), or never (never overwrite). NOTE: This option has no effect when using the cust output format module.

-d dir

Specifies an alternate directory where output files will be created. The default is the current directory.

-f file

Specifies a file from which to read split point data. If not given, then split points are read from stdin.

-l len

Specifies that the input file should be split into smaller files based on multiples of time interval len

-n name

Specifies a prefix name to use when building output filenames. The default prefix is "split-track".

-c num

Specifies the number to start counting from when naming output files. The default is 1.

-p

Preview what changes would be made, without actually making them.

Split points simply mark places within the WAVE data of the input file where tracks will be split. They can be specified in any combination of the following formats:

bytes

where bytes is a specific byte offset

m:ss

where m = minutes and ss = seconds

m:ss.ff

where m = minutes, ss = seconds and ff = frames (75 per second, so ff ranges from 00 to 74)

m:ss.nnn

where m = minutes, ss = seconds and nnn = milliseconds (will be rounded to closest sector boundary, or the first sector boundary if the closest one happens to be the beginning of the file)

CUE sheet

- a simple CUE sheet, in which each "INDEX 01 m:ss:ff" line is converted to a m:ss.ff split point

Split points must be given in increasing order, and must appear one per line. If the byte offset calculated from the final split point equals the input file's WAVE data size, then it is ignored. Since split points specify locations within the input file where tracks will be split, N split points will create N+1 output files. All m:ss formats will create splits on sector boundaries whenever the input file is CD-quality; to force non-sector-aligned splits, use the exact byte format.

-nh

Specifies that the WAVE header should be suppressed from the output. The default is to write the header.

-nd

Specifies that the WAVE data should be suppressed from the output. The default is to write the data.

-nr

Specifies that extra RIFF chunks should be suppressed from the output. The default is to write the extra RIFF chunks.

-np

Specifies that the NULL pad byte at end of odd-sized data chunks should be suppressed from the output, if present. The default is to write the NULL pad byte. This option only applies when WAVE data is also written, otherwise it is ignored.

-s

Check to see whether the WAVE data contained in the input files are identical modulo a byte-shift. Currently, this will only detect differences up to the first 529200 bytes (equal to 3 seconds of CD-quality data). This can be used to compare WAVE data within a pre-burned file to WAVE data in the corresponding track ripped from the burned CD, which is useful if the ripped track came from a CD burned TAO, and thus might have a 2-second gap of silence at the beginning. This option can also help identify a CD burner/CD reader combined read/write offset.

-l

List offsets and values of all differing bytes. Output is similar to 'cmp -l'; in particular, offsets are 1-based. Can be used with the -s switch.

-f fuzz

Sets the "fuzz factor" for determining whether byte-shifted data is identical. fuzz is a positive integer that represents the maximum number of allowable byte mismatches between the two files in the area searched by the -s option. This allows one to check for differing bytes between to files that (a) are byte-shifted and (b) contain at least one error in the area searched by the -s option. The higher the fuzz factor, the longer the search takes, so set it low to begin with (8 or so), and increase it in small steps if needed. NOTE: this switch can only be used with the -s switch.

-c

Specifies that a simple CUE sheet should be output. This is the default action. NOTE: all input files must be CD-quality for CUE sheets to be valid.

-s

Specifies that split points in explicit byte-offset format should be output.

NOTE: file names for files created in conv mode will be named based on the input file name. Specifically, if the input file name ends with the default file extension for that file's format, then the default extension for the desired output format will replace it; otherwise, it will be appended to it. For example, for an output format of shn and a wav input file named 'file.wav', the converted file will be named 'file.shn', since '.wav' is shntool's default extension for the wav format. On the other hand, given the same situation above, but with an input file named 'file.wave', the converted file will be named 'file.wave.shn', since '.wave' does not match '.wav'.

Be aware that some output format encoder programs (e.g. flac, ape) automatically strip headers and/or extra RIFF chunks, while others (e.g. sox) might adjust WAVE data sizes in rare instances in order to align the audio on a block boundary.

-o format

Specifies the output file format. If not given, this defaults to the first file format it can find that supports output.

-O action

Specifies whether output files should be overwritten if they exist. Valid values for action are ask (ask before overwriting), always (always overwrite - this is the default), or never (never overwrite). NOTE: This option has no effect when using the cust output format module.

-d dir

Specifies an alternate directory where output files will be created. The default is the same directory as the associated input file.

This mode doesn't support any additional arguments.

NOTE: file names for files created in strip mode will be based on the input file name with the string '-stripped' appended to it, and the extension will be the default extension of the output file format. For example, with an output file format of wav the file 'bar.shn' would become 'bar-stripped.wav'.

Be aware that some output format encoder programs (e.g. flac, ape) automatically strip headers and/or extra RIFF chunks, while others (e.g. sox) might adjust WAVE data sizes in rare instances in order to align the audio on a block boundary.

-o format

Specifies the output file format. If not given, this defaults to the first file format it can find that supports output.

-O action

Specifies whether output files should be overwritten if they exist. Valid values for action are ask (ask before overwriting), always (always overwrite - this is the default), or never (never overwrite). NOTE: This option has no effect when using the cust output format module.

-d dir

Specifies an alternate directory where output files will be created. The default is the same directory as the associated input file.

-nh

Specifies that WAVE headers should not be made canonical. The default is to canonicalize headers.

-nr

Specifies that extra RIFF chunks should not be stripped. The default is to remove everything that appears after the first data chunk.

-p

Preview what changes would be made, without actually making them.