aboutsummaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md61
1 files changed, 43 insertions, 18 deletions
diff --git a/README.md b/README.md
index fba2024..2f70ecd 100644
--- a/README.md
+++ b/README.md
@@ -3,34 +3,46 @@
**VMusic** is an extension pack for [VirtualBox](https://www.virtualbox.org), containing
some virtual devices for common music hardware:
-* An `adlib` device emulating an OPL2/OPL3 using the [Nuked OPL3 emulator](https://github.com/nukeykt/Nuked-OPL3).
-By default this device is configured on the standard Adlib Gold ports, 0x388-0x38B, but can also be configured
-to listen simultaneously on a second set of ports in order to provide some Sound Blaster Pro/SB FM compatibility
+* A `mpu401` device emulating a MPU-401 "compatible" dumb/UART-only, on the usual ports 0x330-0x331.
+This allows the guest to output MIDI data to the host. The raw MIDI data is sent to a "Virtual RawMIDI" ALSA device
+which can be connected with either a real MIDI device or a synthesizer such as [FluidSynth](https://www.fluidsynth.org/)
+or [Munt](https://sourceforge.net/projects/munt/). MIDI input is also partially supported.
+
+* An `adlib` device emulating an OPL2/OPL3 FM synthesizer using the [Nuked OPL3 emulator](https://github.com/nukeykt/Nuked-OPL3).
+By default this device is configured on the standard AdLib ports, 0x388-0x38B, but can also be configured
+to listen simultaneously on a second set of ports in order to provide Sound Blaster FM compatibility
(e.g. 0x220-0x223).
The generated audio is sent directly via ALSA to the default PCM output device (usually PulseAudio), ignoring
VirtualBox settings.
-* A `mpu401` device emulating a MPU-401 "compatible" dumb/UART-only, on the usual ports 0x330-0x331.
-This allows the guest to output MIDI data to the host. The raw MIDI data is sent to a "Virtual RawMIDI" ALSA device
-which can be connected with either a real MIDI device or a synthesizer such as [FluidSynth](https://www.fluidsynth.org/)
-or [Munt](https://sourceforge.net/projects/munt/).
+* A `emu8000` device emulating the EMU8000 chip, the wavetable synthesis device that was included in the Sound Blaster AWE32,
+using code from the [PCem emulator](https://www.pcem-emulator.co.uk/).
+This allows most software to assume an SB AWE32 is installed (rather than VirtualBox's standard SB16).
+The default base port of 0x620 matches the default base port of VirtualBox's SB (0x220).
+Using this device requires the AWE32.RAW file that can be dumped using the AWE-DUMP tool, as with PCem.
+Like the AdLib device, the generated audio is sent directly via ALSA.
Note that **this extension pack only works with Linux hosts**, but should work with any type of guests.
To make an extension pack work in Windows, it would need to be
[signed like a kernel mode driver](https://forums.virtualbox.org/viewtopic.php?f=10&t=103801),
which is practically impossible for an individual.
-These devices can be used with the standard VirtualBox SB16 emulation, so as to experience a more complete SB16
-emulation, albeit is also not necessary. You can enable each device independently, e.g. to have pure Adlib card only.
-Note that "SB MIDI" support is not implemented; for MIDI out you can only use the Mpu401 device. Most Sound Blaster
-drivers post-SB16 use the Mpu401 device.
+These devices can be combined with the standard VirtualBox SB16 emulation, to experience a more complete SB16
+emulation (or even SB AWE32), albeit it is not necessary.
+You can enable each device independently, e.g. to have pure MPU-401 only.
+Note that "SB MIDI" support is not implemented; for MIDI out you can only use the MPU-401 device. Most Sound Blaster
+drivers post-SB16 already use the MPU-401 device.
+
+### Screenshots
![Screenshot of VirtualBox playing The Secret of Monkey Island while connected to the Munt MT-32 Emulator](http://depot.javispedro.com/vbox/VirtualBoxMunt.png)
+![Screenshot of Windows 98 playing CANYON.MID while showing all the 3 devices available for MIDI output](http://depot.javispedro.com/vbox/win98e.png)
+
# Installing
-You can try using the [VMusic.vbox-extpack](http://depot.javispedro.com/vbox/VMusic-0.2-vbox6.1.30.vbox-extpack)
-I built for VirtualBox 6.1.30,
+You can try using the [VMusic.vbox-extpack](http://depot.javispedro.com/vbox/VMusic-0.3-vbox6.1.32.vbox-extpack)
+I built for VirtualBox 6.1.32,
which you can install into VirtualBox through the VirtualBox Preferences -> Extension Packs GUI,
or by running `VBoxManage extpack install VMusic.vbox-extpack`.
This should work at least for most other recent versions in the 6.1.x series.
@@ -42,12 +54,17 @@ Each device must be enabled on each VM individually, and there is no GUI to do i
Run the following, replacing `$vm` with the name of your Virtual Machine:
```shell
+# To enable the MPU-401 device
+VBoxManage setextradata "$vm" VBoxInternal/Devices/mpu401/0/Trusted 1
# To enable the Adlib device
VBoxManage setextradata "$vm" VBoxInternal/Devices/adlib/0/Trusted 1
-# To enable the Adlib device on the default SB16 ports too
+# To enable the EMU8000 device
+VBoxManage setextradata "$vm" VBoxInternal/Devices/emu8000/0/Config/ROMFile "$HOME/.pcem/roms/awe32.raw"
+
+# Optional: to enable the Adlib device on the default SB16 ports too
VBoxManage setextradata "$vm" VBoxInternal/Devices/adlib/0/Config/MirrorPort "0x220"
-# To enable the MPU-401 device
-VBoxManage setextradata "$vm" VBoxInternal/Devices/mpu401/0/Trusted 1
+# Optional: to enable an IRQ for MPU-401 MIDI input
+VBoxManage setextradata "$vm" VBoxInternal/Devices/mpu401/0/Config/IRQ 9
```
If the devices have been correctly enabled, you should see the following messages in the
@@ -55,14 +72,15 @@ VBox.log file of a virtual machine after it has been powered on:
```{ use_pygments=false }
00:00:00.799849 Installed Extension Packs:
-00:00:00.799866 VMusic (Version: 0.2 r0; VRDE Module: )
+00:00:00.799866 VMusic (Version: 0.3 r0; VRDE Module: )
...
00:00:00.920058 adlib0: Configured on port 0x388-0x38b
00:00:00.920066 adlib0: Mirrored on port 0x220-0x223
00:00:00.920825 mpu401#0: Configured on port 0x330-0x331
+00:00:00.924719 emu8000#0: Configured on ports 0x620-0x623, 0xA20-0xA23, 0xE20-0xE23
```
-### Connecting Adlib
+### Connecting Adlib or EMU8000
You do not need to do anything else to hear the emulated audio.
It will be automatically sent to the default ALSA PCM out device,
@@ -107,6 +125,9 @@ Note that the port numbers may be completely different in your system.
Also, [Qsynth](https://qsynth.sourceforge.io/) (a GUI frontend for FluidSynth) has an option to automatically connect
all virtual MIDI ports to it, in which case you may not need to connect anything.
+For MIDI input, you should do the connection in the opposite direction: connect from your real MIDI hardware to the
+`Virtual RawMIDI` device.
+
# Building
You need the standard C++ building tools, make, libasound and headers (e.g. `libasound2-dev` in Ubuntu).
@@ -121,4 +142,8 @@ E.g. copy `/usr/lib/virtualbox/VBoxRT.so` into `VirtualBox.linux.amd64/VBoxRT.so
After this, just type `make` followed by `make pack` and `VMusic.vbox-extpack` should be generated.
+# Changelog
+
+* v0.3 added support in MPU-401 for UART-mode MIDI input, and the EMU8000 device.
+* v0.2 is the initial release