0
# Signal Processing
1

2
Audio-rate signal processing utilities for mathematical operations, scaling, and control signal generation.
3

4
## Capabilities
5

6
### Core Signal Classes
7

8
Fundamental signal processing building blocks.
9

10
```typescript { .api }
11
/**
12
 * Audio-rate signal with unit conversion and automation
13
 */
14
class Signal<T extends UnitName = "number"> {
15
  constructor(value?: UnitMap[T], units?: T);
16
  
17
  /** Current signal value */
18
  value: UnitMap[T];
19
  
20
  /** Signal units */
21
  units: T;
22
  
23
  /** Whether to convert units */
24
  convert: boolean;
25
  
26
  /** Set value at specific time */
27
  setValueAtTime(value: UnitMap[T], time: Time): this;
28
  
29
  /** Linear ramp to value */
30
  linearRampToValueAtTime(value: UnitMap[T], time: Time): this;
31
  
32
  /** Exponential ramp to value */
33
  exponentialRampToValueAtTime(value: UnitMap[T], time: Time): this;
34
  
35
  /** Ramp to value over duration */
36
  rampTo(value: UnitMap[T], time: Time, startTime?: Time): this;
37
  
38
  /** Target ramp with time constant */
39
  targetRampTo(value: UnitMap[T], time: Time, startTime?: Time): this;
40
  
41
  /** Cancel scheduled changes */
42
  cancelScheduledValues(time: Time): this;
43
  
44
  /** Connect to audio parameter or node */
45
  connect(destination: AudioParam | AudioNode): this;
46
  
47
  /** Disconnect from destinations */
48
  disconnect(): this;
49
}
50

51
/**
52
 * Signal synchronized to transport
53
 */
54
class SyncedSignal extends Signal {
55
  constructor(value?: number, units?: UnitName);
56
  
57
  /** Sync to transport time */
58
  sync(): this;
59
  
60
  /** Unsync from transport */
61
  unsync(): this;
62
}
63
```
64

65
### Mathematical Operations
66

67
Signals for performing mathematical operations on audio signals.
68

69
```typescript { .api }
70
/**
71
 * Add two signals or add constant to signal
72
 */
73
class Add {
74
  constructor(value?: number);
75
  
76
  /** Value to add */
77
  addend: Signal<"number">;
78
  
79
  /** Connect inputs */
80
  connect(destination: AudioNode): this;
81
}
82

83
/**
84
 * Subtract two signals or subtract constant from signal
85
 */
86
class Subtract {
87
  constructor(value?: number);
88
  
89
  /** Value to subtract */
90
  subtrahend: Signal<"number">;
91
}
92

93
/**
94
 * Multiply two signals or multiply signal by constant
95
 */
96
class Multiply {
97
  constructor(value?: number);
98
  
99
  /** Value to multiply by */
100
  factor: Signal<"number">;
101
}
102

103
/**
104
 * Absolute value of signal
105
 */
106
class Abs {
107
  constructor();
108
  
109
  /** Connect input signal */
110
  connect(destination: AudioNode): this;
111
}
112

113
/**
114
 * Negate signal (multiply by -1)
115
 */
116
class Negate {
117
  constructor();
118
}
119

120
/**
121
 * Raise signal to power
122
 */
123
class Pow {
124
  constructor(exp?: number);
125
  
126
  /** Exponent value */
127
  value: number;
128
}
129
```
130

131
### Scaling and Mapping
132

133
Utilities for scaling and mapping signal ranges.
134

135
```typescript { .api }
136
/**
137
 * Linear scaling of signal range
138
 */
139
class Scale {
140
  constructor(min?: number, max?: number);
141
  
142
  /** Minimum output value */
143
  min: number;
144
  
145
  /** Maximum output value */
146
  max: number;
147
}
148

149
/**
150
 * Exponential scaling of signal range
151
 */
152
class ScaleExp {
153
  constructor(min?: number, max?: number, exponent?: number);
154
  
155
  /** Minimum output value */
156
  min: number;
157
  
158
  /** Maximum output value */
159
  max: number;
160
  
161
  /** Scaling exponent */
162
  exponent: number;
163
}
164
```
165

166
### Comparison Operations
167

168
Signal comparison and logic operations.
169

170
```typescript { .api }
171
/**
172
 * Output 1 if input > threshold, 0 otherwise
173
 */
174
class GreaterThan {
175
  constructor(value?: number);
176
  
177
  /** Comparison threshold */
178
  value: number;
179
}
180

181
/**
182
 * Output 1 if input > 0, 0 otherwise
183
 */
184
class GreaterThanZero {
185
  constructor();
186
}
187
```
188

189
### Signal Conversion
190

191
Convert between audio-rate and control-rate signals.
192

193
```typescript { .api }
194
/**
195
 * Convert audio-rate signal to gain-rate (0-1 range)
196
 */
197
class AudioToGain {
198
  constructor();
199
}
200

201
/**
202
 * Convert gain-rate signal to audio-rate
203
 */
204
class GainToAudio {
205
  constructor();
206
}
207
```
208

209
### Waveshaping
210

211
Non-linear signal processing for distortion and waveshaping.
212

213
```typescript { .api }
214
/**
215
 * Waveshaping using lookup table or function
216
 */
217
class WaveShaper {
218
  constructor(mapping?: number[] | ((value: number) => number), length?: number);
219
  
220
  /** Waveshaping curve */
221
  curve: Float32Array | null;
222
  
223
  /** Oversampling factor */
224
  oversample: "none" | "2x" | "4x";
225
  
226
  /** Set curve from array or function */
227
  setMap(mapping: number[] | ((value: number) => number)): this;
228
}
229
```
230

231
### Constant Signals
232

233
Utility signals for providing constant values.
234

235
```typescript { .api }
236
/**
237
 * Zero signal constant
238
 */
239
class Zero {
240
  constructor();
241
  
242
  /** Connect to destination */
243
  connect(destination: AudioNode): this;
244
}
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
import { Signal, Add, Scale, LFO, Oscillator, start } from "tone";
251

252
await start();
253

254
// Create control signals
255
const baseFreq = new Signal(220, "frequency");
256
const lfo = new LFO(2, -50, 50);
257
const add = new Add();
258

259
// Chain: base frequency + LFO modulation
260
baseFreq.connect(add);
261
lfo.connect(add.addend);
262

263
// Connect to oscillator frequency
264
const osc = new Oscillator().toDestination();
265
add.connect(osc.frequency);
266

267
// Start everything
268
lfo.start();
269
osc.start();
270

271
// Automate base frequency
272
baseFreq.rampTo(440, 4);
273

274
// Scale signal example
275
const envelope = new Envelope();
276
const scale = new Scale(200, 2000);
277

278
envelope.connect(scale);
279
scale.connect(osc.frequency);
280
```
281

282
## Types
283

284
```typescript { .api }
285
type UnitName = "number" | "frequency" | "time" | "decibels" | "normalRange" | "positive" | "cents" | "degrees" | "gain" | "bpm";
286

287
type UnitMap = {
288
  number: number;
289
  frequency: number;
290
  time: number;
291
  decibels: number;
292
  normalRange: number;
293
  positive: number;
294
  cents: number;
295
  degrees: number;
296
  gain: number;
297
  bpm: number;
298
};
299

300
interface SignalOptions<T extends UnitName> {
301
  value: UnitMap[T];
302
  units: T;
303
  convert: boolean;
304
}
305

306
interface ScaleOptions {
307
  min: number;
308
  max: number;
309
}
310

311
interface ScaleExpOptions extends ScaleOptions {
312
  exponent: number;
313
}
314

315
interface WaveShaperOptions {
316
  mapping: number[] | ((value: number) => number);
317
  length: number;
318
  oversample: "none" | "2x" | "4x";
319
}
320
```