Virtual Audio Cable Repeater Organizer (Vacro) Users Guide
Doug Lee
Last revised October, 2015

The Virtual Audio Cable Repeater Organizer (Vacro) is a utility program designed to simplify the tasks of creating, launching, and generally managing Virtual Audio Cable (VAC) repeaters. Vacro is not part of VAC itself but is intended for use alongside VAC. Vacro's name is pronounced such that it rhymes with "macro."

Vacro is covered by version 3 of the GNU General Public License; see the file copying.txt for further information. The ConfigObj and Validate modules are under separate license and copyright; see those files for details.

Vacro can perform the following tasks:

Table of Contents

Quick Start Guide

Here's how to get up and running quickly with Vacro:

  1. Download and then run the Python installer, 32 or 64 bit for Windows at your choice, from http://www.activestate.com/activepython.
  2. Download the Vacro zip file from http://www.dlee.org/vacro/.
  3. Unpack the Vacro zip somewhere easy to remember and reach.
  4. Run vacro.py to launch it. A console window and Vacro> prompt should appear.
  5. If you know what your default buffer length is that you use for repeaters, you can make it a Vacro default. To make a default of 100 ms for MME and 40 MS for KS repeaters, type these two lines, or paste them, at the Vacro> prompt:
    defaults MME /BufferMs:100
    defaults KS /BufferMs:40
  6. Start managing repeaters. Commands are explained in following sections, but here are some examples beyond the defaults command just mentioned:
    Command Effect
    MME map l1 Copy audio from the Microsoft Sound Mapper to Virtual Audio Cable line 1.
    MME wireless l2 h2 Connect the input device whose name contains "wireless" to Virtual Audio Cable line 2, and save this repeater under the name "h2."
    close wireless Close (unload) the repeater just started above.
    launch h2 Launch the above repeater by its new name.
    stop h2 Stop but do not unload the repeater.
    start h2 Restart the repeater.
    show h2 Display the repeater's window.
    ls List running repeaters.
    close all Close all running repeaters.

Installation

Vacro currently requires Python to be installed. This requirement may go away in future releases. The ActivePython distribution from ActiveState is recommended for ease of setup. The Win32 package is required and is part of that distribution but does not come bundled automatically with other distributions.

To install Vacro once Python is installed, unpack the Zip file into a folder of your choice.

To run Vacro, launch vacro.py. This should bring up a console window and present a "Vacro>" prompt.

Brief Summary of Commands

Vacro provides the following commands, described in subsequent sections.

Category Command Purpose
Creating and destroying repeaters launch Launch new or saved repeaters and save repeaters for future launching.
  MME, KS Shortcuts for launching new MME and KS type repeaters.
  close Close (unload) repeaters.
  delete or del Delete saved repeaters.
  defaults Set up default options for MME and KS repeater types.
Manipulating running repeaters ls List running repeaters.
  start, stop Start or stop loaded repeaters.
  show, hide Show or hide repeater windows.
Program control and documentation quit, exit, EOF Exit the program.
  help or ? Get a command list or help on a specific command.
  clear or cls Clear the screen.
  errTrace Print a brief trace of the last program error.

Getting Command Help

All commands include built-in documentation accessible by typing help followed by the command of interest. Simply typing help by itself will present a list of available commands.

Manipulating Running Repeaters

Vacro can manipulate any loaded repeater, regardless of how it was started (i.e., regardless of whether Vacro started it). Once Vacro is running, typing ls will list any currently loaded repeaters and indicate the status of each (Stopped or Running).

The following commands can be used against any loaded repeaters by providing part of the text from the repeater's listing after the command, or by typing the command with nothing after it and selecting repeaters from a numbered list:

Stop
Stop the repeater, leaving it loaded but inactive. Its status will change to Stopped.
Start
Start the repeater if it is not running already. Its status will change to Running.
Show
Show the repeater's window.
Hide
Hide the repeater's window (minimize it to the system tray).
Close
Close the repeater. It will be terminated and will stop appearing in the list of loaded repeaters.

If no text is provided after one of the above commands, or if the provided text matches more than one repeater, a list of available repeaters will appear, in which each repeater is shown with a number. Press Enter to abort the command without affecting any repeaters, or select one or more repeaters by number. The following methods of selecting repeaters from this numbered list are supported, shown here by example as if a list containing 9 repeaters has appeared:

2
Select the second repeater from the list.
2,5, 2, 5, or just 2 5
Select repeaters 2 and 5 from the list.
2-5 or 2..5
Select repeaters 2, 3, 4, and 5.
1 3..5, 7-9
Select repeaters 1, 3, 4, 5, 7, 8, and 9. (Of course most people will choose between space and comma and between dash and dots rather than mixing them all in one selection.)
When multiple repeaters are selected in this way, they are acted upon in numeric order regardless of the order in which they are specified; so, for example, selecting "5 2 9" will act on repeater 2, then 5, then 9. Any repeated indices or range overlaps are filtered out, so no repeater will be acted upon twice.

Creating New Repeaters

The launch command can be used to launch a new or saved repeater and can also save the repeater for easier future launching.

For a new repeater, the first parameter after launch is the repeater type, either MME for a Windows Multimedia repeater, or KS for a Kernel Streaming repeater. A simpler way to launch a new repeater is simply to type MME or KS as a command. The following discussion applies to either method.

If no further arguments appear after MME or KS, Vacro will launch a new repeater of the requested type and will leave it in focus on screen for manual configuration. As many repeaters of either type as needed can be opened in this manner without having to use the "Open in New Window" feature of Windows to keep from simply refocusing an existing repeater.

If a single argument appears after MME or KS, it is used as the name (window title) to apply to the new repeater. In this case, Vacro will open the new repeater and leave it on screen but will change its window title to the argument specified:

MME Test1
will open a repeater and name it Test1.
MME "My Repeater"
will open a repeater and name it My Repeater (the quotes are necessary because the name contains a space).

If two or three arguments appear after MME or KS, the first indicates the source (Wave in) device, the second indicates the destination (Wave out) device, and if provided, the third specifies the name of the new repeater and causes the repeater to be saved for future reference by that name. Device specifications are discussed in more detail in the next section, but they can be a short name for a VAC device, the word mapper for the Microsoft Sound Mapper (MME repeaters only), or a partial or full device name. In the latter case, Vacro will match the text against the available options for the device (based on repeater type and whether this is the source or destination). If there is a single match, that device is used. If there are multiple matches, Vacro presents a numbered list of matches and allows one to be chosen by number.

When source and destination devices are indicated as part of a launch command, the new repeater is automatically minimized to the system tray on creation, and focus stays in Vacro itself.

In addition to these arguments, configuration options for the new repeater can be included. These begin with a slash (/) as on actual repeater command lines and are thus distinguishable from the window and device names just discussed. The order and position of these options does not matter. The following commands are all equivalent:

MME l1 l2 /BufferMs:50 /Buffers:6
MME /BufferMs:50 /Buffers:6 l1 l2
MME l1 /BufferMs:50 /Buffers:6 l2
Commonly used options can be set up as defaults for all new repeaters as well; see the Repeater Options and Defaults section, which also lists the available options.

Using Saved Repeaters

As mentioned above, adding a name when specifying input and output devices on a new repeater will save that repeater under the given name for future launching. To launch such a repeater, specify its name in place of MME or KS on the launch command line. Options beginning with a slash (/) may follow the name and will be applied without saving. Any number of repeaters may be launched at once in this fashion:

launch r1 r2 /BufferMs:100 r3 /Buffers:6
launches repeaters called r1, r2, and r3, with special temporary options for r2 and r3.

A launch command with no arguments will display a list of all saved repeaters for selection. As usual with selection lists, any number of repeaters can be selected at once.

To delete one or more saved repeaters, type delete (or just del) with no arguments to select from a list, or with one or more repeater names to delete specific repeaters immediately. Names must match exactly.

Device and Repeater Specifications

Vacro allows partial matching for device and repeater names to minimize typing and also includes very abbreviated names for some standard devices.

A description of the shortened device name system by example follows. Where the number 1 appears below, any VAC device number can be used; for example, l6 refers to VAC line 6.

Short Name MME Repeaters KS Repeaters
L1 Line 1 (Virtual Audio Cable) Virtual Cable 1
M1 Mic 1 (Virtual Audio Cable) Virtual Cable 1
S1 S/PDIF 1 (Virtual Audio Cable) Virtual Cable 1
V1 (not applicable) Virtual Cable 1
Mapper Microsoft Sound Mapper (not applicable)

A device specification not matching one of the above names exactly (except that letter casing doesn't matter) will be matched against the available device names for that device. If there is exactly one match, that device is used. If there are more matches, a list will appear allowing selection of a device by number.

Repeaters can also be matched by partial name but can also be matched by referring to the repeater's status or type, again by partial or whole text. For example, if only one KS repeater is running, "close ks" should close it.

Repeater Options and Defaults

Vacro supports exactly the same repeater command-line options supported by the repeaters themselves, though a few should not be used through Vacro (see below). Defaults for each repeater type can be established via the defaults command, or by placing in a file called vacro.ini sections for each type. Example usage of the defaults command:

defaults
Show the defaults for both repeater types without making changes.
defaults KS
Show the defaults for KS repeaters without making changes.
defaults MME -
Clear the defaults for MME repeaters.
defaults MME /BufferMs:50
Change the buffer length for MME repeaters.
defaults MME /Buffers:6 -/BufferMs
Change buffer count and remove the buffer length default.
An example of settings defaults directly in the ini file (the above commands have the same effect):
[DefaultMMEOptions]
BufferMs=50
Buffers=6
[DefaultKSOptions]
BufferMs=20

The following options are supported:

Option Default/Sample Value Meaning
SamplingRate 48000 Sampling rate.
BitsPerSample 16 Bits per sample.
Channels 2 Number of channels.
ChanCfg   Channel configuration (MME repeaters).
ChanCfgIn   Input channel configuration (KS repeaters)
ChanCfgOut   Output channel configuration (KS repeaters)
BufferMs 500 Total buffering length in milliseconds.
Buffers 12 Number of buffers (parts of buffering space).
Priority Normal Process priority.

Note that the following repeater options should not be used through Vacro because Vacro uses these internally or implements their functionality by other means:

Known Issues

The following issues remain to be addressed as time permits: