| 1 | NAME |
|
|
| 2 | PDL::Audio - Some PDL functions intended for audio processing. |
|
|
| 3 | |
|
|
| 4 | SYNOPSIS |
|
|
| 5 | use PDL; |
|
|
| 6 | use PDL::Audio; |
|
|
| 7 | |
|
|
| 8 | DESCRIPTION |
|
|
| 9 | Oh well ;) Not much "introductory documentation" has been written yet :( |
|
|
| 10 | |
|
|
| 11 | NOTATION |
|
|
| 12 | Brackets around parameters indicate that the respective parameter is |
|
|
| 13 | optional and will be replaced with some default value when absent (or |
|
|
| 14 | "undef", which might be different in other packages). |
|
|
| 15 | |
|
|
| 16 | The sampling frequency and duration are by default (see individual |
|
|
| 17 | descriptions) given in cycles/sample (or samples in case of a duration). |
|
|
| 18 | That means if you want to specify a duration of two seconds, you have to |
|
|
| 19 | multiply by the sampling frequency in HZ, and if you want to specify a |
|
|
| 20 | frequency of 440 Hz, you have to divide by the sampling frequency: |
|
|
| 21 | |
|
|
| 22 | # Syntax: gen_oscil duration*, frequency/ |
|
|
| 23 | $signal = gen_oscil 2*HZ, 440/HZ; |
|
|
| 24 | # with a sampling frequency of 44100 Hertz: |
|
|
| 25 | $signal = gen_oscil 2*44100, 440/44100; |
|
|
| 26 | |
|
|
| 27 | To help you, the required unit is given as a type suffix in the |
|
|
| 28 | parameter name. A "/" means that you have to divide by the sampling |
|
|
| 29 | frequency (to convert from Hertz) and a suffix of "*" indicates that a |
|
|
| 30 | multiplication is required. |
|
|
| 31 | |
|
|
| 32 | Most parameters named "size", "duration" (or marked with "*") can be |
|
|
| 33 | replaced by a piddle, which is then used to give length and from |
|
|
| 34 | (mono/stereo). |
|
|
| 35 | |
|
|
| 36 | HEADER ATTRIBUTES |
|
|
| 37 | The following header attributes are stored and evaluated by most |
|
|
| 38 | functions. PDL::Audio provides mutator methods for all them (e.g. |
|
|
| 39 | |
|
|
| 40 | print "samplerate is ", $pdl->rate; |
|
|
| 41 | $pdl->comment("set the comment to this string"); |
|
|
| 42 | |
|
|
| 43 | rate |
|
|
| 44 | The sampling rate in hz. |
|
|
| 45 | |
|
|
| 46 | filetype |
|
|
| 47 | The filetype (wav, au etc..). Must be one of: |
|
|
| 48 | |
|
|
| 49 | FILE_NEXT FILE_AIFC FILE_RIFF FILE_BICSF FILE_NIST FILE_INRS FILE_ESPS |
|
|
| 50 | FILE_SVX FILE_VOC FILE_SNDT FILE_RAW FILE_SMP FILE_SD2 FILE_AVR |
|
|
| 51 | FILE_IRCAM FILE_SD1 FILE_SPPACK FILE_MUS10 FILE_HCOM FILE_PSION |
|
|
| 52 | FILE_MAUD FILE_IEEE FILE_DESKMATE FILE_DESKMATE_2500 FILE_MATLAB |
|
|
| 53 | FILE_ADC FILE_SOUNDEDIT FILE_SOUNDEDIT_16 FILE_DVSM FILE_MIDI |
|
|
| 54 | FILE_ESIGNAL FILE_SOUNDFONT FILE_GRAVIS FILE_COMDISCO FILE_GOLDWAVE |
|
|
| 55 | FILE_SRFS FILE_MIDI_SAMPLE_DUMP FILE_DIAMONDWARE FILE_REALAUDIO |
|
|
| 56 | FILE_ADF FILE_SBSTUDIOII FILE_DELUSION FILE_FARANDOLE FILE_SAMPLE_DUMP |
|
|
| 57 | FILE_ULTRATRACKER FILE_YAMAHA_SY85 FILE_YAMAHA_TX16 FILE_DIGIPLAYER |
|
|
| 58 | FILE_COVOX FILE_SPL FILE_AVI FILE_OMF FILE_QUICKTIME FILE_ASF |
|
|
| 59 | FILE_YAMAHA_SY99 FILE_KURZWEIL_2000 FILE_AIFF FILE_AU |
|
|
| 60 | |
|
|
| 61 | path |
|
|
| 62 | The filename (or file specification) used to load or save a file. |
|
|
| 63 | |
|
|
| 64 | format |
|
|
| 65 | Specifies the type the underlying file format uses. The samples will |
|
|
| 66 | always be in short or long signed format. |
|
|
| 67 | |
|
|
| 68 | Must be one of |
|
|
| 69 | |
|
|
| 70 | FORMAT_NO_SND FORMAT_16_LINEAR FORMAT_8_MULAW FORMAT_8_LINEAR |
|
|
| 71 | FORMAT_32_FLOAT FORMAT_32_LINEAR FORMAT_8_ALAW FORMAT_8_UNSIGNED |
|
|
| 72 | FORMAT_24_LINEAR FORMAT_64_DOUBLE FORMAT_16_LINEAR_LITTLE_ENDIAN |
|
|
| 73 | FORMAT_32_LINEAR_LITTLE_ENDIAN FORMAT_32_FLOAT_LITTLE_ENDIAN |
|
|
| 74 | FORMAT_64_DOUBLE_LITTLE_ENDIAN FORMAT_16_UNSIGNED |
|
|
| 75 | FORMAT_16_UNSIGNED_LITTLE_ENDIAN FORMAT_24_LINEAR_LITTLE_ENDIAN |
|
|
| 76 | FORMAT_32_VAX_FLOAT FORMAT_12_LINEAR FORMAT_12_LINEAR_LITTLE_ENDIAN |
|
|
| 77 | FORMAT_12_UNSIGNED FORMAT_12_UNSIGNED_LITTLE_ENDIAN COMPATIBLE_FORMAT |
|
|
| 78 | |
|
|
| 79 | PDL::Audio conviniently defines the following aliases for the |
|
|
| 80 | following constants, that are already correct for the host |
|
|
| 81 | byteorder: |
|
|
| 82 | |
|
|
| 83 | FORMAT_ULAW_BYTE FORMAT_ALAW_BYTE FORMAT_LINEAR_BYTE |
|
|
| 84 | FORMAT_LINEAR_SHORT FORMAT_LINEAR_USHORT FORMAT_LINEAR_LONG |
|
|
| 85 | FORMAT_LINEAR_FLOAT FORMAT_LINEAR_DOUBLE |
|
|
| 86 | |
|
|
| 87 | comment |
|
|
| 88 | The file comment (if any). |
|
|
| 89 | |
|
|
| 90 | device |
|
|
| 91 | The device to output audio. One of: |
|
|
| 92 | |
|
|
| 93 | DEV_DEFAULT DEV_READ_WRITE DEV_ADAT_IN DEV_AES_IN DEV_LINE_OUT |
|
|
| 94 | DEV_LINE_IN DEV_MICROPHONE DEV_SPEAKERS DEV_DIGITAL_IN DEV_DIGITAL_OUT |
|
|
| 95 | DEV_DAC_OUT DEV_ADAT_OUT DEV_AES_OUT DEV_DAC_FILTER DEV_MIXER |
|
|
| 96 | DEV_LINE1 DEV_LINE2 DEV_LINE3 DEV_AUX_INPUT DEV_CD_IN DEV_AUX_OUTPUT |
|
|
| 97 | DEV_SPDIF_IN DEV_SPDIF_OUT |
|
|
| 98 | |
|
|
| 99 | EXPORTED CONSTANTS |
|
|
| 100 | In addition to the exported constants described above (and later in the |
|
|
| 101 | function descriptions), this module also exports the mathematical |
|
|
| 102 | constants M_PI and M_2PI, so watch out for clashes! |
|
|
| 103 | |
|
|
| 104 | FUNCTIONS |
|
|
| 105 | sound_format_name format_code |
|
|
| 106 | Return the human-readable name of the file format with code |
|
|
| 107 | "format_code". |
|
|
| 108 | |
|
|
| 109 | sound_type_name type_code |
|
|
| 110 | Return the human-readable name of the sample type with code "type_code". |
|
|
| 111 | |
|
|
| 112 | describe_audio piddle |
|
|
| 113 | Describe the audio stream contained in piddle and return it as a string. |
|
|
| 114 | A fresh piddle might return: |
|
|
| 115 | |
|
|
| 116 | mono sound with 27411 samples |
|
|
| 117 | |
|
|
| 118 | Whereas a freshly loaded soundfile might yield: |
|
|
| 119 | |
|
|
| 120 | stereo sound with 27411 samples, original name "kongas.wav", type 2 (RIFF), |
|
|
| 121 | rate 11025/s (duration 2.49s), format 7 (8-bit unsigned) |
|
|
| 122 | |
|
|
| 123 | raudio path, [option-hash], option => value, ... |
|
|
| 124 | Reads audio data into the piddle. Options can be anything, most useful |
|
|
| 125 | values are "filetype", "rate", "channels" and "format". The returned |
|
|
| 126 | piddle is represents "time" in the outer dimension, and samples in the |
|
|
| 127 | inner (i.e. scalars for mono files, 2-vectors for stereo files): |
|
|
| 128 | |
|
|
| 129 | [ [left0, right0], [left1, right1], ... |
|
|
| 130 | |
|
|
| 131 | # read any file |
|
|
| 132 | $pdl = raudio "file.wav"; |
|
|
| 133 | # read a file. if it is a raw file preset values |
|
|
| 134 | $pdl = raudio "file.raw", filetype => FILE_RAW, rate => 44100, channels => 2; |
|
|
| 135 | |
|
|
| 136 | waudio pdl, [option-hash], option => value, ... |
|
|
| 137 | Writes a pdl as a file. The path is taken from the header (or the |
|
|
| 138 | options), e.g.: |
|
|
| 139 | |
|
|
| 140 | # write a file, using the header of another piddle |
|
|
| 141 | $pdl->waudio ($orig_file->gethdr); |
|
|
| 142 | # write pdl as au file, take rate from the header |
|
|
| 143 | $pdl->waudio (path => "piddle.au", filetype => FILE_AU, format => FORMAT_16_LINEAR; |
|
|
| 144 | |
|
|
| 145 | cut_leading_silence pdl, level |
|
|
| 146 | Cuts the leading silence (i.e. all samples with absolute value < level) |
|
|
| 147 | and returns the resulting part. |
|
|
| 148 | |
|
|
| 149 | cut_trailing_silence pdl, level |
|
|
| 150 | Cuts the trailing silence. |
|
|
| 151 | |
|
|
| 152 | cut_silence pdl, level |
|
|
| 153 | Calls "cut_leading_silence" and "cut_trailing_silence" and returns the |
|
|
| 154 | result. |
|
|
| 155 | |
|
|
| 156 | playaudio pdl, [option-hash], option => value ... |
|
|
| 157 | Play the piddle as an audio file. Options can be supplied either through |
|
|
| 158 | the option hash (a hash-reference), through the pdl header or the |
|
|
| 159 | options: |
|
|
| 160 | |
|
|
| 161 | # play a piddle that has a valid header (e.g. from raudio) |
|
|
| 162 | $pdl->playaudio; |
|
|
| 163 | # play it with a different samplerate |
|
|
| 164 | $pdl->playaudio(rate => 22050); |
|
|
| 165 | |
|
|
| 166 | ulaw2linear |
|
|
| 167 | Signature: (byte u(n); short [o] s(n)) |
|
|
| 168 | |
|
|
| 169 | conversion from (m)u-law into signed, linear, 16 bit samples (rather |
|
|
| 170 | slow) |
|
|
| 171 | |
|
|
| 172 | linear2ulaw |
|
|
| 173 | Signature: (short s(n); byte [o] u(n)) |
|
|
| 174 | |
|
|
| 175 | conversion from signed, linear, 16 bit samples into (m)u-law (rather |
|
|
| 176 | slow) |
|
|
| 177 | |
|
|
| 178 | alaw2linear |
|
|
| 179 | Signature: (byte u(n); short [o] s(n)) |
|
|
| 180 | |
|
|
| 181 | conversion from A-law into signed, linear, 16 bit samples (rather slow) |
|
|
| 182 | |
|
|
| 183 | linear2alaw |
|
|
| 184 | Signature: (short s(n); byte [o] u(n)) |
|
|
| 185 | |
|
|
| 186 | conversion from signed, linear, 16 bit samples into A-law (rather slow) |
|
|
| 187 | |
|
|
| 188 | gen_oscil duration*, freq/, phase-mod, [fm-mod/] |
|
|
| 189 | gen_sawtooth duration*, freq/, phase-mod, [fm-mod/] |
|
|
| 190 | gen_square duration*, freq/, phase-mod, duty, [fm-mod/] |
|
|
| 191 | gen_triangle duration*, freq/, phase-mod, [fm-mod/] |
|
|
| 192 | gen_pulse_train duration*, freq/, phase-mod, [fm-mod/] |
|
|
| 193 | gen_rand duration*, freq/ |
|
|
| 194 | gen_rand_1f duration* |
|
|
| 195 | All of these functions generate appropriate waveforms with frequency |
|
|
| 196 | "freq" (cycles/sample) and phase "phase" (0..1). |
|
|
| 197 | |
|
|
| 198 | The "duration" might be either a piddle (which gives the form of the |
|
|
| 199 | output) or the number of samples to generate. |
|
|
| 200 | |
|
|
| 201 | The output samples are between -1 and +1 (i.e. "-1 <= s <= +1"). |
|
|
| 202 | |
|
|
| 203 | The "duty" parameter of the square generator influences the duty cycle |
|
|
| 204 | of the signal. Zero means 50%-50%, 0.5 means 75% on, 25% off, -0.8 means |
|
|
| 205 | 10% on, 90% off etc... Of course, the "duty" parameter might also be a |
|
|
| 206 | vector of size "duration". |
|
|
| 207 | |
|
|
| 208 | gen_env duration*, xvals, yvals, [base] |
|
|
| 209 | Generates an interpolated envelope between the points given by xvals and |
|
|
| 210 | yvals. When base == 1 (the default) then the values will be linearly |
|
|
| 211 | interpolated, otherwise they follow an exponential curve that is bend |
|
|
| 212 | inwards (base < 1) or outwards (base > 1). |
|
|
| 213 | |
|
|
| 214 | # generate a linear envelope with attack in the first 10% |
|
|
| 215 | gen_env 5000, [0 1 2 9 10], [0 1 0.6 0.6 0]; |
|
|
| 216 | |
|
|
| 217 | gen_adsr duration*, sustain-level, attack-time, decay-time, sustain-time, release-time |
|
|
| 218 | Simple ADSR envelope generator. The "sustain-level" is the amplitude (0 |
|
|
| 219 | to 1) of the sustain level. The other for parameters give the relative |
|
|
| 220 | interval times, in any unit you like, only their relative ratios are |
|
|
| 221 | important. Any of these times might be zero, in which case the |
|
|
| 222 | corresponding part is omitted from the envelope. |
|
|
| 223 | |
|
|
| 224 | gen_asymmetric_fm duration*, freq/, phase, [r , [ratio]] |
|
|
| 225 | "gen_asymmetric_fm" provides a way around the symmetric spectra normally |
|
|
| 226 | produced by FM. See Palamin and Palamin, "A Method of Generating and |
|
|
| 227 | Controlling Asymmetrical Spectra" JAES vol 36, no 9, Sept 88, p671-685. |
|
|
| 228 | |
|
|
| 229 | gen_sum_of_cosines duration*, freq/, phase, ncosines, [fm_mod/] |
|
|
| 230 | Generates a sum of "n" cosines "(1 + 2(cos(x) + cos(2x) + ... cos(nx)) = |
|
|
| 231 | sin((n+.5)x) / sin(x/2))". Other arguments are similar to to |
|
|
| 232 | "gen_oscil". |
|
|
| 233 | |
|
|
| 234 | gen_sine_summation duration*, freq/, phase, [nsines, [a, [b_ratio, [fm_mod/]]]] |
|
|
| 235 | "gen_sine_summation" provides a kind of additive synthesis. See |
|
|
| 236 | J.A.Moorer, "Signal Processing Aspects of Computer Music" and "The |
|
|
| 237 | Synthesis of Complex Audio Spectra by means of Discrete Summation |
|
|
| 238 | Formulae" (Stan-M-5). The basic idea is very similar to that used in |
|
|
| 239 | gen_sum_of_cosines generator. |
|
|
| 240 | |
|
|
| 241 | The default value for "nsines" is 1 (but zero is a valid value), for "a" |
|
|
| 242 | is 0.5 and for "b_ratio" is 1. |
|
|
| 243 | |
|
|
| 244 | (btw, either my formula is broken or the output indeed does not lie |
|
|
| 245 | between -1 and +1, but rather -5 .. +5). |
|
|
| 246 | |
|
|
| 247 | gen_from_table duration*, frequency/, table, [phase], [fm_mod/] |
|
|
| 248 | "gen_from_table" generates a waveform by repeating a waveform given in |
|
|
| 249 | "table", linearly interpolating between successive points of the |
|
|
| 250 | "waveform". |
|
|
| 251 | |
|
|
| 252 | partials2waveshape size*, partials, amplitudes, [phase], [fm_mod/] |
|
|
| 253 | Take a (perl or pdl) list of (integer) "partials" and a list of |
|
|
| 254 | "amplitudes" and generate a single wave shape that results by adding |
|
|
| 255 | these partial sines. |
|
|
| 256 | |
|
|
| 257 | This could (and should) be used by the "gen_from_table" generator. |
|
|
| 258 | |
|
|
| 259 | gen_from_partials duration*, frequency/, partials, amplitudes, [phase], [fm_mod/] |
|
|
| 260 | Take a (perl list or pdl) list of (possibly noninteger) "partials" and a |
|
|
| 261 | list of "amplitudes" and generate the waveform resulting by summing up |
|
|
| 262 | all these partial sines. |
|
|
| 263 | |
|
|
| 264 | filter_one_zero |
|
|
| 265 | Signature: (in(n); [o] out(n); double a0; double a1) |
|
|
| 266 | |
|
|
| 267 | apply a one zero filter, y(n) = a0 x(n) + a1 x(n-1) |
|
|
| 268 | |
|
|
| 269 | filter_one_pole |
|
|
| 270 | Signature: (in(n); [o] out(n); double a0; double b1) |
|
|
| 271 | |
|
|
| 272 | apply a one pole filter, y(n) = a0 x(n) - b1 y(n-1) |
|
|
| 273 | |
|
|
| 274 | filter_two_zero |
|
|
| 275 | Signature: (in(n); [o] out(n); double a0; double a1; double a2) |
|
|
| 276 | |
|
|
| 277 | apply a two zero filter, y(n) = a0 x(n) + a1 x(n-1) + a2 x(n-2) |
|
|
| 278 | |
|
|
| 279 | filter_two_pole |
|
|
| 280 | Signature: (in(n); [o] out(n); double a0; double b1; double b2) |
|
|
| 281 | |
|
|
| 282 | apply a two pole filter, y(n) = a0 x(n) - b1 y(n-1) - b2 y(n-2) |
|
|
| 283 | |
|
|
| 284 | filter_formant |
|
|
| 285 | Signature: (in(n); [o] out(n); double radius; double frequency; double gain) |
|
|
| 286 | |
|
|
| 287 | apply a formant filter, y(n) = x(n) - r*x(n-2) + |
|
|
| 288 | 2*r*cos(2*pi*frequency)*y(n-1) - r*r*y(n-2). A good value for "gain" is |
|
|
| 289 | 1. |
|
|
| 290 | |
|
|
| 291 | filter_ppolar pdl, radius/, frequency/ |
|
|
| 292 | apply a two pole filter (given in polar form). The filter has two poles, |
|
|
| 293 | one at (radius,frequency), the other at (radius,-frequency). Radius is |
|
|
| 294 | between 0 and 1 (but less than 1), and frequency is between 0 and 0.5. |
|
|
| 295 | This is the standard resonator form with poles specified by the polar |
|
|
| 296 | coordinates of one pole. |
|
|
| 297 | |
|
|
| 298 | filter_zpolar pdl, radius/, frequency/ |
|
|
| 299 | apply a two zero filter (given in polar form). See "filter_ppolar". |
|
|
| 300 | |
|
|
| 301 | partials2polynomial partials, [kind] |
|
|
| 302 | "partials2polynomial" takes a list of harmonic amplitudes and returns a |
|
|
| 303 | list of Chebychev polynomial coefficients. The argument "kind" |
|
|
| 304 | determines which kind of Chebychev polynomial we are interested in, 1st |
|
|
| 305 | kind or 2nd kind. (default is 1). |
|
|
| 306 | |
|
|
| 307 | ring_modulate in1, in2 |
|
|
| 308 | ring modulates in1 with in2 (this is just a multiply). |
|
|
| 309 | |
|
|
| 310 | amplitude_modulate am_carrier, in1, in2 |
|
|
| 311 | amplitude modulates am_carrier and in2 with in1 (this calculates in1 * |
|
|
| 312 | (am_carrier + in2)). |
|
|
| 313 | |
|
|
| 314 | filter_sir |
|
|
| 315 | Signature: (x(n); a(an); b(bn); [o]y(n)) |
|
|
| 316 | |
|
|
| 317 | Generic (short delay) impulse response filter. "x" is the input signal |
|
|
| 318 | (which is supposed to be zero for negative indices). "a" contains the |
|
|
| 319 | input (x) coefficients (a0, a1, .. an), whereas "b" contains the output |
|
|
| 320 | (y) coefficients (b0, b1, ... bn), i.e.: |
|
|
| 321 | |
|
|
| 322 | y(n) = a0 x(n) - b1 y(n-1) + a1 x(n-1) - b2 y(n-2) + a2 x(n-2) - b3 ... |
|
|
| 323 | |
|
|
| 324 | This can be used to generate fir and iir filters of any length, or even |
|
|
| 325 | more complicated constructs. |
|
|
| 326 | |
|
|
| 327 | "b0" (then first element of "b") is being ignored currently AND SHOULD |
|
|
| 328 | BE SPECIFIED AS ONE FOR FUTURE COMPATIBILITY |
|
|
| 329 | |
|
|
| 330 | filter_lir |
|
|
| 331 | Signature: (x(n); int a_x(an); a_y(an); int b_x(bn); b_y(bn); [o]y(n)) |
|
|
| 332 | |
|
|
| 333 | Generic (long delay) impulse response filter. The difference to |
|
|
| 334 | "filter_sir" is that the filter coefficients need not be consecutive, |
|
|
| 335 | but instead their indices are given by the "a_x" and "b_x" (integer) |
|
|
| 336 | vectors, while the corresponding coefficients are in "a_y" and "b_y". |
|
|
| 337 | (All "a_x" must be >= 0, while all the "b_x" must be >= 1, as you should |
|
|
| 338 | expect). |
|
|
| 339 | |
|
|
| 340 | See "filter_sir" for more info. |
|
|
| 341 | |
|
|
| 342 | filter_fir input, xcoeffs |
|
|
| 343 | Apply a fir (finite impulse response) filter to "input". This is the |
|
|
| 344 | same as calling: |
|
|
| 345 | |
|
|
| 346 | filter_sir input, xcoeffs, pdl() |
|
|
| 347 | |
|
|
| 348 | filter_iir input, ycoeffs |
|
|
| 349 | Apply a iir (infinite impulse response) filter to "input". This is just |
|
|
| 350 | another way of saying: |
|
|
| 351 | |
|
|
| 352 | filter_sir input, pdl(1), ycoeffs |
|
|
| 353 | |
|
|
| 354 | That is, the first member of "ycoeffs" is being ignored AND SHOULD BE |
|
|
| 355 | SPECIFIED AS ONE FOR FUTURE COMPATIBILITY! |
|
|
| 356 | |
|
|
| 357 | filter_comb input, delay*, scaler |
|
|
| 358 | Apply a comb filter to the piddle "input". This is implemented using a |
|
|
| 359 | delay line of length "delay" (which must be 1 or larger and can be |
|
|
| 360 | non-integer) and a feedback scaler. |
|
|
| 361 | |
|
|
| 362 | y(n) = x(n-size-1) + scaler * y(n-size) |
|
|
| 363 | |
|
|
| 364 | cf. "filter_notch" and |
|
|
| 365 | http://www.harmony-central.com/Effects/Articles/Reverb/comb.html |
|
|
| 366 | |
|
|
| 367 | filter_notch input, delay*, scaler |
|
|
| 368 | Apply a comb filter to the piddle "input". This is implemented using a |
|
|
| 369 | delay line of length "delay" (which must be 1 or larger and can be |
|
|
| 370 | non-integer) and a feedforward scaler. |
|
|
| 371 | |
|
|
| 372 | y(n) = x(n-size-1) * scaler + y(n-size) |
|
|
| 373 | |
|
|
| 374 | As a rule of thumb, the decay time of the feedback part is |
|
|
| 375 | "7*delay/(1-scaler)" samples, so to get a decay of Dur seconds, "scaler |
|
|
| 376 | <= 1-7*delay/(Dur*Srate)". The peak gain is "1/(1-(abs scaler))". The |
|
|
| 377 | peaks (or valleys in notch's case) are evenly spaced at "srate/delay". |
|
|
| 378 | The height (or depth) thereof is determined by scaler -- the closer to |
|
|
| 379 | 1.0, the more pronounced. See Julius Smith's "An Introduction to Digital |
|
|
| 380 | Filter Theory" in Strawn "Digital Audio Signal Processing", or Smith's |
|
|
| 381 | "Music Applications of Digital Waveguides" |
|
|
| 382 | |
|
|
| 383 | filter_allpass input, delay*, scaler-feedback, scaler-feedforward |
|
|
| 384 | "filter_allpass" or "moving average comb" is just like "filter_comb" but |
|
|
| 385 | with an added feedforward term. If "scaler-feedback == 0", we get a |
|
|
| 386 | moving average comb filter. If both scaler terms == 0, we get a pure |
|
|
| 387 | delay line. |
|
|
| 388 | |
|
|
| 389 | y(n) = feedforward*x(n-1) + x(n-size-1) + feedback*y(n-size) |
|
|
| 390 | |
|
|
| 391 | cf. http://www.harmony-central.com/Effects/Articles/Reverb/allpass.html |
|
|
| 392 | |
|
|
| 393 | design_remez_fir filter_size, bands(2,b), desired_gain(b), type, [weight(b)] |
|
|
| 394 | Calculates the optimal (in the Chebyshev/minimax sense) FIR filter |
|
|
| 395 | impulse response given a set of band edges, the desired reponse on those |
|
|
| 396 | bands, and the weight given to the error in those bands, using the |
|
|
| 397 | Parks-McClellan exchange algorithm. |
|
|
| 398 | |
|
|
| 399 | The first argument sets the filter size: "design_remez_fir" returns as |
|
|
| 400 | many coefficients as specified by this parameter. |
|
|
| 401 | |
|
|
| 402 | "bands" is a vector of band edge pairs (start - end), which specify the |
|
|
| 403 | start and end of the bands in the filter specification. These must be |
|
|
| 404 | non-overlapping and sorted in increasing order. Only values between 0 (0 |
|
|
| 405 | Hz) and 0.5 (the Nyquist frequency) are allowed. |
|
|
| 406 | |
|
|
| 407 | "des" specifies the desired gain in these bands. |
|
|
| 408 | |
|
|
| 409 | "weight" can be used to give each band a different weight. If absent, a |
|
|
| 410 | vector of ones is used. |
|
|
| 411 | |
|
|
| 412 | "type" is any of the exported constants "BANDPASS", "DIFFERENTIATOR" or |
|
|
| 413 | "HILBERT" and can be used to select various design types (use "BANDPASS" |
|
|
| 414 | until this is documented ;) |
|
|
| 415 | |
|
|
| 416 | filter_src input, srate, [width], [sr-mod] |
|
|
| 417 | Generic sampling rate conversion, implemented by convoluting "input" |
|
|
| 418 | with a sinc function of size "width" (default when unspecified or zero: |
|
|
| 419 | 5). |
|
|
| 420 | |
|
|
| 421 | "srate" determines the input rate / output rate ratio, i.e. values > 1 |
|
|
| 422 | speed up, values < 1 slow down. Values < 0 are allowed and reverse the |
|
|
| 423 | signal. |
|
|
| 424 | |
|
|
| 425 | If "sr_mod" is omitted, the size of the output piddle is calculcated as |
|
|
| 426 | "length(input)/abs(srate)", e.g. it provides the full stretched or |
|
|
| 427 | shrinked input signal. |
|
|
| 428 | |
|
|
| 429 | If "sr_mod" is specified it must be as large as the desired output, i.e. |
|
|
| 430 | it's size determines the output size. Each value in "sr_mod" is added to |
|
|
| 431 | "srate" at the given point in "time", so it can be used to "modulate" |
|
|
| 432 | the sampling rate change. |
|
|
| 433 | |
|
|
| 434 | # create a sound effect in the style of "Forbidden Planet" |
|
|
| 435 | $osc = 0.3 * gen_oscil $osc, 30 / $pdl->rate; |
|
|
| 436 | $output = filter_src($input, 1, 0, $osc); |
|
|
| 437 | |
|
|
| 438 | filter_contrast_enhance input, enhancement |
|
|
| 439 | Contrast-enhancement phase-modulates a sound file. It's like audio MSG. |
|
|
| 440 | The actual algorithm is (applied to the normalised sound) |
|
|
| 441 | "sin(input*pi/2 + (enhancement*sin(input*2*pi)))". The result is to |
|
|
| 442 | brighten the sound, helping it cut through a huge mix. |
|
|
| 443 | |
|
|
| 444 | filter_granulate input, expansion, [option-hash], option => value... |
|
|
| 445 | "filter_granulate" "granulates" the sound file file. It is the poor |
|
|
| 446 | man's way to change the speed at which things happen in a recorded sound |
|
|
| 447 | without changing the pitches. It works by slicing the input file into |
|
|
| 448 | short pieces, then overlapping these slices to lengthen (or shorten) the |
|
|
| 449 | result; this process is sometimes known as granular synthesis, and is |
|
|
| 450 | similar to the "freeze" function. The duration of each slice is "length" |
|
|
| 451 | -- the longer, the more like reverb the effect. The portion of the |
|
|
| 452 | length (on a scale from 0 to 1.0) spent on each ramp (up or down) is |
|
|
| 453 | "ramp". This can control the smoothness of the result of the overlaps. |
|
|
| 454 | The more-or-less average time between successive segments is "hop". The |
|
|
| 455 | accuracy at which we handle this hopping is set by the float "jitter" -- |
|
|
| 456 | if "jitter" is very small, you may get an annoying tremolo. The overall |
|
|
| 457 | amplitude scaler on each segment is "scaler" -- this is used to try to |
|
|
| 458 | to avoid overflows as we add all these zillions of segments together. |
|
|
| 459 | "expansion" determines the input hop in relation to the output hop; an |
|
|
| 460 | expansion-amount of 2.0 should more or less double the length of the |
|
|
| 461 | original, whereas an expansion-amount of 1.0 should return something |
|
|
| 462 | close to the original speed. |
|
|
| 463 | |
|
|
| 464 | The defaults for the arguments/options are: |
|
|
| 465 | |
|
|
| 466 | expansion 1.0 |
|
|
| 467 | length(*) 0.15 |
|
|
| 468 | scaler 0.6 |
|
|
| 469 | hop(*) 0.05 |
|
|
| 470 | ramp 0.4 |
|
|
| 471 | jitter(*) 0.5 |
|
|
| 472 | maxsize infinity |
|
|
| 473 | |
|
|
| 474 | The parameters/options marked with (*) actually depend on the sampling |
|
|
| 475 | rate, and are always multiplied by the "rate" attribute of the piddle |
|
|
| 476 | internally. If the piddle lacks that attribute, 44100 is assumed. NOTE: |
|
|
| 477 | This is different to most other filters, but should be ok since |
|
|
| 478 | "filter_granulate" only makes sense for audiofiles. |
|
|
| 479 | |
|
|
| 480 | audiomix pos1, data1, pos2, data2, ... |
|
|
| 481 | Generate a mix of all given piddles. The resulting piddle will contain |
|
|
| 482 | the sum of all data-piddles at their respective positions, so some |
|
|
| 483 | scaling will be necessary before or after the mixing operation (e.g. |
|
|
| 484 | scale2short). |
|
|
| 485 | |
|
|
| 486 | # mix the sound gong1 at position 0, the sound bass5 at position 22100 |
|
|
| 487 | # and gong2 at position 44100. The resulting piddle will be large enough |
|
|
| 488 | # to accomodate all the sounds: |
|
|
| 489 | $mix = audiomix 0, $gong1, 44100, $gong2, 22100, $gong2 |
|
|
| 490 | |
|
|
| 491 | filter_center piddle |
|
|
| 492 | Normalize the piddle so that it is centered around "y = 0" and has |
|
|
| 493 | maximal amplitude of 1. |
|
|
| 494 | |
|
|
| 495 | scale2short piddle |
|
|
| 496 | This method takes a sound in any format (preferably float or double) and |
|
|
| 497 | scales it to fit into a signed short value, suitable for playback using |
|
|
| 498 | "playudio" or similar functions. |
|
|
| 499 | |
|
|
| 500 | gen_fft_window size*, type, [$beta] |
|
|
| 501 | Creates and returns a specific fft window. The "type" is any of the |
|
|
| 502 | following. These are (case-insensitive) strings, so you might need to |
|
|
| 503 | quote them. |
|
|
| 504 | |
|
|
| 505 | RECTANGULAR just ones (the identity window) |
|
|
| 506 | HANNING 0.50 - 0.50 * cos (0 .. 2pi) |
|
|
| 507 | HAMMING 0.54 - 0.46 * cos (0 .. 2pi) |
|
|
| 508 | WELCH 1 - (-1 .. 1) ** 2 |
|
|
| 509 | PARZEN the triangle window |
|
|
| 510 | BARTLETT the symmetric triangle window |
|
|
| 511 | BLACKMAN2 blackman-harris window of order 2 |
|
|
| 512 | BLACKMAN3 blackman-harris window of order 3 |
|
|
| 513 | BLACKMAN4 blackman-harris window of order 4 |
|
|
| 514 | EXPONENTIAL the exponential window |
|
|
| 515 | KAISER the kaiser/bessel window (using the parameter C<beta>) |
|
|
| 516 | CAUCHY the cauchy window (using the parameter <beta>) |
|
|
| 517 | POISSON the poisson window (exponential using parameter C<beta>) |
|
|
| 518 | RIEMANN the riemann window (sinc) |
|
|
| 519 | GAUSSIAN the gaussian window of order C<beta>) |
|
|
| 520 | TUKEY the tukey window (C<beta> specifies how much of the window |
|
|
| 521 | consists of ones). |
|
|
| 522 | COSCOS the cosine-squared window (a partition of unity) |
|
|
| 523 | SINC same as RIEMANN |
|
|
| 524 | HANN same as HANNING (his name was Hann, not Hanning) |
|
|
| 525 | |
|
|
| 526 | LIST this "type" is special in that it returns a list of all types |
|
|
| 527 | |
|
|
| 528 | cplx(2,n) = rfft real(n) |
|
|
| 529 | Do a (complex fft) of "real" (extended to complex so that the imaginary |
|
|
| 530 | part is zero), and return the complex fft result. This function tries to |
|
|
| 531 | use PDL::FFTW (which is faster for large vectors) when available, and |
|
|
| 532 | falls back to PDL::FFT, which is likely to return different phase signs |
|
|
| 533 | (due to different kernel functions), so beware! In fact, since "rfft" |
|
|
| 534 | has to shuffle the data when using PDL::FFT, the fallback is always |
|
|
| 535 | slower. |
|
|
| 536 | |
|
|
| 537 | When using PDL::FFTW, a wisdom file ~/.pdl_wisdom is used and updated, |
|
|
| 538 | if possible. |
|
|
| 539 | |
|
|
| 540 | real(n) = irfft cplx(2,n) |
|
|
| 541 | The inverse transformation (see "rfft"). "irfft rfft $pdl == $pdl" |
|
|
| 542 | always holds. |
|
|
| 543 | |
|
|
| 544 | spectrum data, [norm], [window], [beta] |
|
|
| 545 | Returns the spectrum of a given pdl. If "norm" is absent (or "undef"), |
|
|
| 546 | it returns the magnitude of the fft of "data". When "norm" == 1 (or "eq |
|
|
| 547 | 'NORM'", case-insensitive), it returns the magnitude, normalized to be |
|
|
| 548 | between zero and one. If "norm" == 0 (or "eq 'dB'", case-insensitive), |
|
|
| 549 | then it returns the magnitude in dB. |
|
|
| 550 | |
|
|
| 551 | "data" is multiplied with "window" (if not "undef") before calculating |
|
|
| 552 | the fft, and usually contains a window created with "gen_fft_window" |
|
|
| 553 | (using "beta"). If "window" is a string, it is handed over to |
|
|
| 554 | "gen_fft_window" (together with the beta parameter) to create a window |
|
|
| 555 | of suitable size. |
|
|
| 556 | |
|
|
| 557 | This function could be slightly faster. |
|
|
| 558 | |
|
|
| 559 | concat pdl, pdl... |
|
|
| 560 | This is not really an audio-related function. It simply takes all |
|
|
| 561 | piddles and concats them into a larger one. At the moment it only |
|
|
| 562 | supports single-dimensional piddles and is implemented quite slowly |
|
|
| 563 | using perl and data-copying, but that might change... |
|
|
| 564 | |
|
|
| 565 | filter_convolve |
|
|
| 566 | Signature: (input(n); kernel(m); int fftsize(); [o]output(n)) |
|
|
| 567 | |
|
|
| 568 | info not available |
|
|
| 569 | |
|
|
| 570 | rshift |
|
|
| 571 | Signature: (x(n); int shift(); c(); [oca]y(n)) |
|
|
| 572 | |
|
|
| 573 | Shift vector elements without wrap and fill the free space with a |
|
|
| 574 | constant. Flows data back & forth, for values that overlap. |
|
|
| 575 | |
|
|
| 576 | Positive values shift right, negative values shift left. |
|
|
| 577 | |
|
|
| 578 | polynomial |
|
|
| 579 | Signature: (coeffs(n); x(m); [o]out(m)) |
|
|
| 580 | |
|
|
| 581 | evaluate the polynomial with coefficients "coeffs" at the position(s) |
|
|
| 582 | "x". "coeffs[0]" is the constant term. |
|
|
| 583 | |
|
|
| 584 | linear_interpolate |
|
|
| 585 | Signature: (x(); fx(n); fy(n); [o]y()) |
|
|
| 586 | |
|
|
| 587 | Look up the ordinate "x" in the function given by "fx" and "fy" and |
|
|
| 588 | return a linearly interpolated value (somewhat optimized for many |
|
|
| 589 | lookups). |
|
|
| 590 | |
|
|
| 591 | "fx" specifies the ordinates (x-coordinates) of the function and most be |
|
|
| 592 | sorted in increasing order. "fy" are the y-coordinates of the function |
|
|
| 593 | in these points. |
|
|
| 594 | |
|
|
| 595 | bessi0 |
|
|
| 596 | Signature: (a(); [o]b()) |
|
|
| 597 | |
|
|
| 598 | calculate the (approximate) modified bessel function of the first kind |
|
|
| 599 | |
|
|
| 600 | fast_sin |
|
|
| 601 | Signature: (r(n); [o]s(n)) |
|
|
| 602 | |
|
|
| 603 | fast sine function (inaccurate table lookup with ~12 bits precision) |
|
|
| 604 | |
|
|
| 605 | AUTHOR |
|
|
| 606 | Marc Lehmann <schmorp@schmorp.de>. The ideas were mostly taken from |
|
|
| 607 | common lisp music (CLM), by Bill Schottstaedt "bil@ccrma.stanford.edu". |
|
|
| 608 | I also borrowed many explanations (and references) from the clm docs and |
|
|
| 609 | some code from clm.c. Highly inspiring! |
|
|
| 610 | |
|
|
| 611 | SEE ALSO |
|
|
| 612 | perl(1), PDL. |
|
|
| 613 | |
|
|
