code.vuplus.com Git - vuplus_xbmc/blob - lib/libmodplug/README

   1 Modplug Plugin for XMMS v2.0 / libmodplug v0.8.5
   2  Based on the ModPlug sound engine by Olivier Lapicque <olivierl@jps.net>
   3  XMMS plugin by Kenton Varda <temporal@gauge3d.org>
   4  Maintainer is now Konstanty Bialkowski <konstanty@ieee.org>
   5
   6 Olivier Lapicque, author of Modplug, which is arguably the best quality
   7 MOD-playing software available, has placed his sound rendering code in the
   8 public domain.  This library and plugin is based on that code.
   9
  10 For more information on libmodplug, the library for decoding mod-like music
  11 formats, see libmodplug/README.
  12
  13 Contents
  14 --------
  15  1. Requirements
  16  2. Features
  17  3. Options
  18  4. Troubleshooting
  19
  20 ---------------
  21 1. Requirements
  22 ---------------
  23 - POSIX OS (Linux or other unix*)
  24 - XMMS 1.0.0 or higher (only for modplug-xmms plugin).
  25
  26 * This library is only guaranteed to work on Linux.  I have received
  27   conflicting reports on whether or not it will work on Solaris x86.
  28   One person reported that the plugin compiled fine with the
  29   "-fpermissive" compiler flag, which I have added.  Others had far
  30   more trouble.  Note that a recent change to the library should allow
  31   it to work on PPC and other big-endian systems.
  32
  33 * Under linux there is also modplugplay contributed, which allows command
  34  line playing of mod files under Linux.
  35
  36 -----------
  37 2. Features
  38 -----------
  39 - Plays 22 different mod formats, including:
  40     MOD, S3M, XM, IT, 669, AMF (both of them), AMS, DBM, DMF, DSM, FAR,
  41     MDL, MED, MTM, OKT, PTM, STM, ULT, UMX, MT2, PSM
  42 - Plays zip, rar, gzip, and bzip2 compressed mods.  The following
  43     extensions are recognized:
  44     zip:  MDZ,  S3Z,  XMZ,  ITZ
  45     rar:  MDR,  S3R,  XMR,  ITR
  46     gzip: MDGZ, S3GZ, XMGZ, ITGZ
  47    You can also load plain old ZIP, RAR, and GZ files.  If ModPlug finds
  48    a mod in them, it will play it.
  49    Note: To play these formats, you need to have the associated
  50     decompression utilities (unzip, gunzip, unrar) installed.
  51    Note(2): The format of the mod is NOT determined from the extension on
  52     compressed mods.  For example, if you zipped a UMX mod and gave it the
  53     extension MDZ, it would work fine.
  54 - plays timidity's GUS patch files (*.pat):
  55    a multi sample pat file with n samples can be played with a Frere Jacques
  56    canon with n voices.
  57 - plays all types of MIDI files (*.mid):
  58    uses the timidity .pat files for samples (when available)
  59    recognizes environment variables:
  60
  61      MMPAT_PATH_TO_CFG  set to the directory where the file "timidity.cfg" and
  62       the subdirectory "instruments" can be found,
  63        default: "/usr/local/share/timidity".
  64       MMMID_SPEED for experimenting with the mod speed (1 thru 9)
  65       MMMID_VERBOSE for feedback on the conversion process
  66       MMMID_DEBUG for sake of completeness, only useful for maintainers
  67
  68 - plays textfiles written in the ABC music notation (*.abc):
  69    uses the timidity .pat files for samples (when available)
  70    recognizes environment variables:
  71
  72       MMPAT_PATH_TO_CFG set to the directory where the file "timidity.cfg" and
  73        the subdirectory "instruments" can be found,
  74        default: "/usr/local/share/timidity".
  75
  76       MMABC_NO_RANDOM_PICK when not set and the abc file contains multiple songs
  77        (X:n) the first song to be played will be picked at random another click
  78        on the play button advances to the next
  79        song in the file (or the first when the last song has been
  80        played), when set it can be 0 (zero) or not numeric
  81        to let it play all songs in the file, a positive number n to
  82        let it play the n-th song in the file, a negative number -n to
  83        let it play the n-th song in the file and advancing to the next
  84        song when the play button is clicked.
  85
  86       MMABC_DUMPTRACKS when set it gives diagnostic information on stdout,
  87        values can be:
  88
  89         all - every event is printed
  90         nonotes - only the control events (looping, breaks etc.) are printed
  91            any other value prints the control events and every note event
  92            immediately succeeding the control events.
  93 - Slightly better sound quality than Mikmod.  Vastly superior quality
  94    over Winamp.
  95 - All XMMS calls are supported exept for the band gains on the
  96    equalizer.  The preamp is supported, but MOD music is not anywhere
  97    near as cheap to equalize as MP3.  Thus, equalization does is not
  98    supported in this version.  However, a variable bass boost option
  99    is available in the configuration dialog (see below).
 100 - Tons of playback options (see below).
 101
 102 ----------
 103 3. Options
 104 ----------
 105 All of the following items are configurable from the plugin
 106 configuration dialog box.
 107
 108 Sampling rate: Higher is better.  Note that the sound is rendered at a
 109  higher sampling rate and converted down to increase quality.
 110
 111 Bits per sample: 8-bit or 16-bit sound.  Note that all computations are
 112  done at 32-bit and converted down to the sampling rate you specify.
 113
 114 Channels: mono/stereo.  Note that all computations are done in stereo.
 115  If you choose mono, the channels will be mixed.
 116
 117 Resampling: Method used to convert samples to different sampling rates.
 118  "Nearest" is the fastest setting (but sounds terrible), while
 119  "8-tap fir" is the best-quality setting.
 120
 121 Noise Reduction: Reduces noise. :)
 122
 123 Fast Playlist Info: When this option is on, names of songs in your
 124  playlist will load considerably faster, but song lengths will not be
 125  shown and only MOD, S3M, XM, and IT formats will have their names shown.
 126  Don't worry, though, because all the data which is skipped will still be
 127  loaded when you actually play the song.  This should probably always be
 128  on.
 129
 130 Reverb: A nice reverb effect.  The depth and delay of the reverb can be
 131  tuned to your liking using the sliders.
 132
 133 Bass boost: Variable bass boost effect.  The "range" slider controls the
 134  frequency range of the bass boost.  If you increase this value, higher
 135  frequencies will be boosted, but the overall volume increase will be
 136  less.  (you can compensate by using the volume slider:)
 137
 138 Surround: Dolby Pro-Logic surround effect.  Depth and delay can be fine
 139  tuned.
 140
 141 Preamp: A global volume boost.  Note that setting the preamp too high
 142  will cause clipping (nasty clicks and pops).
 143
 144 Looping: Some mods have loops built-in.  Normally, these loops are
 145  ignored because otherwise the same mod would play forever.  However,
 146  you can choose to respect the loops, or even set a number of times to
 147  follow a loop.
 148
 149 ------------------
 150 4. Troubleshooting
 151 ------------------
 152
 153 Problem:
 154  None of the config options seem to have any affect on the sound quality.
 155
 156 Possible cause:
 157  You did not disable MikMod, so mods are being played by it rather than
 158  by ModPlug.
 159
 160 Solution:
 161  Disable MikMod in the XMMS input plugins configuration dialog.
 162
 163 Alternative cause:
 164  You are not playing a mod-like file.  ModPlug only plays mod-like file
 165  formats, and has no affect on mp3's or other non-mod formats.  (Note:
 166  Yes, I have actually had people e-mail me with this problem.)
 167
 168 Solution:
 169  Download some mods.  You can start at <http://www.traxinspace.org>.
 170
 171
 172 Problem:
 173  Some of my files load up, but show garbled info in the playlist and/or
 174  don't play correctly.
 175
 176 Possible cause:
 177  The mod is in a different format than its file format suggests.
 178  Modplug-XMMS uses a combination of file extension and contents to figure
 179  out what format a mod is in, and can be thrown off if a mod is
 180  incorrectly labeled.
 181
 182 Solution:
 183  Turning off "fast info" in the configuration may fix the problem.  This
 184  will cause Modplug-XMMS to detect all basic mod types by content, but
 185  archive types will still be detected by extension.  If this doesn't
 186  solve the problem, then you probably have files which are actually
 187  compressed archives but are not labeled as such.  For example, you may
 188  have a file "aws_anew.xm" which is actually a ZIP archive.  You will
 189  have to either unzip these files or rename them to have an extension
 190  associated with their type.  In the case of a ZIP, you can use any of
 191  the extensions "ZIP, MDZ, S3Z, XMZ, ITZ".  (Note that these five types
 192  are all treated exactly the same -- the actual format of the mod is
 193  detected by contents.)
 194
 195
 196 Problem:
 197  Everything appears to be working, but no sound is being generated.
 198  MP3's play just fine.
 199
 200 Possible cause:
 201  Modplug has a relatively low default volume, and you may just not be
 202  hearing it.  (Note:  Yes, more that one person has e-mailed me with
 203  this problem.)
 204
 205 Solution:
 206  Turn up your volume.  You may wish to do this via the "preamp"
 207  setting in the ModPlug configuration.  This way, you won't have to
 208  turn down your volume again when you play an MP3.
 209
 210
 211 Problem:
 212  You have a mod which is rendered incorrectly by ModPlug-XMMS.
 213
 214 Possible cause:
 215  This could be our fault. :)
 216
 217 Solution:
 218  First, test the mod using the Windows version of ModPlug, if you can.
 219  If it sounds wrong there, then send the mod and a bug report to
 220  Olivier Lapicque <olivierl@jps.net>.  If the mod plays correctly in
 221  Windows, however, then the bug is my fault.  In that case, e-mail
 222  me (Konstanty) <konstanty@ieee.org>. (previously Kenton Varda at
 223  <temporal@gauge3d.org>).
 224
 225
 226 Problem:
 227  I have a problem which is not listed here, or an idea for a cool
 228  feature.
 229
 230 Solution:
 231  E-mail me (Konstanty) at <konstanty@ieee.org>.  I would be
 232  happy to hear any suggestions or problems you have.
 233