Game_Music_Emu 0.6.0 Pre-release -------------------- Author : Shay Green Author : Chris Moeller Website: http://www.slack.net/~ant/libs/ Website: http://bitbucket.com/kode54/Game_Music_Emu Forum : http://groups.google.com/group/blargg-sound-libs License: GNU Lesser General Public License (LGPL) NOTE: This file has not been fully updated yet! Contents -------- * Overview * C and C++ interfaces * Function reference * Error handling * Emulator types * M3U playlist support * Information fields * Track length * Loading file data * Sound parameters * VGM/GYM YM2413 & YM2612 FM sound * Modular construction * Obscure features * Solving problems * Deprecated features * Thanks Overview -------- This library can open game music files, play tracks, and read game and track information tags. To play a game music file, do the following: * Open the file with gme_open_file() * Start a track with gme_start_track(); * Generate samples as needed with gme_play() * Play samples through speaker using your operating system * Delete emulator when done with gme_delete() Your code must arrange for the generated samples to be played through the computer's speaker using whatever method your operating system requires. There are many additional features available; you can: * Determine of the type of a music file without opening it with gme_identify_*() * Load just the file's information tags with gme_info_only * Load from a block of memory rather than a file with gme_load_data() * Arrange for a fade-out at a particular time with gme_set_fade * Find when a track has ended with gme_track_ended() * Seek to a new time in the track with gme_seek() * Load an extended m3u playlist with gme_load_m3u() * Get a list of the voices (channels) and mute them individually with gme_voice_names() and gme_mute_voice() * Change the playback tempo without affecting pitch with gme_set_tempo() * Adjust treble/bass equalization with gme_set_equalizer() * Associate your own data with an emulator and later get it back with gme_set_user_data() * Register a function of yours to be called back when the emulator is deleted with gme_set_user_cleanup() Refer to gme.h for a comprehensive summary of features. C and C++ interfaces -------------------- While the library is written in C++, an extensive C interface is provided in gme.h. This C interface will be referred to throughout this documentation unless a feature is only available in the full C++ interface. All C interface functions and other names have the gme_ prefix, so you can recognize a C++-only feature by the lack of gme_ in the names used (contact me if you'd like a feature added to the C interface). If you're building a shared library, I highly recommend sticking to the C interface only, because it will be more stable between releases of the library than the C++ interface. Finally, the C and C++ interfaces can be freely mixed without problems. Compare demo/basics.c with demo/cpp_basics.cpp to see how the C and C++ interfaces translate between each other. Function reference ------------------ Read the following header files for a complete reference to functions and features. The second group of header files can only be used in C++. blargg_config.h Library configuration gme.h C interface (also usable from C++) Gme_File.h File loading and track information Music_Emu.h Track playback and adjustments Data_Reader.h Custom data readers Effects_Buffer.h Sound buffer with adjustable stereo echo and panning M3u_Playlist.h M3U playlist support Gbs_Emu.h GBS equalizer settings Nsf_Emu.h NSF equalizer settings Spc_Emu.h SPC surround disable Vgm_Emu.h VGM oversampling disable and custom buffer query Error handling -------------- Functions which can fail have a return type of gme_err_t (blargg_err_t in the C++ interfaces), which is a pointer to an error string (const char*). If a function is successful it returns NULL. Errors that you can easily avoid are checked with debug assertions; gme_err_t return values are only used for genuine run-time errors that can't be easily predicted in advance (out of memory, I/O errors, incompatible file data). Your code should check all error values. To improve usability for C programmers, C++ programmers unfamiliar with exceptions, and compatibility with older C++ compilers, the library does *not* throw any C++ exceptions and uses malloc() instead of the standard operator new. This means that you *must* check for NULL when creating a library object with the new operator. When loading a music file in the wrong emulator or trying to load a non-music file, gme_wrong_file_type is returned. You can check for this error in C++ like this: gme_err_t err = gme_open_file( path, &emu ); if ( err == gme_wrong_file_type ) ... To check for minor problems, call gme_warning() to get a string describing the last warning. Your player should allow the user some way of knowing when this is the case, since these minor errors could affect playback. Without this information the user can't solve problems as well. When playing a track, gme_warning() returns minor playback-related problems (major playback problems end the track immediately and set the warning string). Emulator types -------------- The library includes several game music emulators that each support a different file type. Each is identified by a gme_type_t constant defined in gme.h, for example gme_nsf_emu is for the NSF emulator. If you use gme_open_file() or gme_open_data(), the library does the work of determining the file type and creating an appropriate emulator. If you want more control over this process, read on. There are two basic ways to identify a game music file's type: look at its file extension, or read the header data. The library includes functions to help with both methods. The first is preferable because it is fast and the most common way to identify files. Sometimes the extension is lost or wrong, so the header must be read. Use gme_identify_extension() to find the correct game music type based on a filename. To identify a file based on its extension and header contents, use gme_identify_file(). If you read the header data yourself, use gme_identify_header(). If you want to remove support for some music types to reduce your executable size, edit GME_TYPE_LIST in blargg_config.h. For example, to support just NSF and GBS, use this: #define GME_TYPE_LIST gme_nsf_type, gme_gbs_type M3U playlist support -------------------- The library supports playlists in an extended m3u format with gme_load_m3u() to give track names and times to multi-song formats: AY, GBS, HES, KSS, NSF, NSFE, and SAP. Some aspects of the file format itself is not well-defined so some m3u files won't work properly (particularly those provided with KSS files). Only m3u files referencing a single file are supported; your code must handle m3u files covering more than one game music file, though it can use the built-in m3u parsing provided by the library. Information fields ------------------ Support is provided for the various text fields and length information in a file with gme_track_info(). If you just need track information for a file (for example, building a playlist), use gme_new_info() in place of gme_new_emu(), load the file normally, then you can access the track count and info, but nothing else. M3U VGM GYM SPC SAP NSFE NSF AY GBS HES KSS ------------------------------------------------------- Track Count | * * * * * * * * * | System | * * * * * * * * * * | Game | * * * * * * * | Song | * * * * * * * | Author | * * * * * * * * | Copyright | * * * * * * * * | Comment | * * * * | Dumper | * * * * | Length | * * * * * * | Intro Length| * * * | Loop Length | * * * As listed above, the HES and KSS file formats don't include a track count, and tracks are often scattered over the 0-255 range, so an m3u playlist for these is a must. Unavailable text fields are set to an empty string and times to -1. Your code should be prepared for any combination of available and unavailable fields, as a particular music file might not use all of the supported fields listed above. Currently text fields are truncated to 255 characters. Obscure fields of some formats are not currently decoded; contact me if you want one added. Track length ------------ The library leaves it up to you as to when to stop playing a track. You can ask for available length information and then tell the library what time it should start fading the track with gme_set_fade(). By default it also continually checks for 6 or more seconds of silence to mark the end of a track. Here is a reasonable algorithm you can use to decide how long to play a track: * If the track length is > 0, use it * If the loop length > 0, play for intro + loop * 2 * Otherwise, default to 2.5 minutes (150000 msec) If you want to play a track longer than normal, be sure the loop length isn't zero. See Music_Player.cpp around line 145 for example code. By default, the library skips silence at the beginning of a track. It also continually checks for the end of a non-looping track by watching for 6 seconds of unbroken silence. When doing this is scans *ahead* by several seconds so it can report the end of the track after only one second of silence has actually played. This feature can be disabled with gme_ignore_silence(). Loading file data ----------------- The library allows file data to be loaded in many different ways. All load functions return an error which you should check. The following examples assume these variables: Music_Emu* emu; gme_err_t error; If you're letting the library determine a file's type, you can use either gme_open_file() or gme_open_data(): error = gme_open_file( pathname, &emu ); error = gme_open_data( pointer, size, &emu ); If you're manually determining file type and using used gme_new_emu() to create an emulator, you can use the following methods of loading: * From a block of memory: error = gme_load_data( emu, pointer, size ); * Have library call your function to read data: gme_err_t my_read( void* my_data, void* out, long count ) { // code that reads 'count' bytes into 'out' buffer // and return 0 if no error } error = gme_load_custom( emu, my_read, file_size, my_data ); * If you must load the file data into memory yourself, you can have the library use your data directly *without* making a copy. If you do this, you must not free the data until you're done playing the file. error = emu->load_mem( pointer, size ); * If you've already read the first bytes of a file (perhaps to determine the file type) and want to avoid seeking back to the beginning for performance reasons, use Remaining_Reader: Std_File_Reader in; error = in.open( file_path ); char header [4]; error = in.read( &header, sizeof header ); ... Remaining_Reader rem( &header, sizeof header, &in ); error = emu->load( rem ); If you merely need access to a file's header after loading, use the emulator-specific header() functions, after casting the Music_Emu pointer to the specific emulator's type. This example examines the chip_flags field of the header if it's an NSF file: if ( music_emu->type() == gme_nsf_type ) { Nsf_Emu* nsf_emu = (Nsf_Emu*) music_emu; if ( nsf_emu->header().chip_flags & 0x01 ) ... } Contact me if you want more information about loading files. Sound parameters ---------------- All emulators support an arbitrary output sampling rate. A rate of 44100 Hz should work well on most systems. Since band-limited synthesis is used, a sampling rate above 48000 Hz is not necessary and will actually reduce sound quality and performance. All emulators also support adjustable gain, mainly for the purpose of getting consistent volume between different music formats and avoiding excessive modulation. The gain can only be set *before* setting the emulator's sampling rate, so it's not useful as a general volume control. The default gains of emulators are set so that they give generally similar volumes, though some soundtracks are significantly louder or quieter than normal. Some emulators support adjustable treble and bass frequency equalization (AY, GBS, HES, KSS, NSF, NSFE, SAP, VGM) using set_equalizer(). Parameters are specified using gme_equalizer_t eq = { treble_dB, bass_freq }. Treble_dB sets the treble level (in dB), where 0.0 dB gives normal treble; -200.0 dB is quite muffled, and 5.0 dB emphasizes treble for an extra crisp sound. Bass_freq sets the frequency where bass response starts to diminish; 15 Hz is normal, 0 Hz gives maximum bass, and 15000 Hz removes all bass. For example, the following makes the sound extra-crisp but lacking bass: gme_equalizer_t eq = { 5.0, 1000 }; gme_set_equalizer( music_emu, &eq ); Each emulator's equalization defaults to approximate the particular console's sound quality; this default can be determined by calling equalizer() just after creating the emulator. The Music_Emu::tv_eq profile gives sound as if coming from a TV speaker, and some emulators include other profiles for different versions of the system. For example, to use Famicom sound equalization with the NSF emulator, do the following: music_emu->set_equalizer( Nsf_Emu::famicom_eq ); VGM/GYM YM2413 & YM2612 FM sound -------------------------------- The library plays Sega Genesis/Mega Drive music using a YM2612 FM sound chip emulator based on the Gens project. Because this has some inaccuracies, other YM2612 emulators can be used in its place by re-implementing the interface in YM2612_Emu.h. Available on my website is a modified version of MAME's YM2612 emulator, which sounds better in some ways and whose author is still making improvements. VGM music files using the YM2413 FM sound chip are also supported, but a YM2413 emulator isn't included with the library due to technical reasons. I have put one of the available YM2413 emulators on my website that can be used directly. Modular construction -------------------- The library is made of many fairly independent modules. If you're using only one music file emulator, you can eliminate many of the library sources from your program. Refer to the files list in readme.txt to get a general idea of what can be removed, and be sure to edit GME_TYPE_LIST (see "Emulator types" above). Post to the forum if you'd like me to put together a smaller version for a particular use, as this only takes me a few minutes to do. If you want to use one of the individual sound chip emulators (or CPU cores) in your own console emulator, first check the libraries page on my website since I have released several of them as stand alone libraries with included documentation and examples on their use. If you don't find it as a standalone library, contact me and I'll consider separating it. The "classic" sound chips use my Blip_Buffer library, which greatly simplifies their implementation and efficiently handles band-limited synthesis. It is also available as a stand alone library with documentation and many examples. Obscure features ---------------- The library's flexibility allows many possibilities. Contact me if you want help implementing ideas or removing limitations. * Uses no global/static variables, allowing multiple instances of any emulator. This is useful in a music player if you want to allow simultaneous recording or scanning of other tracks while one is already playing. This will also be useful if your platform disallows global data. * Emulators that support a custom sound buffer can have *every* voice routed to a different Blip_Buffer, allowing custom processing on each voice. For example you could record a Game Boy track as a 4-channel sound file. * Defining BLIP_BUFFER_FAST uses lower quality, less-multiply-intensive synthesis on "classic" emulators, which might help on some really old processors. This significantly lowers sound quality and prevents treble equalization. Try this if your platform's processor isn't fast enough for normal quality. Even on my ten-year-old 400 MHz Mac, this reduces processor usage at most by about 0.6% (from 4% to 3.4%), hardly worth the quality loss. Solving problems ---------------- If you're having problems, try the following: * If you're getting garbled sound, try this simple siren generator in place of your call to play(). This will quickly tell whether the problem is in the library or in your code. static void play_siren( long count, short* out ) { static double a, a2; while ( count-- ) *out++ = 0x2000 * sin( a += .1 + .05*sin( a2+=.00005 ) ); } * Enable debugging support in your environment. This enables assertions and other run-time checks. * Turn the compiler's optimizer is off. Sometimes an optimizer generates bad code. * If multiple threads are being used, ensure that only one at a time is accessing a given set of objects from the library. This library is not in general thread-safe, though independent objects can be used in separate threads. * If all else fails, see if the demos work. Deprecated features ------------------- The following functions and other features have been deprecated and will be removed in a future release of the library. Alternatives to the deprecated features are listed to the right. Music_Emu::error_count() warning() load( header, reader ) see "Loading file data" above Spc_Emu::trailer() track_info() Spc_Emu::trailer_size() Gym_Emu::track_length() track_info() Vgm_Emu::gd3_data() track_info() Nsfe_Emu::disable_playlist() clear_playlist() Thanks ------ Big thanks to Chris Moeller (kode54) for help with library testing and feedback, for maintaining the Foobar2000 plugin foo_gep based on it, and for original work on openspc++ that was used when developing Spc_Emu. Brad Martin's excellent OpenSPC SNES DSP emulator worked well from the start. Also thanks to Richard Bannister, Mahendra Tallur, Shazz, nenolod, theHobbit, Johan Samuelsson, and nes6502 for testing, using, and giving feedback for the library in their respective game music players.