MrsWatson is a command-line audio plugin host. It takes an audio and/or MIDI file as input, and processes it through one or more audio plugins. Currently MrsWatson only supports VST 2.x plugins, but more formats are planned in the future. MrsWatson was designed for primarily three purposes:
- Audio plugin development and testing
- Automated audio processing for servers or other offline applications
- Unit testing audio plugins
Say you have an audio file which you would like to process with an effect plugin.
mrswatson --input mysong.wav --output out.wav --plugin myplugin
This will run mysong.wav through the myplugin VST, placing the processed
output in out.wav, as well as logging some output to the console:
- 00000000 000000 MrsWatson version 0.9.7 initialized, build 20150112
- 00000000 000000 Setting 2 channels
- 00000000 000000 Setting sample rate to 44100Hz
- 00000000 000000 Plugin 'myplugin.vst' is of type VST2.x
- 00000000 000000 Opening VST2.x plugin 'myplugin.vst'
- 00000000 000001 Starting processing input source
- 00010752 000002 Total processing time 1ms, approximate breakdown:
- 00010752 000002 MrsWatson Initialization: 1ms (69.4%)
- 00010752 000002 MrsWatson Input Source: 0ms (12.4%)
- 00010752 000002 MrsWatson Output Source: 0ms (11.6%)
- 00010752 000002 myplugin.vst Audio Processing: 0ms (3.9%)
- 00010752 000002 myplugin.vst MIDI Processing: 0ms (0.0%)
- 00010752 000002 Read 10595 frames from mysong.wav
- 00010752 000002 Wrote 10752 frames to out.wav
- 00010752 000002 Shutting down
- 00010752 000002 Closing plugin 'myplugin.vst'
- 00010752 000002 Goodbye!
To see more or less logging output, use the --verbose or --quiet options,
respectively. MrsWatson generates colored output (if your terminal supports
it) with two times per line, the first for the current sample and the second
for the time in milliseconds since processing began. The sample time also
changes colors after every 44100 samples to help visually break up processing
times.
To process a MIDI file through an instrument using an FXP preset to be loaded into the VST, you'd do something like this:
mrswatson --midi-file mysong.mid --output out.wav --plugin piano,soft.fxp
Like the first example, a list of plugins separated with semi-colons can be given here so that the audio generated by the instrument can be processed through any number of effects. Each plugin name can be followed by a comma and the location to a preset file to be loaded before processing.
Complete help for MrsWatson can be found by running the program with no
arguments, or with --help. To see extended help for all options (which prints
quite a lot of output) run mrswatson --help full.
Currently, MrsWatson loads plugins by their short name by searching in the
standard installation locations for your platform, as well as the current
working directory and by absolute path. Use the --list-plugins option to see
the order of locations searched and the plugins found there.
MrsWatson supports setting plugin parameters with the --parameter switch.
However, if you would like to set many parameters on a plugin, it may be more
efficient to create an FXP preset and load it with the plugin. For information
on presets, run mrswatson --help plugin.
MrsWatson supports both 32-bit and 64-bit plugins, but not in the same
executable. Two executables are shipped in the distribution zipfile for each
platform, mrswatson (the 32-bit variant), and mrswatson64 (the 64-bit
variant). Each one is only able to process with plugins of the same
architecture. Running either executable with the --list-plugins switch will
print out all supported plugins that the program is compatible with.
Although on Mac OS X, a single Universal Binary could theoretically be used to suport both architectures, Darwin will always launch one matching the system's architecture. Thus, it would be impossible to load 32-bit plugins on a 64-bit Mac. For this reason (and also to be consistent with other platforms MrsWatson runs on), Universal Binaries are not used on Mac OS X.
As MrsWatson is a new codebase, there are lots of missing features, some more important than others. To encourage a quick initial release, the following features are not yet present in MrsWatson, but may be added at some point in the future:
- AudioUnit plugins on Mac OSX
- File support for compressed audio
- Resampling of input source if desired
- True realtime mode
- Input/output from system audio devices
I have also tried to identify incomplete areas of the code and log them to the console, which means that we are aware that this feature is missing and will be added soon. If you see some other missing functionality or experience a crash or other bug, please report an issue on the project page.
If you believe you have found a bug in MrsWatson, please try first running it
with the --verbose argument. This will generate extra logging output which
may help to solve the problem.
The easiest way to report a bug is to send an email to Teragon Audio's support
address: support (at) teragonaudio (dot) com. MrsWatson has a special
command-line switch to aid in diagnosing runtime problems, --error-report.
When enabled it will create a zipfile on the desktop containing the input,
output, logs, and optionally the plugins themselves. Please include these
reports for bugs resulting in incorrect behavior or crashes.
A test suite program, named mrswatsontest, can be found in the Mrswatson
zipfile. If tests fail on your platform, please report this along with your
bug. Please note that there is also a 64-bit version of mrswatsontest.
MrsWatson uses GitHub issues for bug reporting, if you would like to submit an issue yourself.
Instructions for building MrsWatson can be found in the file BUILDING.md.
MrsWatson takes its name from a prior product from Teragon Audio called MissWatson (and the original name there, in case you were wondering, is a bit of a joke on the Dr. Watson utility).
In 2009 I sold the exclusive rights to MissWatson to a company interested in using it for server-side audio processing. As per the terms of our agreement, I made one last public release, and removed the code from my website. Since then, I have received numerous emails and inquiries regarding the project, mostly from plugin developers or people interested in VST technology. Though I have no regrets about discontinuing the original MissWatson (particularly since I didn't have time to properly maintain it), I felt that it was a useful utility which should be made available and open-sourced.
In 2011, my NDA with the aforementioned company expired, and I started working on a new MissWatson. MrsWatson is the result of this labor.
As I no longer have the source code for MissWatson, MrsWatson is a black-box implementation. They share only the name and concept in common. The two programs are incompatible and have fundamentally different behavior. They are also written in different languages (the original in C++, MrsWatson in C), and have completely different internal architecture.
If you are using MrsWatson to do something cool, please send me a link to your project! If you appreciate MrsWatson and would like to donate money, please instead make a donation to a charity on our behalf, and let us know about it. The organizations which have helped us the most are:
- EFF: Without the EFF, programs like MrsWatson would be significantly harder to create and distribute.
- Wikipedia: Writing MrsWatson involves a lot of research as well as coding, and Wikipedia is an essential part of this.
Big additional thanks to:
- Andrew McCrea, (@thrusong)
- Michael Pruett, (@mpruett)
- Jarl Friis (@jarl-dk)
MrsWatson is made available under the BSD license. For more details, see the
LICENSE.txt file distributed with the source code. MrsWatson also uses the
following third-party libraries, which are licensed under the respective
agreements:
- VST: Licensed under Steinberg's VST SDK license agreement, version 2.4. For more information, see Steinberg's developer portal.
- libaudiofile: Written by Michael Pruett, licensed under GNU Library General Public License.