347 lines
14 KiB
Plaintext
347 lines
14 KiB
Plaintext
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>
|