HelpSource/Classes/Signal.schelp

   1 CLASS::Signal
   2 summary::Sampled audio buffer
   3 related::Classes/Wavetable
   4 categories:: Signals
   5
   6 DESCRIPTION::
   7 A Signal is a FloatArray that represents a sampled function of time buffer.  Signals support math operations.
   8
   9 CLASSMETHODS::
  10
  11 method::sineFill
  12 Fill a Signal of the given size with a sum of sines at the given amplitudes and phases. The Signal will be normalized.
  13 code::
  14 Signal.sineFill(1000, 1.0/[1, 2, 3, 4, 5, 6]).plot;
  15 ::
  16 argument::size
  17 the number of samples in the Signal.
  18 argument::amplitudes
  19 an Array of amplitudes for each harmonic beginning with the fundamental.
  20 argument::phases
  21 an Array of phases in radians for each harmonic beginning with the fundamental.
  22
  23 method::chebyFill
  24 Fill a Signal of the given size with a sum of Chebyshev polynomials at the given amplitudes. For eventual use in waveshaping by the Shaper ugen; see link::Classes/Shaper:: helpfile and link::Classes/Buffer#-cheby#Buffer:cheby:: too.
  25 code::
  26 Signal.chebyFill(1000, [1]).plot;
  27 Signal.chebyFill(1000, [0, 1]).plot;
  28 Signal.chebyFill(1000, [0, 0, 1]).plot;
  29 Signal.chebyFill(1000, [0.3, -0.8, 1.1]).plot;
  30 ::
  31 argument::size
  32 the number of samples in the Signal.
  33 argument::amplitudes
  34 an Array of amplitudes for each Chebyshev polynomial beginning with order 1.
  35
  36 method::hanningWindow
  37 Fill a Signal of the given size with a Hanning window.
  38 code::
  39 Signal.hanningWindow(1024).plot;
  40 Signal.hanningWindow(1024, 512).plot;
  41 ::
  42 argument::size
  43 the number of samples in the Signal.
  44 argument::pad
  45 the number of samples of the size that is zero padding.
  46
  47 method::hammingWindow
  48 Fill a Signal of the given size with a Hamming window.
  49 code::
  50 Signal.hammingWindow(1024).plot;
  51 Signal.hammingWindow(1024, 512).plot;
  52 ::
  53 argument::size
  54 the number of samples in the Signal.
  55 argument::pad
  56 the number of samples of the size that is zero padding.
  57
  58 method::welchWindow
  59 Fill a Signal of the given size with a Welch window.
  60 code::
  61 Signal.welchWindow(1024).plot;
  62 Signal.welchWindow(1024, 512).plot;
  63 ::
  64 argument::size
  65 the number of samples in the Signal.
  66 argument::pad
  67 the number of samples of the size that is zero padding.
  68
  69 method::rectWindow
  70 Fill a Signal of the given size with a rectangular window.
  71 code::
  72 Signal.rectWindow(1024).plot;
  73 Signal.rectWindow(1024, 512).plot;
  74 ::
  75 argument::size
  76 the number of samples in the Signal.
  77 argument::pad
  78 the number of samples of the size that is zero padding.
  79
  80 method::fftCosTable
  81 Fourier Transform: Fill a Signal with the cosine table needed by the FFT methods. See also the instance methods link::#-fft:: and link::#-ifft::.
  82 code::
  83 Signal.fftCosTable(512).plot;
  84 ::
  85
  86 INSTANCEMETHODS::
  87
  88 private::performBinaryOpOnSignal, performBinaryOpOnComplex, performBinaryOpOnSimpleNumber
  89
  90 method::plot
  91 Plot the Signal in a window. The arguments are not required and if not given defaults will be used.
  92 code::
  93 Signal.sineFill(512, [1]).plot;
  94 Signal.sineFill(512, [1]).plot("Signal 1", Rect(50, 50, 150, 450));
  95 ::
  96 argument::name
  97 a String, the name of the window.
  98 argument::bounds
  99 a Rect giving the bounds of the window.
 100
 101 method::play
 102 Loads the signal into a buffer on the server and plays it. Returns the buffer so you can free it again.
 103 code::
 104 b = Signal.sineFill(512, [1]).play(true, 0.2);
 105 b.free; // free the buffer again.
 106 ::
 107 argument::loop
 108 A link::Classes/Boolean:: whether to loop the entire signal or play it once. Default is to loop.
 109 argument::mul
 110 volume at which to play it, 0.2 by default.
 111 argument::numChannels
 112 if the signal is an interleaved multichannel file, number of channels, default is 1.
 113 argument::server
 114 the server on which to load the signal into a buffer.
 115
 116 method::waveFill
 117 Fill the Signal with a function evaluated over an interval.
 118 code::
 119 (
 120 a = Signal.newClear(512);
 121 a.waveFill({ arg x, i; sin(x).max(0) }, 0, 3pi);
 122 a.plot;
 123 )
 124 ::
 125 argument::function
 126 a function that should calculate the value of a sample.
 127
 128 The function is called with two arguments:
 129 definitionList::
 130 ## x || the value along the interval.
 131 ## i || the sample index.
 132 ::
 133
 134 argument::start
 135 the starting value of the interval.
 136 argument::end
 137 the ending value of the interval.
 138
 139 method::asWavetable
 140 Convert the Signal into a Wavetable.
 141 code::
 142 Signal.sineFill(512, [1]).asWavetable.plot;
 143 ::
 144
 145 method::fill
 146 Fill the Signal with a value.
 147 code::
 148 Signal.newClear(512).fill(0.2).plot;
 149 ::
 150
 151 method::scale
 152 Scale the Signal by a factor strong::in place::.
 153 code::
 154 a = Signal[1, 2, 3, 4];
 155 a.scale(0.5); a;
 156 ::
 157
 158 method::offset
 159 Offset the Signal by a value strong::in place::.
 160 code::
 161 a = Signal[1, 2, 3, 4];
 162 a.offset(0.5); a;
 163 ::
 164
 165 method::peak
 166 Return the peak absolute value of a Signal.
 167 code::
 168 Signal[1, 2, -3, 2.5].peak;
 169 ::
 170
 171 method::normalize
 172 Normalize the Signal strong::in place:: such that the maximum absolute peak value is 1.
 173 code::
 174 Signal[1, 2, -4, 2.5].normalize;
 175 Signal[1, 2, -4, 2.5].normalize(0, 1);  // normalize only a range
 176 ::
 177
 178 method::normalizeTransfer
 179 Normalizes a transfer function so that the center value of the table is offset to zero and the absolute peak value is 1. Transfer functions are meant to be used in the link::Classes/Shaper:: ugen.
 180 code::
 181 Signal[1, 2, 3, 2.5, 1].normalizeTransfer;
 182 ::
 183
 184 method::invert
 185 Invert the Signal strong::in place::.
 186 code::
 187 a = Signal[1, 2, 3, 4];
 188 a.invert(0.5); a;
 189 ::
 190
 191 method::reverse
 192 Reverse a subrange of the Signal strong::in place::.
 193 code::
 194 a = Signal[1, 2, 3, 4];
 195 a.reverse(1, 2); a;
 196 ::
 197
 198 method::fade
 199 Fade a subrange of the Signal strong::in place::.
 200 code::
 201 a = Signal.fill(10, 1);
 202 a.fade(0, 3);           // fade in
 203 a.fade(6, 9, 1, 0);     // fade out
 204 ::
 205
 206 method::integral
 207 Return the integral of a signal.
 208 code::
 209 Signal[1, 2, 3, 4].integral;
 210 ::
 211
 212 method::overDub
 213 Add a signal to myself starting at the index. If the other signal is too long only the first part is overdubbed.
 214 code::
 215 a = Signal.fill(10, 100);
 216 a.overDub(Signal[1, 2, 3, 4], 3);
 217
 218                 // run out of range
 219 a = Signal.fill(10, 100);
 220 a.overDub(Signal[1, 2, 3, 4], 8);
 221
 222 a = Signal.fill(10, 100);
 223 a.overDub(Signal[1, 2, 3, 4], -4);
 224
 225 a = Signal.fill(10, 100);
 226 a.overDub(Signal[1, 2, 3, 4], -1);
 227
 228 a = Signal.fill(10, 100);
 229 a.overDub(Signal[1, 2, 3, 4], -2);
 230
 231 a = Signal.fill(4, 100);
 232 a.overDub(Signal[1, 2, 3, 4, 5, 6, 7, 8], -2);
 233 ::
 234
 235 method::overWrite
 236 Write a signal to myself starting at the index. If the other signal is too long only the first part is overdubbed.
 237 code::
 238 a = Signal.fill(10, 100);
 239 a.overWrite(Signal[1, 2, 3, 4], 3);
 240
 241                 // run out of range
 242 a = Signal.fill(10, 100);
 243 a.overWrite(Signal[1, 2, 3, 4], 8);
 244
 245 a = Signal.fill(10, 100);
 246 a.overWrite(Signal[1, 2, 3, 4], -4);
 247
 248 a = Signal.fill(10, 100);
 249 a.overWrite(Signal[1, 2, 3, 4], -1);
 250
 251 a = Signal.fill(10, 100);
 252 a.overWrite(Signal[1, 2, 3, 4], -2);
 253
 254 a = Signal.fill(4, 100);
 255 a.overWrite(Signal[1, 2, 3, 4, 5, 6, 7, 8], -2);
 256 ::
 257
 258 method::blend
 259 Blend two signals by some proportion.
 260 code::
 261 Signal[1, 2, 3, 4].blend(Signal[5, 5, 5, 0], 0);
 262 Signal[1, 2, 3, 4].blend(Signal[5, 5, 5, 0], 0.2);
 263 Signal[1, 2, 3, 4].blend(Signal[5, 5, 5, 0], 0.4);
 264 Signal[1, 2, 3, 4].blend(Signal[5, 5, 5, 0], 1);
 265 Signal[1, 2, 3, 4].blend(Signal[5, 5, 5, 0], 2);
 266 ::
 267
 268 subsection::Fourier Transform
 269
 270 method::fft
 271 Perform an FFT on a real and imaginary signal in place. See also the class method link::#*fftCosTable::.
 272 code::
 273 (
 274 var size = 512, real, imag, cosTable, complex;
 275
 276 real = Signal.newClear(size);
 277                 // some harmonics
 278 real.sineFill2([[8], [13, 0.5], [21, 0.25], [55, 0.125, 0.5pi]]);
 279                 // add a little noise
 280 real.overDub(Signal.fill(size, { 0.2.bilinrand }));
 281
 282 imag = Signal.newClear(size);
 283 cosTable = Signal.fftCosTable(size);
 284
 285 complex = fft(real, imag, cosTable);
 286 [real, imag, (complex.magnitude) / 100 ].flop.flat
 287         .plot("fft", Rect(0, 0, 512 + 8, 500), numChannels: 3);
 288 )
 289 ::
 290
 291 method::ifft
 292 Perform an inverse FFT on a real and imaginary signal in place. See also the class method link::#*fftCosTable::.
 293 code::
 294 (
 295 var size = 512, real, imag, cosTable, complex, ifft;
 296
 297 real = Signal.newClear(size);
 298                 // some harmonics
 299 real.sineFill2([[8], [13, 0.5], [21, 0.25], [55, 0.125, 0.5pi]]);
 300                 // add a little noise
 301 real.overDub(Signal.fill(size, { 0.2.bilinrand }));
 302
 303 imag = Signal.newClear(size);
 304 cosTable = Signal.fftCosTable(size);
 305
 306 complex = fft(real, imag, cosTable).postln;
 307 ifft = complex.real.ifft(complex.imag, cosTable);
 308
 309 [real, ifft.real].flop.flat
 310         .plot("fft and back", Rect(0, 0, 512 + 8, 500), numChannels: 2);
 311 )
 312 ::
 313
 314 subsection::Unary Messages
 315
 316 Signal will respond to unary operators by returning a new Signal.
 317 code::
 318 x = Signal.sineFill(512, [0, 0, 0, 1]);
 319 [x, x.neg, x.abs, x.sign, x.squared, x.cubed, x.asin.normalize, x.exp.normalize, x.distort].flop.flat
 320         .plot(numChannels: 9);
 321 ::
 322
 323 method::neg, abs, sign, squared, cubed, sqrt, exp, log, log2, log10, sin, cos, tan, asin, acos, atan, sinh, cosh, tanh, distort, softclip, nyqring, isPositive, isNegative, isStrictlyPositive
 324
 325 subsection::Binary Messages
 326
 327 Signal will respond to binary operators by returning a new Signal.
 328 code::
 329 (
 330 x = Signal.fill(512, { rrand(0.0, 1.0) });
 331 y = Signal.fill(512, { |i| (i * pi / 64).sin });
 332 [x, y, (x + y) * 0.5, x * y, min(x, y), max(x, y) ].flop.flat
 333         .plot(numChannels: 6);
 334 )
 335 ::
 336 method::+, -, *, /, div, %, **, min, max, ring1, ring2, ring3, ring4,
 337 difsqr, sumsqr, sqrdif, absdif, amclip, scaleneg, clip2, excess, <!
 338