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