path: root/plugins/shn/README

NOTE: this is not original xmms-shn
this code is a port of xmms-shn to deadbeef plugin API

=== original xmms-shn README starts here ===

xmms-shn version 2.4.x


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


-------
License
-------

xmms-shn is dual-licensed.  The code taken from the sources of 'shorten' remains
under the shorten license (see doc/LICENSE.shorten), while the rest of the code
is GPL (see COPYING).


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

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

  http://www.etree.org/shnutils/
  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.4.x ->
Configure.


Error Display tab:
==================

  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.


Seek Tables tab:
================

  Alternate seek table file locations:
  ------------------------------------

  These options allow you to specify alternate directores to search for .skt
  (seek table) files.  These directories will be searched after all other attempts
  to locate a seek table for a given file have failed.

  The "Relative seek table path" option allows you to specify a subdirectory
  relative to the base directory of a given file, where seek tables may reside.
  This is useful if you create seek table files for a group of .shn files, and
  store them in a commonly-named subdirectory of that group.

  The "Absolute seek table path" option allows you to specify an absolute directory
  where seek tables may reside.  This is useful if you create seek table files for
  multiple groups of .shn files and store them in the same directory.

  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' (whether at the end,
      or hidden behind an ID3v1 tag)

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

  3.  look for a seek table in '/mnt/shn/relative_dir/filename.skt', where
      'relative_dir' is the directory specified in the "Relative seek table path"
      option

  4.  look for a seek table in '/absolute_dir/filename.skt', where 'absolute_dir'
      is the directory specified in the "Absolute seek table path" option


Miscellaneous tab:
==================

  Miscellaneous options:
  ----------------------

  The "Swap audio bytes on output" option is useful in situations where every file
  you play back is static.  This is known to help on the following platforms:

    + Sun Ultra 10 and Ultra 30 both running Solaris 8
    + SGI Octane/Irix 6.5


  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]:".

  The "Load text files in file information box" option specifies whether text files
  found in the same or parent directory as the given file should be loaded into the
  file information box.  Each file found will be loaded in a separate tab.  The tabs
  will be labeled "Text file n", where n starts at 1 and increases with each new
  text file.

  The "Text file extensions" option lets you specify a comma-separated list of case-
  sensitive file extensions that xmms-shn will recognize as text files.  The default
  list is "txt,nfo".  This option is only useful if "Load text files in file
  information box" is enabled.

  Note:

  Text file support is useful for quickly determining information about the given
  file and/or the show it belongs to, assuming such information is contained within
  the text files.

  Text file location assumes some combination of the following two directory
  structures: all text files and .shn files in the same directory, or text files
  in a directory with all .shn files in subdirectories one level deep.  This
  pretty much covers all directory structures seen on live music servers and file-
  sharing programs.


--------------------
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:
===============

  Filename:  Shows the full path to the .shn file being examined.

  Length:  Shows the length of the WAVE data in the file, in m:ss.nnn 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 millisecond.

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

  Seek table revision:  Shows the revision number of the seek tables, if
  present.  Note that it is possible for this field to contain a numeric value,
  even when the file is not seekable - for example, xmms-shn might detect that
  certain seek tables are unsupported or buggy, and disable seeking in those
  files.

  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.

  Sector misalignemt:  If the file is CD-quality, then the sector misalignment
  is simply the remainder when the data size is divided by 2352; i.e. it is the
  number of bytes by which the audio data exceeds the previous sector boundary.

  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.

  Possible problems:
  ------------------

  File contains ID3v2 tag:  Shows whether the file contains an ID3v2 tag, and
  if so, how many bytes it occupies.  This is not a problem for xmms-shn (it
  was able to read the file after all), but could pose a problem for programs
  that are not able to process files with ID3v2 tags.


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

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


Text file n tab(s):
===================

  These tabs, if any, show the contents of all text files found in the same
  directory or parent directory as the given file.  The associated file name for
  each tab is contained in the frame surrounding the text, and the full path to
  the file being displayed is shown just above the text.  You can control which
  files are considered to be text files with the "Text file extensions" option in
  the configuration window.  Make sure to select the "Load text files in file
  information box" option if you want to see these tabs.

 
--------------------
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 at any of the URLs below:

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

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

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.

** NOTE ON SEEKING IN FILES ENCODED WITH NON-DEFAULT OPTIONS **

Seek tables are unable to support all types of SHN files due to limitations in
their original design.  The only files they can fully support are ones encoded
with the following values:

  -c = 1 or 2  (number of channels, default is 1)
  -p in the range [0 .. 3]  (maximum LPC predictor order, default is 0)
  -m in the range [0 .. 4]  (number of block for mean estimation, default is 4)

If xmms-shn detects a file encoded with parameters that fall outside of these
ranges, then seeking is automatically disabled for that file.


----------
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 always enjoy getting feedback.

Enjoy!

Jason Jordan <shnutils@freeshell.org>


==================
Document revision:
==================

$Id: README,v 1.27 2007/03/29 00:08:05 jason Exp $