uFMOD is an XM player library written in assembly language. It's perfect for size- and speed-critical applications, click free, highly reliable, easy to use, open source, multiplatform. File, resources and direct memory playback supported. It is able to play even damaged and non-standard XM tracks. Usage examples available for the following compilers: Visual C++, C#, Visual Basic, PureBasic, FreeBASIC, BlitzMax, Emergence BASIC, Delphi, Borland C++ Builder, Dev-C++ (MingW), FreePascal, MASM32, FASM, NASM and TASM.

• WINMM, DirectSound or OpenAL?
• Tools
  • XMStrip
  • Eff
• Compiling the library
• Examples
• Reducing the executable file size
• FAQ
• Thanks

 
WINMM, DirectSound or OpenAL?

uFMOD for Win32 supports WINMM, DirectX® DirectSound and OpenAL. All three drivers have pros and cons. DirectSound provides sound effects, mixing capabilities and a wide range of advanced features, like 3D sound. It is even considered to be more reliable than WINMM. On the other hand, WINMM is almost always available, even in good old Windows 95. OpenAL is cross-platform (available in Windows, Linux, Macintosh, etc.), features hardware accelerated environmental effects, very useful in game development. However, it is not preinstalled in Windows XP and earlier, except in some OEM machines with high-end Creative sound cards. So, you'd probably need to download the redistributable OpenAL drivers prior to starting developing OpenAL-powered applications. Depending on hardware and drivers, WINMM output could sound clearer than DirectSound's or viceversa. However, most users won't tell the difference. If you are not sure which uFMOD version to choose for your project, probably the standard WINMM version whould suit your needs better. At least, it's easier to use: just a couple of lines of source code will do the job.

 
Tools

There are 2 freeware tools currently available to use along with uFMOD: XMStrip and Eff. Both utilities have dual interface: console and graphical (GUI). When ran with command line arguments, console mode is triggered. GUI is rather self-explanatory. Next, we'll explain console-based usage.

XMStrip expects an XM filename on input, repacks the file contents to make it smaller, without losing sound quality. What it does exactly is removing overhead data (dummy instruments, patterns and junk metadata), stripping reserved and currently unused bytes, repacking pattern data. Typing xmstrip /h produces the following output:

 uFMOD XMSTRIP
 USAGE:  xmstrip [options] file [output]
         file   - input file name, which can
                  contain wildcards (* and ?)         
                  for batch processing.
         output - optional output file name
 options:
  /c - clean only (don't strip)
 When [output] is not specified, XMSTRIP
 attempts to overwrite the input. If file
 name contains spaces, enclose it in "".

Keep in mind, that other XM players whould probably reject a 'stripped' XM file. The /c option is useful for 'recovering' such a stripped file or just cleaning a regular file intended to be played with any other XM player.

Eff is useful for advanced users, willing to squeeze every single byte out of their applications. The general idea is to extract only those features you do mean to use in your application, recompile the uFMOD library from source and obtain the smallest possible footprint. So, let's start opening the command shell and typing eff /h to request the following prompt:

 uFMOD XM effects extractor
 USAGE:  eff [options] file
         file - input file name
         options:
          /Dm - generate a masm32/tasm dump
          /Dd - generate a Pascal (Delphi) dump
          /Dc - generate a C/C++ dump
          /Ds - generate an RCDATA resource dump
          /Di - disable infoAPI:
                    uFMOD_GetStats, uFMOD_GetRowOrder,
                    uFMOD_GetTitle and uFMOD_GetTime
          /Dp - disable uFMOD_Pause, uFMOD_Resume
                    and XM_SUSPENDED
          /Dv - disable volume control
          /Dj - disable Jump2Pattern
          /Df - disable loading XM from file
          /Dr - disable loading XM from resource
          /Dl - disable XM_NOLOOP
          /M  - mark & clear unused chunks of
                data in a masm32/tasm compatible dump

As you can see, the last parameter is expected to be a filename, specifying the XM file you plan to use in your application. Additional options:

• /Dm produces a hex dump from the given XM file, suitable for MASM32 and TASM. Both MASM32 and TASM examples included in the current uFMOD release use such hex dumps instead of regular resources to save some bytes.
• /Dd and /Dc produce hex dumps in Pascal (Delphi, Kylix, FreePascal) or C/C++ format respectively.
• /Ds generates a hex dump in RCDATA format, used in resource scripts. Some resource script compilers don't support the Microsoft's id RCDATA "filename" syntax. An RCDATA hex dump should be used for compatibility with early GNU resource compilers, like the one included in Dev-C++.
• Specify /Di to disable all the information functions: uFMOD_GetStats, uFMOD_GetRowOrder, uFMOD_GetTitle and uFMOD_GetTime. Removing them reduces the library size and makes it somewhat faster.
• /Dp removes uFMOD_Pause and uFMOD_Resume functions and makes uFMOD ignore the XM_SUSPENDED flag. If you don't plan to use pause/resume features, add this option to the command line and save some more bytes.
• uFMOD_SetVolume not only makes the library bigger, but also consumes some additional CPU time. Just use /Dv to turn it off and recover some bytes and clock cycles ;)
• /Dj disables the Jump2Pattern feature. This is an advanced feature, not used in most applications. Check the "Reducing the executable file size" section for more information on using Jump2Pattern.
• Not going to play files and/or resources? - An optimization geek uses hex dumps instead of resources anyway! Then, you'd probably like to use /Df and /Dr in order to make the library smaller.
• /Dl (lower-case letter L) makes uFMOD ignore the XM_NOLOOP flag (and makes the library smaller and faster, as expected).
• Finally, a really insane optimization option is available only for MASM32/TASM coders. There are some byte chunks inside every XM file, which are reserved for future use or just holding metadata (comments, adds and so on). /M marks all such 'holes' in the hex dump and makes them available for something more useful, like storing code and/or data right inside the XM track. Masm32\winmm\ example uses this feature.

eff /Dmpvjfrl /M example.xm
eff /M /Dm /Dp /Dv /Dj /Df /Dr /Dl example.xm
eff -M -Dmpvjfrl example.xm

The above commands produce a MASM32/TASM dump with all the 'holes' properly outlined and cleared by default. The EFF.INC header contains the XM effects actually used in the given XM file and some additional flags to disable pause/resume, volume control, Jump2Pattern, file and resource support and XM_NOLOOP. Copy EFF.INC to ufmodlib\src\ and recompile the library (check the following section for a quick guide). Enjoy your own extremely optimized uFMOD build, but keep in mind that it contains a subset of XM effects. So, it will play normally only the given XM file!

 
Compiling the library

Recompiling the library sources is required after using Eff or to enable some special features in a regular build (check the Options table below). Some people might consider modifying the source code of the library just to practice assembly programming or for any other reason. Well, the following information is intended only for those interested in the subject.

The complete source code is included in ufmodlib\src\:

• eff.inc is a header file. The Eff tool generates this file. Modifying it directly is not recommended.
• equs.inc contains most of the structures and constant definitions.
• core.asm contains most of the uFMOD source code. The exactly same file is used in Win32, Linux, Unix/BSD and KolibriOS packages. Loading an XM track, mixing sound channels, XM effects handling and other common algorithms are all implemented in this file.
• ufmod.asm contains platform-specific implementation: file and resource handling, threading, etc. The contents of this file vary in Win32, Linux, Unix/BSD and KolibriOS.
• fasm.asm contains Flat Assembler (FASM) specific definitions. This stub file makes it possible to compile uFMOD using FASM.
• masm.asm contains MASM32/TASM specific definitions. This stub file makes it possible to compile uFMOD using MASM32 or TASM.
• nasm.asm contains Netwide Assembler (NASM) specific definitions. This stub file makes it possible to compile uFMOD using NASM.
• ufmod.desc, oalufmod.desc and dsufmod.desc are PureBasic library description files. PureBasic Library SDK requires these files to compile uFMOD in PureLibrary format.
• ufmod.def, oalufmod.def and dsufmod.def are DLL definition files. They are used for building uFMOD as DLL.

ufmodlib\import\ contains the source code required to generate all the import libraries used along with uFMOD. Some of them are required for building the uFMOD library for Visual Basic 6 and FreePascal. These are already prebuilt and located in ufmodlib\lib\. DirectSound and OpenAL import libraries for various compilers are also included here. All these libraries are built using the ImpLib SDK, which can be downloaded as a stand-alone project from the following website: implib.sourceforge.io. ufmodlib\import\buildall.bat is a batch file. It recompiles all of the import libreries mentioned above.

There's a tool available in ufmodlib\bin\. It is used to make a regular OMF object file compatible with Delphi. It's not as powerful as EliCZ' OMF2D, but smart enough to make a Delphi compatible uFMOD library. When building uFMOD in OMF format with NASM, o4delphi gets involved.

Once you are done modifying the uFMOD sources, next step is compiling them. Pick one of the batch files located in ufmodlib\ depending on the target compiler you want to build uFMOD for. The following table should help you selecting the proper batch file:

Now open the selected batch file in a plain text editor. Everything contained between the following lines:

rem *** CONFIG START

rem *** CONFIG END

SET UF_MASM=C:\masm32

SET UF_MASM=D:\TOOLS\MASM32

SET UF_ARCH=ar

SET UF_ARCH=C:\Program files\BlitzMax\bin\ar.exe

Run the batch to build all the available library targets: WINMM, OpenAL and DirectX DirectSound. That's all!

 
Examples

Compiler-specific usage examples are provided in separate folders. Every example folder contains WINMM and DirectX projects. OpenAL examples are available for most of the compilers as well. Most representative examples contain prebuild executables to show the smallest image size achieved so far. Prebuilt binaries are neither compressed, nor packed.

 
Reducing the executable file size

Use Eff to optimize the library and make it smaller.

When embedding the XM track directly into the executable or attaching it as a raw binary resource, it's sometimes worth it trying to optimize the XM itself. Modplug Player features ADPCM compression, which makes the XM somewhat smaller, but it's a lossy compression! Use XMStrip for lossless (in terms of sound quality) size optimization.

If you're sure all XM tracks your application is going to use are valid (not damaged or otherwise modified), rebuild the library in UNSAFE mode.

Try using the undocumented directive /opt:nowin98 while linking a Visual C++ or MASM32 project to minimize section alignment. The .rdata section (read-only data, where the IAT and some other constants reside) and .text section (usually contains executable code) could be safely combined together into a single section. Try adding the following directives to MS LINK.EXE or POLINK.EXE command line: /MERGE:.rdata=.text

There's another MS linker-specific known issue. link.exe attaches some unnecessary data between DOS stub and the beginning of PE header. It's easy to spot the dead weight in a Hex editor - it begins with a magic word 'Rich'. The encoded machine compid follows the magic word. If you don't want your executables being signed this way or just don't like to spend some extra bytes (actually, it's half a Kb!) on the signature, there's a couple of workarounds available. First, you can switch to another linker. Or you can search the web to find an article on patching link.exe. Psst! It's written in russian and available somewhere at wasm.ru.

Delphi likes to include a Relocation Table (.reloc section) inside every single executable. That's not required for a typical exe to run (but not a DLL!) and you may safely remove that section. Try using StripReloc by Jordan Russel, PE Optimizer by Dr. Golova or a similar tool in case you don't know how to remove relocations by hand.

Visual Basic and Delphi like to create a Resources section (.rsrc) even if it doesn't contain any useful resources. So, it's usually safe to remove the whole resources section if it doesn't contain forms, XMs or anything your program might really need. The same applies to .flat sections inside PureBasic executables. Be careful while performing this kind of operation on your exe!

Packers and exe compressors, such as FSG and UPX, make executables smaller. Anyway, to make things fair, the sample executables are not compressed at all!

When using MS-COFF import libraries (like kernel32.lib, libkernel32.a, etc.) some space is wasted in the executable image to hold the original thunks tables. These tables are only required when binding the executable image. If you don't plan to bind your executables, you can get rid of the original thunks and save up to 512 bytes or even a couple of kilobytes when importing a large amount of symbols. To do so you should replace the original import libraries, shipped with your compiler SDK (Visual Studio, masm32, etc.) whith modified (stripped) import libraries and rebuild your projects. You can make a "stripped" import library with ImpLib SDK.

That's pretty much everything one should know about optimizing an executable file for size. Let's talk some more about optimizing the XM file size:

An advanced XM file size optimization method involves merging various XM tracks in a single composite file. Since you can share the instruments in a composite file, the resulting file size could be a lot smaller than the sum of the separate file sizes before merging. Even without sharing the instruments it will be smaller because of the XM file header being declared only once. Let's see an example with 3 XM files:

File 1 : XM1_HEADER P11 P12 P13     I11 I12
File 2 : XM2_HEADER P21 P22 P23 P24 I21 I22 I23 I24
File 3 : XM3_HEADER P31             I31

First, let's merge them in a single file without sharing the instruments:

File 4 : XM4_HEADER P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I23 I24 I31

File 4 : XM4_HEADER P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I24

Using Jump2Pattern has another advantage: switching is done much faster (practically in no time), as opposed to stopping and reloading a track. So, you can use this feature when quickly switching the background music is required.

 
FAQ

Q: Is uFMOD free for any type of use? Even commercial?
A: Yes, currently it is.

Q: Where can I get XM files from?
A: Try visiting The Mod Archive. They have a huge archive of free tracker music in XM, IT, S3M and MOD format. You can use Open Modplug Tracker to convert IT, S3M and MOD tracks to XM format without apparent degradation. There are many talented composers out there in the web sharing their music at no cost. Just don't forget the copyright!

Q: Is uFMOD related in some way to Firelight Technologies® FMOD and miniFMOD sound libraries?
A: Not any more. Up until 2004 uFMOD was based on the latest miniFMOD public source code release. Since then, library sources had been completely rewritten, introducing many new features. So, uFMOD is in no way representative of FMOD and miniFMOD sources.

Q: Some XM player libraries claim to add only N kilobytes to the executable file. How many Kb does uFMOD add exactly to the executable's size?
A: It is impossible to tell an exact value, because it depends on library features used (especially, when using the Eff utility), test program code layout, XM file size (when embedding the XM into the EXE). It also depends on the linker options. For example, MASM32\minimal.exe is 5.632 bytes without compression, PE format hacking or any other dirty size optimization tricks.

Q: Where can I get the official XM file format specification from?
A: No official and up to date specification exists. However, you can take a look at "The Unofficial XM File Format Specification: FastTracker II, ADPCM and Stripped Module Subformats". This document covers most aspects of the original XM file format and all the non-standard extensions currently supported by uFMOD. ModePlug's public source code (it's C++) also serves as reference material on module file formats.

 
Thanks go out to

antarman, Barracuda, bogrus, chris_b, cresta, dododo, flaith, Four-F, GL#0M, norki, q_q, ReSampled, S_T_A_S_, ts-soft, voodooattack and yoxola for reporting bugs, requesting interesting features, submitting usage examples and otherwise helping us improve uFMOD.

[WASM.RU], CelerSMS and SourceForge.net for support and hosting.

 
Copyright

uFMOD sources, binaries and utility programs © 2005 - 2022 Asterix and Quantum.
All rights reserved.

Sample tunes:

• «mini.xm» by ReSampled © 2006 - 2022.
• BlitzXMK.XM from Jump2Pat example © 2007 - 2022 Kim (aka norki).