partikkel — Granular synthesizer with "per grain" control over many of its parameters. Has a sync input to sychronize its internal grain scheduler clock to an external clock source.
partikkel was conceived after reading Curtis Roads' book "Microsound", and the goal was to create an opcode that was capable of all time-domain varieties of granular synthesis described in this book. The idea being that most of the techniques only differ in parameter values, and by having a single opcode that can do all varieties of granular synthesis makes it possible to interpolate between techniques. Granular synthesis is sometimes dubbed particle synthesis, and it was thought apt to name the opcode partikkel to distinguish it from other granular opcodes.
Some of the input parameters to partikkel is table numbers, pointing to tables where values for the "per grain" parameter changes are stored. partikkel can use single-cycle or complex (e.g. sampled sound) waveforms as source waveforms for grains. Each grain consists of a mix of 4 source waveforms. Individual tuning of the base frequency can be done for each of the 4 source waveforms. Frequency modulation inside each grain is enabled via an auxillary audio input (awavfm). Trainlet synthesis is available, and trainlets can be mixed with wavetable based grains. Up to 8 separate audio outputs can be used. Fractional output values will distribute a grain between two outputs and a "panning law" table can be devised to control the amplitude scaling between output pairs.
a1 [, a2, a3, a4, a5, a6, a7, a8] partikkel agrainfreq, \
kdistribution, idisttab, async, kenv2amt, ienv2tab, ienv_attack, \
ienv_decay, ksustain_amount, ka_d_ratio, kduration, kamp, igainmasks, \
kwavfreq, ksweepshape, iwavfreqstarttab, iwavfreqendtab, awavfm, \
ifmamptab, kfmenv, icosine, ktraincps, knumpartials, kchroma, \
ichannelmasks, krandommask, kwaveform1, kwaveform2, kwaveform3, \
kwaveform4, iwaveamptab, asamplepos1, asamplepos2, asamplepos3, \
asamplepos4, kwavekey1, kwavekey2, kwavekey3, kwavekey4, imax_grains \
[, iopcode_id, ipanlaws]
idisttab -- function table number, distribution for random grain displacements over time. The table values are interpreted as "displacement amount" scaled by 1/grainrate. This means that a value of 0.5 in the table will displace a grain by half the grainrate period. The table values are read randomly, and scaled by kdistribution. For realistic stochastic results, it is advisable not to use a too small table size, as this limits the amount of possible displacement values. This can also be utilized for other purposes, e.g. using quantized displacement values to work with controlled time displacement from the periodic grain rate. If kdistribution is negative, the table values will be read sequentially. A default table might be selected by using -1 as the ftable number, for idisttab the default uses a zero distribution (no displacement).
ienv_attack -- function table number, attack shape of grain. Needs extended guard point. A default table might be selected by using -1 as the ftable number, for ienv_attack the default uses a square window (no enveloping).
ienv_decay -- function table number, decay shape of grain. Needs extended guard point. A default table might be selected by using -1 as the ftable number, for ienv_decay the default uses a square window (no enveloping).
ienv2tab -- function table number, additional envelope applied to grain, done after attack and decay envelopes. Can be used e.g. for fof formant synthesis. Needs extended guard point. A default table might be selected by using -1 as the ftable number, for ienv2tab the default uses a square window (no enveloping).
icosine -- function table number, must contain a cosine, used for trainlets. Table size should be at least 2048 for good quality trainlets.
igainmasks -- function table number, gain per grain. The sequence of values in the table is as follows: index 0 is used as a loop start point in reading the values, index 1 is used as a loop end point. Remaining indices contain gain values (normally in range 0 - 1, but other values are allowed, negative values will invert phase of waveform inside grain) for a sequence of grains, these are read at grain rate enabling exact patterns of "gain per grain". The loop start and end points are zero based with an origin at index 2, e.g. a loop start value of 0 and loop end value of 3 will read indices 2,3,4,5 in a loop at grain rate. A default table might be selected by using -1 as the ftable number, for igainmasks the default disables gain masking (all grains are given a gain masking value of 1).
ichannelmasks -- function table number, see igainmasks for a description of how the values in the table are read. Range is 0 to N, where N is the number of output channels. A value of zero will send the grain to audio output 1 from the opcode. Fractional values are allowed, e.g. a value of 3.5 will mix the grain equally to outputs 4 and 5. The channelmask value wraps around from the last to the first output, so that a vaalue of N-0.5 will mix the grain equally between the last and the first output. If another panning law between outputs is desired, this can be described in the ipanlaws table. The user is responsible for keeping the values in range, the opcode will crash with out of range values. A default table might be selected by using -1 as the ftable number, for ichannelmasks the default disables channel masking (all grains are given a channel masking value of 0 and are sent to partikkel audio out 1).
iwavfreqstarttab -- function table number, see igainmasks for a description of how the values in the table are read. Start frequency multiplicator for each grain. Pitch will glide from start frequency to end frequency following a line or curve as set by ksweepshape. A default table might be selected by using -1 as the ftable number, for iwavfreqstarttab the default uses a multiplicator of 1, disabling any start frequency modification.
iwavfreqendtab -- function table number, see iwavfreqstarttab. End frequency multiplicator for each grain. A default table might be selected by using -1 as the ftable number, for iwavfreqendtab the default uses a multiplicator of 1, disabling any end frequency modification.
ifmamptab -- function table number, see igainmasks for a description of how the values in the table are read. Frequency modulation index per grain. The signal awavfm will be multiplied by values read from this table. A default table might be selected by using -1 as the ftable number, for ifmamptab the default uses 1 as the index multiplicator, enabling fm for all grains.
iwaveamptab -- function table number, the indices are read in a similar way to what is used for igainmasks. Index 0 is used as a loop start point, and index 1 is used as a loop end point. The rest of the indices are read in groups of 5, where each value represent a gain value for each of the 4 source waveforms, and the 5th value represent trainlet amplitude. A default table might be selected by using -1 as the ftable number, for iwaveamptab the default uses an equal mix of all 4 source waveforms (each with an amplitude of 0.5) and setting trainlet amp to zero.
Computation of trainlets can be CPU intensive, and setting ktrainamp to zero will skip most of the trainlet computations. Trainlets will be normalized to peak (ktrainamp), compensating for amplitude variations caused by variations in kpartials and kchroma.
imax_grains -- maximum number of grains per k-period. Estimating a large value should not affect performance, exceeding this value will lead to "oldest grains" being deleted.
iopcode_id -- the opcode id, linking an instance of partikkel to an instance of partikkelsync, the linked partikkelsync will output trigger pulses synchronized to partikkel's grain maker scheduler. The default value is zero, which means no connection to any partikkelsync instances.
ipanlaws -- function table number. The table describes the panning curve used for fractional channelmask values. Fractional channelmask values will mix a grain to two neighbouring outputs, with the relative gain set by the fractional value. By default (if no ipanlaws table is described, a linear gain relationship is used, so that a channelmask value of e.g. 1.5 distributes the grain with 0.5 gain to output 2 and 0.5 gain to output 3. The ipanlaws table can be used to describe other gain control curves (panning laws). The table should contain 8 such gain control curves, each governing the panning between two neighbouring outputs. The curves should appear one after another in the table, in a concatenated fashion. GEN 18 can be used to create this table from separate panning curve tables (see example below). The first curve describes the panning law between output 1 and output 2, the next is for panning between outputs 2 and 3, and so on. The last curve describes the panning law between the last and the first output. The table is indexed by the channelmask value such that one output (of an output pair goverened by the panning law) uses the index (tablesize/8*channelmask) while the other of the two outputs reads the value at index (tablesize/8*(int(channelmask+1)-frac(channelmask))). This means that if the panning law value halfway between these two channel masks is e.g. 0.7 (which would give approximately equal power panning), then each of those two outputs will use 0.7 as the gain value.
xgrainfreq -- number of grains per second. A value of zero is allowed, and this will defer all grain scheduling to the sync input.
async -- sync input. Input values are added to the phase value of the internal grain maker clock, enabling tempo synchronization with an external clock source. As this is an a-rate signal, inputs are usually pulses of length 1/sr. Using such pulses, the internal phase value can be "nudged" up or down, enabling soft or hard synchronization. Negative input values decrements the internal phase, while positive values in the range 0 to 1 increments the internal phase. An input value of 1 will always make partikkel generate a grain. If the value remains at 1, the internal grain scheduler clock will pause but any currently playing grains will still play to end.
kdistribution -- periodic or stochastic distribution of grains, 0 = periodic. Stochastic grain displacement is in the range of kdistribution/grainrate seconds. The stochastic distribution profile (random distribution) can be set in the idisttab table. If kdistribution is negative, the result is deterministic time displacement as described by idisttab (sequential read of displacement values). Maximum grain displacement in all cases is limited to 10 seconds, and a grain will keep the values (duration, pitch etc) it was given when it was first generated (before time displacement). Since grain displacement is relative to the grain rate, displacement amount is undefined at 0Hz grain rate and kdistribution is completely disabled in this case.
kenv2amt -- amount of enveloping for the secondary envelope for each grain. Range 0 to 1, where 0 is no secondary enveloping (square window), a value of 0.5 will use an interpolation between a square window and the shape set by ienv2tab.
ksustain_amount -- sustain time as fraction of grain duration. I.e. balance between enveloped time(attack+decay) and sustain level time. The sustain level is taken from the last value of the ienv_attack ftable.
ka_d_ratio -- balance between attack time and decay time. For example, with ksustain_amount set to 0.5 and ka_d_ratio set to 0.5, the attack envelope of each grain will take 25% of the grain duration, full amplitude (sustain) will be held for 50% of the grain duration, and the decay envelope will take the remaining 25% of the grain duration.
kduration -- grain duration in milliseconds.
kamp -- amplitude scaling of the opcode's output. Multiplied by per grain amplitude read from igainmasks. Source waveform playback inside grains can consume a significant amount of CPU cycles, especially if grain duration is long so that we have a lot of overlapping grains. Setting kamp to zero will skip waveform playback inside grains (and not generate any sound, obviously). This can be used as a "soft" bypass method if we want to keep the opcode active but silent for some periods of time.
kwavfreq -- transposition scaling. Multiplied with start and end transposition values read from iwavfreqstarttab and iwavfreqendtab.
ksweepshape -- transposition sweep shape, controls the curvature of the transposition sweep. Range 0 to 1. Low values will hold the transposition at the start value longer and then drop to the end value quickly, high values will drop to the end value quickly. A value of 0.5 will give a linear sweep. A value of exactly 0 will bypass sweep and only use the start frequency, while a value of exactly 1 will bypass sweep and only use the end frequency. The sweep generator might be slightly inaccurate in hitting the end frequency when using a steep curve and very long grains.
awavfm -- audio input for frequency modulation inside grain.
kfmenv -- function table number, envelope for FM modulator signal enabling the modulation index to change over the duration of a grain.
ktraincps -- trainlet fundamental frequency.
knumpartials -- number of partials in trainlets.
kchroma -- chroma of trainlets. A value of 1 give equal amplitude to each partial, higher values will reduce the amplitude of lower partials while strengthening the amplitude of the higher partials.
krandommask -- random masking (muting) of individual grains. Range 0 to 1, where a value of 0 will give no masking (all grains are played), and a value of 1 will mute all grains.
kwaveform1 -- table number for source waveform 1.
kwaveform2 -- table number for source waveform 2.
kwaveform3 -- table number for source waveform 3.
kwaveform4 -- table number for source waveform 4.
asamplepos1 -- start position for reading source waveform 1 (in range 0..1).
asamplepos2 -- start position for reading source waveform 2.
asamplepos3 -- start position for reading source waveform 3.
asamplepos4 -- start position for reading source waveform 4.
kwavekey1 -- original key of source waveform 1. Can be used to transpose each source waveform independently.
kwavekey2 -- as kwavekey1, but for source waveform 2.
kwavekey3 -- as kwavekey1, but for source waveform 3.
kwavekey4 -- as kwavekey1, but for source waveform 4.
Here is an example of the partikkel opcode. It uses the file partikkel.csd.
Example 734. Example of the partikkel opcode.
See the sections Real-time Audio and Command Line Flags for more information on using command line flags.
<CsoundSynthesizer> <CsOptions> ; Select audio/midi flags here according to platform -odac ;;;realtime audio out ;-iadc ;;;uncomment -iadc if real audio input is needed too ; For Non-realtime ouput leave only the line below: ; -o partikkel.wav -W ;;; for file output any platform </CsOptions> <CsInstruments> sr = 44100 ksmps = 20 nchnls = 2 giSine ftgen 0, 0, 65537, 10, 1 giCosine ftgen 0, 0, 8193, 9, 1, 1, 90 instr 1 kgrainfreq = 200 ; 4 grains per second kdistribution = 0 ; periodic grain distribution idisttab = -1 ; (default) flat distribution used for grain distribution async = 0 ; no sync input kenv2amt = 0 ; no secondary enveloping ienv2tab = -1 ; default secondary envelope (flat) ienv_attack = -1 ; ; default attack envelope (flat) ienv_decay = -1 ; ; default decay envelope (flat) ksustain_amount = 0.5 ; time (in fraction of grain dur) at sustain level for each grain ka_d_ratio = 0.5 ; balance between attack and decay time kduration = (0.5/kgrainfreq)*1000 ; set grain duration relative to grain rate kamp = 5000 ; amp igainmasks = -1 ; (default) no gain masking kwavfreq = 440 ; fundamental frequency of source waveform ksweepshape = 0 ; shape of frequency sweep (0=no sweep) iwavfreqstarttab = -1 ; default frequency sweep start (value in table = 1, which give no frequency modification) iwavfreqendtab = -1 ; default frequency sweep end (value in table = 1, which give no frequency modification) awavfm = 0 ; no FM input ifmamptab = -1 ; default FM scaling (=1) kfmenv = -1 ; default FM envelope (flat) icosine = giCosine ; cosine ftable kTrainCps = kgrainfreq ; set trainlet cps equal to grain rate for single-cycle trainlet in each grain knumpartials = 3 ; number of partials in trainlet kchroma = 1 ; balance of partials in trainlet ichannelmasks = -1 ; (default) no channel masking, all grains to output 1 krandommask = 0 ; no random grain masking kwaveform1 = giSine ; source waveforms kwaveform2 = giSine ; kwaveform3 = giSine ; kwaveform4 = giSine ; iwaveamptab = -1 ; (default) equal mix of all 4 sourcve waveforms and no amp for trainlets asamplepos1 = 0 ; phase offset for reading source waveform asamplepos2 = 0 ; asamplepos3 = 0 ; asamplepos4 = 0 ; kwavekey1 = 1 ; original key for source waveform kwavekey2 = 1 ; kwavekey3 = 1 ; kwavekey4 = 1 ; imax_grains = 100 ; max grains per k period asig partikkel kgrainfreq, kdistribution, idisttab, async, kenv2amt, ienv2tab, \ ienv_attack, ienv_decay, ksustain_amount, ka_d_ratio, kduration, kamp, igainmasks, \ kwavfreq, ksweepshape, iwavfreqstarttab, iwavfreqendtab, awavfm, \ ifmamptab, kfmenv, icosine, kTrainCps, knumpartials, \ kchroma, ichannelmasks, krandommask, kwaveform1, kwaveform2, kwaveform3, kwaveform4, \ iwaveamptab, asamplepos1, asamplepos2, asamplepos3, asamplepos4, \ kwavekey1, kwavekey2, kwavekey3, kwavekey4, imax_grains outs asig, asig endin </CsInstruments> <CsScore> i1 0 5 ; partikkel e </CsScore> </CsoundSynthesizer>
Here is another example of the partikkel opcode. It uses the file partikkel-2.csd.
Example 735. Example 2 of the partikkel opcode.
<CsoundSynthesizer> <CsOptions> ; Select audio/midi flags here according to platform ; Audio out -odac ;;;RT audio ; For Non-realtime ouput leave only the line below: ; -o partikkel-2.wav -W ;;; for file output any platform </CsOptions> <CsInstruments> sr = 44100 ksmps = 20 nchnls = 2 ; Example by Joachim Heintz and Oeyvind Brandtsegg 2008 giCosine ftgen 0, 0, 8193, 9, 1, 1, 90 ; cosine giDisttab ftgen 0, 0, 32768, 7, 0, 32768, 1 ; for kdistribution giFile ftgen 0, 0, 0, 1, "Mathews.wav", 0, 0, 0 ; soundfile for source waveform giWin ftgen 0, 0, 4096, 20, 9, 1 ; grain envelope giPan ftgen 0, 0, 32768, -21, 1 ; for panning (random values between 0 and 1) ; ************************************************* ; partikkel example, processing of soundfile ; uses the file "fox.wav" ; ************************************************* instr 1 /*score parameters*/ ispeed = p4 ; 1 = original speed igrainrate = p5 ; grain rate igrainsize = p6 ; grain size in ms icent = p7 ; transposition in cent iposrand = p8 ; time position randomness (offset) of the pointer in ms icentrand = p9 ; transposition randomness in cents ipan = p10 ; panning narrow (0) to wide (1) idist = p11 ; grain distribution (0=periodic, 1=scattered) /*get length of source wave file, needed for both transposition and time pointer*/ ifilen tableng giFile ifildur = ifilen / sr /*sync input (disabled)*/ async = 0 /*grain envelope*/ kenv2amt = 1 ; use only secondary envelope ienv2tab = giWin ; grain (secondary) envelope ienv_attack = -1 ; default attack envelope (flat) ienv_decay = -1 ; default decay envelope (flat) ksustain_amount = 0.5 ; no meaning in this case (use only secondary envelope, ienv2tab) ka_d_ratio = 0.5 ; no meaning in this case (use only secondary envelope, ienv2tab) /*amplitude*/ kamp = 0.4*0dbfs ; grain amplitude igainmasks = -1 ; (default) no gain masking /*transposition*/ kcentrand rand icentrand ; random transposition iorig = 1 / ifildur ; original pitch kwavfreq = iorig * cent(icent + kcentrand) /*other pitch related (disabled)*/ ksweepshape = 0 ; no frequency sweep iwavfreqstarttab = -1 ; default frequency sweep start iwavfreqendtab = -1 ; default frequency sweep end awavfm = 0 ; no FM input ifmamptab = -1 ; default FM scaling (=1) kfmenv = -1 ; default FM envelope (flat) /*trainlet related (disabled)*/ icosine = giCosine ; cosine ftable kTrainCps = igrainrate ; set trainlet cps equal to grain rate for single-cycle trainlet in each grain knumpartials = 1 ; number of partials in trainlet kchroma = 1 ; balance of partials in trainlet /*panning, using channel masks*/ imid = .5; center ileftmost = imid - ipan/2 irightmost = imid + ipan/2 giPanthis ftgen 0, 0, 32768, -24, giPan, ileftmost, irightmost ; rescales giPan according to ipan tableiw 0, 0, giPanthis ; change index 0 ... tableiw 32766, 1, giPanthis ; ... and 1 for ichannelmasks ichannelmasks = giPanthis ; ftable for panning /*random gain masking (disabled)*/ krandommask = 0 /*source waveforms*/ kwaveform1 = giFile ; source waveform kwaveform2 = giFile ; all 4 sources are the same kwaveform3 = giFile kwaveform4 = giFile iwaveamptab = -1 ; (default) equal mix of source waveforms and no amplitude for trainlets /*time pointer*/ afilposphas phasor ispeed / ifildur /*generate random deviation of the time pointer*/ iposrandsec = iposrand / 1000 ; ms -> sec iposrand = iposrandsec / ifildur ; phase values (0-1) krndpos linrand iposrand ; random offset in phase values /*add random deviation to the time pointer*/ asamplepos1 = afilposphas + krndpos; resulting phase values (0-1) asamplepos2 = asamplepos1 asamplepos3 = asamplepos1 asamplepos4 = asamplepos1 /*original key for each source waveform*/ kwavekey1 = 1 kwavekey2 = kwavekey1 kwavekey3 = kwavekey1 kwavekey4 = kwavekey1 /* maximum number of grains per k-period*/ imax_grains = 100 aL, aR partikkel igrainrate, idist, giDisttab, async, kenv2amt, ienv2tab, \ ienv_attack, ienv_decay, ksustain_amount, ka_d_ratio, igrainsize, kamp, igainmasks, \ kwavfreq, ksweepshape, iwavfreqstarttab, iwavfreqendtab, awavfm, \ ifmamptab, kfmenv, icosine, kTrainCps, knumpartials, \ kchroma, ichannelmasks, krandommask, kwaveform1, kwaveform2, kwaveform3, kwaveform4, \ iwaveamptab, asamplepos1, asamplepos2, asamplepos3, asamplepos4, \ kwavekey1, kwavekey2, kwavekey3, kwavekey4, imax_grains outs aL, aR endin </CsInstruments> <CsScore> ;i1 st dur speed grate gsize cent posrnd cntrnd pan dist i1 0 3 1 200 15 0 0 0 0 0 s i1 0 3 1 200 15 400 0 0 0 0 s i1 0 3 1 15 450 400 0 0 0 0 s i1 0 3 1 15 450 400 0 0 0 0.4 s i1 0 3 1 200 15 0 400 0 0 1 s i1 0 6 .5 200 20 0 0 600 .5 1 s i1 0 12 .25 200 15 0 1000 400 1 1 e </CsScore> </CsoundSynthesizer>
Here is an example of using panning laws with channelmasks in partikkel. It uses the file partikkel-panlaws.csd.
Example 736. Example with panning laws with channel masks.
<CsoundSynthesizer> <CsOptions> ; Select audio/midi flags here according to platform ; Audio out -odac ;;;RT audio ; For Non-realtime ouput leave only the line below: ; -o partikkel-panlaws.wav -W ;;; for file output any platform </CsOptions> <CsInstruments> nchnls = 4 0dbfs = 1 giSine ftgen 0, 0, 65536, 10, 1 giCosine ftgen 0, 0, 8192, 9, 1, 1, 90 giSigmoRise ftgen 0, 0, 8193, 19, 0.5, 1, 270, 1 giSigmoFall ftgen 0, 0, 8193, 19, 0.5, 1, 90, 1 giLinUp ftgen 0, 0, 8192, 7, 0, 8192, 1 giConcaveUp ftgen 0, 0, 8192, 16, 0, 8192, 1.5, 1 giConvexUp ftgen 0, 0, 8192, 16, 0, 8192, -1.5, 1 giPanLaws ftgen 0, 0, 8192, 18, giLinUp, 1, 0, 1023, giConcaveUp, 1, 1024, 2047, giConvexUp, 1, 2048, 3071, giSigmoRise, 1, 3072, 4095 instr 1 ; channel masking table, using just one single mask here ichannelmasks ftgentmp 0, 0, 32, -2, 0, 0, 0 ; continuously write to masking table, ; slowly panning the grains from output to output ; over a 10 second period kchn phasor 0.1 kchn = kchn*4 tablew kchn, 2, ichannelmasks ; init unused arate signals awavfm = 0 asamplepos1 = 0 async = 0 a1,a2,a3,a4 partikkel 4, 0, -1, async, 0, -1, giSigmoRise, giSigmoFall, 0.9, 0.5, 100, ampdbfs(-9), -1, 1, 0, -1, -1, awavfm, -1, -1, giCosine, 1, 1, 1, ichannelmasks, 0, giSine, giSine, giSine, giSine, -1, asamplepos1, asamplepos1, asamplepos1, asamplepos1, 440, 440, 440, 440, 100, 1, giPanLaws outch 1, a1, 2, a2, 3, a3, 4, a4 endin </CsInstruments> <CsScore> i1 0 12 </CsScore> </CsoundSynthesizer>