Audio Director Manager (Audir) 3.0 Users Guide
Doug Lee
Last Revised June, 2023

The Audio Director Manager (Audir, pronounced similarly to "odder") is a utility program designed to simplify the tasks of creating, launching, and generally managing programs that direct (or repeat) audio among devices and files. At this writing, this utility will be most useful to those who also use Virtual Audio Cable (VAC), though it can also manage Sound eXchange (SoX) processes for repeating audio among devices and cables and recording and playing audio files. Support for further audio handlers may be added in the future.

Note that Audir is not itself an audio repeater or director; it simply manages programs that do this. As such, Audir is not part of, or directly associated with, either VAC or SoX; but it requires one or the other or both in order to be useful. As of October, 2019, a Windows binary version of SoX is bundled with Audir for convenience.

Audir can perform the following tasks:

Audir also provides a few convenient shortcuts for more complex SoX effects chains that may be commonly used.

Licenses

Table of Contents

Quick Start Guide

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

  1. Download the Audir zip file. This includes a Windows executable, Python 3.7 source code, and support files required when running Audir.
  2. Unpack the zip file into a folder of your choice from which to run the program.
  3. If you plan to use the Windows executable and want easier access, use Windows Explorer to drop a shortcut for audir.exe onto your Desktop or into a preferred location. Audir can be run from source under Python 3.7, but setup for this scenario is not covered in this document and includes installation of Python 3.7 on Windows.
  4. Make sure the audio handlers you plan to use are installed and working properly. Setup and usage of audio handlers (e.g., VAC and SoX) is beyond the scope of this Guide, though examples will abound that demonstrate usage of the supported handlers with Audir. Audio handlers supported by Audir at this writing:
    Audio handlers supported by Audir
    Audio Handler License Information Supported/Tested Versions URL
    Virtual Audio Cable (VAC) Commercial, $25.00 or so 4.14, 4.15, and various 4.6x http://software.muzychenko.net/eng/vac.htm
    Sound eXchange (SoX) Free, GNU license version 2 14.4.1 and 14.4.2 Windows builds http://sox.sourceforge.net/
    Note that, as of October, 2019, a Windows binary version of SoX is bundled with Audir for convenience. The bundled version is 14.4.1 because this author finds that version the fastest under Windows. If you have a SoX version installed in a normal location (under one of Window's Program Files folders), Audir will use it instead of the built-in version by default. You can force Audir to use a specific version of SoX if necessary. To do this, add a line specifying the folder path to %APPDATA%\Audir\audir.ini such as this in the Global section:
    SoXPath=c:\audir\sox_win
    Note that only the folder path is specified, not the actual sox.exe file name.
  5. To launch Audir, run audir.exe if you are using the stand-alone executable, or launch audir.py if running from source. A console window and Audir> prompt should appear.
  6. If you find you have buffer lengths (or other parameters) that remain constant for particular repeater types, you can make Audir defaults for them. The following examples work well on this author's laptop as of this writing:
    defaults MME /BufferMs:100
    defaults KS /BufferMs:40
    defaults SoX --input-buffer 32 --buffer 2048
    Defaults can be overridden for a particular repeater. For example, SoX may require a larger effects buffer for the pitch effect than for more commonly used effects:
    sox l2 l4 --buffer 16384 pitch 400
    (Note that the default --input-buffer 32 will still be applied here.)
  7. Start managing repeaters. Commands are explained in following sections, but here are some examples beyond the defaults command just mentioned:
    Example Audir commands
    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.
    sox --buffer 2048 l4 map highpass 150 treble -10 :l4at Start a SoX instance that repeats VAC line 4 to the default output device with bass and treble attenuation. Save this under the name "l4at."
    ls List running repeaters.
    ls -t l1 List repeaters whose destination device is VAC line 1.
    edit (or just ed) Open a Notepad window containing all loaded repeaters for live editing. See the Editing Repeaters section for details.
    close all Close all running repeaters.

Brief Summary of Commands

Audir provides the following commands, described in subsequent sections. Note that the term "repeater" here is used to apply to any process managed by Audir. This includes MME and KS VAC repeaters as well as SoX processes started by Audir. SoX "repeaters" are usually used just like VAC repeaters but can also transfer audio between devices and files rather than just between devices.

Brief summary of Audir commands
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 VAC repeaters.
  SoX Shortcut for launching new SoX processes for audio transfer among devices and files, possibly with effects such as compression, filtering, equalizers, etc.
  close Close (unload) repeaters.
  delete or del Delete saved repeaters.
  defaults Set up default options for MME, KS, and SoX repeater types.
Manipulating running repeaters ls List running repeaters.
  start, stop Start or stop loaded repeaters (not supported by SoX).
  show, hide Show or hide repeater windows (not supported by SoX).
  info Show information about specific loaded repeaters.
  edit (or just ed) Open a Notepad window containing all loaded repeaters for live editing. See the Editing Repeaters section for details.
Program control and documentation quit, exit, EOF Exit the program.
  help or ? Get a command list or help on a specific command.
  rel Print information on available, not installed releases of this application.
  clear or cls Clear the screen.
  errTrace Print a brief trace of the last program error.
  about Print information about the application that also prints on application launch.
  alias Create a command alias to simplify common operations.

General Command Information

All commands include built-in documentation accessible by typing help followed by the command of interest. A question mark (?) can be used in place of help, in which case the space between it and the command of interest is not required. Simply typing help or ? by itself will present a list of available commands.

The command help selection (or ?selection) will print helpful information on how to select items, such as repeaters, from a numbered list. This application supports a powerful syntax for acting on multiple items at once with a single command in some cases.

Letter casing in commands is not significant; e.g., "MME h1 /BufferMs:50" and "mme h1 /bufferms:50" are identical. Names of saved repeaters (like h1 here), however, must match exactly, including case. In this guide, command elements are usually cased based on their common appearance in Virtual Audio Cable and SoX documentation.

Manipulating Running Repeaters

Audir can manipulate any loaded VAC repeater, regardless of how it was started (i.e., regardless of whether Audir started it). (SoX processes are only managed by Audir if Audir started them.)

Once Audir is running, typing ls will list any currently loaded repeaters and indicate the status of each (e.g., Stopped or Running). The resulting list can be filtered by any combination of the following additional command-line arguments:

-f dev
Limit the listed repeaters to those whose source (from) device is dev. For example, ls -f l3 will only show repeaters that are obtaining sound from VAC line 3.
-t dev
Limit the listed repeaters to those whose destination (to) device is dev. For example, ls -t l1 will only show repeaters that are sending sound to VAC line 1.
filter
Show only repeaters whose descriptions contain the given filter string. Case is not significant here. ls stopped will list only stopped repeaters, for example. ls MME will list only MME-type repeaters. (If a repeater's name contains a filter string, it will also be included though.)

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. See also the Editing Repeaters section for a very powerful way to stop, restart, modify, close, and in some cases start new repeaters from a full text window.

Stop
Stop the repeater if it is running, leaving it loaded but inactive. Its status will change to Stopped. SoX repeaters do not support this command.
Start
Start the repeater if it is stopped. Its status will change to Running. SoX repeaters do not support this command.
Show
Show the repeater's window (not for SoX processes).
Hide
Hide the repeater's window (minimize it to the system tray). SoX processes have no windows and are thus always hidden, nor do they appear in the system tray. Use the ls command to find these.
Info
Show information about the repeater.
Close
Close the repeater. It will be terminated and will stop appearing in the list of loaded repeaters. For repeaters with windows and/or system tray icons, these should go away also.

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. Most users will just enter a single number and press Enter to select one repeater, but requesting action on several repeaters at once is also supported.

If more than one repeater name (or partial name) appear after one of these commands, each is matched against the list of running repeaters, and each will produce a selection list if it matches more than one repeater. This syntax allows multiple repeaters to be affected at once without necessarily having to handle a selection list; e.g., close r1 r5 r7 to close three named repeaters at once. This example mirrors the command launch r1 r5 r7 for launching multiple repeaters at once.

The following methods of selecting repeaters from a 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.)
!4 5
Select all repeaters except 4 and 5. A leading exclamation point negates the list after it.
all
Select all repeaters.
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 VAC Repeaters

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

For a new VAC 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, Audir 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, Audir will open the new repeater and leave it on screen but will change its window title to the argument specified, plus the repeater type:

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

If more arguments appear after MME or KS, they may consist of source and destination devices (required), repeater options starting with a slash (/), and/or a name under which to save this repeater for future reference prefixed with a colon (:).

The first two arguments that do not begin with a slash are taken to be the input and output devices for the repeater. Device specifications are discussed in more detail in the Device and Repeater Specifications section, but they can be a short name for a VAC device, the word mapper (map is usually enough) for the Microsoft Sound Mapper (MME repeaters only), or a partial or full device name. In the latter case, Audir 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, Audir 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 Audir itself.

Except for the order of input and output devices, the order of arguments when launching an MME or KS repeater 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 VAC Repeater Options and Defaults section, which also lists the available options.

Creating New SoX Processes

Just as for VAC repeaters, the launch command can be used to launch a new or saved SoX repeater and can also save the repeater for easier future launching. To launch a SoX repeater, start the command with launch SoX or just SoX (case does not matter).

At least two arguments must appear after SoX: The first indicates the source for the audio transfer, and the second indicates the destination. There may be arguments after the device indications, which are treated as SoX options and effects and their arguments. In complex cases, the specific positions of device names among SoX options and effects can be indicated with "waveIn" and "waveOut" (case-insensitive) keywords; though this is rarely necessary. See examples below.

Source and destination specifications may be device names or shortcuts as for VAC repeaters but may also be file names or paths. See the Device and Repeater Specifications section for details on specifying devices. Using a device for source and a file for destination effectively creates a sound recorder that runs until stopped. Using a file for the source and a device for the destination creates a player that runs until stopped by the user or until the audio in the source file is exhausted. (It is technically possible to use a file for both source and destination, but there is probably no reason to do this from inside Audir rather than using SoX directly.)

Warning: When using Audir and SoX to record or play files, it is currently necessary to specify a full file path. When doing this, do one of the following to avoid interpretation errors:

For example, to play the file my_song.wav in folder c:\music, do not type this:
sox c:\music\my_song.wav map
but use one of these instead:
sox c:\\music\\my_song.wav map
sox c:/music/my_song.wav map
sox 'c:\music\my_song.wav' map
sox "c:\music\my_song.wav" map
Attempting to use single backslashes without quoting can cause files to be referenced or created in unexpected places or to go nowhere; for example, the path c:\downloads\test.wav may become c:downloadstest.wav.

As with VAC repeaters, it is also possible to save a SoX specification for easy reuse. Do this by including among arguments, usually as the final argument, the desired name preceded by a colon; e.g.,

SoX l2 map highpass 100 treble -10 :l2at

Examples of permitted SoX launch commands:

sox l2 map highpass 100 treble -10 :l2at
sox l2 map --buffer 2048 highpass 100 treble -10 :l2at
sox l2 c:/sounds/output.wav --buffer 2048 highpass 100 treble -10
sox l2 c:/sounds/output.wav --buffer 2048 waveIn -g waveOut rate 16000
sox http://www.streamOfMyFaves.com/128k/listen.ogg map -t ogg waveIn waveOut vol 0.5 :radio1
The penultimate example above requires the waveIn and waveOut markers because of the intervening -g option, which sets up GSM encoding for the output wave file. The final example above creates a "radio1" configuration so that subsequently typing "launch radio1" will start playing a radio station at half volume through the default output sound device. The waveIn and waveOut markers are required in this case in order to allow the Ogg type to be included. (streamOfMyFaves.com is a fictitious Internet address and does not exist at this writing.)

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 a repeater type (MME, KS, or SoX) on the launch command line. For KS and MME repeaters, 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. Due to the richness and complexity of the SoX command-line syntax, temporary options/effects are not supported for SoX repeaters.

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 choose from all saved repeaters, or with one or more arguments to narrow down the selection list before it is presented. Arguments can be a simple string like "h1" to include all repeaters whose names, ignoring case, contain "h1"; or "r:" followed by a regular expression, again case ignored, to include all repeaters whose names match the expression. Examples of this type of argument include "r:^h" to include all repeaters whose names start with "h" or "H", and "r:h$" for all repeaters whose names end with "h" or "H."

Device and Repeater Specifications

Audir 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.

Shortened device names and their translations
Short Name MME and SoX 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 (map is usually enough) 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 the appropriate device type (input or output). 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.

VAC Repeater Options and Defaults

Audir supports exactly the same repeater command-line options supported by the repeaters themselves, though a few should not be used through Audir (see below). Defaults for each repeater type can be established via the defaults command. Examples:

defaults
Show the defaults for all 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.

The following VAC repeater options are supported (list obtained from VAC 4.14 and 4.15 documentation):

VAC repeater options and their meanings
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.
OutputPreFill 50 Percent of output queue to pre-fill before starting output (KS repeaters starting in VAC 4.15).
ContQueueIn, ContQueueOut No value Use continuous queue mode with input or output pin (legacy only) (KS repeaters starting in VAC 4.15).

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

SoX Repeater Options and Defaults

At this writing, SoX supports approximately 64 effects that can be applied to audio as it passes between devices and files. Effects can be combined in an "effects chain" or, in complex cases, multiple effects chains that run sequentially. A full discussion of SoX effects and chains is beyond the scope of this Guide, but some example effect chains follow. The SoX documentation contains many more examples.

Example SoX effects
Effects Description
vol 0.5 Cut the output volume in half.
highpass 100 Apply a highpass filter.
bass -15 treble -15 Reduce low and high frequency sound.
compand 0.3,1 6:-70,-60,-20 -5 -90 0.2 Compress the dynamic range such as for listening in a car (from SoX man page). SoX also includes an mcompand effect for more complex needs; see the example below this table.
equalizer 60 .001h -180 equalizer 120 .001h -180 Remove fundamental and first harmonic of a 60 Hz hum with minimal disturbance to the remaining signal.
echo 1 1 500 .5 1000 .25 Add two echos at 0.5 seconds and 1 second delay from original audio, at decreasing volumes.
loudness A human-ear loudness curve as provided by buttons on many stereo systems.
oops An "out of phase stereo" effect that results in only the differences between the stereo channels being audible.
reverb 100 0 100 100 A reverb effect that simulates a very large space.
pitch -200 Lower the pitch of the audio by 200 cents (a full musical step).
remix 1 1 Only pass through the left channel, but into both channels of the result.
riaa Apply the standard RIAA vinyl playback equalization curve.

For a final and very complex example (taken from the SoX man page), the following command, if given on one line as Audir input (and with a sufficiently old SoX version that supports the filter effect), will create a SoX repeater that takes sound from VAC line 1 and sends it to VAC line 2 after applying an effect chain that compresses the audio in a manner commonly done for US FM radio broadcasting (including 75us pre-emphasis):

sox l1 l2 gain -3 filter 8000- 29 100 mcompand "0.005,0.1 -47,-40,-34,-34,-17,-33" 100 "0.003,0.05 -47,-40,-34,-34,-17,-33" 400 "0.000625,0.0125 -47,-40,-34,-34,-15,-33" 1600 "0.0001,0.025 -47,-40,-34,-34,-31,-31,-0,-30" 6400 "0,0.025 -38,-31,-28,-28,-0,-25" gain 15 highpass 22 highpass 22 filter -n 255 -b 16 -17500 gain 9 :broadcast12
For an actual simulation of FM radio sound, as opposed to the broadcast signal condition just given, add "lowpass -1 17801" just before the ":broadcast12" above. (Sadly, the filter effect used in the above example has since been removed from SoX in favor of the newer sinc effect. At this writing, the exact way to replicate the original effects using sinc is not clear.)

Note that the following SoX options and effects should not be used with Audir:

Additionally, these should not be used when the source is a device rather than a file because these require a full scan of the source audio stream, which is not possible with a source that is a device:

Note that although piping options are not supported, pipes created by using "|sox ..." in place of device names are allowed. This is very advanced and probably rare usage, however. The following example uses a second SoX process to generate a ringtone-like sound which is then trimmed to one second duration and volume-reduced (to avoid clipping) by the main SoX process:

sox "|sox -n -p synth 0.075 trap A4 : synth 0.075 trap F4 : restart" -d trim 0 0:1 vol 0.5
In that example, the "|sox ..." sequence is used as the source endpoint, and -d makes sound go to the default output device.

SoX supports a SOXOPTS environment variable that can include default options to apply to all SoX invocations. While use of this approach is not required for Audir SoX processes since Audir includes a system for managing defaults, any options found in a SOXOPTS environment variable will be honored by SoX processes that Audir launches.

SoX Effect Shortcuts and the sfx command

Audir defines a number of SoX effect shortcuts. The syntax of these shortcuts is deliberately unlike that of native SoX effects, to make it easier to distinguish between the two. Each shortcut, when typed as part of a SoX repeater specification, is expanded into the native SoX equivalent. This may be one effect or a whole sequence of effects.

Warning: These shortcuts and their expansions may change without notice and should be considered experimental. When a repeater is saved, these shortcuts are expanded before saving though; so any changes in expansions will not alter or break saved repeaters.

To see exactly what a shortcut will do, in terms of actual SoX effects, use the sfx command. For example,

sfx comp35
will print the SoX effects that would be used in place of that shortcut:
compand .01,.01 -35,-20,0,-10
Some shortcut translations are admittedly quite complex. The following convoluted sequence is generated by the shortcut nv45@600/800 as of this writing (December 4, 2022):
vol .01 equalizer 600 800h 55 compand .0001,.05 6:-45.0001,-45,-inf,0,-inf 0 0 .0015 silence 1 0 .001% -1 0 .001% -1 .022 .001% equalizer 600 800h -55 vol 100
The nr effect will also produce a "profile effects" line; this will be explained in the "NR For Noise Reduction section.

The defined Audir SoX effect shortcuts are described in the following subsections.

H and L, For High-Pass and Low-Pass Filters

Syntax
h<f> or l<f>
Examples

Shortcuts for specifying high-pass and low-pass filters. These are mostly to simplify direct typing of effect chains. Decimal frequencies are permitted though they may not be very useful.

Comp, For Compressing Audio

Syntax
comp<dB>[s]
Examples

A very reactive compression of dynamic range. Higher values of <dB> produce more compression. If the optional trailing s is present, each stereo channel is compressed independently, so that a loud sound in one channel will not reduce the volume of the other.

Eqs, For Removing Harmonics With Equalizers

Syntax
eqs<f1>[-<f2>][/<width>]
Examples

Removes the fundamental and indicated harmonics of a tone, usually a hum, from the signal. The starting and ending frequencies may be integers or floating-point numbers. If the ending frequency is omitted, the effect produces just one band removal. Equalizers are generated for each integer multiple of the start frequency that is less than or equal to the ending frequency. If a width is given, it is used; otherwise, a width per band of 0.0001h is used.

Note that widths can be given in any units accepted by SoX. At this writing, these are h (Hz), k (kHz), o (octaves), and q. Of these, the last two are scaled around each band whereas the first two maintain constant width in Hz. The effect is that removed bands for higher multiples of the base frequency become increasingly wider for q and o but not for h and k. In practice, this author finds such width increases produce more undesirable signal loss; but the trade-off may be of benefit for certain cases, such as when processing a recording in which the entire signal's speed fluctuates slightly but continuously. A tape recording made on a machine with significant flutter, and a VoIP conversation recording that contains a hum but that was carried over a poor Internet connection that caused compensatory speed fluctuations in the audio, are two examples that might benefit from scaled band size.

fmr and fms, For Simulating FM Radio Sound and FM Broadcast Signal Condition

Syntax
fmr or fms
Examples

Simulates FM radio sound or FM broadcast signal condition, with standard US-style 75us pre-emphasis. Unfortunately at this writing, these effects are imperfect because they necessarily include guessed replacements for two filter effects that SoX no longer supports.

Sil, For Removing Silence and Quiet Audio

Syntax
sil<percent>
Examples

Removes (trims out) silence. <percent> is the percentage of the signal (by amplitude) to remove. As a special historical case, a value with a leading 0 is treated as a decimal value; thus, sil01 is the same as sil0.1. Reliance on this historical behavior is not recommended.

NV and OV For Gating Out High or Low Level Audio

Syntax
nv<dB>[@<center>[/<width>]] ov<dB>[@<center>[/<width>]]
Examples

Noise gating: nv to remove high-level sounds and ov to remove low-level sounds. Historically, nv and ov stood for "no vocals" and "only vocals," respectively. This author used nv to test individual vocal tracks, before mixing, for stray background sounds. The nv and ov effects are meant to be the inverses of one another.

<dB> indicates the decibel level above which for nv, or below which for ov, to remove signal. If specified, <center> indicates a central frequency that is first boosted and then removed again after gating. This facilitates removing or exclusively preserving vocals, for example. The default width of the boosted frequency range is 400 Hz, but <width> can also be given to change this.

The following caveats apply to the nv and ov effects:

NR For Noise Reduction (not in real time)

Syntax
nr<start>,<length>[<factor>]
Examples

Noise reduction via temporary inline noise profile. Samples length of the input starting at start to create a noise profile, then pipes the profile into SoX and uses factor to determine how much noise to remove. If factor is less than 1, it is simply used on the resulting noisered effect. If factor is 1 or omitted, the noisered factor will be 0.0. If factor is greater then 1, the noisered factor is 0.0 and a vol <factor> effect is prepended to the noisered effect.

Note that this effect will not work well (if at all) in a streamed-input situation because of the need to sample input in a separate process before starting to copy input to output. Even if this problem is one day fixed in Audir, use of this effect in real time would require human prediction of when a good noise sample would occur in real time. The recommended alternative for a real-time stream is to craft in advance a suitable noise profile file and then use it via the native SoX noisered effect for the stream.

The sfx command for examining shortcut translations will also show the SoX effects that would be used to create the noise profile for this effect:

Audir> sfx nr3:0,0:2,1.1
vol 1.1 noisered - 0.0
Profile effects: trim 3:0 0:2 noiseprof -
The first line of output is the effect chain generated for the repeater itself. vol 1.1 comes from the ":1.1" part of the nr effect. The second line indicates the SoX effect chain that would generate the profile - two seconds taken from the three-minute mark in the input. The final dash indicates that this effect chain is intended to pipe into the main SoX invocation.

DTMF For Generating Telephone Keypad Tones

Syntax
dtmf<string>[/[<duration>][/[<delay>][/[<fade>][/[<end>]]]]]
Examples

DTMF or touch-tone dialing sound generation. For each character in <string>, produces the corresponding set of two tones comprising the telephone keypad sound for that button. Valid characters are the numbers 0 through 9, * and # for the keys to the left and right of 0 on a standard telephone keypad, and A through D (in upper or lower case) for the column of buttons to the right of the normal keys on some keypads. The optional parameters after this string will be explained shortly but are not likely to be needed in most circumstances.

Note that since this effect generates its own sound, it is generally useful only when the input source is -n. An example Audir command: sox -n l1 dtmf438# would send to Virtual Audio Cable line 1 the sounds representing the telephone keypad keys "4 3 8 Pound."

A particularly handy Audir trick for use with the dtmf effect is to create an alias that automatically sends the sounds to the correct device:

alias dtmf sox -n l1 dtmf%1
will define an Audir command alias so that the following simpler command will send the codes for "4 3 8 Pound" to Virtual Audio Cable line 1:
dtmf 438#
Notice though that whereas there is no space in the SoX dtmf effect between dtmf and the digits to dial, there must be a space between an alias and the argument passed to that alias.

This effect supports up to four additional parameters, separated from the dialing string and from each other by slashes (/). If you wish to skip a parameter and specify a later one, include the slash for the skipped parameter. The parameters, in order, are as follows, with the defaults indicated:

  1. duration: The duration of each tone in milliseconds, default 200 ms.
  2. delay: The delay in milliseconds between tones, default 100 ms.
  3. fade: The length in milliseconds of the fade applied to both the beginning and end of each tone, to avoid clicks in the output. The default is 20 ms.
  4. end: The length in milliseconds of the final delay, after all tones have played, before the effect is fully completed. The default is one second (1000 ms). This delay is sometimes required in order to prevent SoX from exiting too quickly and producing the error message "ValueError: SoX process run failure" even when the effect otherwise succeeded. Typically, this is only a problem for very short DTMF strings. A specification like dtmf7035551212#///0 prevents this final delay from occurring at all.

Command Aliases

The alias command is useful for creating simplifications of common commands. For example, to load a series of repeaters that you have saved under various names, you could make an init alias to load them:

alias init launch mic1 36 46 6real
(In this author's notation, these repeater names mean "mic to line 1, VAC line 3 to line 6, line 4 to line 6, and line 6 to Realtek sound device.") Thereafter, simply typing "init" will launch all listed repeaters. Creating an automatic repeater launch shortcut then becomes a matter of placing an "audir init" shortcut in the Windows Startup folder. Changing the list of repeaters is as simple as entering a replacement for the alias.

Simple aliases just consist of material to replace the alias on the command line; for example, the command "alias c clear" will make the command c clear the screen. "alias lsox ls sox" will make lsox a shortcut for the command "ls sox" for listing running SoX repeaters.

More complicated aliases are also supported: Aliases can accept parameters and use them as appropriate. An example already given is the alias in the DTMF effect section:

alias dtmf sox -n l1 dtmf%1
In that alias definition, %1 represents the first item typed by the Audir user after the dtmf alias; thus, for the command line "dtmf 438#," %1 will become 438# when the alias expands. This will make the user command result in the actual Audir command "sox -n l1 dtmf438#."

Editing Repeaters

Audir includes a very powerful feature that allows a whole set of repeaters to be managed live from a text window. From this window, repeaters can be reviewed, modified, quickly closed and reopened, and (for MME and KS repeaters) stopped and started with realtime results.

To invoke this feature, type edit, or just ed, from an Audir command prompt. A Notepad window will open containing a list of all loaded repeaters (running and stopped), along with a short block of instructions above the list. The Audir command window will be suspended until this Notepad instance is closed, though information will appear in the Audir window each time the Notepad window is updated and saved.

In the Notepad window, each loaded repeater is represented by a line much like the one typed initially to create it. There are two departures from the Audir command-line syntax, however: If the repeater has a name, the name will appear at the start of the line and will be followed with a colon (:), rather than appearing at the end of the line and prefixed with a colon (this makes identifying named repeaters easier). A stopped repeater will be prefixed with an exclamation mark (!). This allows quick toggling on/offof repeaters that support the stop and start commands.

The following operations are now possible. Save the file, such as by typing Ctrl+S, at any time to apply the changes to the set of loaded repeaters.

A new repeater may also be created by adding a line for it. The following warnings apply, however:

For these reasons, it is usually best to create all new repeaters from within Audir itself, then edit them as necessary in Notepad via the edit command. Alternatively, create the new repeater in Notepad but then immediately close the Notepad window after saving it, reopening with a new edit command if desired in order to obtain the actual command line for the repeater.

Example uses of the edit command:

It is possible to use an editor other than Notepad. To do this, add a line specifying the editor to %APPDATA%\Audir\audir.ini such as this in the Global section:

editor=wordpad
A .exe extension will be added if no extension is given.

Miscellaneous Hints and Tips

The following tips and hints are derived from this author's personal experience. Your mileage may vary.

Starting in VAC version 4.15 (released in December, 2015), typing Ctrl+C while in a "Wave in" or "Wave out" box of an MME or KS repeater window will copy the selected device name to the clipboard. This may facilitate creation of Audir repeater configurations for saving and reuse.

Optimal default buffer sizes for Virtual Audio Cable and/or SoX may change on an update. This author found, for example, that a SoX default of --buffer 1024 was sufficient for SoX 14.4.1 but that a buffer size of 2048 or 4096 was required for SoX 14.4.2 to avoid lost sound. Default buffer sizes will also vary of course based on other factors such as system load and other running applications.

Interesting uses of SoX repeaters:

When using the SoX pitch effect, a buffer of at least 8192 may be required. The same goes for the noisered effect, which can crash with an insufficient buffer size.. The pitch effect's buffer size requirements seem more intensive for lowering than for raising pitch.

In the unlikely event it becomes desirable to reload a repeater without changing it while in an edit command's Notepad window, simply add or remove an extra space from between items on the repeater's line, then save the file.

If you need an Audir prompt while an edit window is active, just launch a second Audir instance. (Just be careful not to start a second simultaneous edit session - it should work, but it could sure cause confusion).

Known Issues

The following issues may be addressed as time permits:

Revision History

This section lists changes among Audir releases, most recent first.

Revision 471, June 24, 2023

The subfolder in this distribution that contains a Windows SoX implementation is changed from sox to sox_win. Anyone who placed a SoXPath entry in the [Global] section of audir.ini and who used that setting to load this SoX implementation explicitly will need to update that path accordingly. Example:

[Global]
SoXPath=c:\audir\sox_win
Anyone installing this Audir revision over a previous one may safely remove the sox subfolder and its contents.

Anyone (this author included) who has had difficulty in recent months loading SoX repeaters from Audir for specific sound devices should try again, as the trouble seems to have cleared up. The cause of both the problems and the resolution are not known, but suspects include Windows updates, device driver updates, and unrealized side effects of other Audir changes. This author's difficulties were specifically with an Andrea PureAudio USB device.

There is a new rel command for printing the release notes for all updates that have not already been installed. The material printed by this command comes directly from the Revision History section of this document's online version. The formatting may be less visually appealing than in a web browser however, due to limitations of Windows console output. For those who like to live on the edge, rel -b will check for and print release notes for beta revisions instead of releases.

The delete command is changed to ease deletion of repeaters whose names match a search:

There are three adjustments to the eqs effect:

The nv and sil effects use 0 for time threshholds instead of positive small values as before.

The dtmf effect supports four new optional parameters. These allow changes to the duration of tones, the duration of silence between them, the fade at the beginning and end of each tone, and the delay after all tones have played before the effect completes.

Some output and help should be better formatted.

Revision 421, April 11, 2022

Revision 408, September 16, 2021

Revision 362, November 18, 2020

Revision 347, October 09, 2020

Revision 344, October 04, 2020

Revision 3.0.0.320, released May 12, 2020

This is the first released Audir version that runs under Python 3.7 rather than 2.7. Anyone running Audir from source must now use Python 3.7.

Other changes:

Revision 184, posted March 7, 2016

Revision 178, posted February 5, 2016

This release adds a stand-alone installer. This works without requiring Python to be installed.

Revision 175, posted February 5, 2016

This is the first release under the name Audir (this program was formerly named Vacro).

This is the first revision released since Vacro revision 84. There are many changes. The two most notable changes are the addition of Sound eXchange (SoX) support and the ability to edit repeaters in a Notepad window and update them in real time.

A SoX process can now be used as a sound recorder, a sound or URL stream player (probably less commonly needed), or a repeater. In any of these roles, SoX provides approximately 64 effects that can be applied to audio streams in real time. Examples include high, low, and bandpass filtering, equalizers, compression/expansion (of dynamic range), pitch alteration, and even AM and FM synthesis. Audir includes a few custom SoX effect shortcuts for convenience as well.

There is a new edit command that opens a Notepad window listing all loaded repeaters. From this window, repeaters can be stopped, started, modified, or closed. New repeaters can even be launched from this window, though caveats apply; see the Users Guide for details. This feature makes experimenting with SoX effects easy and fast and even simplifies saving and updating saved repeaters.

Other changes:

Revision 84, posted November 7, 2015

This is the last revision released under the name Vacro before the name changed to Audir.

The list of available named repeaters produced by typing the launch command with no arguments now omits named repeaters that are already loaded.

The defaults command may now be typed with no arguments to display the defaults for both MME and KS repeater types at once.

The manual now includes a Quick Start section.

Revision 80, posted October 27, 2015

Selection lists for repeaters and devices allow multiple selections at once; so, for example, it is possible to close several repeaters at once. Numbers may be separated by commas and/or spaces, and ranges like 1-3 and 1..3 are also supported.

There is now a defaults command for setting up default repeater options. defaults MME /BufferMs:100 sets up a default buffer length for MME repeaters. See the manual for a list of supported options.

Repeaters named on the command line are saved under that name for future reference, and the launch command supports launching them by name: MME l1 l2 12 creates a repeater named "12" that connects VAC line 1 to line 2. Subsequently, launch 12 can be used to launch it. launch 12 /BufferMs:200 launches it with a 200 ms buffer length without changing the normal buffer length for that repeater.

There is now a delete (or just del) command for deleting saved repeaters.

The manual includes a succinct command list near the beginning.

Vacro attempts to set its console title to "Vacro."

Revision 61

First public revision posted. Allows repeaters to be created, closed, started, stopped, shown, hidden, and listed from within Vacro.