CsoundManual - Previous section - Contents - Index - Next

SIGNAL GENERATORS

     kr   line          ia, idur1, ib
     ar   line          ia, idur1, ib
     kr   expon         ia, idur1, ib 
     ar   expon         ia, idur1, ib 
     kr   linseg        ia, idur1, ib[, idur2, ic[...]] 
     ar   linseg        ia, idur1, ib[, idur2, ic[...]] 
     kr   expseg        ia, idur1, ib[, idur2, ic[...]] 
     ar   expseg        ia, idur1, ib[, idur2, ic[...]] 
     kr   phasor        kcps[, iphs]
     ar   phasor        xcps[, iphs] 
     ir   table         indx, ifn[, ixmode][, ixoff][, iwrap]
     ir   tablei        indx, ifn[, ixmode][, ixoff][, iwrap]
     kr   table         kndx, ifn[, ixmode][, ixoff][, iwrap]
     kr   tablei        kndx, ifn[, ixmode][, ixoff][, iwrap]
     ar   table         andx, ifn[, ixmode][, ixoff][, iwrap]
     ar   tablei        andx, ifn[, ixmode][, ixoff][, iwrap]
     kr   oscil1        idel, kamp, idur, ifn
     kr   oscil1i       idel, kamp, idur, ifn
     kr   oscil         kamp, kcps, ifn[, iphs]
     kr   oscili        kamp, kcps, ifn[, iphs]
     ar   oscil         xamp, xcps, ifn[, iphs]
     ar   oscili        xamp, xcps, ifn[, iphs]
     ar   foscil        xamp, kcps, kcar, kmod, kndx, ifn[, iphs]
     ar   foscili       xamp, kcps, kcar, kmod, kndx, ifn[, iphs]

          itablew       isig, indx, ifn [,ixmode] [,ixoff] [,iwgmode]
          tablew        ksig, kndx, ifn [,ixmode] [,ixoff] [,iwgmode] 
          tablew        asig, andx, ifn [,ixmode] [,ixoff] [,iwgmode] 
          tablewkt      ksig, kndx, kfn [,ixmode] [,ixoff] [,iwgmode]  
          tablewkt      asig, andx, kfn [,ixmode] [,ixoff] [,iwgmode] 

     ir   itableng      ifn 
     kr   tableng       kfn
          itablegpw     ifn
          tablegpw      kfn
          tablemix      kdft, kdoff, klen, ks1ft, ks1off, ks1g, ks2ft, \
                          ks2off, ks2g
          itablemix     idft, idoff, ilen, is1ft, is1off, is1g, is2ft, \
                          is2off, is2g
          tablecopy     kdft, ksft 
          itablecopy    idft, isft  

     ar   tablera       kfn, kstart, koff
 kstart   tablewa       kfn, asig, koff 

ar1[,ar2] loscil        xamp, kcps, ifn[, ibas][, imod1,ibeg1,iend1]
                          [, imod2,ibeg2,iend2]
     ar   buzz          xamp, xcps, knh, ifn[, iphs]
     ar   gbuzz         xamp, xcps, knh, kih, kr, ifn[, iphs]
     ar   adsyn         kamod, kfmod, ksmod, ifilcod 

     ar   pvoc          ktimpnt, kfmod, ifilcod[, ispecwp]
kfr,kap   pvread        ktimpnt,  ifile, ibin                   
          pvbufread     ktimpnt, ifile
     ar   pvinterp      ktimpnt, kfmod, ifile, kfreqscale1,\
                        kfreqscale2, kampscale1, kampscale2, \
                        kfreqinterp, kampinterp
     ar   pvcross       ktimpnt, kfmod, ifile, kamp1, kamp2,[ispecwp]
          tableseg      ifn1, idur1, ifn2[, idur2, ifn3[...]]
          tablexseg     ifn1, idur1, ifn2[, idur2, ifn3[...]]
     ar   vpvoc         ktimpnt, kfmod, ifile, [ispecwp]

     ar   fof           xamp, xfund, xform, koct, kband, kris, kdur, kdec,
                        iolaps, ifna, ifnb, itotdur[, iphs][, ifmode] 
     ar   fof2          xamp, xfund, xform, koct, kband, kris, kdur, kdec,
                        iolaps, ifna, ifnb, itotdur, kphs, kgliss 
     ar   fog             xamp, xdens, xtrans, xspd, koct, kband, kris,  \
                        kdur, kdec, iolaps, ifna, ifnb, itotdur[, iphs] \    
                        [, itmode] 
     ar   grain         xamp, xpitch, xdens, kampoff, kpitchoff, \
                        kgdur, igfn,iwfn,imgdur
     ar   granule       xamp, ivoice, iratio, imode, ithd, ifn, \
                        ipshift,igskip, igskip_os, ilength, kgap, igap_os,\
                        kgsize, igsize_os, iatt, idec [,iseed][,ipitch1] \
                        [,ipitch2][,ipitch3][,ipitch4][,ifnenv]

     ar   pluck         kamp, kcps, icps, ifn, imeth [, iparm1, iparm2] 
     kr   rand          xamp[, iseed]
     kr   randh         kamp, kcps[, iseed]
     kr   randi         kamp, kcps[, iseed]
     ar   rand          xamp[, iseed]
     ar   randh         xamp, xcps[, iseed]
     ar   randi         xamp, xcps[, iseed]

          xlinrand      krange 
          xtrirand      krange
          xexprand      krange
          xbexprnd      krange
          xcauchy               kalpha
          xpcauchy      kalpha
          xpoisson      klambda
          xgauss        krange
          xweibull      ksigma, ktau
          xbeta         krange, kalpha, kbeta
          xuniform      krange
  
ar[,ac]   sndwarp       xamp, xtimewarp, xresample, ifn1, ibeg,\
                        iwsize, irandw, ioverlap, ifn2, itimemode
ar1,ag2[,ac1,ac2] sndwarpst xamp, xtimewarp, xresample, ifn1,\
                        ibeg, iwsize, irandw, ioverlap, ifn2, itimemode


CsoundManual - Top of this section - Previous - Contents - Index - Next

line, expon, linseg,expseg

     kr   line      ia, idur1, ib
     ar   line      ia, idur1, ib
     kr   expon     ia, idur1, ib 
     ar   expon     ia, idur1, ib 
     kr   linseg    ia, idur1, ib[, idur2, ic[...]] 
     ar   linseg    ia, idur1, ib[, idur2, icI...]]
     kr   expseg    ia, idur1, ib[, idur2, ic[...]]
     ar   expseg    ia, idur1, ib[, idur2, ic[...]]


DESCRIPTION

Output values kr or ar trace a straight line (exponential curve) or a series of line segments (exponential segments) between specified points.

INITIALIZATION

ia- starting value. Zero is illegal for exponentials.

ib, ic, etc. - value after dur1 seconds, etc. For exponentials, must be non-zero and must agree in sign with ia.

idur1 - duration in seconds of first segment. A zero or negative value will cause all initialization to be skipped.

idur2, idur3, etc. - duration in seconds of subsequent segments. A zero or negative value will terminate the initialization process with the preceding point, permitting the last-defined line or curve to be continued indefinitely in performance. The default is zero.

PERFORMANCE

These units generate control or audio signals whose values can pass through 2 or more specified points. The sum of dur values may or may not equal the instrument's performance time: a shorter performance will truncate the specified pattern, while a longer one.will cause the last-defined segment to continue on in the same direction.

EXAMPLE:

     k2   expseg 440, p3/2,880, p3/2,440  

This statement creates a control signal which moves exponentially from 440 to 880 and back, over the duration p3.


CsoundManual - Top of this section - Previous - Contents - Index - Next

phasor

     kr   phasor    kcps[, iphs] 
     ar   phasor    xcps[, iphs]  


DESCRIPTION

Produce a normalized moving phase value.

INITIALIZATION

iphs (optional) - initial phase, expressed as a fraction of a cycle (0 to 1). A negative value will cause phase initialization to he skipped. The default value is zero.

PERFORMANCE

An internal phase is successively accumulated in accordance with the cps frequency to produce a moving phase value, normalized to lie in the range 0. <= phs < 1.

When used as the index to a table unit, this phase (multiplied by the desired function table length) will cause it to behave like an oscillator.

Note that phasor is a special kind of integrator, accumulating phase increments that represent frequency settings.

EXAMPLE:

          phasor     1                   ; cycle once per second
  kpch    table      k1 * 12, 1          ; through 12-note pch table
  a1      oscil      p4, cpspch(kpch), 2 ; with continuous sound


CsoundManual - Top of this section - Previous - Contents - Index - Next

table, tablei, oscil1, oscil1i

     ir   table          indx, ifn[, ixmode][, ixoff][, iwrap]
     ir   tablei         indx, ifn[, ixmode][, ixoff][, iwrap]
     kr   table          kndx, ifn[, ixmode][, ixoff][, iwrap]
     kr   tablei         kndx, ifn[, ixmode][, ixoff][, iwrap]
     ar   table          andx, ifn[, ixmode][, ixoff][, iwrap]
     ar   tablei         andx, ifn[, ixmode][, ixoff][, iwrap]
     kr   oscil1         idel, kamp, idur, ifn
     kr   oscil1i        idel, kamp, idur, ifn 


DESCRIPTION

Table values are accessed by direct indexing or by incremental sampling.

INITIALIZATION

ifn - function table number. tablei, oscil1i require the extended guard point.

ixmode (optional) - ndx data mode. 0 = raw ndx, 1 = normalized (0 to 1). The default value is 0.

ixoff (optional) - amount by which ndx is to be offset. For a table with origin at center, use tablesize/2 (raw) or .5 (normalized). The default value is 0.

iwrap (optional) - wraparound ndx flag. 0 = nowrap (ndx < 0 treated as ndx=0; ndx > tablesize sticks at ndx=size), 1 = wraparound. The default value is 0.

idel - delay in seconds before oscil1 incremental sampling begins.

idur - duration in seconds to sample through the oscil1 table just once. A zero or negative value will cause all initialization to be skipped.

PERFORMANCE

table invokes table lookup on behalf of init, control or audio indices. These indices can be raw entry numbers (0,l,2...size - 1) or scaled values (0 to 1-e). Indices are first modified by the offset value then checked for range before table lookup (see iwrap). If ndx is likely to be full scale, or if interpolation is being used, the table should have an extended guard point. table indexed by a periodic phasor ( see phasor) will simulate an oscillator.

oscil1 accesses values by sampling once through the function table at a rate determined by idur. For the first idel seconds, the point of scan will reside at the first location of the table; it will then begin moving through the table at a constant rate, reaching the end in another idur seconds; from that time on (i.e. after idel + idur seconds) it will remain pointing at the last location. Each value obtained from sampling is then multiplied by an amplitude factor kamp before being written into the result.

tablei and oscil1i are interpolating units in which the fractional part of ndx is used to interpolate between adjacent table entries. The smoothness gained by interpolation is at some small cost in execution time (see also oscili, etc.), but the interpolating and non-interpolating units are otherwise interchangeable. Note that when tablei uses a periodic index whose modulo nis less than the power of 2 table length, the interpolation process requires that there be an (n+ 1)th table value that is a repeat of the 1st ( see F statement in Score).


CsoundManual - Top of this section - Previous - Contents - Index - Next

oscil, oscili, foscil, foscili

     kr   oscil           kamp, kcps, ifn[, iphs]
     kr   oscili          kamp, kcps, ifn[, iphs]
     ar   oscil           xamp, xcps, ifn[, iphs]
     ar   oscili          xamp, xcps, ifn[, iphs]
     ar   foscil    xamp, kcps, kcar, kmod, kndx, ifn[, iphs]
     ar   foscili   xamp, kcps, kcar, kmod, kndx, ifn[, iphs] 


DESCRIPTION

Table ifn is incrementally sampled modulo the table length and the value obtained is multiplied by amp.

INITIALIZATION

ifn - function table number. Requires a wrap-around guard point.

iphs (optional) - initial phase of sampling, expressed as a fraction of a cycle (0 to 1). A negative value will cause phase initialization to be skipped. The default value is 0.

PERFORMANCE

The oscil units output periodic control (or audio) signals consisting of the value of kamp(xamp)times the value returned from control rate (audio rate) sampling of a stored function table. The internal phase is simultaneously advanced in accordance with the cps input value. While the amplitude and frequency inputs to the K-rate oscils are scalar only, the corresponding inputs to the audio-rate oscils may each be either scalar or vector, thus permitting amplitude and frequency modulation at either sub-audio or audio frequencies.

foscil is a composite unit that effectively banks two oscils in the familiar Chowning FM setup, wherein the audio-rate output of one generator is used to modulate the frequency input of another (the "carrier"). Effective carrier frequency = kcps * kcar, and modulating frequency = kcps * kmod. For integral values of kcar and kmod, the perceived fundamental will be the minimum positive value of kcps * (kcar - n * kmod), n = 1,1,2,... The input kndx is the index of modulation (usually time-varying and ranging 0 to 4 or so) which determines the spread of acoustic energy over the partial positions given by n = 0,1,2,.., etc. ifn should point to a stored sine wave.

oscili and foscili differ from oscil and foscil respectively in that the standard procedure of using a truncated phase as a sampling index is here replaced by a process that interpolates between two successive lookups. Interpolating generators will produce a noticeably cleaner output signal, but they may take as much as twice as long to run. Adequate accuracy can also be gained without the time cost of interpolation by using large stored function tables of 2K, 4K or 8K points if the space is available.

EXAMPLE:

     k1   oscil     10, 5, 1            ; 5 cps vibrato
     a1   oscil     5000, 440 + k1, 1   ; around A440 + -10 cps


CsoundManual - Top of this section - Previous - Contents - Index - Next

itablew, tablew, tablewkt

   itablew      isig, indx, ifn [, ixmode] [, ixoff] [, iwgmode]
   tablew       ksig, kndx, ifn [, ixmode] [, ixoff] [, iwgmode] 
   tablew       asig, andx, ifn [, ixmode] [, ixoff] [, iwgmode] 
   tablewkt     ksig, kndx, kfn [, ixmode] [, ixoff] [, iwgmode]  
   tablewkt     asig, andx, kfn [, ixmode] [, ixoff] [, iwgmode]  


DESCRIPTION

These opcodes operate on existing function tables, changing their contents. itablew is used when all inputs are init time variables or constants and you only want to run it at the initialisation of the instrument. tablew is for writing at k or at a rates, with the table number being specified at init time. tablewkt is the same, but uses a k rate variable for selecting the table number. The valid combinations of variable types are shown by the first letter of the variable names.

INITIALIZATION

isig, ksig, asig- The value to be written into the table.

indx, kndx, andx - Index into table, either a positive number range matching the table length (ixmode = 0) or a 0 to 1 range (ixmode != 0)

ifn, kfn - Table number. Must be >= 1. Floats are rounded down to an integer. If a table number does not point to a valid table, or the table has not yet been loaded (gen01) then an error will result and the instrument will be de-activated.

ixmode - 0 : xndx and ixoff ranges match the length of the table. !=0 : xndx and ixoff have a 0 to 1 range. Default 0

ixoff - 0: Total index is controlled directly by xndx. ie. the indexing starts from the start of the table. !=0: Start indexing from somewhere else in the table. Value must be positive and less than the table length (ixmode = 0) or less than 1 (ixmode !=0). Default 0

iwgmode - 0: Limit mode; 1: Wrap mode; 2: Guardpoint mode. Default 0

PERFORMANCE

Limit mode (0)

Limit the total index (ndx + ixoff) to between 0 and the guard point. For a table of length 5, this means that locations 0 to 3 and location 4 (the guard point) can be written. A negative total index writes to location 0. Total indexes > 4 write to location 4.

Wrap mode (1)

Wrap total index value into locations 0 to E, where E is one less than either the table length or the factor of 2 number which is one less than the table length. For example, wrap into a 0 to 3 range - so that total index 6 writes to location 2.

Guardpoint mode (2)

The guardpoint is written at the same time as location 0 is written - with the same value.

This facilitates writing to tables which are intended to be read with interpolation for producing smooth cyclic waveforms. In addition, before it is used, the total index is incremented by half the range between one location and the next, before being rounded down to the integer address of a table location.

Normally (igwmode = 0 or 1) for a table of length 5 - which has locations 0 to 3 as the main table and location 4 as the guard point, a total index in the range of 0 to 0.999 will write to location 0. ("0.999" means just less than 1.0.) 1.0 to 1.999 will write to location 1 etc. A similar pattern holds for all total indexes 0 to 4.999 (igwmode = 0) or to 3.999 (igwmode = 1). igwmode = 0 enables locations 0 to 4 to be written - with the guardpoint (4) being written with a potentially different value from location 0.

With a table of length 5 and the iwgmode = 2, then when the total index is in the range 0 to 0.499, it will write to locations 0 and 4. Range 0.5 to 1.499 will write to location 1 etc. 3.5 to 4.0 will _also_ write to locations 0 and 4.

This way, the writing operation most closely approximates the results of interpolated reading. Guard point mode should only be used with tables that have a guardpoint.

Guardpoint mode is accomplished by adding 0.5 to the total index, rounding to the next lowest integer, wrapping it modulo the factor of two which is one less than the table length, writing the the table (locations 0 to 3 in our example) and then writing to the guard point if index == 0.

tablew has no output value. The last three parameters are optional and have default values of 0.

Caution with k rate table numbers :

The following notes also apply to the tablekt and tableikt ugens which can now have their table number changed at k rate.

At k rate or a rate, if a table number of < 1 is given, or the table number points to a non-existent table, or to one which has a length of 0 (it is to be loaded from a file later) then an error will result and the instrument will be deactivated.

AUTHOR:

Robin Whittle
Australia
May 1997


CsoundManual - Top of this section - Previous - Contents - Index - Next

tablegpw, tableng, tablemix, tablecopy, itablegpw, itablemix, itablecopy, itableng

ir itableng     ifn 
kr tableng      kfn
   itablegpw    ifn
   tablegpw     kfn
   tablemix     kdft, kdoff, klen, ks1ft, ks1off, ks1g, ks2ft, ks2off, ks2g
   itablemix    idft, idoff, ilen, is1ft, is1off, is1g, is2ft, is2off, is2g
   tablecopy    kdft, ksft 
   itablecopy   idft, isft 


DESCRIPTION

These opcodes allow to copy, mix and interrogate tables.

INITIALIZATION

ifn, kfn - Table number to be interrogated

kdft - Destination function table.

kdoff - Offset to start writing from. Can be negative.

kdft - Number of destination function table.

ksft - Number of source function table.

klen - Number of write operations to perform. Negative means work backwards.

ks1ft, ks2ft - Source function tables. These can be the same as the destination table, if care is exercised about direction of copying data.

ks1off, ks2off -Offsets to start reading from in source tables.

ks1g, ks2g - Gains to apply when reading from the source tables. The results are added and the sum is written to the destination table.

PERFORMANCE

tableng

These return the length of the specified table. This will be a power of two number in most circumstances - it will not show whether a table has a guardpoint or not - it seems this information is not available in the table's data structure. If table is not found, then 0 will be returned.

Likely to be useful for setting up code for table manipulation operations, such as tablemix and tablecopy.

tablgpw

For writing the table's guard point, with the value which is in location 0. Does nothing if table does not exist.

Likely to be useful after manipulating a table with tablemix or tablecopy.

tablemix

This ugen mixes from two tables, with separate gains into the destination table. Writing is done for klen locations, usually stepping forward through the table - if klen is positive. If it is negative, then the writing and reading order is backwards - towards lower indexes in the tables. This bidirectional option makes it easy to shift the contents of a table sideways by reading from it and writing back to it with a different offset.

If klen is 0, no writing occurs. Note that the internal integer value of klen is derived from the ANSI C floor() function - which returns the next most negative integer. Hence a fractional negative klen value of -2.3 would create an internal length of 3, and cause the copying to start from the offset locations and proceed for two locations to the left.

The total index for table reading and writing is calculated from the starting offset for each table, plus the index value, which starts at 0 and then increments (or decrements) by 1 as mixing proceeds.

These total indexes can potentially be very large, since there is no restriction on the offset or the klen. However each total index for each table is ANDed with a length mask (such as 0000 0111 for a table of length 8) to form a final index which is actually used for reading or writing. So no reading or writing can occur outside the tables. This is the same as "wrap" mode in table read and write. These ugens do not read or write the guardpoint. If a table has been rewritten with one of these, then if it has a guardpoint which is supposed to contain the same value as the location 0, then call tablegpw afterwards.

The indexes and offsets are all in table steps - they are not normalised to 0 - 1. So for a table of length 256, klen should be set to 256 if all the table was to be read or written.

The tables do not need to be the same length - wrapping occurs individually for each table.

tablecopy

Simple, fast table copy ugens. Takes the table length from the destination table, and reads from the start of the source table. For speed reasons, does not check the source length - just copies regardless - in "wrap" mode. This may read through the source table several times. A source table with length 1 will cause all values in the destination table to be written to its value.

Table copy cannot read or write the guardpoint. To read it use table read, with ndx = the table length. Likewise use table write to write it.

To write the guardpoint to the value in location 0, use tablegpw.

This is primarily to change function tables quickly in a real-time situation.

AUTHOR:

Robin Whittle
Australia
May 1997


CsoundManual - Top of this section - Previous - Contents - Index - Next

tablera, tablewa

   ar       tablera     kfn, kstart, koff
   kstart   tablewa     kfn, asig, koff 


DESCRIPTION

These ugens read and write tables in sequential locations to and from an a rate variable. Some thought is required before using them. They have at least two major, and quite different, applications which are discussed below.

INITIALIZATION

ar - a rate destination for reading ksmps values from a table.

kfn - i or k rate number of the table to read or write.

kstart - Where in table to read or write.

asig - a rate signal to read from when writing to the table.

koff - i or k rate offset into table. Range unlimited - see explanation at end of this section.

PERFORMANCE

In one application, these are intended to be used in pairs, or with several tablera ugens before a tablewa - all sharing the same kstart variable.

These read from and write to sequential locations in a table at audio rates, with ksmps floats being written and read each cycle.

tablera starts reading from location kstart. tablewa starts writing to location kstart, and then writes to kstart with the number of the location one more than the one it last wrote. (Note that for tablewa, kstart is both an input and output variable.) If the writing index reaches the end of the table, then no further writing occurs and zero is written to kstart.

For instance, if the table's length was 16 (locations 0 to 15), and ksmps was 5. Then the following steps would occur with repetitive runs of the tablewa ugen, assuming that kstart started at 0.

Run no. Initial  Final    locations written 
        kstart   kstart 
1       0        5        0 1 2 3 4 
2       5        10       5 6 7 8 9 
3       10       15       10 11 12 13 14 
4       15       0        15 

This is to facilitate processing table data using standard a rate orchestra code between the tablera and tablewa ugens:

Notes on tablera and tablewa :

These are a fudge, but they allow all Csounds k rate operators to be used (with caution) on a rate variables - something that would only be possible otherwise by ksmps = 1, downsamp and upsamp.

Several cautions:

EXAMPLES:

                                  
 kstart   =       0      ; Read 5 values from table into an 
                         ; a rate variable.
 lab1:
   atemp  tablera ktabsource, kstart, 0 
                         ; Process the values using a rate code.
   atemp  =       log(atemp)    ; Write it back to the table
   kstart tablewa ktabdest, atemp, 0 
         ; Loop until all table locations have been processed.
 if ktemp > 0 goto lab1 
   
    


The above example shows a processing loop, which runs every k cycle, reading each location in the table ktabsource, and writing the log of those values into the same locations of table ktabdest.

This enables whole tables, parts of tables (with offsets and different control loops) and data from several tables at once to be manipulated with a rate code and written back to another (or to the same) table. This is a bit of a fudge, but it is faster than doing it with k rate table read and write code.

Another application is:

   kzero = 0                    
   kloop = 0                    
                                 
   kzero tablewa 23, asignal, 0 ; ksmps a rate samples written
                                ; into locations 0 to (ksmps -1) of table 23.
                                
   lab1: ktemp table kloop, 23  ; Start a loop which runs ksmps times, 
                                ; in which each cycle processes one of 
    [ Some code to manipulate ] ; table 23's values with k rate orchestra
    [ the value of ktemp. ]     ; code.
                                 
    tablew ktemp, kloop, 23     ; Write the processed value to the table.
                                ;
   kloop = kloop + 1            ; Increment the kloop, which is both the
                                ; pointer into the table and the loop 
   if kloop < ksmps goto lab1   ; counter. Keep looping until all values
                                ; in the table have been processed.
                                
   asignal   tablera 23, 0, 0   ; Copy the table contents back
                                ; to an a rate variable.


koff - This is an offset which is added to the sum of kstart and the internal index variable which steps through the table. The result is then ANDed with the lengthmask (000 0111 for a table of length 8 - or 9 with guardpoint) and that final index is used to read or write to the table. koff can be any value. It is converted into a long using the ANSI floor() function so that -4.3 becomes -5. This is what we would want when using offsets which range above and below zero.

Ideally this would be an optional variable, defaulting to 0, however with the existing Csount orchestra read code, such default parameters must be init time only. We want k rate here, so we cannot have a default.


CsoundManual - Top of this section - Previous - Contents - Index - Next

loscil

 ar1[,ar2]  loscil   xamp, kcps, ifn[, ibas][,imod1,ibeg1,iend1] \
                     [, imod2,ibeg2,iend2]


DESCRIPTION

Read sampled sound (mono or stereo) from a table, with optional sustain and release looping.

INITIALIZATION

ifn - function table number, typically denoting an AIFF sampled sound segment with prescribed looping points. The source file may be mono or stereo.

ibas (optional) - base frequency in cps of the recorded sound. This optionally overrides the frequency given in the AIFF file, but is required if the file did not contain one. The default value is 0 (no override).

imod1, imod2 (optional) - play modes for the sustain and release loops. A value of 1 denotes normal looping, 2 denotes forward & backward looping, 0 denotes no looping. The default value (-1) will defer to the mode and the looping points given in the source file.

ibeg1, iend1, ibeg2, iend2 (optional, dependent on mod1, mod2) - begin and end points of the sustain and release loops. These are measured in sample frames from the beginning of the file, so will look the same whether the sound segment is monaural or stereo.

PERFORMANCE

loscil samples the ftable audio at a rate determined by kcps, then multiplies the result by xamp. The sampling increment for kcps is dependent on the table's base-note frequency ibas, and is automatically adjusted if the orchestra sr value differs from that at which the source was recorded. In this unit, ftable is always sampled with interpolation.

If sampling reaches the sustain loop endpoint and looping is in effect, the point of sampling will be modified and loscil will continue reading from within that loop segment. Once the instrument has received a turnoff signal (from the score or from a MIDI noteoff event), the next sustain endpoint encountered will be ignored and sampling will continue towards the release loop end-point, or towards the last sample (henceforth to zeros).

loscil is the basic unit for building a sampling synthesizer. Given a sufficient set of recorded piano tones, for example, this unit can resample them to simulate the missing tones. Locating the sound source nearest a desired pitch can be done via table lookup. Once a sampling instrument has begun, its turnoff point may be unpredictable and require an external release envelope; this is often done by gating the sampled audio with linenr, which will extend the duration of a turned-off instrument by a specific period while it implements a decay.

EXAMPLE:

   inum   notnum
   icps   cpsmidi
   iamp   ampmidi   3000, 1
   ifno   table     inum, 2       ;notnum to choose an audio sample
   ibas   table     inum, 3
   kamp   linenr    iamp, 0, .05, .01 ;at noteoff, extend by 50 ms.
   asig   loscil    kamp, icps, ifno, cpsoct(ibas/12. + 3)


CsoundManual - Top of this section - Previous - Contents - Index - Next

buzz, gbuzz

     ar   buzz      xamp, xcps, knh, ifn[, iphs]
     ar   gbuzz     xamp, xcps, knh, klh, kr, ifn[, iphs]


DESCRIPTION

Output is a set of harmonically related cosine partials.

INITIALIZATION

ifn - table number of a stored function containing (for buzz) a sine wave, or (for gbuzz) a cosine wave. In either case a large table of at least 8192 points is recommended.

iphs (optional) - initial phase of the fundamental frequency, expressed as a fraction of a cycle (0 to 1). A negative value will cause phase initialization to be skipped. The default value is zero

PERFORMANCE

These units generate an additive set of harmonically related cosine partials of fundamental frequency xcps, and whose amplitudes are scaled so their summation peak equals xamp. The selection and strength of partials is determined by the following control parameters:

knh - total number of harmonics requested. Must be positive.

klh - lowest harmonic present. Can be positive, zero or negative. In gbuzz the set of partials can begin at any partial number and proceeds upwards; if klh is negative, all partials below zero will reflect as positive partials without phase change (since cosine is an even function), and will add constructively to any positive partials in the set.

kr - specifies the multiplier in the series of amplitude coefficients. This is a power series: if the klhth partial has a strength coefficient of A, the (klh + n)th partial will have a coefficient of A * (kr ** n), i.e. strength values trace an exponential curve. kr may be positive, zero or negative, and is not restricted to integers.

buzz and gbuzz are useful as complex sound sources in subtractive synthesis. buzz is a special case of the more general gbuzz in which klh = kr= 1; it thus produces a set of knh equal-strength harmonic partials, beginning with the fundamental. (This is a band-limited pulse train; if the partials extend to the Nyquist, i.e. knh = int (sr / 2 / fundamental freq.), the result is a real pulse train of amplitude xamp.) Although both knh and klh may be varied during performance, their internal values are necessarily integer and may cause "pops" due to discontinuities in the output; kr, however, can be varied during performance to good effect. Both buzz and gbuzz can be amplitude- and/or frequency-modulated by either control or audio signals.

N.B. These two units have their analogs in GEN11, in which the same set of cosines can be stored in a function table for sampling by an oscillator. Although computationally more efficient, the stored pulse train has a fixed spectral content, not a time-varying one as above.


CsoundManual - Top of this section - Previous - Contents - Index - Next

adsyn, pvoc

     ar   adsyn     kamod, kfmod, ksmod, ifilcod 
     ar   pvoc      ktimpnt, kfmod, ifilcod [, ispecwp] 


DESCRIPTION

Output is an additive set of individually controlled sinusoids, using either an oscillator bank or phase vocoder resynthesis.

INITIALIZATION

ifilcod - integer or character-string denoting a control-file derived from analysis of an audio signal. An integer denotes the suffix of a file adsyn.m or pvoc.m; a character-string (in double quotes) gives a filename, optionally a full pathname. If not fullpath, the file is sought first in the current directory, then in the one given by the environment variable SADIR (if defined). adsyn control contains breakpoint amplitude- and frequency-envelope values organized for oscillator resynthesis, while pvoc control contains similar data organized for fft resynthesis. Memory usage depends on the size of the files involved, which are read and held entirely in memory during computation but are shared by multiple calls ( see also lpread).

ispecwp (optional) - if non-zero, attempts to preserve the spectral envelope while its frequency content is varied by kfmod. The default value is zero.

PERFORMANCE

adsyn synthesizes complex time-varying timbres through the method of additive synthesis. Any number of sinusoids, each individually controlled in frequency and amplitude, can be summed by high-speed arithmetic to produce a high-fidelity result.

Component sinusoids are described by a control file describing amplitude and frequency tracks in millisecond breakpoint fashion. Tracks are defined by sequences of 16-bit binary integers:

-1, time, amp, time, amp,...

-2, time, freq, time, freq,...

such as from hetrodyne filter analysis of an audio file. ( For details see the Appendix on hetro.) The instantaneous amplitude and frequency values are used by an internal fixed-point oscillator that adds each active partial into an accumulated output signal. While there is a practical limit (currently 50) on the number of contributing partials, there is no restriction on their behavior over time. Any sound that can be described in terms of the behavior of sinusoids can be synthesized by adsyn alone.

Sound described by an adsyn control file can also be modified during re-synthesis. The signals kamod, kfmod, ksmod will modify the amplitude, frequency, and speed of contributing partials. These are multiplying factors, with kfmod modifying the cps frequency and ksmod modifying the speed with which the millisecond bread-point line-segments are traversed. Thus .7, 1.5, and 2 will give rise to a softer sound, a perfect fifth higher, but only half as long. The values 1,1,1 will leave the sound unmodified. Each of these inputs can be a control signal.

pvoc implements signal reconstruction using an fft-based phase vocoder. The control data stems from a precomputed analysis file with a known frame rate. The passage of time through this file is specified by ktimpnt, which represents the time in seconds. ktimpnt must always be positive, but can move forwards or backwards in time, be stationary or discontinuous, as a pointer into the analysis file. kfmod is a control-rate transposition factor: a value of 1 incurs no transposition, 1.5 transposes up a perfect fifth, and .5 down an octave.

This implementation of pvoc was written by Dan Ellis. It is based in part on the system of Mark Dolson, but the pre-analysis concept is new.


CsoundManual - Top of this section - Previous - Contents - Index - Next

pvread, pvbufread, pvinterp, pvcross, tableseg, tablexseg, vpvoc

kfreq,kamp    pvread        ktimpnt,  ifile, ibin                   
              pvbufread     ktimpnt, ifile
        ar    pvinterp      ktimpnt, kfmod, ifile, kfreqscale1,\
                               kfreqscale2, kampscale1, kampscale2, \
                               kfreqinterp, kampinterp
        ar    pvcross       ktimpnt, kfmod, ifile, kamp1, kamp2,\
                               [ispecwp]
              tableseg      ifn1, idur1, ifn2[, idur2, ifn3[...]]
              tablexseg     ifn1, idur1, ifn2[, idur2, ifn3[...]]
        ar    vpvoc         ktimpnt, kfmod, ifile, [ispecwp]


DESCRIPTION

pvread reads from a pvoc file and returns the frequency and amplitude from a single anaylsis channel or bin. The returned values can be used anywhere else in the csound instrument. For example, one can use them as arguments to an oscillator to synthesize a single component from an analyzed signal or a bank of pvreads can be used to resynthesize the analyzed sound using additive synthesis by passing the frequency and magnitude values to a bank of oscillators.

pvbufread reads from a pvoc file and makes the retrieved data available to any following pvinterp and pvcross units that appear in an instrument before a subsequent pvbufread (just as lpread and lpreson work together). The data is passed internally and the unit has no output of its own. pvinterp and pvcross allow the interprocessing of two phase vocoder analysis files prior to the resynthesis which these units do also. Both of these units receive data from one of the files from a previously called pvbufread unit. The other file is read by the pvinterp and/or pvcross units. Since each of these units has its own time-pointer the analysis files can be read at different speeds and directions from one another. pvinterp does not allow for the use of the ispecwp process as with the pvoc and vpvoc units.

pvinterp interpolates between the amplitudes and frequencies, on a bin by bin basis, of two phase vocoder analysis files (one from a previously called pvbufread unit and the other from within its own argument list), allowing for user defined transitions between analyzed sounds. It also allows for general scaling of the amplitudes and frequencies of each file separately before the interpolated values are calculated and sent to the resynthesis routines. The kfmod argument in pvinterp performs its frequency scaling on the frequency values after their derivation from the separate scaling and subsequent interpolation is performed so that this acts as an overall scaling value of the new frequency components.

pvcross applies the amplitudes from one phase vocoder analysis file to the data from a second file and then performs the resynthesis. The data is passed, as described above, from a previously called pvbufread unit. The two k-rate amplitude arguments are used to scale the amplitudes of each files separately before they are added together and used in the resynthesis (see below for further explanation). The frequencies of the first file are not used at all in this process. This unit simply allows for cross-synthesis through the application of the amplitudes of the spectra of one signal to the frequencies of a second signal. Unlike pvinterp, pvcross does allow for the use of the ispecwp as in pvoc and vpvoc.

tableseg and tablexseg are like linseg and expseg but interpolate between values in a stored function tables. The result is a new function table passed internally to any following vpvoc or voscili which occurs before a subsequent tableseg or tablexseg (much like lpread/lpreson pairs work). The uses of these are described below under vpvoc and (see also voscili which allows the use of these units in an interpolating oscillator).

vpvoc is identical to pvoc except that it takes the result of a previous tableseg or tablexseg and uses the resulting function table (passed internally to the vpvoc), as an envelope over the magnitudes of the analysis data channels. The result is spectral enveloping. The function size used in the tableseg should be framesize/2, where framesize is the number of bins in the phase vocoder analysis file that is being used by the vpvoc. Each location in the table will be used to scale a single analysis bin. By using different functions for ifn1, ifn2, etc.. in the tableseg, the spectral envelope becomes a dynamically changing one.

PERFORMANCE

ifile is the pvoc number (n in pvoc.n) or the name in quotes of the analysis file made using pvanal. See pvoc documentation in Csound manual.

kfreq and kamp are the outputs of the pvread unit. These values, retrieved from a phase vocoder analysis file, represent the values of frequency and amplitude from a single analysis channel specified in the ibin argument. Interpolation between analysis frames is performed at k-rate resolution and dependent of course upon the rate and direction of ktimpnt.

ktimpnt, kfmod, and ispecwp used in pvread and vpvoc are exactly the same as for pvoc (see above description of pvinterp for its special use of kfmod).

ibin is the number of the analysis channel from which to return frequency in cps and magnitude.

kfreqscale1, kfreqscale2, kampscale1, kampscale2 are used in pvinterp to scale the frequencies and amplitudes stored in each frame of the phase vocoder analysis file. kfreqscale1 and kampscale1 scale the frequencies and amplitudes of the data from the file read by the previously called pvbufread (this data is passed internally to the pvinterp unit). kfreqscale2 and kampscale2 scale the frequencies and amplitudes of the file named by ifile in the pvinterp argument list and read within the pvinterp unit. By using these arguments it is possible to adjust these values before applying the interpolation. For example, if file1 is much louder than file2, it might be desirable to scale down the amplitudes of file1 or scale up those of file2 before interpolating. Likewise one can adjust the frequencies of each to bring them more in accord with one another (or just the opposite of course!) before the interpolation is performed.

kfreqinterp and kampinterp, used in pvinterp, determine the interpolation distance between the values of one phase vocoder file and the values of a second file. When the value of kfreqinterp is 0, the frequency values will be entirely those from the first file (read by the pvbufread), post scaling by the kfreqscale1 argument. When the value of kfreqinterp is 1 the frequency values will be those of the second file (read by the pvinterp unit itself), post scaling by kfreqscale2. When kfreqinterp is between 0 and 1 the frequency values will be calculated, on a bin, by bin basis, as the percentage between each pair of frequencies (in other words, kfreqinterp=.5 will cause the frequencies values to be half way between the values in the set of data from the first file and the set of data from the second file). kampinterp1 and kampinterp2 work in the same way upon the amplitudes of the two files. Since these are k-rate arguments, the percentages can change over time making it possible to create many kinds of transitions between sounds.

ifn1, ifn2, ifn3, etc... in tableseg and tablexseg are stored functions, created from an f-card in the numeric notelist. ifn1, ifn2, and so on, MUST be the same size.

idur1, idur2, etc...in tableseg and tablexseg are the durations during which interpolation from one table to the next will take place.

EXAMPLE:

The example below shows the use pvread to synthesize a single component from a phase vocoder analysis file. It should be noted that the kfreq and kamp outputs can be used for any kind of synthesis, filtering, processing, and so on.

ktime         line    0, p3, 3 
kfreq, kamp   pvread  ktime, "pvoc.file", 7 ; read
                                        ;data from 7th analysis bin.  
asig          oscili  kamp, kfreq, 1  ; function 1
                                        ;is a stored sine

The example below shows an example using pvbufread with pvinterp to interpolate between the sound of an oboe and the sound of a clarinet. The value of kinterp returned by a linseg is used to determine the timing of the transitions between the two sounds. The interpolation of frequencies and amplitudes are controlled by the same factor in this example, but for other effects it might be interesting to not have them sychnronized in this way. In this example the sound will begin as a clarinet, transform into the oboe and then return again to the clarinet sound. The value of kfreqscale2 is 1.065 because the oboe in this case is a semitone higher in pitch than the clarinet and this brings them approximately to the same pitch. The value of kampscale2 is .75 because the analyzed clarinet was somewhat louder than the analyzed oboe. The setting of these two parameters make the transition quite smooth in this case, but such adjustments are by no means necessary or even advocated.

ktime1  line      0, p3, 3.5 ; used as index in the "oboe.pvoc" file
ktime2  line      0, p3, 4.5 ; used as index in the "clar.pvoc" file
kinterp linseg    1, p3*.15, 1, p3*.35, 0, p3*.25, 0, p3*.15, 1, p3*.1, 1
        pvbufread ktime1, "oboe.pvoc"
apv     pvinterp  ktime2,1,"clar.pvoc",1,1.065,1,.75,1-kinterp,1-kinterp

Below is an example using pvbufread with pvcross. In this example the amplitudes used in the resynthesis gradually change from those of the oboe to those of the clarinet. The frequencies, of course, remain those of the clarinet throughout the process since pvcross does not use the frequency data from the file read by pvbufread.

ktime1  line    0, p3, 3.5 ; used as index in the "oboe.pvoc" file
ktime2  line    0, p3, 4.5 ; used as index in the "clar.pvoc" file
kcross  expon   .001, p3, 1
        pvbufread       ktime1, "oboe.pvoc"
apv     pvcross ktime2, 1, "clar.pvoc", 1-kcross, kcross

In following example using vpvoc shows the use of functions such as

        f 1 0 256 5 .001 128 1 128 .001
        f 2 0 256  5 1 128 .001 128 1
        f 3 0 256  7 1 256 1

to scale the amplitudes of the separate analysis bins.

ktime   line            0, p3,3 ; time pointer, in seconds, into file
        tablexseg       1, p3*.5, 2, p3*.5, 3
apv     vpvoc           ktime,1, "pvoc.file"

The result would be a time-varying "spectral envelope" applied to the phase vocoder analysis data. Since this amplifies or attenuates the amount of signal at the frequencies that are paired with the amplitudes which are scaled by these functions, it has the effect of applying very accurate filters to the signal. In this example the first table would have the effect of a band- pass filter , gradually be band-rejected over half the note's duration, and then go towards no modification of the magnitudes over the second half.


CsoundManual - Top of this section - Previous - Contents - Index - Next

fof, fof2

     ar   fof  xamp, xfund, xform, koct, kband, kris, kdur, kdec, \
                    iolaps, ifna, ifnb, itotdur[, iphs][, ifmode]  
     ar   fof2  xamp, xfund, xform, koct, kband, kris, kdur, kdec, \
                    iolaps, ifna, ifnb, itotdur, kphs, kgliss  


DESCRIPTION

Audio output is a succession of sinusoid bursts initiated at frequency xfund with a spectral peak at xform. For xfund above 25 Hz these bursts produce a speech-like formant with spectral characteristics determined by the k-input parameters. For lower fundamentals this generator provides a special form of granular synthesis.

fof2 implements k-rate incremental indexing into ifna function with each successive burst.

INITIALIZATION

iolaps - number of preallocated spaces needed to hold overlapping burst data. Overlaps are frequency dependent, and the space required depends on the maximum value of xfund * kdur. Can be over-estimated at no computation cost. Uses less than 50 bytes of memory per iolap.

ifna, ifnb- table numbers of two stored functions. The first is a sine table for sineburst synthesis (size of at least 4096 recommended). The second is a rise shape, used forwards and backwards to shape the sineburst rise and decay; this may be linear ( GEN07) or perhaps a sigmoid ( GEN19).

itotdur - total time during which this fof will be active. Normally set to p3. No new sineburst is created if it cannot complete its kdur within the remaining itotdur.

iphs (optional) - initial phase of the fundamental, expressed as a fraction of a cycle (0 to 1). The default value is 0.

ifmode (optional) - formant frequency mode. If zero, each sineburst keeps the xform frequency it was launched with. If non-zero, each is influenced by xform continuously. The default value is 0.

PERFORMANCE

xamp - peak amplitude of each sineburst, observed at the true end of its rise pattern. The rise may exceed this value given a large bandwidth (say, Q < 10) and/or when the bursts are overlapping.

xfund - the fundamental frequency (in Hertz) of the impulses that create new sinebursts.

xform - the formant frequency, i.e. freq of the sinusoid burst induced by each xfund impulse. This frequency can be fixed for each burst or can vary continuously (see ifmode).

koct - octaviation index, normally zero. If greater than zero, lowers the effective xfund frequency by attenuating odd-numbered sinebursts. Whole numbers are full octaves, fractions transitional.

kband - the formant bandwidth (at -6dB), expressed in Hz. The bandwidth determines the rate of exponential decay throughout the sineburst, before the enveloping described below is applied.

kris, kdur, kdec - rise, overall duration, and decay times (in seconds) of the sinusoid burst. These values apply an enveloped duration to each burst, in similar fashion to a Csound linen generator but with rise and decay shapes derived from the ifnb input. kris inversely determines the skirtwidth (at -40 dB) of the induced formant region. kdur affects the density of sineburst overlaps, and thus the speed of computation. Typical values for vocal imitation are .003,.02,.007.

In the fof2 implementation, kphs allows k-rate indexing of function table ifna with each succesive burst, making it suitable for time-warping applications. Values of for kphs are normalized from 0 to 1, 1 being the end of the function table ifna. kgliss - sets the end pitch of each grain relative to the initial pitch, in octaves. Thus kgliss = 2 means that the grain ends two octaves above its initial pitch, while kgliss = -5/3 has the grain ending a perfect major sixth below. Note: There are no optional parameters in fof2

Csound's fof generator is loosely based on Michael Clarke's C-coding of IRCAM's CHANT program (Xavier Rodet et al.). Each fof produces a single formant, and the output of four or more of these can be summed to produce a rich vocal imitation. fof synthesis is a special form of granular synthesis, and this implementation aids transformation between vocal imitation and granular textures. Computation speed depends on kdur, xfund, and the density of any overlaps.


CsoundManual - Top of this section - Previous - Contents - Index - Next

fog

   ar   fog    xamp, xdens, xtrans, xspd, koct, kband, kris,  \
                  kdur, kdec, iolaps, ifna, ifnb, itotdur[, iphs] \    
                  [, itmode] 


DESCRIPTION

Audio output is a succession of grains derived from data in a stored function table ifna. The local envelope of these grains and their timing is based on the model of fof synthesis and permits detailed control of the granular synthesis.

INITIALIZATION

iolaps - number of pre-located spaces needed to hold overlapping grain data. Overlaps are density dependent, and the space required depends on the maximum value of xdens* kdur. Can be over-estimated at no computation cost. Uses less than 50 bytes of memory per iolaps.

ifna, ifnb - table numbers of two stored functions. The first is the data used for granulation, usually from a soundfile (GEN01). The second is a rise shape, used forwards and backwards to shape the grain rise and decay; this is normally a sigmoid (GEN19) but may be linear (GEN07).

itotdur - total time during which this fog will be active. Normally set to p3. No new grain is created if it cannot complete its kdur within the remaining itotdur.

iphs (optional) - initial phase of the fundamental, expressed as a fraction of a cycle (0 to 1). The default value is 0.

itmode (optional) - transposition mode. If zero, each grain keeps the xtrans value it was launched with. if non-zero, each is influenced by xtrans continuously. The default value is 0.

PERFORMANCE

xamp - amplitude factor. Amplitude is also dependent on the number of overlapping grains, the interaction of the rise shape (ifnb) and the exponential decay (kband), and the scaling of the grain waveform (ifna). The actual amplitude may therefore exceed xamp.

xdens - density. The frequency of grains per second.

xtrans - transposition factor. The rate at which data from the stored function table ifna is read within each grain. This has the effect of transposing the original material. A value of 1 produces the original pitch. Higher values transpose upwards, lower values downwards. Negative values result in the function table being read backwards.

xspd - speed. The rate at which successive grains advance through the stored function table ifna. xspd is in the form of an index (0 to 1) to ifna. This determines the movement of a pointer used as the starting point for reading data within each grain. (xtrans determines the rate at which data is read starting from this pointer.)

koct - octaviation index. The operation of this parameter is identical to that in fof.

kband, kris, kdur, kdec - grain envelope shape. These parameters determine the exponential decay (kband), and the rise (kris), overall duration (kdur,) and decay (kdec ) times of the grain envelope. Their operation is identical to that of the local envelope parameters in fof.

The Csound fog generator is by Michael Clarke, extending his earlier work based on IRCAM's fof algorithm.

EXAMPLE:

 ;p4 = transposition factor
 ;p5 = speed factor
 ;p6 = function table for grain data
 i1  = sr/ftlen(p6) ;scaling to reflect sample rate and table length
 a1  phasor i1*p5 ;index for speed
 a2  fog    5000, 100, p4, a1, 0, 0, , .01, .02, .01, 2, p6, 1, p3, 0, 1 

AUTHOR:

Michael Clark
Huddersfield
May 1997


CsoundManual - Top of this section - Previous - Contents - Index - Next

grain

      ar    grain   xamp, xpitch, xdens, kampoff, kpitchoff, kgdur, \
                      igfn,iwfn,imgdur


DESCRIPTION

Generates granular synthesis textures.

INITIALIZATION

igfn, igdur - igfn is the ftable number of the grain waveform. This can be just a sine wave or a sampled sound of any length. Each grain will start from a random table position and sustain for igdur seconds.

iwfn - Ftable number of the amplitude envelope used for the grains (see also GEN20).

imgdur - Maximum grain duration in seconds. This the biggest value to be assigned on kgdur.

PERFORMANCE

xamp - Total amplitude of the sound.

xpitch - Grain frequency in cps.

xdens - Density of grains measured in grains per second. If this is constant then the output is synchronous granular synthesis, very similar to fof. If xdens has a random element (like added noise), then the result is more like asynchronous granular synthesis.

kampoff - Maximum amplitude deviation from kamp. This means that the maximum amplitude a grain can have is xamp + kampoff and the minimum is kamp. If kampoff is set to zero then there is no random amplitude for each grain.

kpitchoff - Maximum pitch deviation from kpitch in cps. Similar to kampoff.

kgdur - Grain duration in seconds. The maximum value for this should be declared in imgdur. If kgdur at any point becomes greater than imgdur, it will be truncated to imgdur.


CsoundManual - Top of this section - Previous - Contents - Index - Next

granule

asig    granule  xamp, ivoice, iratio, imode, ithd, ifn, ipshift, \
                   igskip, igskip_os, ilength, kgap, igap_os, kgsize, \
                   igsize_os, iatt, idec [,iseed][,ipitch1][,ipitch2] \
                   [,ipitch3][,ipitch4][,ifnenv]


DESCRIPTION

The granule unit generator (Allan Lee) is more complex than grain (above), but does add new possibilities. This is a shorten manual, without the pictures,

granule is a Csound unit generator which employs a wavetable as input to produce granularly synthesized audio output. Wavetable data may be generated by any of the gen subroutines such as gen01 which reads an audio data file into a wavetable. This enable a sampled sound to be used as the source for the grains. Up to 128 voices are implemented internally.The maximum number of voices can be increased by redefining the variable MAXVOICE in the grain4.h file. granule has a build-in random number generator to handle all the random offset parameters. Thresholding is also implemented to scan the source function table at initialization stage. This facilitates features such as skipping silence passage between sentences.

The characteristics of the synthesis are controlled by 22 parameters. xamp is the amplitude of the output and it can be either audio rate or control rate variable. All parameters with prefix i must be valid at Init time, parameters with prefix k can be either control or Init values.

PERFORMANCE

xamp - amplitude.

ivoice - number of voices.

iratio - ratio of the speed of the gskip pointer relative to output audio sample rate. eg. 0.5 will be half speed.

imode - +1 grain pointer move forward (same direction of the gskip pointer), -1 backward (oppose direction to the gskip pointer) or 0 for random.

ithd - threshold, if the sampled signal in the wavetable is smaller then ithd, it will be skipped.

ifn - function table number of sound source.

ipshift - pitch shift control. If ipshift is 0, pitch will be set randomly up and down an octave. If ipshift is 1, 2, 3 or 4, up to four different pitches can be set amount the number of voices definded in ivoice. The optional parameters ipitch1, ipitch2, ipitch3 and ipitch4 are used to quantify the pitch shifts.

igskip - initial skip from the beginning of the function table in sec.

igskip_os - gskip pointer random offset in sec, 0 will be no offset.

ilength - length of the table to be used starting from igskip in sec.

kgap - gap between grains in sec.

igap_os - gap random offset in % of the gap size, 0 gives no offset.

kgsize - grain size in sec.

igsize_os - grain size random offset in % of grain size, 0 gives no offset.

iatt - attack of the grain envelope in % of grain size.

idec - decade of the grain envelope in % of grain size.

[iseed] - optional, seed for the random number generator, default is 0.5.

[ipitch1], [ipitch2], [ipitch3], [ipitch4]- optional, pitch shift parameter, used when ipshift is set to 1, 2, 3 or 4. Time scaling technique is used in pitch shift with linear interpolation between data points. Default value is 1, the original pitch.

EXAMPLE:

Orchestra file:

sr = 44100
kr = 4410
ksmps = 10
nchnls = 2
instr 1
;
k1      linseg  0,0.5,1,(p3-p2-1),1,0.5,0
a1      granule  p4*k1,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14,p15,\
                   p16,p17,p18,p19,p20,p21,p22,p23,p24
a2      granule  p4*k1,p5,p6,p7,p8,p9,p10,p11,p12,p13,p14,p15,\
                   p16,p17,p18,p19, p20+0.17,p21,p22,p23,p24
        outs a1,a2
endin

Score file:

; f statement read sound file sine.aiff in the SFDIR 
; directory into f-table 1
f1      0 524288 1 "sine.aiff" 1 0
i1      0 10 2000 64 0.5 0 0 1 4 0 0.005 10 0.01 50 0.02 50 30 30 0.39 \
        1 1.42 0.29 2
e

The above example reads a sound file called sine.aiff into wavetable number 1 with 524,288 samples. It generates 10 seconds of stereo audio output using the wavetable. In the orchestra file, all parameters required to control the synthesis are passed from the score file. A linseg function generator is used to generate an envelope with 0.5 second of linear attack and decade. Stereo effect is generated by using different seeds for the two granule function calls. In the example, 0.17 is added to p20 before passing into the second granule call to ensure that all of the random offset events are different from the first one.

In the score file, the parameters are interpreted as:

p5  (ivoice) the number of voices is set to 64
p6  (iratio) is set to 0.5, it scan the wavetable at half of the speed
      of the audio output rate
p7  (imode) is set to 0, the grain pointer only move forward
p8  (ithd) is set to 0, skipping the thresholding process
p9  (ifn) is set to 1, function table number 1 is used
p10 (ipshift) is set to 4, four different pitches are going to be
      generated
p11 (igskip) is set to 0 and p12 (igskip_os) is set to 0.005, no
      skipping into the wavetable and a 5 mSec random offset is used
p13 (ilength) is set to 10, 10 seconds of the wavetable is to be used 
p14 (kgap) is set to 0.01 and p15 (igap_os) is set to 50, 10 mSec gap
      with 50% random offset is to be used
p16 (kgsize) is set to 0.02 and p17 (igsize_os) is set to 50, 20 mSec
      grain with 50% random offset is used
p18 (iatt) and p19 (idec) are set to 30, 30% of linear attack and
      decade is applied to the grain
p20 (iseed) seed for the random number generator is set to 0.39
p21 - p 24 are pitches set to 1 which is the original pitch, 1.42
      which is a 5th up, 0.29 which is a 7th down and finally 2 which is
      an octave up.


CsoundManual - Top of this section - Previous - Contents - Index - Next

pluck

     ar   pluck     kamp, kcps, icps, ifn, imeth [, iparm1, iparm2] 


DESCRIPTION

Audio output is a naturally decaying plucked string or drum sound based on the Karplus-Strong algorithms.

INITIALIZATION

icps - intended pitch value in cps, used to set up a buffer of 1 cycle of audio samples which will be smoothed over time by a chosen decay method. icps normally anticipates the value ofkcps, but may be set artificially high or low to influence the size of the sample buffer.

ifn - table number of a stored function used to initialize the cyclic decay buffer. If ifn = 0, a random sequence will be used instead.

imeth - method of natural decay. There are six, some of which use parameters values that follow.

  1. simple averaging. A simple smoothing process, uninfluenced by parameter values.

  2. stretched averaging. As above, with smoothing time stretched by a factor of iparm1 ( >= 1 ).

  3. simple drum. The range from pitch to noise is controlled by a 'roughness factor' in iparm1 (0 to 1). Zero gives the plucked string effect, while 1 reverses the polarity of every sample (octave down, odd harmonics). The setting .5 gives an optimum snare drum.

  4. stretched drum. Combines both roughness and stretch factors. iparm1 is roughness (0 to 1), and iparm2 the stretch factor ( >= 1 ).

  5. weighted averaging. As method 1, with iparm1 weighting the current sample (the status quo) and iparm2 weighting the previous adjacent one. iparm1 + iparm2must be <= 1.

  6. 1st order recursive filter, with coefs .5. Unaffected by parameter values.

iparm1, iparm2 (optional) - parameter values for use by the smoothing algorithms (above). The default values are both 0.

PERFORMANCE

An internal audio buffer, filled at I-time according to ifn, is continually resampled with periodicity kcps and the resulting output is multiplied by kamp. Parallel with the sampling, the buffer is smoothed to simulate the effect of natural decay.

Plucked strings (1,2,5,6) are best realized by starting with a random noise source, which is rich in initial harmonics. Drum sounds (methods 3,4) work best with a flat source (wide pulse), which produces a deep noise attack and sharp decay.

The original Karplus-Strong algorithm used a fixed number of samples per cycle, which caused serious quantization of the pitches available and their intonation. This implementation resamples a buffer at the exact pitch given by kcps, which can be varied for vibrato and glissando effects. For low values of the orch sampling rate (e.g. sr = 10000), high frequencies will store only very few samples (sr / icps). Since this may cause noticeable noise in the resampling process, the internal buffer has a minimum size of 64 samples. This can be further enlarged by setting icps to some artificially lower pitch.


CsoundManual - Top of this section - Previous - Contents - Index - Next

rand, randh, randi

     kr   rand      xamp[, iseed]
     kr   randh     kamp, kcps[, iseed]
     kr   randi     kamp, kcps[, iseed]
     ar   rand      xamp[, iseed]
     ar   randh     xamp, xcps[, iseed]
     ar   randi     xamp, xcps[, iseed] 


DESCRIPTION

Output is a controlled random number series between +amp and -amp

INITIALIZATION

iseed (optional) - seed value for the recursive psuedo-random formula. A value between 0 and +1 will produce an initial output of kamp * iseedA negative value will cause seed re-initialization to be skipped. The default seed value is .5.

PERFORMANCE

The internal psuedo-random formula produces values which are uniformly distributed over the range kamp to -kamp. rand will thus generate uniform white noise with an R.M.S value of kamp / root 2.

The remaining units produce band-limited noise: the cps parameters permit the user to specify that new random numbers are to be generated at a rate less than the sampling or control frequencies. randh will hold each new number for the period of the specified cycle; randi will produce straightline interpolation between each new number and the next.

EXAMPLE:

   i1   =      octpch(p5) ; center pitch, to be modified
   k1   randh  1,10       ;10 time/sec by random displacements up to 1 octave
   a1   oscil  5000, cpsoct(i1+k1), 1


CsoundManual - Top of this section - Previous - Contents - Index - Next

x-class noise

        xlinrand        krange 
        xtrirand        krange
        xexprand        krange
        xbexprnd        krange
        xcauchy         kalpha
        xpcauchy        kalpha
        xpoisson        klambda
        xgauss          krange
        xweibull        ksigma, ktau
        xbeta           krange, kalpha, kbeta
        xuniform        krange 


DESCRIPTION

All of the following opcodes operate in i-, k- and a-rate. The output rate depends on the first letter of the opcode, a for a-rate, k for k- rate and i for i-rate.

xlinrand krange - Linear distribution random number generator. krange is the range of the random numbers [0 - krange). Outputs only positive numbers.

xtrirand krange - Same as above only ouputs both negative and positive numbers.

xexprand krange - Exponential distribution random number generator. krange is the range of the random numbers [0 - krange). Outputs only positive numbers.

xbexprnd krange - Same as above, only extends to negative numbers too with an exponential distribution.

xcauchy kalpha -Cauchy distribution random number generator. kalpha controls the spread from zero (big kalpha => big spread). Outputs both positive and negative numbers.

xpcauchy kalpha - Same as above, ouputs positive numbers only.

xpoisson klambda - Poisson distribution random number generator. klambda is the mean of the distribution. Outputs only positive numbers.

xgauss krange - Gaussian distribution random number generator. krange is the range of the random numbers (-krange - 0 - krange). Outputs both positive and negative numbers.

xweibull ksigma, ktau - Weibull distribution random number generator. ksigma scales the spread of the distribution and ktau, if greater than one numbers near ksigma are favored, if smaller than one small values are favored and if t equals 1 the distribution is exponential. Outputs only positive numbers.

xbeta krange, kalpha, kbeta - Beta distribution random number generator. krange is the range of the random numbers [0 - krange). If kalpha is smaller than one, smaller values favor values near 0. If kbeta is smaller than one, smaller values favor values near krange. If both kalpha and kbeta equal one we have uniform distribution. If both kalpha and kbeta are greater than one we have a sort of gaussian distribution. Outputs only positive numbers.

xuniform krange - Uniform distribution random number generator. krange is the range of the random numbers [0 - krange).

For more detailed explanation of these distributions, see:

1. C. Dodge - T.A. Jerse 1985. Computer music. Schirmer books. pp.265 - 286

2. D. Lorrain. A panoply of stochastic cannons. In C. Roads, ed. 1989. Music machine . Cambridge, Massachusetts: MIT press, pp. 351 - 379.

EXAMPLE:

a1  atrirand    32000         ; Audio noise with triangle distribution
k1  kcauchy     10000         ; Control noise with Cauchy dist.
i1  ibetarand   30000, .5, .5 ; i-time random value, beta dist.


CsoundManual - Top of this section - Previous - Contents - Index - Next

sndwarp, sndwarpst

asig[,acmp] sndwarp   xamp, xtimewarp, xresample, ifn1, ibeg,\
                        iwsize, irandw, ioverlap, ifn2, itimemode

asig1,asig2[,acmp1,acmp2] sndwarpst xamp, xtimewarp, xresample, ifn1,\
                         ibeg, iwsize, irandw, ioverlap, ifn2, itimemode


DESCRIPTION

sndwarp reads sound samples from a table and applies time-stretching and/or pitch modification. Time and frequency modification are indepentant from one another. For example, a sound can be stretched in time while raising the pitch! The window size and overlap arguments are important to the result and should be experimented with. In general they should be as small as possible. For example, start with iwsize=sr/10 and ioverlap=15. Try irandw=iwsize*.2. If you can get away with less overlaps, the program will be faster. But too few may cause an audible flutter in the amplitude. The algorithm reacts differently depending upon the input sound and there are no fixed rules for the best use in all circumstances. But with proper tuning, excellent results can be achieved.

INITIALIZATION

ifn1 is the number of the table holding the sound samples which will be subjected to the sndwarp processing. GEN01 is the appropriate function generator to use to store the sound samples from a pre-existing soundfile.

ibeg is the time in seconds to begin reading in the table (or soundfile). When itimemode is non- zero, the value of itimewarp is offset by ibeg.

iwsize is the window size in samples used in the time scaling algorithm.

irandw is the bandwidth of a random number generator. The random numbers will be added to iwsize.

ioverlap determines the density of overlapping windows.

ifn2 is a function used to shape the window. It is usually used to create a ramp of some kind from zero at the beginning and back down to zero at the end of each window. Try using a half a sine (ie: f1 0 16384 9 .5 1 0) which works quite well. Other shapes can also be used.

PERFORMANCE

asig is the single channel of output from the sndwarp unit generator while asig1 and asig2 are the stereo (left and right) outputs from sndwarpst. sndwarp assumes that the function table holding the sampled signal is a mono one while sndwarpst assumes that it is stereo. This simply means that sndwarp will index the table by single-sample frame increments and sndwarpst will index the table by a two-sample frame increment. The user must be aware then that if a mono signal is used with sndwarst or a stereo one with sndwarp, time and pitch will be altered accordingly.

acmp in sndwarp and acmp1, acmp2 in sndwarpst, are single layer (no overlaps), unwindowed versions of the time and/or pitch altered signal. They are supplied in order to be able to balance the amplitude of the signal output, which typically contains many overlapping and windowed versions of the signal, with a clean version of the time-scaled and pitch-shifted signal. The sndwarp process can cause noticeable changes in amplitude, (up and down), due to a time differential between the overlaps when time-shifting is being done. When used with a balance unit, acmp, acmp1, acmp2 can greatly enhance the quality of sound. They are optional, but note that in sndwarpst they must both be present in the syntax (use both or neither). An example of how to use this is given below.

xamp is the value by which to scale the amplitude (see note on the use of this when using acmp, acmp1, acmp2).

xtimewarp determines how the input signal will be stretched or shrunk in time. There are two ways to use this argument depending upon the value given for itimemode. When the value of itimemode is 0, xitimewarp will scale the time of the sound. For example, a value of 2 will stretch the sound by 2 times. When itimemode is any non-zero value then xtimewarp is used as a time pointer in a similar way in which the time pointer works in lpread and pvoc. An example below illustrates this. In both cases, the pitch will NOT be altered by this process. Pitch shifting is done independently using xresample.

xresample is the factor by which to change the pitch of the sound. For example, a value of 2 will produce a sound one octave higher than the original. The timing of the sound, however, will NOT be altered.

EXAMPLE:

The below example shows a slowing down or stretching of the sound stored in the stored table (ifn1). Over the duration of the note, the stretching will grow from no change from the original to a sound which is ten times "slower" than the original. At the same time the overall pitch will move upward over the duration by an octave.

iwindfun=1
isampfun=2
ibeg=0
iwindsize=2000
iwindrand=400
ioverlap=10
awarp   line    1, p3, 1
aresamp line    1, p3, 2
kenv    line    1, p3, .1
asig    sndwarp kenv,awarp,aresamp,isampfun,ibeg,iwindsize,iwindrand, \
                ioverlap,iwindfun,0

Now, here's an example using xtimewarp as a time pointer and using stereo:

itimemode     =         1
atime         line      0, p3, 10
asig1, asig2  sndwarpst kenv, atime, aresamp, sampfun, ibeg, \
                           iwindsize, iwindrand, ioverlap, \
                           iwindfun, itimemode

In the above, atime advances the time pointer used in the sndwarp from 0 to 10 over the duration of the note. If p3 is 20 then the sound will be two times slower than the original. Of course you can use a more complex function than just a single straight line to control the time factor.

Now the same as above but using the balance function with the optional outputs:

asig,acmp   sndwarp  1,awarp,aresamp,isampfun,ibeg,iwindsize,iwindrand,\
                            ioverlap,iwindfun,itimemode

abal        balance asig, acmp
asig1,asig2,acmp1,acmp2 sndwarpst 1, atime, aresamp, sampfun,\
                                ibeg, iwindsize, iwindrand, \
                                ioverlap, iwindfun, itimemode
abal1       balance asig1, acmp1
abal2       balance asig2, acmp2

In the above two examples notice the use of the balance unit. The output of balance can then be scaled, enveloped, sent to an out or outs, and so on. Notice that the amplitude arguments to sndwarp and sndwarpst are "1" in these examples. By scaling the signal after the sndwarp process, abal, abal1, and abal2 should contain signals that have nearly the same amplitude as the original input signal to the sndwarp process. This makes it much easier to predict the levels and avoid samples out of range or sample values that are too small.

More advice: Only use the stereo version when you really need to be processing a stereo file. It is someone slower than the mono version and if you use the balance function it is slower again. There is nothing wrong with using a mono sndwarp in a stereo orchestra and sending the result to one or both channels of the stereo output!


CsoundManual - Top of this section - Previous - Contents - Index - Next