-
Notifications
You must be signed in to change notification settings - Fork 0
/
MrsWatson.html
365 lines (302 loc) · 15.4 KB
/
MrsWatson.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>MrsWatson</title>
<link rel="stylesheet" href="/css/reset.css" type="text/css" />
<link rel="stylesheet" href="/css/default.css" type="text/css" />
<link rel="stylesheet" href="/css/button.css" type="text/css" />
<script language="javascript" src="/js/email.js"></script>
<!-- google analytics -->
<script type='text/javascript'>
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type='text/javascript'>
var pageTracker = _gat._getTracker("UA-4400684-1");
pageTracker._initData();
pageTracker._trackPageview();
</script>
</head>
<body>
<div id="smallheader">
<div class="wrapper">
<div id="logo">
<a href="/"><img src="/images/ta_logo_inverted.png" alt="Teragon Audio"/></a>
</div>
<!--
<div id="right">
<form method="get" id="searchform" action="#">
<fieldset class="search">
<input type="text" class="box" />
<button class="btn" title="Search">Search</button>
</fieldset>
</form>
</div>
-->
</div>
</div>
<div id="contentpart">
<div class="wrapper">
<ul class="menu">
<li class="menuitem"><a href="index.html">Home</a></li>
<li class="menuitem"><a href="/software.html">Software</a></li>
<li class="menuitem"><a href="/developers.html">Developer Portal</a></li>
<li class="menuitem"><a href="/performers.html">Performer Portal</a></li>
<li class="menuitem"><a href="/contact.html">Contact</a></li>
</ul>
<div id="content">
<div id="main" class="news">
<!-- Start content -->
<h1 id="mrswatson">MrsWatson</h1>
<p><strong>NOTE</strong>: This software is unsupported and is no longer being updated or
maintained. It likely will not work on newer versions of macOS.</p>
<p>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:</p>
<ul>
<li>Audio plugin development and testing</li>
<li>Automated audio processing for servers or other applications</li>
<li>Unit testing audio plugins</li>
</ul>
<h2 id="examples">Examples</h2>
<p>Say you have an audio file which you would like processed through a group of
mastering plugins.</p>
<pre><code>mrswatson --input mysong.pcm --output out.pcm --plugin plugin1;plugin2
</code></pre>
<p>This will print the following output:</p>
<pre><code>- 00000000 000000 Plugin 'plugin1' is of type VST2.x
- 00000000 000000 Plugin 'plugin2' is of type VST2.x
- 00000000 000000 MrsWatson version 0.1.0 initialized
- 00000000 000000 Opening VST2.x plugin 'plugin1'
- 00000000 000029 Opening VST2.x plugin 'plugin2'
- 00000000 000144 Processing with samplerate 44100, blocksize 512, 2 channels
- 03532800 000204 Total processing time 60ms, approximate breakdown by component:
- 03532800 000204 plugin1: 38ms
- 03532800 000204 plugin2: 11ms
- 03532800 000204 MrsWatson: 11ms
- 03532800 000204 Read 3528000 frames from mysong.pcm, wrote 3532800 frames to out.pcm
- 03532800 000204 Shutting down
- 03532800 000210 Closing plugin 'plugin1'
- 03532800 000212 Closing plugin 'plugin2'
- 03532800 000212 Goodbye!
</code></pre>
<p>To see more or less logging output, use the <code>--verbose</code> or <code>--quiet</code> 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. This value can be changed with the <code>--zebra-size</code> option.</p>
<p>To process a MIDI file through an instrument, you’d do something like this:</p>
<pre><code>mrswatson --midi-file mysong.mid --output out.pcm --plugin piano,soft.fxp
</code></pre>
<p>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.</p>
<p>Complete help for MrsWatson can be found by running the program with no
arguments, or with <code>--help</code>. The <code>--help</code> switch prints quite a lot of output,
so you can also use <code>--options</code> to see all supported options and their default
values.</p>
<h2 id="loading-plugins">Loading Plugins</h2>
<p>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 <code>--list-plugins</code> option to see
the order of locations searched and the plugins found there.</p>
<p>While MrsWatson has some understanding of getting and setting plugin
parameters, it does not extend this functionality to the end user. Rather than
passing a huge list of parameters on the command line, one should instead
create a preset for the plugin and load it with the comma-separated syntax
as shown above.</p>
<h2 id="limitations">Limitations</h2>
<p>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:</p>
<ul>
<li>AudioUnit plugins on Mac OSX</li>
<li>File support for compressed audio</li>
<li>Resampling of input source if desired</li>
<li>True realtime mode</li>
</ul>
<p>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 <a href="http://github.com/teragonaudio/MrsWatson">project page</a>.</p>
<h2 id="bug-reporting">Bug Reporting</h2>
<p>If you believe you have found a bug in MrsWatson, please try first running it
with the <code>--verbose</code> argument. This will generate extra logging output which
may help to solve the problem.</p>
<p>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, <code>--error-report</code>.
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.</p>
<p>A test suite program, named <code>mrswatsontest</code>, can be found in the Mrswatson
zipfile. If tests fail on your platform, please report this along with your
bug.</p>
<p>MrsWatson uses <a href="https://github.com/teragonaudio/MrsWatson/issues">GitHub issues</a> for bug reporting, if you would like to
submit an issue yourself.</p>
<h2 id="building">Building</h2>
<p>Instructions for building MrsWatson can be found in the file
<a href="https://github.com/teragonaudio/MrsWatson/blob/master/doc/Building.md">Building.txt</a>.</p>
<h2 id="history-and-name">History and Name</h2>
<p>MrsWatson takes its name from a prior product from <a href="http://www.teragonaudio.com">Teragon Audio</a> called
<em>MissWatson</em> (and the original name there, in case you were wondering, is a
bit of a joke on the <a href="http://en.wikipedia.org/wiki/Dr._Watson_(debugger)">Dr. Watson</a> utility).</p>
<p>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.</p>
<p>In 2011, my NDA with the aforementioned company expired, and I started working
on a new MissWatson. MrsWatson is the result of this labor.</p>
<p>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 <strong>incompatible</strong> and have <strong>fundamentally different behavior</strong>.
They are also written in different languages (the original in C++, MrsWatson
in C), and have completely different internal architecture.</p>
<p>But just as wildfires usher in new growth, the rewrite of MissWatson to
MrsWatson has had some advantages as well. Benchmarking the old application
against the new one shows that the rewrite performs over twice as fast as the
previous version! Additionally, the new version is much more portable, easier
to maintain, and extensible than its predecessor.</p>
<p>If you have built some system which used the original MissWatson, then you
will likely have to make some big changes to migrate to MrsWatson. Likewise,
if you were using some of the original MissWatson code in your project, you
will <em>not</em> be able to replace it with MrsWatson without significant work on
your end. Migration to the new MrsWatson is strongly encouraged.</p>
<h2 id="donate">Donate</h2>
<p>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:</p>
<ul>
<li><a href="https://supporters.eff.org/donate">EFF</a>: Without the EFF, programs like MrsWatson would be significantly
harder to create and distribute.</li>
<li><a href="http://wikimediafoundation.org/wiki/WMFJA085/en">Wikipedia</a>: Writing MrsWatson involves a lot of research as well as
coding, and Wikipedia is an essential part of this.</li>
</ul>
<h2 id="special-thanks">Special Thanks</h2>
<p>Big additional thanks to:</p>
<ul>
<li>Andrew McCrea, (@thrusong)</li>
<li>Michael Pruett, (@mpruett)</li>
</ul>
<h2 id="licensing">Licensing</h2>
<p>MrsWatson is made available under the BSD license. For more details, see the
<code>LICENSE.txt</code> file distributed with the source code. MrsWatson also uses the
following third-party libraries, which are licensed under the respective
agreements:</p>
<ul>
<li><a href="http://www.steinberg.net/en/company/developer.html">VST</a>: Licensed under Steinberg’s VST SDK license agreement, version 2.4.
For more information, see Steinberg’s developer portal.</li>
<li><a href="http://audiofile.68k.org/">libaudiofile</a>: Written by Michael Pruett, licensed under GNU Library
General Public License.</li>
</ul>
<hr />
<p>Changelog:</p>
<p>Version 0.9.7:</p>
<ul>
<li>New command-line option for setting parameters</li>
<li>Ensure that executable runs on 10.5 and above</li>
<li>Now have a single option for setting time signature</li>
<li>Handle key signature & proprietary MIDI meta events</li>
<li>Fix several small memory leaks</li>
<li>Fix several crashes</li>
<li>Log CPU usage overloads</li>
<li>Bugfixes, tests with 32/64 bit detection</li>
<li>Bugfixes, tests with big/little endian detection</li>
<li>New and more robust file API</li>
<li>Fix CMake project generation on Mac/Windows</li>
<li>Allow test suite to show log output from app</li>
<li>Improve internal documentation</li>
</ul>
<p>Version 0.9.6:</p>
<ul>
<li>Compatibility with VST shell plugins (including Waves plugins)</li>
<li>Compatibility fixes with plugins that declare more than 2 outputs
(including Independence)</li>
<li>Compatibility fixes for Chainer and other plugins which rely on VstEvents*
struct to remain in memory during processReplacing()</li>
<li>MrsWatson now sends correct musical time in PPQ/Bars when asked by plugin</li>
<li>Add 64-bit binaries to distribution zipfile (experimental)</li>
<li>Fix tons of memory leaks; test suite now runs with 0 bytes leaked</li>
<li>Fix several memory corruption bugs, valgrind now runs test suite with no
errors</li>
<li>Windows build migrated to cmake</li>
<li>Several other bugfixes and small improvements</li>
</ul>
<p>Version 0.9.5:</p>
<ul>
<li>Better support for MIDI meta events. Tempo and time signature are now
correctly read from MIDI files.</li>
<li>Fix a bug where MrsWatson would not know when to stop processing an
instrument plugin chain.</li>
<li>Fix a bug where some monophonic VSTi’s would not receive notes data in an
expected format.</li>
<li>Fix some memory corruption bugs.</li>
<li>Improved application test suite.</li>
</ul>
<p>Version 0.9.4:</p>
<ul>
<li>Fix several heap corruption bugs</li>
<li>Fix build on linux</li>
<li>Organizing code into packages</li>
<li>Various small bugfixes</li>
<li>Improve test coverage</li>
</ul>
<p>Version 0.9.3:</p>
<ul>
<li>Introduce CMake as build system for unix platforms (Linux & Mac OSX)</li>
<li>Several crash fixes reported by users</li>
<li>Ability to generate diagnostic error reports</li>
<li>Improved logging</li>
<li>Improved test coverage</li>
<li>More accurate time recording on all platforms</li>
<li>Other small improvements</li>
<li>FXP presets with chunks now supported</li>
</ul>
<p>Version 0.9.2:</p>
<ul>
<li>Using Visual Studio to build on Windows</li>
<li>Introduced test suite, though test coverage is current small</li>
<li>Experimental native support for writing WAVE data (only active
for the Windows build right now).</li>
<li>Update to audiofile 0.3.4</li>
<li>Fix a number of Windows bugs</li>
<li>Improved log formatting</li>
<li>Can send time in PPQ</li>
<li>Command line option for manually setting MIDI time division</li>
</ul>
<p>Version 0.9.1:</p>
<ul><li> Switching from libaiff to audiofile (provides WAV support)</li></ul>
<p>Version 0.9.0:
(No comment)</p>
<!-- End content -->
</div>
<div id="sidebar">
<ul class="sidemenu">
<li><a href="http://static.teragonaudio.com/downloads/MrsWatsonMrsWatson.zip" class="downloadbutton"><b>Download</b></a><p></p></li>
<li><a href="https://github.com/teragonaudio/MrsWatson/zipball/master">Source code</a></li>
<li><a href="https://github.com/teragonaudio/MrsWatson">Project page</a></li>
</ul>
</div>
</div>
<div style="clear:both;"></div>
<div id="bottom">
<p class="footer">
<b>Having problems with this software?</b> Send an email to
<script>mail2("support", "teragonaudio", 0, "subject=MrsWatson", "support at teragonaudio dot com")</script>.
Copyright (c) 2012 Teragon Audio. All Rights Reserved.
</p>
</div>
</div>
</div>
</body>
</html>