491
|
1 Game_Music_Emu 0.3.0 Notes
|
|
2 --------------------------
|
|
3 Author : Shay Green <hotpop.com@blargg>
|
|
4 Website: http://www.slack.net/~ant/
|
|
5 Forum : http://groups.google.com/group/blargg-sound-libs
|
|
6
|
|
7
|
|
8 Overview
|
|
9 --------
|
|
10 This library is composed of several independent game music emulators
|
|
11 derived from the common Music_Emu interface. Each emulator can load a
|
|
12 game music file and play from any track. To play a game music file, do
|
|
13 the following:
|
|
14
|
|
15 - Determine file's type
|
|
16 - Create appropriate emulator
|
|
17 - Set sample rate
|
|
18 - Load file into emulator
|
|
19 - Start desired track
|
|
20 - When samples are needed, call play()
|
|
21 - When done, delete emulator
|
|
22
|
|
23 See Music_Emu.h for reference.
|
|
24
|
|
25
|
|
26 Information Fields
|
|
27 ------------------
|
|
28 Game music files include text fields with information about the game and
|
|
29 track. These are stored in the file's header or in an embedded block.
|
|
30 Text fields in most game music formats do *not* have a nul terminator if
|
|
31 the string completely fills the field. The simplest way to handle this
|
|
32 is to copy the string out and manually add a nul terminator at the end.
|
|
33
|
|
34 This library is currently focused only on actual emulation, so it
|
|
35 doesn't provide a common interface to the different schemes each game
|
|
36 music file format uses. Refer to the file's official specification for
|
|
37 further information.
|
|
38
|
|
39
|
|
40 Modular Construction
|
|
41 --------------------
|
|
42 The library is made of many fairly independent modules. If you're using
|
|
43 only one music file emulator, you can eliminate many of the library
|
|
44 sources from your program. Refer to the files list in readme.txt to get
|
|
45 a general idea of what can be removed. Post to the forum if you'd like
|
|
46 me to put together a smaller version for a particular use, as this only
|
|
47 takes me a few minutes to do.
|
|
48
|
|
49 If you want to use one of the individual sound chip emulators in your
|
|
50 console emulator, first check the libraries page on my website since I
|
|
51 have released several of them as standalone libraries with included
|
|
52 documentation and examples on their use.
|
|
53
|
|
54 The "classic" sound chips use my Blip_Buffer library, which greatly
|
|
55 simplifies their implementation and efficiently handles band-limited
|
|
56 synthesis. It is also available as a standalone library with
|
|
57 documentation and many examples.
|
|
58
|
|
59
|
|
60 Sound Parameters
|
|
61 ----------------
|
|
62 All emulators support adjustable output sampling rate, set with
|
|
63 Music_Emu::set_sample_rate(). A rate of 44100 should work well on most
|
|
64 systems. Since band-limited synthesis is used, a sampling rate above
|
|
65 48000 Hz is not necessary.
|
|
66
|
|
67 Some emulators support adjustable treble and bass frequency equalization
|
|
68 (NSF, GBS, VGM) using Music_Emu::set_equalizer(). Parameters are
|
|
69 specified using Music_Emu::equalizer_t eq = { treble_dB, bass_freq }.
|
|
70 Treble_dB sets the treble level (in dB), where 0.0 dB gives normal
|
|
71 treble; -200.0 dB is quite muffled, and 5.0 dB emphasizes treble for an
|
|
72 extra crisp sound. Bass_freq sets the frequency where bass response
|
|
73 starts to diminish; 15 Hz is normal, 0 Hz gives maximum bass, and 15000
|
|
74 Hz removes all bass. For example, the following makes the sound
|
|
75 extra-crisp but lacking bass:
|
|
76
|
|
77 Music_Emu::equalizer_t eq = { 5.0, 1000 };
|
|
78 music_emu->set_equalizer( eq );
|
|
79
|
|
80 Each emulator's equalization defaults to a profile that approximates its
|
|
81 particular console's sound quality; this default can be determined by
|
|
82 calling Music_Emu::equalizer() just after creating the emulator. Some
|
|
83 emulators include other profiles for different versions of the system.
|
|
84 The Music_Emu::tv_eq profile gives sound as if coming from a TV speaker.
|
|
85 For example, to use Famicom sound equalization with the NSF emulator, do
|
|
86 the following:
|
|
87
|
|
88 nsf_emu->set_equalizer( Nsf_Emu::famicom_eq );
|
|
89
|
|
90
|
|
91 VGM/GYM YM2413 & YM2612 FM Sound
|
|
92 --------------------------------
|
|
93 The library plays Sega Genesis/Mega Drive music using a YM2612 FM sound
|
|
94 chip emulator based on Gens. Because this has some inaccuracies, other
|
|
95 YM2612 emulators can be used in its place by reimplementing the
|
|
96 interface in YM2612_Emu.h. Available on my website is a modified version
|
|
97 of MAME's YM2612 emulator, which sounds better in some ways and whose
|
|
98 author is still making improvements.
|
|
99
|
|
100 VGM music files using the YM2413 FM sound chip are also supported, but a
|
|
101 YM2413 emulator isn't included. Similar to above, I have put one of the
|
|
102 available YM2413 emulators on my website that can be used directly.
|
|
103
|
|
104
|
|
105 Misc
|
|
106 ----
|
|
107 Some emulators have constructor parameters which can be specified when
|
|
108 creating the object. For example, this creates a Vgm_Emu with
|
|
109 oversampling off and a tempo of 83%:
|
|
110
|
|
111 Vgm_Emu* emu = new Vgm_Emu( false, 0.83 );
|
|
112
|
|
113 For a full example of using Game_Music_Emu see the source code for Game
|
|
114 Music Box, a full-featured game music player for Mac OS:
|
|
115
|
|
116 http://www.slack.net/~ant/game-music-box/dev.html
|
|
117
|
|
118
|
|
119 Thanks
|
|
120 ------
|
|
121 Big thanks to Chris Moeller (kode54) for help with library testing and
|
|
122 feedback, for maintaining the Foobar2000 plugin foo_gep based on it, and
|
|
123 for original work on openspc++ that was used when developing Spc_Emu.
|
|
124 Brad Martin's excellent OpenSPC SNES DSP emulator worked well from the
|
|
125 start. Also thanks to Richard Bannister, Mahendra Tallur, Shazz, and the
|
|
126 Audacious team for testing and using the library in their game music
|
|
127 players.
|
|
128
|
|
129
|
|
130 Solving Problems
|
|
131 ----------------
|
|
132 If you're having problems, try the following:
|
|
133
|
|
134 - Enable debugging support in your environment. This enables assertions
|
|
135 and other run-time checks.
|
|
136
|
|
137 - Turn the compiler's optimizer is off. Sometimes an optimizer generates
|
|
138 bad code.
|
|
139
|
|
140 - If multiple threads are being used, ensure that only one at a time is
|
|
141 accessing a given set of objects from the library. This library is not
|
|
142 in general thread-safe, though independent objects can be used in
|
|
143 separate threads.
|
|
144
|
|
145 - If all else fails, see if the demos work.
|
|
146
|
|
147
|
|
148 Error handling
|
|
149 --------------
|
|
150 Functions which can fail have a return type of blargg_err_t, which is a
|
|
151 pointer to an error string (const char*). If the function is successful
|
|
152 it returns blargg_success (NULL), otherwise it returns a pointer to an
|
|
153 error string. Errors which the caller can easily detect are only checked
|
|
154 with debug assertions; blargg_err_t returns values are only used for
|
|
155 genuine run-time errors that can't be easily predicted in advance (out
|
|
156 of memory, I/O errors, incompatible file data).
|
|
157
|
|
158 To allow compatibility with older C++ compilers, no exceptions are
|
|
159 thrown by any of the modules and code is generally exception-safe. Any
|
|
160 exceptions thrown by the standard library or caller-supplied functions
|
|
161 are allowed to propagate normally.
|
|
162
|
|
163
|
|
164 Configuration
|
|
165 -------------
|
|
166 The header "blargg_common.h" is used to establish a common environment,
|
|
167 and is #included at the beginning of all library headers and sources. It
|
|
168 attempts to automatically determine the features of the environment, but
|
|
169 might need help. Refer to "blargg_common.h" for descriptions of
|
|
170 features.
|
|
171
|
|
172 If defined HAVE_CONFIG_H in the compiler command-line, the user-provided
|
|
173 "config.h" is included at the beginning of each library header file,
|
|
174 allowing configuration options for the library to be set. I have
|
|
175 attempted to design the library so that configuration can be done
|
|
176 *without* modifying any of the library sources and header files. This
|
|
177 makes it easy to upgrade to a new version without losing any
|
|
178 customizations to its configuration.
|
|
179
|
|
180 Post to the forum if you have problems or suggestions.
|
|
181
|