Audio Overload SDK - Development Release 1.4.8 February 15, 2009

Copyright (c) 2007-2009 R. Belmont and Richard Bannister. All rights reserved.

Please refer to license.txt for the specific licensing details of this software.

---

This SDK opens up some of the music file format engines developed for the Audio Overload project. You may use this code to play the formats on systems we don't support or inside of applications other than AO.

Prerequisites

pkg-config and GLFW 3 are required to compile the debug GUI. Depending on your distribution, they can be installed as follows:

• On Arch: sudo pacman -S glfw
• On Debian: sudo apt-get install libglfw3-dev
• On MinGW/MSYS2 (64-bit): pacman -S pkg-config mingw-w64-x86_64-glfw

Alternatively, you can compile Audio Overload without the GUI by setting the environment variable NOGUI before you run make:

	NOGUI=1 make

Compilation

Make sure that you've pulled all Git submodules together with this repo:

	git clone --recursive https://github.com/nmlgc/aosdk.git

On Windows, MinGW is required to build the code through the Makefile. Cygwin's own gcc is unsupported, so make sure to specify MinGW's gcc in the CC environment variable when building on Cygwin or MSYS2:

	# For 32-bit builds
	CC=i686-w64-mingw32-gcc make
	# For 64-bit builds
	CC=x86_64-w64-mingw32-gcc make

On Linux, set the environment variable OSTYPE to linux before you run make:

	OSTYPE=linux make

To build on a big-endian platform, change LSB_FIRST=1 to =0 in the Makefile.

By default, the code is compiled with optimizations using the release make target. Use the debug target to generate debugging information and disable optimizations:

	make debug

New in Release 1.4.8

• Guard against invalid data sometimes created by makessf.py (fixes crashing Pebble Beach ST-V rips)

---

MIDI dumping support

The following table lists the MIDI events generated by the MIDI dumper for each individual engine, as well as the loss of data in this conversion.

Engine	Note On (Pitch)	Note On (Velocity)	Note Off
Capcom QSound (.qsf)
Sega Saturn (.ssf)
Sony PlayStation 1 (.psf, .spu)
Sega Dreamcast (.dsf)	✔ (- 5½ octaves)	✔ (- 1 bit)	✔
Sony PlayStation 2 (.psf2)

---

Entry points of an AO engine are as follows:

• int32 XXX_start(uint8 *, uint32)

  This function attempts to recognize and load a file of a specific type. It is assumed external code has already checked the file's signature in cases where that's possible. The first parameter is a pointer to the entire file in memory, and the second is the length of the file. The return value is AO_SUCCESS if the engine properly loaded the file and AO_FAIL if it didn't.

• int32 XXX_sample(stereo_sample_t *)

  This function actually plays the song, generates the next sample in 16-bit stereo format at 44100 Hz, and returns it through the given pointer.

• int32 XXX_frame(void)

  This function is called once per frame and can be used to update the internal state of the format engine if necessary.

• int32 XXX_stop(void)

  This function ceases playback and cleans up the engine. You must call _start() again after this to play more music.

• int32 XXX_command(int32, int32)

  For some engines, this allows you to send commands while a song is playing. The first parameter is the command (these are defined in ao.h), the second is the parameter. These commands are as follows:

  • COMMAND_PREV (parameter ignored) - for file formats which have more than one song in a file (NSF), this moves back one song.

  • COMMAND_NEXT (parameter ignored) - for file formats which have more than one song in a file (NSF), this moves forward one song.

  • COMMAND_RESTART (parameter ignored) - Restarts the current song from the beginning. Not supported by all engines.

  • COMMAND_HAS_PREV (parameter ignored) - for file formats which have more than one song in a file (NSF), this checks if moving backwards from the current song is a valid operation. (Returns AO_FAIL if not)

  • COMMAND_HAS_NEXT (parameter ignored) - for file formats which have more than one song in a file (NSF), this checks if moving forward from the current song is a valid operation. (Returns AO_FAIL if not)

  • COMMAND_GET_MIN (parameter ignored) - for file formats which have more than one song in a file (NSF), this returns the lowest valid song number.

  • COMMAND_GET_MAX (parameter ignored) - for file formats which have more than one song in a file (NSF), this returns the highest valid song number.

  • COMAND_JUMP - for file formats which have more than one song in a file (NSF), this command jumps directly to a specific song number, which is passed in as the parameter.

• int32 XXX_fillinfo(ao_display_info *)

  This function fills out the ao_display_info struct (see ao.h for details) with information about the currently playing song. The information provided varies by engine.