Pinvol

Article published by MJR on http://mjrnet.org/pinscape/PinVol.html#install


Overview

PinVol is an open-source Windows program that makes it easier to control the audio volume on a virtual pinball cabinet. I wrote it in an attempt to fix some specific annoyances on my own cab, but it might be useful to other pin cab builders as well, because the things that were bugging me all come from the basic virtual pinball software environment that most of us use.

The big thing PinVol does is let you equalize the volume level from one table to the next, by setting a relative volume level for each table that's automatically restored each time you return to the table. PinVol is designed to be operated via cabinet buttons, so it takes its input from your choice of keyboard keys and/or joystick buttons. It has a few other special tricks for cabs, too, such as controlling multiple sound cards at once, and a Night Mode option.

PinVol controls the audio volume on your cabinet through software, by adjusting the Windows master line-out volume level. It can't reach out and turn the physical volume knob on your amplifier. If you're using an external amplifier, you'll have to leave it set to a fixed volume, and let Windows make adjustments through the line-out level. Most cab builders use this approach anyway, because the audio amplifier is usually hidden inside the cabinet, so its volume knob (if it even has one) isn't easily accessible. Some pin cab builders do go to lengths to make the amp's volume knob accessible, though. If you went that route, you can still use PinVol, but you'll want to set your physical volume knob all the way up and then forget it exists from that point on, so that the software has full control over the volume.

Features

Assignable hotkeys and joystick buttons. PinVol is built specifically for pin cabs, not desktop users. In a cab, you don't want to get out the mouse and mess with a Windows program. So PinVol does everything with keyboard keys and/or joystick buttons. For each function, you can assign a key or button of your choosing. This lets you set it up to work with cabinet buttons you've already configured, so that you can control the audio volume conveniently from your cabinet buttons.

In my recommendations at the bottom of this page, I have some suggestions about how to set up your buttons to make the audio controls easy to access but unobtrusive.

Pop-up volume display. In the same way you don't want to mess with the mouse for input, you don't want to switch to another window to see status information. PinVol provides a cabinet-friendly volume display that pops up briefly when you make a change to any of the volume settings to show the relevant new settings. You can arrange the size, position, and orientation of the volume display by clicking the "Customize" button in the PinVol window. The pop-up is designed to look like a TV volume bar, rather than a Windows window, to make it mesh better with the video-game environment.

Table volume memory. This brings us to the thing that got me started on PinVol in the first place: the way different Visual Pinball tables can have wildly different volume levels. Some tables are really quiet, some are really loud. I've always found it annoying that I have to adjust the volume up or down whenever I switch to a new table just to get a reasonably constant overall volume level. It's a really trivial problem in the scheme of things, but a pin cab is a computer, for heaven's sake; computers are supposed to free us from this sort of busywork, not make more of it!

PinVol's solution to this little nuisance is to remember separate volume levels for each table. PinVol automatically keeps track of which Visual Pinball table is running at any given time. For each one, it maintains a separate volume level slot in its memory. If the table is one of the really quiet ones, you can turn the table volume up; if it's one of the loud ones, turn the table volume down. PinVol saves each table's individual volume setting in a disk file. Each time you switch to a new table, PinVol restores the table volume that you set last time you played that table.

You don't have to do anything to tell PinVol that you switched tables. You don't ever have to press "save" or "restore" buttons to tell PinVol you want to change the table's volume memory. It's all automatic. PinVol monitors what's running on its own, and switches volume levels whenever the foreground application changes.

Separate Global and Table volumes. But what if you want to make everything louder or quieter across the board? For example, what if you want to turn things up for a party, or turn things down for late-night play?

To deal with this, PinVol actually has two volume level controls: a Global level that affects all tables, and a Table level that only affects the currently active table. There are separate Volume Up/Volume Down hotkeys for each volume type, so you can choose what you're adjusting by pressing the appropriate keys or buttons.

The Table level is stored as a percentage that's applied to whatever Global level is currently in effect. So if you want to make all tables uniformly louder or quieter, you can adjust the Global level accordingly. When you switch to a new table, the new table's saved volume level adjustment will still be loaded as always, but it'll be applied to the new Global level, so it'll be proportionally louder or quieter.

The idea is that the individual Table level settings equalize the volume level from one table to the next, so that everything has a fairly uniform apparent volume. The Table level is thus a relative volume adjustment. The Global level, on the other hand, lets you control the absolute volume level, so that you can make everything uniformly louder or quieter to suit the current playing environment.

Night Mode. The Global volume level setting lets you make everything louder or quieter, but for the sake of convenience, there's also a Night Mode setting that turns the volume down to a lower level with a single button press. And when you're ready to switch back to normal volume, pressing the button again restores the global volume level that was previously in effect. The Night Mode level is itself saved as a separate setting, so once you find a comfortable level for quieter play, you can go right back to that level without having to hunt around for it again.

If you're using a Pinscape controller unit, PinVol automatically senses when the Pinscape unit is in Night Mode. PinVol switches to Mode when Pinscape is in night mode, and switches back when Pinscape is in normal mode. This means that you don't even have to assign a separate key or button if you're using Pinscape Night Mode. PinVol will simply sync up by itself, no configuration required.

Multiple sound card support. Another issue for many pin cab people is that the standard Windows audio controls aren't very convenient to use when you have more than one audio device. Many pin cabs have two sound cards: one for the backbox audio, which plays the main ROM soundtrack like in a real machine, and a second for speakers inside the cabinet that play back the sound effects for playfield mechanicals, like the sound of the ball rolling and bumping into things. Windows does let you set the volume level for each sound card, but only one at a time; Windows doesn't have a concept of a "master volume" level that adjusts all of the sound cards together. The independent level setup is nice for equalizing the loudness levels between your different speakers, but it's not so nice when you want to turn down the volume for everything for quieter play at night, for example.

PinVol can control multiple sound cards simultaneously, but only if you want it to. By default, it only controls the "default" audio device that you select with the Windows control panels. If you have two or more sound cards, click the "Select audio devices" button in the PinVol window. This will let you pick the devices to place under PinVol's control.

When you select a secondary sound card, you can decide whether or not you want the device's volume to change with different tables. Check the box labeled "Apply the per-table volume level to this device" if you want the volume to vary, or un-check it to use a fixed volume. If you use a fixed volume, the device will still track the global volume setting, but the volume won't change each time you load a table.

In either case, you can set a relative volume for the secondary device via the slider that appears next to the device name in the Audio Outputs list. This lets you adjust the device's audio level relative to the primary audio card.

Custom programs

Starting with version 1.7, PinVol lets you add your own items to the list of programs it recognizes. PinVol saves and restores separate volume levels for custom entries just like it does for the built-in systems.

The UI for adding a new program to the list is a little unfriendly, in that you have to hand-edit the settings file. So start by opening the settings file in Notepad or another plain-text editor. (Make sure that PinVol isn't running while you do this, since you don't want it to write to the file while you're editing it.)

The settings file is called PinVolSettings.ini, and you'll find it in the same folder where you installed the PinVol program file.

To add a new custom program entry, add a line like this at the end of the file:

Program = displayName: "Notepad", exe: "notepad.exe"

As you can see, the line consists of a series of "name: value" pairs, separated by commas. The values should be enclosed in quotes. If you want to use a literal quote character within a value, write it twice: "This is a ""quoted string"" in a value".

Here are the keywords you can use:

  • displayName: Required. This is the name that PinVol will display in the volume popup each time this program comes to the foreground. It's also the "key" used to identify this program in the list of saved volume settings.

    If you use windowTitlePattern to identify the application, you can refer to regular expression groups by using "$n" syntax. $1 refers to the first parenthesized group in the regular expression pattern, $2 refers to the second, and so on up to $9. $& is the whole window title name, and $$ is a literal dollar sign.

  • appType: Optional. An internal identifier for the application type. If you omit this, the display name is used as the appilcation type. If you create multiple entries for the same program, you can use this to tell PinVol that they're all really the same thing, so that PinVol doesn't keep popping up the volume bar every time you switch between instances of the program.

  • exe: Optional. The name of the program executable (.exe file) to match for this program. If this is specified, PinVol will identify this program by matching the foreground process's .exe file name to this string. Upper/lower case differences are ignored, so WORD.EXE matches word.exe. Don't specify any path here; just use the basic filename.

  • windowTitle: Optional. The title of the window to match for this program. If this is specified, PinVol will identify this program by matching the foreground window's title text. Upper/lower case is important here and must match exactly.

  • windowPattern: Optional. A regular expression to match to the window title. If this is specified, PinVol will identify this program by matching the foreground window's title text to this regular expression pattern. C# regular expressions are used here, so you can refer to any Microsoft documentation on C# Regex patterns, such as here.

At least one of exe, windowTitle, or windowPattern must be included in your program specifier, since PinVol needs some way to match the program. If you include more than one of these, all of the items you include will have to match for the program to be recognized.

New in v1.7 (March 2019)

  • You can now add your own custom items to the list of programs that PinVol recognizes. See Custom Programs above for details.

  • Game launches with Visual Pinball from a front end program are a little smoother now. In the past, launching a VP game made the volume display pop up showing "System" while the game was being loading, before switching to the game title once it was running. PinVol now recognizes the VP loading phase and skips that the extra popup. There should now only be one volume popup during the loading process, showing the name of the new game.

  • Joystick buttons should now be properly recognized on devices with non-consecutive button numbering (which is unusual in practice, but is allowed by the USB joystick protocol).

New in v1.6 (February 2019)

  • The program now looks for its saved settings file (PinVolSettings.ini) in its own program folder, rather than in the current working directory. (This doesn't make any difference when launching the program from the Windows desktop, since Windows automatically sets the working directory to the program's own folder for normal launches, but it can affect launches from other programs that might set other working directories before launching sub-programs.)

New in v1.5 (January 2019)

  • The program now recognizes "Demon's Tilt" (a commercial game available on Steam), allowing its custom volume level to be saved.

New in v1.4 (September 2018)

  • Game pad devices are now treated as equivalent to joysticks. (Only joysticks were recognized in the past. Some devices, such as Zeb's plunger kit, identify themselves as game pads instead, so couldn't be used for button input in past versions.)

  • The extra DLLs included in past versions are no longer needed, as they're now bundled into the program .exe file.

New in v1.3 (August 2018)

  • PinVol recognizes PinUP Popper and Pinball FX3 and saves custom volume levels for each. (PinVol can't currently distinguish among different FX3 games, so it saves them all under a single custom volume level. Hopefully the FX3 games all have consistent enough volume levels that this won't be a serious limitation.)

New in v1.2 (July 2018)

  • A new Default Volume control lets you set the initial volume level for new tables that don't already have saved volume settings in the PinVol table list. In earlier versions, new tables just got whatever volume level was already in effect, which was sometimes jarringly loud if you were coming from a quieter table where you had to crank the volume way up.

  • PinVol recognizes the new PinballY launcher as a separate program with its own saved volume level.

  • Launchers like PinballY can now send table titles to PinVol to use in the pop-up volume display. This makes the display a little friendlier by showing the actual title of the table (e.g., "Medieval Madness") rather just than the filename.

  • PinVol's methodology for recognizing which program is in the foreground has been changed slightly to make it a little faster and more reliable.

  • The on-screen display should do a better job of not stealing keyboard focus from other windows when it pops up.

New in v1.1 (May 2017)

  • You can now control the secondary audio devices independently on a table-by-table basis if you wish. To do this, go back to the main window and check the box labeled Enable independent per-table volume for secondary audio devices. You can now click in the "Secondary devices" volume control boxes to assign a separate set of local volume keys for the secondary devices. This makes the secondary audio device work just like the primary device: using the extra keys, you can now set independent levels for the primary and secondary devices for each table. PinVol saves the levels and restores both local levels each time you return to a table.

Installation and setup

Step 1: Download and unpack. Download the Zip file and unpack it into a folder on your hard disk. Almost any folder will do, except don't put it anywhere within the Program Folders tree, because Windows blocks writes to these folders. PinVol needs to write to its home folder because it keeps its settings files there, to keep things simple.

Step 2: Unblock the program file (if necessary). If you have any trouble launching PinVol, right-click the PinVol.exe file and select Properties. Check if there's a message in the dialog saying something like "This program came from the Internet and has been blocked." If so, there should be an "Unblock" button you can click to make the file runnable.

Step 3: Create a Startup shortcut. To take full advantage of PinVol, you'll want to launch it at system startup and leave it running in the background all the time. To set it up to launch when you log in, create a Startup shortcut for it in your Start Menu:

  • If your version of Windows has a Start menu, open it, find "Startup" in the "Programs" submenu, and double-click it.

  • If you have a Windows version without the Start menu, press Windows+R on the keyboard, then type (or copy) this into the box and press return: %AppData%\microsoft\windows\start menu\programs\startup

  • In either case, go to the folder where you installed PinVol. Drag the program icon using the right mouse button (i.e., right-click and drag), and drop it into the Startup folder you just opened. On the context menu that appears after dropping the file, click Create Shortcut Here.

  • If you wish, you can arrange to have PinVol always start up minimized, so that its window is hidden and it only appears as a task bar icon. Right-click the new shortcut in the Startup folder and select Properties. Find "Run: Normal Window", and change it to "Minimized".

Step 4: Select options. To configure settings, simply run the program. The main window shows all of the options. Look over the settings and make any desired changes. If you want to change a key assignment, click the mouse in the box for the key, then press whatever keyboard key or joystick button you want to assign. You can assign keys in combination with modifiers (such as Ctrl+Shift+F10), but you can't use the modifier keys alone, since the Windows hotkey system doesn't allow this. If you don't want to assign any key at all to a function, right-click the box for the key and select "No Key".

Changes to options are applied immediately and saved automatically.

Attention PinballX users

PinballX runs in "full screen" mode by default, which completely takes over the primary monitor. This makes it impossible for PinVol to display its volume level popup screen. Fortunately, PinballX has an option that makes it more cooperative. Fire up the PinballX Settings program and go to the Display Settings screen. Set these options:

  • Window/Full Screen: Windowed

  • Full screen windowed: Yes

Tips and recommendations

Initial table volume setup

PinVol is designed to be automatic enough that you don't really have to drop everything and adjust every table immediately on installation. You can just go on with play as normal and make adjustments as needed. Each time you come to a table you haven't played since installing PinVol, adjust its Table volume to a comfortable level. You should find yourself making these adjustments less often the more you play, since any table you've adjusted already will have its volume restored automatically when you return to it.

For "normal" play, I recommend setting the GLOBAL volume level to about 80% to 85%. This is a good baseline level for normal play because it gives you lots of room to adjust the loud tables downwards, but is a high enough absolute level that you'll be able to make the quieter tables loud enough by turning their Table volumes way up. A baseline in the 80-85% range also leaves you with some headroom in the Global volume to make the machine extra-loud for a party or the like.

Cabinet button setup

The thing most pin cab people do with their volume controls is to hide them: on the bottom of the cabinet, inside the coin door, etc. There's another approach that I like better.

If you're using an i-Pac or a Pinscape controller for button wiring, you can designate one of your regular buttons as a "Shift" button that gives your other buttons a second meaning. That effectively doubles the number of controls you have without adding physical buttons. I think this is especially good for volume controls, because this is a function you want to be able to access easily, but not one suited to visible extra buttons.

Here's the setup I like. Assign the Extra Ball button as the shift button, and use the (shifted) flipper and Magna Save buttons as volume controls. I like using Extra Ball as the shift button because it's so rarely used for its main function. The Shift feature doesn't take away its main function as the Extra Ball button, so you still have that when you need it, but it lets you get more mileage out of a button that you probably rarely use. The Extra Ball button is also a good choice as a Shift button because no one would ever accidentally press it in combination with another button; it's just not used that way in normal play.

I like the right flipper and Magna Save buttons as Local Volume Up/Down, because they're in easy reach and they make a nice up/down pair. I'd recommend mapping them (in their shifted roles, of course) to high-numbered function keys, say F19 and F20, since those are basically never used by any other applications. It's best to pick keys that aren't used for anything else by any other software, because hotkeys are system-wide and thus override any other uses.

After you set up the shifted key assignments in your i-Pac or Pinscape keyboard setup, set the PinVol hotkeys for Local Volume Up/Down to match. Now, whenever you load a table and want to tweak its volume level, hold down Extra Ball and use the right flipper/magna buttons to adjust the volume to your liking.

You can do the same thing with the left flipper/magna buttons for the Global Volume keys. Assign the shifted meaning for these to, say, F17 and F18.

By the way, if you're looking for those high-numbered function keys (F17, F18, ...) in your key encoder setup program and can't find them, it's probably because your key encoder doesn't support those keys at all. The whole reason I recommend them is that applications aren't likely to use them for anything because they're so rarely implemented on real keyboards. But by the same token, key encoders don't tend to support them because they're so rarely used. The Pinscape controller supports them, but I don't think the i-Pac does. An alternative for the i-Pac is to use "macro" keys that combine function keys with modifiers, such as Windows+Control+F10. Complex combinations like that are also unlikely to collide with any application you're likely to use, so they should be safe as hotkeys. Or, if your key encoder can assign joystick buttons, you can go that route, since regular applications won't use any of those.

Major Frenchy