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 ================== Document revision: ================== $Id: README,v 1.27 2007/03/29 00:08:05 jason Exp $