-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathboar.1
156 lines (156 loc) · 9.16 KB
/
boar.1
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
.Dd $Mdocdate$
.Dt boar 1
.Os
.Sh NAME
.Nm boar
.Nd micro audio synthesis environment
.Sh SYNOPSIS
.Nm boar
.Op -option n ...
.Sh DESCRIPTION
.Pp
The Barely Operational Audio REPL (BOAR) is a small program that opens a handle to sndio and allows the user to play with carrier/modulator oscillator pairs by issuing commands from stdin. It lacks the features of many other synthesizers, but makes up for this with its light weight and small, readable source code.
.Pp
All startup options are paired with a single integer as their parameter unless otherwise indicated. boar already starts with sane defaults, so the user needn't dive through these too often. Some of these flags are not even implemented yet and have no effect.
.Bl -tag -width Ds
.It Fl blocks
The number of blocks to use in audio buffering. More results in sluggish input.
.El
.Bl -tag -width Ds
.It Fl rate
The sample rate of audio output.
.El
.Bl -tag -width Ds
.It Fl polyphony
The number of audio voices that can simultaneously play.
.El
.Sh INTERACTIVE SESSION
.Pp
Once running, boar accepts a few single argument commands from the user. The parameters to these commands can be one of the following types:
.Bd -literal -offset indent
\& nil No parameter at all
\& uint A unipolar (positive) integer
\& int A bipolar (positive or negative) integer
\& ufloat A unipolar (positive) integer
\& float A bipolar (positive or negative) float
\& char A single alphabetic character
\& string Any text
.Ed
.Pp
Functions that expect certain numerical types can accept other numbers in some cases. A function that requires a float will understand `1` as `1.0`, for instance. Unipolar functions cannot accept bipolar values, however.
.Pp
boar's commands are as follows. They are single characters that are decorated with a period (f.), a colon (f:), or remain unadorned (f).
.Bl -tag -width Ds
.It # [string]
A comment. Any text behind this is ignored. Useful in annotating files full of boar commands that are expected to be loaded by the program.
.El
.Bl -tag -width Ds
.It a/A [ufloat]
Sets the envelope attack for the carrier (a) or modulator (A). This is the amount of seconds the parameter being enveloped takes to reach its full effect.
.El
.Bl -tag -width Ds
.It a./A. [int]
Sets the envelope attack wave shape for the carrier (a.) or modulator (A.).
.El
.Bl -tag -width Ds
.It b [ufloat]
Sets the left/right audio output channel balance. 0.5 represents full volume in both left/right channels. 0.0 represents full volume in the left channel with the right one muted. 1.0 represents full volume in the right channel with the left one muted.
.El
.Bl -tag -width Ds
.It c/C [uint]
Adjust the harmonic complexity muting on carrier (c) or modulator (C). At the default value of zero, the full harmonics of a wave are audible, but higher values will produce a more mellow signal. This has no effect on sines or noise.
.El
.Bl -tag -width Ds
.It d/D [ufloat]
Sets the envelope decay for the carrier (d) or modulator (D). This is the amount of seconds the parameter being enveloped takes to reach its sustain level after the attack has taken place.
.El
.Bl -tag -width Ds
.It d./D. [int]
Sets the envelope decay wave shape for the carrier (d.) or modulator (D.).
.El
.Bl -tag -width Ds
.It d:/D: [uint]
Set the envelope to loop between the A/D stages if enabled with a value of 1. Pass 0 to disable. Can be used as a LFO over carrier/modulator amplitude.
.El
.Bl -tag -width Ds
.It k/K [int]
Set the key follow curve of the carrier (k) or the modulator (K). The curve is a wavetable from the w/W command. The amplitude of operators will be multiplied by the note number's place along this curve. The performer will usually want to dampen the amplitudes found at higher note numbers, so negative values are recommended to produce reversed curves.
.El
.Bl -tag -width Ds
.It l/L [ufloat]
Set the level of the carrier (l) and modulator (L). Carrier level is the main volume of the boar instance, and must be between 0.0 and 1.0. Modulation levels determine the modulation index of the operator pair, and can be as high as one wishes. A higher modulation level results in more harmonic content.
.El
.Bl -tag -width Ds
.It n [uint]
Play a note, where the argument is a MIDI note number between 0 and 127. Notes cannot be stacked during pitched playback (but can be if the x/X commands are run). Running n against an already playing note will reset its envelope back to the attack stage. Once the number of active notes exceeds the value specified in the -polyphony flag, new notes will deactivate old ones to make room for themselves. This does not take place in a first-in-first-out manner; the oldest note is not necessarily the first one to have its space stolen. This unpredictability may be undesirable, and could be reformed in future versions of boar. If velocity sensitivity is enabled with t/T commands, then the upper byte of n's argument will be read as a velocity parameter between 0 and 127, while the lower byte will be the usual MIDI note number.
.El
.Bl -tag -width Ds
.It o [uint]
Turns an active note off. A note can be deactivated by passing its MIDI note number, or the 2 byte combination of a velocity value and a note. `o 60` and `o 32316` will both turn off the same note.
.El
.Bl -tag -width Ds
.It p/P [ufloat]
Set the pitch ratio between the note and the carrier (p) or modulator (P) oscillator. If a note is 440hz and the ratio is set to 2.0, then the oscillator with have a frequency of 880hz. This allows the performer to detune carriers and alter the timbre of modulators.
.El
.Bl -tag -width Ds
.It q [nil]
Quits the program.
.El
.Bl -tag -width Ds
.It r/R [ufloat]
Sets the envelope release for the carrier (r) or modulator (R). This is the amount of seconds the parameter being enveloped takes to reach zero after its corresponding note has been turned off.
.El
.Bl -tag -width Ds
.It r./R. [int]
Sets the envelope release wave shape for the carrier (r.) or modulator (R.).
.El
.Bl -tag -width Ds
.It s/S [ufloat]
Sets the envelope sustain for the carrier (s) or modulator (S). This is the level at which the parameter being enveloped will be multiplied against after the attack and decay have taken place. Values between 0.0 and 1.0 are honored.
.El
.Bl -tag -width Ds
.It s./S. [ufloat]
Sets the envelope depth for the carrier (s.) or modulator (S.). At its fullest depth (1.0), an envelope will exert complete control over its parameter. At its lowest (0.0) it will have no effect. A value between these extremes will allow the envelope to provide subtle accents to its parameter.
.El
.Bl -tag -width Ds
.It t/T [int]
Sets the touch sensitivity curve of the carrier (t) or modulator (T). Its argument is one of the wavetables specified in the w/W command entry. Depending upon the curve selected, boar's operators will respond differently to varying pressure on the keyboard. This parameter is set to 0 by default: a flat wavetable that does not respond to pressure at all. Users are advised not to change this value unless they are piping (filtered) musical keyboard input into boar; specifying velocity values in the REPL itself is a tedious process. See the note (n) command for more information.
.El
.Bl -tag -width Ds
.It U [uint]
Selects a note number to tune. When the tuning command (u) is run, it will target this note.
.El
.Bl -tag -width Ds
.It u [ufloat]
Tunes the selected note's (U) pitch by a float factor. Entering `u 0.75` will tell the selected note to play at three quarters its normal frequency, for instance. Alternative scales can be implemented by tuning each note in terms of an offset from the standard twelve-tone series.
.El
.Bl -tag -width Ds
.It u.
Which parameter the tuning commands (u/U) should affect. 0 alters carrier tuning and 1 alters the modulator.
.El
.Bl -tag -width Ds
.It w/W [int]
Set the waveform for the carrier (w) or modulator (W), where the argument is one of the following:
.Bd -literal -offset indent
\& 0 flat (silence)
\& 1 sine
\& 2 square
\& 3 triangle
\& 4 ramp (sawtooth)
\& 5 exponential
\& 6 logarithmic
\& 7 noise
\&
.Ed
Providing a negative parameter will tell the affected operator to read its wavetable in reverse. The effect is usually not audible with periodic waves, but it can be heard in very slow modulations.
.El
.Bl -tag -width Ds
.It x/X [ufloat]
Sets the carrier (x) or modulator (X) to a fixed frequency in hz. The specific values of notes will no longer have an effect on the operator's pitch. This is useful for patches that require aharmonic content. Fixed frequency mode is exited when x/X is set to 0.0.
.El
.Sh HISTORY
boar was written in 2019, but it came out of the ashes of aborted (and far more ambitious) efforts in realtime synthesis dating back to 2014. This modest program largely has John Chowning to thank, as it leverages his groundbreaking work in FM synthesis, best elucidated his book "FM Theory and Applications." Curtis Roads also contributed a wealth of knowledge with his "Computer Music Tutorial." The communities at Vintage Synth Explorer and KVR Audio also patiently guided the author through many basic DSP concepts.
.Sh AUTHORS
Written by Jim Dalrymple. http://dalrym.pl
.Sh CAVEATS
boar makes no use of readline. If you'd like to scroll through your input history, please call the program in `rlwrap boar`.