-
Notifications
You must be signed in to change notification settings - Fork 0
/
vgmslap.txt
294 lines (214 loc) · 13.9 KB
/
vgmslap.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
################################################################################
# __ _______ __ __ _____ _ _ #
# \ \ / / ____| \/ |/ ____| | | | #
# \ \ / / | __| \ / | (___ | | __ _ _ __ | | Release 4 #
# \ \/ /| | |_ | |\/| |\___ \| |/ _` | '_ \| | by Wafflenet, 2023-2024 #
# \ / | |__| | | | |____) | | (_| | |_) |_| www.wafflenet.com #
# \/ \_____|_| |_|_____/|_|\__,_| .__/(_) #
# (VGM Silly Little AdLib Player) | | #
# |_| #
# #
################################################################################
== [ About ] ===================================================================
VGMSlap is an open-source, MS-DOS based player for Yamaha OPL1/2/3 Video Game
Music (VGM) files. It features a visually pleasing display of each synthesizer
channel's parameters, GD3 tags, and simple playlist support.
== [ System Requirements ] =====================================================
VGMSlap has been tested and works on processors as slow as a 286-12 (the slowest
thing I have with an OPL in it), though some settings changes are required.
For best results, a fast 386 or better is preferred. (See the Performance Tips
section below for more information)
VGMSlap runs in real mode, so only 640k of RAM is needed (probably less but I
haven't tested for exact numbers). A VGA card supporting 80x50 text mode is
also recommended.
You'll also need a sound card with a Yamaha OPL2 (YM3812), Yamaha OPL3 (YMF262)
or compatible chip. The dual OPL2 chips on the Sound Blaster Pro 1.0 card are
also supported, although this is not extensively tested since I do not own a
card.
You will only be able to play VGMs compatible with your card. Check the table:
.---------------------------------------------------.
| Your Chip | Compatible VGMs |
|---------------------------------------------------|
| Yamaha YM3812 (OPL2) | Yamaha YM3526 (OPL) |
| | Yamaha YM3812 (OPL2) |
|---------------------------------------------------|
| 2x Yamaha YM3812 (OPL2) | Yamaha YM3526 (OPL) |
| | Yamaha YM3812 (OPL2) |
| | 2x Yamaha YM3812 (OPL2) |
|---------------------------------------------------|
| Yamaha YMF262 (OPL3) | Yamaha YM3526 (OPL) |
| | Yamaha YM3812 (OPL2) |
| | 2x Yamaha YM3812 (OPL2) |
| | Yamaha YMF262 (OPL3) |
'---------------------------------------------------'
VGMSlap will NOT run correctly under Windows. At best, it'll be really slow.
Please use pure DOS!
== [ Usage ] ===================================================================
Simply call VGMSlap from the command line along with the name of a VGM file or
playlist. (More info on playlists is provided later in this document)
VGMSLAP FILENAME.VGM
Both VGM and gzipped VGM (VGZ) files are supported. VGZ files will be
temporarily decompressed to the same folder that VGMSLAP.EXE is in.
Once in the program, a few keys are available:
Arrow Keys: Move forward and backwards through a playlist.
(Only available if using a playlist)
Page Up/Down: Move forward and backwards 10 tracks in a playlist.
(Only available if using a playlist)
Esc: Quit VGMSlap
R: Reset the OPL chip.
Note, this WILL mess up playback. It's basically a debug key I
left in, but it might be useful as an emergency panic button!
== [ How to Read the Channel Display ] =========================================
VGMSlap puts a lot of info on the screen about the internal OPL registers, so
you can see exactly what is going on behind the scenes to make the chip produce
sound. Here's a quick primer on how to read this information. It does assume
that you have a slight understanding of how FM chips work - there are many
resources online that go over this info in detail.
Here is an example channel, a standard two-operator channel:
.-Ch.01--------------------------------.
|#--. /\/\ E675 T--K 2 1.5 00 3 |
| |-># x2 204|
|#--' ^-^- F324 -VS- F --- 2A (n)|
'--------------------------------------'
(A) (B) (C) (D) (E)(F) (G)(H)(I)
A. A small diagram shows how the modulator (cyan) and carrier (green) are
connected and output the note (yellow). Note these colors as they are
used throughout the channel table.
B. ASCII-art approximations of the OPL waveforms currently selected.
C. Operator ADSR (Attack/Decay/Sustain/Release) envelope data, in that
order. Values are from 0 to F (15).
D. Operator flags for Tremolo/Amplitude Vibrato (T), Frequecy Vibrato (V),
Sound Sustaining (S), and Key Scaling (K), in that order.
E. Frequency multiplication factor.
F. Key scale attenuation level, in dB per octave.
G. Output level. This is technically "output attenuation", that is, a value
of "00" means full volume, and "3F" is silence.
H. Feedback modulation factor (the amount of the modulator that is sent back
into itself). Note that for space reasons, this is not depicted in the
diagram at (A).
I. Note information. The top number is the "block number" (roughly the
octave) and the middle number is the frequency number. These can be
converted to a sound frequency in Hz using the equation:
Frequency = (49716*FrequencyNumber)/(2^(20-BlockNumber))
I do eventually plan to add this math and automatically convert it to
a note value, but it's a lot of multiplication and division and has
performance implications, so there's still some investigation needed.
The bottom line has a music note - represented as "n" in the drawing
above - which lights up when a channel's key-on flag is set.
If the OPL chip is in percussion/rhythm mode, channels 7-9 are used
for percussion instruments. The music note will change to a ! to
represent this. (Note that some songs may not appear to activate these
channels due to how percussion mode works. The flags may not be on long
enough to be visible!)
On 2xOPL2 or OPL3 VGMs, you will also see the parentheses surrounding
the note. These will light up based on the stereo panning for that
channel. On single OPL2 VGMs these will not be visible.
For four-operator OPL3 channels, two channels are combined. The first two lines
will be the first channel's operators, and the second two lines will be the
second channel's operators. A "4OP" indicator will show in the top-right of the
channel. Feedback and note information are shared by the combined channels.
== [ Configuration ] ===========================================================
VGMSLAP.CFG is used to configure your OPL chip's I/O port and some playback and
performance options. I've included info on the options in the included default
VGMSLAP.CFG, and I don't feel like repeating myself here, so go check it out for
more info.
== [ Setting Up Playlists ] ====================================================
A playlist can be made to play multiple VGMs in sequence.
Simply create a text file with the first line being #VGMLIST and then each line
after that containing a single filename. Playlist entries can use relative
paths from the current working directory, or full paths to the files.
An example of a playlist could look like the following:
#VGMLIST
C:\MUSIC\ALIBI.VGM
C:\STUFF\HIGHWAYS.VGZ
C:\MUSIC\TREEONFI.VGM
Then, just call VGMSlap with the playlist name instead of a VGM file!
Extension doesn't matter, it can just be .TXT, though I usually use .PLS to
differentiate them from normal text files. It's your call.
== [ Performance Tips ] ========================================================
I am not a trained programmer with an eye for optimization; in fact, this is
basically only my second ever C program of any meaningful substance. I hope
that I will be able to optimize VGMSlap over time as I learn more. Here are
some tips that may help if your music is lagging or stuttering.
- For slower machines, you can edit VGMSLAP.CFG and lower the timing resolution
by changing the DIVIDER option, but playback accuracy will be reduced*.
You probably won't have to set this very high - DIVIDER 2 worked well on a
386SX-40 for me, and even just DIVIDER 3 made my 286-12 happy! However, there
are some systems with unusually slow interrupt handling that might need higher
values. An example of this is my "Pocket386" which despite also having a
386SX-40 works best with at least DIVIDER 5!
*OK, hopping on the soapbox for a sec. The reduction in "accuracy" is
technically true, but most VGMs are logged from playback engines that have
considerably lower resolution than the format's 44100Hz base rate. As a
result, you probably won't actually notice any problems unless you set an
absurdly high DIVIDER value (like 255). Even then, I've found that it
mostly just makes fancier percussion instruments a little "clicky".
Don't sweat it too much if you need to increase the value. :)
- There is a lot of behind the scenes code that goes into interpreting and
displaying the OPL channel data. This is additional CPU overhead and if you
have a slow VGA card, the screen updates might introduce even more lag. You
might want to try the STRUGGLE option in VGMSLAP.CFG, which removes the
channel display completely and keeps you in 80x25 text mode. It's also nice
if you just want a less busy screen!
- VGMSlap runs entirely in real mode and thus currently does not use memory
above 640k, so VGMs have to be streamed from disk. Most systems I've tested
on have been fast enough to handle this without issue, but in the few cases of
slower disks, I've had success running VGMSlap and VGMs from a RAM drive, or
using SmartDrive caching.
== [ Known Issues ] ============================================================
- There is probably not as much error checking as would be preferred. Don't try
to get cheeky and make VGMSlap do weird things, or else face the consequences!
- Dual OPL2 detection is effectively untested, as I literally do not have any
real card to test with. I got it working in DOSBox, at least. If you own one
of these cards, I would be curious to hear about your experience.
- If your system is REALLY slow, there's a very real chance that VGMSlap will
effectively lock up your system - the music will keep going but you won't be
able to exit the program until the song finishes. It's basically unable to
detect keypresses because the CPU is so busy. This is much improved as of R2,
but not eliminated. I'll eventually come up with a solution. Until then,
use this as a sign that you need a higher DIVIDER setting in VGMSLAP.CFG.
== [ License Info ] ============================================================
VGMSlap incorporates zlib 1.2.11:
(C) 1995-2017 Jean-loup Gailly and Mark Adler
This software is provided 'as-is', without any express or implied
warranty. In no event will the authors be held liable for any damages
arising from the use of this software.
Permission is granted to anyone to use this software for any purpose,
including commercial applications, and to alter it and redistribute it
freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
2. Altered source versions must be plainly marked as such, and must not be
misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
Jean-loup Gailly Mark Adler
jloup@gzip.org madler@alumni.caltech.edu
The VGMSlap software and code itself is licensed under the MIT License:
Copyright 2023-2024 Wafflenet
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the “Software”), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
== [ Contact ] =================================================================
If you want to contact me directly, there are many ways to do so:
Email: kyle@wafflenet.com
Discord: @mrksoft
Twitter/X: @MrKsoft486
Mastodon/Fediverse: @mrksoft@bitbang.social
BlueSky: @mrksoft.bsky.social
PS. If you're looking for VGM files to play in VGMSlap, why not check out
Wafflenet's very own OPL Archive? It's an ever-growing collection of VGMs for
OPL-series sound chips, and can be found at www.opl.wafflenet.com!