uFMOD for Linux

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 and direct memory playback supported. It is able to play even damaged and non-standard XM tracks. Usage examples available for the following compilers: GCC, Tcl/Tk, PureBasic, BlitzMax, FreeBASIC, FreePascal, FASM, NASM and GAS.

OSS, ALSA or OpenAL?
Tools
- XMStrip
- Eff
Compiling the library
Examples
Reducing the executable file size
FAQ
Thanks

OSS, ALSA or OpenAL?

uFMOD for Linux supports OSS, ALSA and OpenAL. All three drivers have pros and cons. ALSA is the built-in audio system in most 2.6.x Linux distros. OSS, however, is the default sound driver in 2.4.x and even earlier (those are almost obsolete nowadays). So, many people consider OSS being a deprecated audio driver and ALSA being it's actual replacement. That's not exactly true, since there are many high-end systems using commercial OSS drivers. There are soundcards not fully supported or completely unsupported in ALSA, but perfectly usable with OSS. The counterpart is also true. ALSA is currently available only in Linux, while OSS may be found in many other Unix-like systems: FreeBSD, Solaris, etc. ALSA and OpenAL require linking to a shared library (libasound.so and libopenal.so respectively), which makes it harder if at all possible building static executables, without dependencies. The good thing about ALSA is it's higher performance on modern sound devices, support for plugins (virtual soundcards), complete OSS drivers emulation in order to support OSS applications. OpenAL is cross-platform (available in Windows, Linux, Macintosh, etc.), features hardware accelerated environmental effects, very useful in game development. If you don't already have OpenAL installed, you need to download the redistributable OpenAL drivers prior to starting developing OpenAL-powered applications. If you are not sure which uFMOD version to choose for your project, probably the standard OSS 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. Linux OSS version is completely source-level compatible with Windows WINMM and Unix/BSD OSS-only versions. That allows writing multiplatform applications! When developing a Linux-only application intended for 2.6.x or later kernels, ALSA whould be more recommended. OpenAL is also recommended for multiplatform projects, especially in game development.

Tools

There are 2 freeware tools currently available to use along with uFMOD: XMStrip and Eff. Both utilities are terminal-based, but there are also graphical (GUI) frontends available made in Tcl/Tk: effgui and xmstripgui respectively. On most machines you can just doubleclick the executable script file in order to launch Tcl/Tk and start executing the given script, assuming Tcl/Tk has been properly installed. Sometimes an explicit wish ./<script-name> command should be entered in a terminal emulator or a more complex set of steps be performed in order to make it work. GUI is rather self-explanatory. Next, we'll explain the terminal interface.


SVN	Complete source code available

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 produces the following output:

 USAGE:  xmstrip [options] file [output]
         file   - input file name.
         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 a terminal and typing ./eff to request the following prompt:

 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
          /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. Neither of them have any use in Linux, but the syntax is also suitable for FASM and NASM. However, both FASM and NASM support embedding binary content from a file directly. So, the only real use of this option in Linux has to do with /M (see below).
/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. No real use in Linux.
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 - only memory arrays? Then, you'd probably like to use /Df 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 assembly 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.

On success, Eff produces a file EFF.INC and a hex dump, if requested. Some examples (all correct):

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

The above commands produce an assembly 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, loading files 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, though an assembly coder never pays attention to this kind of recommendations anyway :)
core.asm contains most of the uFMOD source code. The exactly same file is used in Linux, Unix/BSD, Win32 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 I/O, threading, etc. The contents of this file vary in Linux, Unix/BSD, Win32 and KolibriOS.
fasm.asm contains Flat Assembler (FASM) specific definitions. This stub file makes it possible to compile uFMOD using FASM.
nasm.asm contains Netwide Assembler (NASM) specific definitions. This stub file makes it possible to compile uFMOD using NASM.
ufmod.desc, oalufmod.desc and alsaufmod.desc are PureBasic library description files. PureBasic Library SDK requires these files to compile uFMOD in PureLibrary format.

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

Makefile	Target compiler(s)	Notes
Makefile	GCC, Tcl/Tk, FreeBASIC, FreePascal, FASM, NASM, GAS	FreePascal users should set UF_FMT option to LIB. All other users should set it to OBJ instead. FreeBASIC, FreePascal, FASM and NASM are also SourceForge projects!
MakePB	PureBasic
MakeBMod	BlitzMax
make.bat	GCC, Tcl/Tk, FreeBASIC, FreePascal, FASM, NASM, GAS	This is a Win32 batch file for crosscompiling uFMOD for Linux.

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

*** CONFIG START

and

*** CONFIG END

is configurable. An additional step should be taken when crosscompiling in Win32 (skip the following frame when compiling in Linux):

Check the Pathes section. There is an option saying:

SET UF_NASM=\nasm

If you do have NASM installed, make sure the above path points exactly to where nasmw.exe is located. Let's say NASM has been installed to D:\TOOLS\NASM. Then, you'd have to modify the above entry as follows:

SET UF_NASM=D:\TOOLS\NASM

Not all of the pathes are used to recompile the libraries. For example, if you prefer using FASM as your default assembler, you don't need to setup the NASM path. The UF_ARCH path contains a filename:

SET UF_ARCH=ar

ar.exe is supposed to be in one of the directories that are listed in the PATH environment variable. If not, you'd have to modify the above entry. Let's say C:\Program files\BlitzMax\bin\ar.exe is the correct path. So, let's modify the UF_ARCH variable:

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

Make sure all the pathes actually required to build the libraries have been set correctly.

Then, procede modifying the available options, according to the following table:

Option^*	Description	Values^*
UF_RAMP	This option controls the volume ramping (interpolation) mechanism. Ramping is intended to suppress audible clicks, but sometimes it may introduce distortion. STRONG is the default value recommended for most applications. It detects volume changes during sample playback and softens them using a 32 stage linear ramp. WEAK uses 16 linear stages only. It is less effective than STRONG, but distortion is also less likely to happen. NONE doesn't perform ramping at all. No ramping = no distortion, but most XM samples will produce clicks, unless the samples are well balanced enough.	NONE, WEAK, STRONG
UF_FREQ	Mixing rate (in Hz). 44100 was the default value until uFMOD v1.20. It is useful only for compatibility with QEMU-embedded Linux boxes. 48KHz actually sounds better on most soundcards and uses less system resources. So, 48000 is the new default value recommended for most applications. 22050 is supported just for fun (rememder the Amiga days...)	22050, 44100, 48000
UF_FMT	Produce a static library (lib.a) or a plain object file (.o). FreePascal examples use static libraries, while all other examples use plain object files.	OBJ, LIB
UF_ASM	Assembler. Yes, the uFMOD libraries are compilable with either FASM or NASM. Choose your favorite :)	FASM, NASM
UF_MODE	NORMAL is the default value. Nothing special. UNSAFE disables checking an XM track for validity at load time. When you are sure all XM tracks are valid (you can use Eff or XMStrip to verify an XM file), you can recompile uFMOD in UNSAFE mode to reduce the file size and maximize the loading speed. Keep in mind that a damaged XM file can actually crash uFMOD while in UNSAFE mode! Recompiling uFMOD in BENCHMARK mode makes available a performance counter, which tells the exact amount of clock cycles used to produce about 21 ms of sound @ 48KHz. This mode is meant to be used for comparing the performance of different uFMOD versions. BENCHMARK mode is available only in C, FASM, NASM and GAS.	NORMAL, UNSAFE, BENCHMARK

* Every makefile uses a subset of this options and values.

When using the Makefile, just run GNU Make to compile the library: make. When using a non-standard makefile name, specify it on the command line: make -f MakeBMod. Run the make or batch file to build all the available library targets: OSS, ALSA and OpenAL. That's all!

Examples

Compiler-specific usage examples are provided in separate directories. Every example subdirectory contains OSS, ALSA and OpenAL projects. Most representative examples contain prebuild executables to show the smallest image size achieved so far. Prebuilt binaries are neither compressed, nor packed.

A note on using OpenAL
When using OpenAL, make sure you have the latest stable OpenAL library release. It is strongly recommended to update to version 0.0.8 or above. Version 0.0.7 may sometimes "freeze" for a while when releasing the currently selected OpenAL context. Version 0.0.6 (this one is commonly preinstalled in Mandrake 10 and earlier) has serious memory leaks. The latest stable OpenAL RPM can be downloaded from the official OpenAL website.

Dir	Compiler	Contributed by	Notes
TclTk	Tcl/Tk	*	Simple graphical XM players.
Gcc	GNU C	*	A GTK example showing how to use the Jump2Pattern feature is available here. It uses a composite XM tracked by Kim (aka norki). For more information on composite XM files and the Jump2Pattern feature, refer to the following section. There is a dynamic OpenAL example here as well - it will run even when libopenal.so is not found.
Fasm	Flat Assembler	*	Pure FASM (no linker, OSS) and FASM plus GNU C linker examples provided just to show both ways to build an executable using FASM.
Nasm	Netwide Assembler	*	Pure NASM (no linker, OSS) and NASM plus GNU C linker examples provided just to show both ways to build an executable using NASM.
Gas	GNU Assembler	*
PureBasic	PureBasic	*	PureBasic 3.81 or later required. Copy the given purelibraries to [PureBasic]/purelibraries/userlibraries before compiling the projects. An online help for PureBasic uFMOD API is available in the HELP subdirectory. Complete and up-to-date OpenAL PureLibrary is available. uFMOD for OpenAL require this library. You can also use it in stand alone projects.
BlitzMax	BlitzMax	*, flaith	Complete documentation provided. Complete and up-to-date OpenAL module for BlitzMax is available. uFMOD for OpenAL require this module. You can also use it in stand alone projects.
FreeBASIC	FreeBASIC	voodooattack, antarman	Using a visualization based on Torus by rel.
FreePascal	FreePascal	*	Tested with FPC v2.1.4. Complete and up-to-date OpenAL unit for FreePascal is available. uFMOD for OpenAL require this unit. You can also use it in stand alone projects.

* Quantum, Asterix

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.

Use strip and sstrip to remove unnecessary data introduced by the compiler/linker. Whole sections may sometimes be removed without breaking the executable.

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

Take a look at "A Whirlwind Tutorial on Creating Really Teensy ELF Executables for Linux" by Brian Raiter for additional size optimization tips.

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

Legend: XMn_HEADER is the header of the n-th XM file. Pni is the i-th pattern of the n-th XM file. Ini is the i-th instrument of the n-th XM file.

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

Now, let's say I12 is very similar or even equal to I23 and I24 is the same as I31. So, we can modify P2n to make them use I12 instead of I23 and P31 to use I24, so that we can remove I23 and I31:

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

You'll have to modify the looping and pattern jumping commands and the references to instruments in "files" 2 and 3. Obviously, you can merge just 2 files or more than 3. XM file format limits the amount of patterns and instruments in a single file. That's the general idea. You'd have to learn how to use a tracker in order to perform this kind of optimization. Once you've got all your files merged, you can issue a single uFMOD_PlaySong function call and trigger all the "files" with uFMOD_Jump2Pattern. For example, uFMOD_Jump2Pattern(3) will start playing the 2nd "file", uFMOD_Jump2Pattern(7) will launch the 3rd and uFMOD_Jump2Pattern(0) will reset to the first "file". The exact indexes depend on your pattern layout. Gcc/OSS/ contains a practical example.

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 executable file). It also depends on the linker options. For example, Fasm/minimal is 4.921 bytes without compression.

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_, 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

Sample tunes:

μFMOD v1.25 for Linux (i386)