SHNTOOL(1)

NAME
shntool - a multi-purpose WAVE data processing and reporting utility

SYNOPSIS
shntool mode ...
shntool [ -m | -v | -h ]

DESCRIPTION
shntool is a command-line utility to view and/or modify WAVE data and properties. It runs in several different operating modes, and supports various file formats.

shntool is comprised of three parts - its core, mode modules, and format modules. This helps to make the code easier to maintain, as well as aid other programmers in developing new functionality. The distribution archive contains a file named 'modules.howto' that describes how to create a new mode or format module, for those so inclined.

  Mode modules
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

    join
        Joins CD-quality PCM WAVE data from multiple files into one large file

    split
        Splits CD-quality PCM WAVE data from one file into smaller files

    cat Writes (catenates) PCM WAVE data from a single file to stdout

    cmp Compares PCM WAVE data in two files

    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.

  Format modules
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 standard WAVE data file

    shn shorten low complexity waveform coder [1]

    kxs kexis lossless WAV file compressor - EXPERIMENTAL (input only) [2]

    null
        sends output to /dev/null (output only, useful for dry-runs in fix 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 file type should be - otherwise, shntool decides for you by selecting the first format module it finds that supports output.

OPTIONS
When run without a mode, shntool takes these command-line arguments:

-m  Shows detailed module information

-v  Shows version information

-h  Shows a help screen

All mode modules support their own -v and -h options, as well as the -- option, which indicates that the command-line arguments following it should not be processed as switches (i.e. they should be treated as file names). In addition to these, each mode supports its own set of optional arguments, described below.

  len mode optional arguments

-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.

  fix mode optional arguments
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.

-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.

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

-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.

  join mode optional arguments
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'.

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

-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. The default is to pad the file.

-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.

  split mode optional arguments
NOTE: file names for files created in split mode are of the form prefixNN.ext, where NN 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.

-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.

-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.

  Specifying split points

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)

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; to force non-sector-aligned splits, use the exact byte format.

  cat mode optional arguments

-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.

  cmp mode optional arguments
This mode doesn't support any additional arguments.

  info mode optional arguments
This mode doesn't support any additional arguments.

  strip mode optional 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'.

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

-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.

-nc 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.

NOTES
shntool is a misnomer, since it processes WAVE data, not shorten data. The name is a holdover from its early days as 'shnlen', a program created specifically to extract information about WAVE data stored within .shn files.

Aliases for shntool are prefixed with 'shn' instead of 'wav' to avoid possible collisions with existing programs.

AUTHOR
Jason Jordan <shnutils@freeshell.org>

SEE ALSO
The latest version of shntool can always be found at <http://shnutils.freeshell.org/>.

[1] More information on the shorten low complexity waveform coder can be found at <http://www.softsound.com/Shorten.html>.

[2] More information on the kexis lossless WAV file compressor can be found at <http://sourceforge.net/projects/kexis/>.