xmms-shn version 2.2.4


--------
Overview
--------

xmms-shn provides playback support for shorten (.shn) files in XMMS.  Real-time
seeking support is provided for .shn files that have accompanying seek tables
generated by shorten 3.x.  Otherwise, seeking is not supported.

See the "Shorten 3.x overview" section below for more information about this new
seek-enabled version of shorten.


------------
Availability
------------

The latest version of this plugin can always be found at the sites below:

  http://shnutils.etree.org/
  http://shnutils.freeshell.org/

Please see the ChangeLog file for changes to this plugin since its creation.


------------
Dependencies
------------

As of version 2.0, xmms-shn no longer depends on an external shorten executable
to work, since the core shorten algorithm has been incorporated directly into
xmms-shn.

You should have XMMS 1.0.0 or newer, and GTK & GLIB 1.2.2 or newer.  The
configure script will usually find these if you installed them from source.
However, if you installed any of the above via .rpm's, then you may need to tell
the configure script where to find them.  To see what options are available,
type:

% ./configure --help

The applicable options are the following:

  --with-xmms-prefix=PFX  Prefix where XMMS is installed (optional)
  --with-xmms-exec-prefix=PFX Exec prefix where XMMS is installed (optional)
  --with-glib-prefix=PFX   Prefix where GLIB is installed (optional)
  --with-glib-exec-prefix=PFX Exec prefix where GLIB is installed (optional)
  --disable-glibtest       Do not try to compile and run a test GLIB program
  --with-gtk-prefix=PFX   Prefix where GTK is installed (optional)
  --with-gtk-exec-prefix=PFX Exec prefix where GTK is installed (optional)
  --disable-gtktest       Do not try to compile and run a test GTK program


-----------------------------------
Building and installing this plugin
-----------------------------------

For instructions on how to build and install this plugin, please consult the
INSTALL file.  It is usually as simple as the following:

% ./configure
% make
% su -c "make install"
Password:                             (give your root password here)
%


---------------------
Configuration options
---------------------

This section details the options that can be found in the plugin's configuration
window in XMMS, under Preferences -> Audio I/O Plugins -> SHN Player 2.2.4 ->
Configure.


Error display options:
======================

  This option determines where any error messages go - to a popup window,
  to standard error, or to the bit bucket.  Pretty self-explanatory.


Alternate .skt file location:
=============================

  This option allows you to specify an alternate directory to search for .skt
  (seek table) files.  This directory will be searched after all other attempts
  to locate a seek table for a given file have failed.

  When searching for seek tables belonging to a file (e.g. '/mnt/shn/filename.shn'),
  xmms-shn will do the following, in this order, until it either finds a seek table
  or runs out of places to check for one:

  1.  look for a seek table appended to '/mnt/shn/filename.shn'

  2.  look for a seek table in '/mnt/shn/filename.skt'

  3.  look for a seek table in '/alternate/dir/filename.skt', where '/alternate/dir'
      is the directory specified in this option


Debug options:
==============

  The "Display debug info to stderr" option specifies whether to display debugging
  messages to stderr.  This is potentially useful for remote debugging, and also
  just to see what's going on.  Debug lines are always shown with a prefix of
  "xmms-shn [debug]:".

  Note that if "Display debug info to stderr" is enabled, and the error display
  option is set to /dev/null, then all non-debug messages that normally would be
  suppressed are displayed to stderr with a prefix of "xmms-shn [error]:".


--------------------
File information box
--------------------

This section describes the output shown in the file information window, which
can be viewed by choosing 'File Inf.' from the 'Misc. Opt' button in the
playlist editor, or selecting 'View File Info' from XMMS's main popup menu.

Properties tab:
===============

  Length:  Shows the length of the WAVE data in the file, in m:ss format.  If
  the WAVE data is CD-quality (see below for definition), then the length is
  shown in m:ss.ff format, where ff is a number from 00 to 74 that best
  approximates the number of frames (2352-byte blocks) remaining after m:ss.

    Note on rounding:  If the WAVE data is CD-quality, then its length is
                       rounded to the nearest frame.  Otherwise, it is rounded
                       to the nearest second.

  Seekable:  Shows whether a seek table was found for the given file.

  Compression ratio:  Shows the compression ratio for the given file.  This is
  simply the file's actual size divided by its total size, as calculated from
  the chunk size contained in the WAVE header.  Note that if the given file is
  truncated (or has junk appended to it), then the compression ratio will be
  skewed accordingly.

CD-quality properties:
----------------------

  CD-quality:  Shows whether the given file is CD-quality.  A file is considered
  to be CD-quality if its header indicates 2 channels, 16 bits/sample, 44100
  samples/second, and 176400 average bytes/second.

  Cut on a sector boundary:  If the given file is CD-quality, then this shows
  whether the length of its WAVE data is a multiple of 2352 bytes (1/75 of a
  second).  Otherwise, "n/a" is displayed.

  Long enough to be burned:  If the given file is CD-quality, then this shows
  whether the length of its WAVE data is long enough to be burned (705600 bytes,
  or 3 seconds in length).  Otherwise, "n/a" is displayed.

WAVE properties:
----------------

  Non-canonical header:  Shows whether the WAVE header is canonical.  A header
  is considered canonical if it is 44 bytes long (this is the smallest possible
  size that a WAVE header can be).

  Extra RIFF chunks:  Shows whether there are any extra RIFF chunks following
  the data chunk in the WAVE stream.


Details tab:
============

  This tab primarily shows the raw information taken from the WAVE header of the
  given file.  Each entry is self-explanatory.


--------------------
Shorten 3.x overview
--------------------

Wayne Stielau has extended shorten 2.3 to support the creation of seek tables.
Seek tables are simply descriptions of the internal state of the shorten
algorithm at specific points in the decompression.  This allows a modified
shorten decoder to restore the decoder state of the shorten algorithm for a
point at (or very close to) the desired seek point.  You can get the latest
version via any of the URLs below:

  http://shnutils.etree.org/
  http://shnutils.freeshell.org/

Seek tables may be appended to the .shn itself, or stored in a separate file
(usually with a suffix of '.skt').  xmms-shn supports both of these options.

The current implementation creates a seek table entry once every 25600 samples.
For 'CD-quality' WAVE data (44100 samples/sec), this provides a granularity of 1
seek table entry per 25600/44100 ~= 0.58 seconds, more than what is needed by
either XMMS or WinAmp.

At 80 bytes per seek table entry, you can expect the seek table to add about
0.1% to the size of the existing shortened file, for 'CD-quality' WAVE data.
So the seek table generated for 1 GB of already-shortened 'CD-quality' WAVE data
will fit on a floppy!  Quite a deal, if you ask me.  :-)

Best of all, shorten 3.x is fully backward compatible with version 2.3, meaning
that any files created by shorten 3.x can be processed by version 2.3 with no
problems.

The command line options for dealing with seek tables in shorten 3.x are:

  -e       erase seek table appended to input file                          * +
  -i       inquire as to whether a seek table is appended to input file     *
  -k       append seek table information to existing shorten file             +
  -s       generate seek table information in separate file [input file].skt
  -S[name] generate seek table information in separate file given by [name]
  -v 3     format version number (2: no seek info; 3: default)              *

 * only available in versions 3.2 and up
 + option may not be visible - contact me if you would like to use it

By default, any file shortened with version 3.x will automatically have seek
tables appended to it.  In later versions (3.2 and up), you can disable this
with the -v2 switch.


----------
Known bugs
----------

I test this plugin aggressively until I can no longer make it crash.  That does
not mean that there are no bugs.  If you can crash it, I want to hear about it -
please report it to me at the address below.  The xmms-shn webpage (see the
Availability section above) will always contain an up-to-date list of reported
bugs, so be sure to check that page before you send me a bug report.

Also, feel free to send me any questions, comments, feature requests, patches...
I like to get any kind of feedback.

Enjoy!

Jason Jordan <shnutils@freeshell.org>
