diff options
Diffstat (limited to 'plugins/shn/README')
| -rw-r--r-- | plugins/shn/README | 355 |
1 files changed, 355 insertions, 0 deletions
diff --git a/plugins/shn/README b/plugins/shn/README new file mode 100644 index 00000000..942d8ace --- /dev/null +++ b/plugins/shn/README @@ -0,0 +1,355 @@ +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 $ |