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.
------------
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 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 generated by shorten for files that were encoded with non-default
options do not seem to work correctly in most cases. Normal playback works
fine, but any attempt to seek within such a file may cause the audio to become
garbled. This appears to be due to an unforseen limitation in the design of
seek table generation in shorten - for example, as stated above, seek tables
were intended to be generated once every 25600 samples, but this is not true if
an alternate block size is given with the -b option. Encoding options that seem
to be able to cause this problem when set to non-default values are the -b, -m
and -p options. Since there is no reliable way to identify such files, the best
xmms-shn can do is attempt to seek based on the values in the seek tables. If
the sound becomes garbled, then you have likely run across one of these files,
and are out of luck.
----------
Known bugs
----------
1. Not really a bug in xmms-shn, but under certain conditions, seeking may not
work correctly. The primary symptom of this is garbled audio after a seek is
performed. See the section above titled "NOTE ON SEEKING IN FILES ENCODED
WITH NON-DEFAULT OPTIONS" for more information.
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>
5379d9bab7