Description

Reads audio data from a file, and can alter its pitch using one of several available interpolation types, as well as convert the sample rate to match the orchestra sr setting. diskin2 can also read multichannel files with any number of channels in the range 1 to 24. diskin2 allows more control and higher sound quality than diskin, but there is also the disadvantage of higher CPU usage.

Syntax

a1[, a2[, ... a24]] diskin2 ifilcod, kpitch[, iskiptim \
      [, iwrap[, iformat [, iwsize[, ibufsize[, iskipinit]]]]]]

Initialization

ifilcod -- integer or character-string denoting the source soundfile name. An integer denotes the file soundin.ifilcod; a character-string (in double quotes, spaces permitted) gives the filename itself, optionally a full pathname. If not a full path, the named file is sought first in the current directory, then in those given by the environment variable SSDIR (if defined) then by SFDIR. See also GEN01. Note: files longer than 2^31-1 sample frames may not be played correctly on 32 bit platforms; this means a maximum length about 3 hours with a sample rate of 192000 Hz.

iskiptim (optional, defaults to zero) -- time in seconds of input sound to be skipped, assuming kpitch=1. Can be negative, to add -iskiptim/kpitch seconds of delay instead of skipping sound.

iwrap (optional, defaults to zero) -- if set to any non-zero value, read locations that are negative or are beyond the end of the file are wrapped to the duration of the sound file instead of assuming zero samples. Useful for playing a file in a loop.

iformat (optional, defaults to zero) -- sample format, for raw (headerless) files only. This parameter is ignored if the file has a header. Allowed values are:

iwsize (optional, defaults to zero) -- interpolation window size, in samples. Can be one of the following:

Zero or negative values select the default, which is cubic interpolation.

ibufsize (optional, defaults to 0) -- buffer size in mono samples (not sample frames). This is only the suggested value, the actual setting will be rounded so that the number of sample frames is an integer power of two and is in the range 128 (or iwsize if greater than 128) to 1048576. The default, which is 4096, and is enabled by zero or negative values, should be suitable for most uses, but for non-realtime mixing of many large sound files, a high buffer setting is recommended to improve the efficiency of disk reads. For real time audio output, reading the files from a fast RAM file system (on platforms where this option is available) with a small buffer size may be preferred.

iskipinit (optional, defaults to 0) -- skip initialization if set to any non-zero value.

Performance

a1 ... a24 -- output signals, in the range -0dbfs to 0dbfs. Any samples before the beginning (i.e. negative location) and after the end of the file are assumed to be zero, unless iwrap is non-zero. The number of output arguments must be the same as the number of sound file channels - which can be determined with the filenchnls opcode, otherwise an init error will occur.

kpitch -- transpose the pitch of input sound by this factor (e.g. 0.5 means one octave lower, 2 is one octave higher, and 1 is the original pitch). Fractional and negative values are allowed (the latter results in playing the file backwards, however, in this case the skip time parameter should be set to some positive value, e.g. the length of the file, or iwrap should be non-zero, otherwise nothing would be played). If interpolation is enabled, and the sample rate of the file differs from the orchestra sample rate, the transpose ratio is automatically adjusted to make sure that kpitch=1 plays at the original pitch. Using a high iwsize setting (40 or more) can significantly improve sound quality when transposing up, although at the expense of high CPU usage.

Example

<CsoundSynthesizer>
<CsOptions>
; set this to a directory where beats.wav can be found
--env:SSDIR+=/Csound/Documentation/manual/examples
</CsOptions>
<CsInstruments>
sr      =  48000
ksmps   =  32
nchnls  =  2

       instr 1

ktrans  linseg 1, 5, 2, 10, -2
a1      diskin2 "beats.wav", ktrans, 0, 1, 0, 32
       outs a1, a1
       endin

</CsInstruments>
<CsScore>

i 1 0 15
e

</CsScore>
</CsoundSynthesizer>

See Also

in, inh, ino, inq, ins, soundin and diskin2

Credits

Author: Istvan Varga

2005

New in version 5.00