ultimate user guide

altsound 2

This guide will attempt to explain what AltSound 2 is, how it works, and how to use it.
It is intended for end users. Join our discord for support related inquires.

version 1.0 by Author Dave Roscoe aka 'MrGrynch', video tutorial by 'idigstuff'

AltSound 2

What is it?

AltSound is a concatenation of the words “Alternative” and “Sound”.
It is literally an alternative sound library to replace sounds provided by the ROMs of virtual pinball games. AltSound 2 is a completely redesigned implementation of the original AltSound processing code, with bug fixes, new features, and a new AltSound library format.

It is 100% backward compatible with all existing AltSound formats.

AltSound 2

do i need it?

Like the original AltSound, in many cases, you don’t.
However, there are reasons you may want to use AltSounds, and others where it is more of a necessity:

Poor sound quality of the original ROM
Reskin of an existing ROM-based game to create a new one
A simple desire for better sound quality in general

Poor ROM Sound Quality

Due to either incorrect or incomplete emulation, or poor sound quality of the original ROM itself, users may want to replace the built-in ROM sounds with something that sounds better. AltSounds provide the means to do this.

General Desire for Better Sound Quality

The golden age of pinball is largely behind us. Some say it is seeing something of a resurgence, but the large body of games played today were developed quite a long time ago. The sound hardware of the time cannot compare to what’s available today on even modest gaming computers.

While some embrace the limitations of the era with nostalgia, others want a more modern treatment to pinball sound. AltSound provides the ability to accommodate that desire.

Reskin of Existing ROM-Based Game

Sometimes, authors will repurpose an existing ROM-based virtual pinball game to create a completely new game. This is called “reskinning” a game, and it poses a problem. Since the only available ROM emulation is for the original game, and the sounds are hard-coded into it, it may not be suitable for the new game. It is not practical to create a new ROM, or replace the sounds within the ROM.

There are two main approaches to addressing this:

Create a “muted” ROM. These are modified ROMs where the built-in sounds are muted or disabled. The author of the table must provide the missing sounds. This is typically done with a PUP Pack or from the table implementation itself. This is a very labor-intensive approach, but provides the greatest level of control.
Create an AltSound package. The AltSound package provides the alternate sounds that are played in place of the ROM sounds at the appropriate times within the game. Once created, this frees the author to focus on the mechanics of the game they are creating. The virtual pinball emulator software takes care of the rest. It is an easier implementation at the expense of total control of the sound behavior.

AltSound 2 Format Overview

There are three formats supported by AltSound 2:

Legacy (PinSound)
AltSound (Traditional)
G-Sound (GrynchSound)

Legacy (PinSound)

The original AltSounds were based on a product called PinSound. PinSound is a combination of hardware and software used by physical pinball enthusiasts to enhance the sounds of their tables. Its library format consists of a nested directory structure describing the different sound types, such as “jingle”, “single”, “sfx”, “voice”, etc.

Each directory can contain information that controls how the sound types are played. Additionally, each sound type directory is further subdivided into other subdirectories which represent the individual sounds that fall within the parent sound type. In addition to the sound files themselves, these too may contain information that controls how the sounds are played, which supersede any controls defined previously for that sound type.

AltSound (Traditional)

AltSound is a bit confusing as a format description, since it also describes what it is. However, that’s the way things are, so we have to live with it. The Traditional AltSound format replaced the Legacy PinSound format for virtual pinball authors, and is used for all new AltSound packages produced today. The library format consists of a single CSV file: altsound.csv, which lists all of the sounds that can be played, as well as additional information which controls how and when the sounds are played, and the interaction behaviors between different sounds. The library definition CSV file and the sound files themselves reside in a single directory.

G-Sound (GrynchSound)

G-Sound is a new AltSound format, introduced with AltSound 2, and included in VPinMAME 3.6 and later. It was created to address shortcomings of the Traditional AltSound format, and provide a better environment for authors to create AltSound packages for virtual pinball games. Like the Traditional AltSound format, the G-Sound format consists of a single CSV file: g-sound.csv, which lists all of the sounds that can be played, as well as additional information which controls how and when the sounds are played, and the interaction behaviors between different sounds. The library definition CSV file and the sound files themselves reside in a single directory.

how to use

altsound 2

If you are already familiar with the previous AltSound implementation, most of this will already be known to you. It is still useful to read through, as new options are available for resolving problems. If you’re looking for an AltSound package for your game, start at altsound.vpin24.com. There are also AltSound packages available on vpuniverse.com. If you don’t see what you are looking for, you could always become an author of one!

Once you’ve downloaded an AltSound package for your game, unzip it. It is a good idea to unzip it into a temporary folder. If, for some reason, the author did not zip the entire folder, but instead zipped only the files, this will prevent the unzipped files from littering the folder you unzipped from.

Once you’ve unzipped the AltSound package, It should have created a folder that matches the name of the ROM for your game.

If the folder name mostly matches, except for the numbers/letters at the end of the folder name, it is possible that the ROM version used for the AltSound is different than the installed game. In this case, you can try renaming the folder to match. Keep in mind, however, that the differences between versions could impact sounds, and the AltSound may not work 100%. (but probably will)
If you unzipped into a subfolder as suggested and it contains a bunch of files, rather than another folder, rename the subfolder to match the ROM name. Again, if the AltSound package was created for a different ROM version, it may not work 100% (but probably will)

Copy the folder that matches your ROM name into your “altsound” folder. It is located at the root of your VPinMAME installation:

Now that the AltSound package has been installed, launch Visual Pinball X (VPX) and run your game. When the game is running, press the F1 key. This will bring up the options menu:

Use the TAB key to cycle through the options until you get to “Alt. Sound Mode (0-3)”. The value you enter here will vary depending on the AltSound format of your package and your sound hardware:

If the folder contains an “altsound.csv” or “g-sound.csv” file, enter “1” here.
If the folder contains subfolders with names like “jingle”, “single”, “voice”, etc. and you are NOT running on PinSound sound hardware, enter “1” here. Note: this only works for the unencrypted versions of the PinSound libraries, which are now quite old.
If the folder contains subfolders with names like “jingle”, “single”, “voice”, etc. and you are running on PinSound sound hardware, enter “2” here.
Note: This will also require you to run the PinSound Audio Studio prior to launching. This too only works for the unencrypted versions of the PinSound libraries.

When done, use TAB until the OK button is highlighted and press ENTER. Close down VPX and relaunch your game. If everything worked, you should now be hearing your AltSound playing instead of the ROM sounds.

altsound 2

troubleshooting

Prior to AltSound 2, many users experienced issues with AltSound volumes being too low, or behaving erratically. The reason for this is tied to the way VPinMAME tries to recreate some of the original ROM volume behavior in the AltSound. This does not always work as intended. To maintain backward compatibility, this feature is preserved by default in AltSound 2. However, there is now a workaround:.

The first time you run a game with AltSound, a .ini file is created that allows you to modify some of the behaviors of AltSound. This file is “altsound.ini'' and is located in the altsound/<ROM name> for your game (G-Sound packages already come with the .ini file):

Open this file and locate the ”rom_volume_ctrl” configuration parameter:

Set “rom_volume_ctrl” to zero and save the file. Do not change any settings that are not in the [system] or [logging] section unless you know what you are doing. Most of the other settings apply only to G-Sound packages.

Getting Help

Devs make mistakes and it’s possible you’ve found one. Help is available, but you must do a little bit to help us help you. If you spot a problem with an AltSound package, here’s what you need to do. As soon as you spot a problem:

Shut down VPX
Go to your “tables” folder
Locate the “altsound.log” file
Copy it into an empty folder
Into that same folder add:
- The altsound.csv or g-sound.csv for the game. These are located in the VPinMAME altsound/<ROM name> folder
Zip up the folder and create an issue on PinMAME GitHub
In the issue, describe the problem and attach the zipped file you just created
Sit back and wait for help

Prioritized Support

If you want to turbocharge your support issue and help ensure a rapid response and solution, there’s a little more you can do before creating your issue. When you spot a problem:

- Shut down VPX
- Go to your VPinMAME altsound/<ROM name> folder
- Open the altsound.ini file
- Set “record_sound_cmds” to “1”

Set “logging_level” to “Debug” (case doesn’t matter)

Recreate the problem
Shut down VPX
Go to your “tables” folder
Locate the “altsound.log” file
Copy it into an empty folder
Go to your <VPinMAME>/altsound/<ROM name> folder
Locate the <ROM name>-cmdlog.txt file and altsound/g-sound.csv file
Copy that into the same folder
Zip up the folder and create an issue on PinMAME GitHub
In the issue, describe the problem and attach the zipped file you just created
Sit back and enjoy expedited help and the eternal gratitude of a Dev

SUPPORT PRO TIP

Want to always ensure speedy and gracious support? Whenever you install and configure a new AltSound package:

Run the game briefly to create the altsound.ini file. This step is only necessary for legacy PinSound and traditional AltSound packages. G-Sound packages will already have a .ini file, so this step can be skipped
Follow the above instructions to set “logging_level = Debug” and “record_sound_cmds = 1”
Save the ini file.

Now, whenever you find a problem, you always have the extra fuel to ensure turbocharged support
(and don’t forget, the eternal gratitude of a Dev)

Happy Gaming!