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 in versions before 5.14, and 40 after.

Syntax

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

ar1[] diskin2 ifilcod[, kpitch[, iskiptim \
      [, iwrap[, iformat[, iwsize[, ibufsize[, iskipinit]]]]]]]

(in the array output version, the number of output channels does not have an upper limit.)

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³¹-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.

	Note
	If iwrap is not 0 (locations are wrapped), iskiptim will not delay the sound if a negative value is used. Instead, the negative value will be "wrapped" from the end of the file.

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.

	Note
	If iwrap is enabled, the file length should not be shorter than the interpolation window size (see below), otherwise there may be clicks in the sound output.

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.

	Note
	If interpolation is used, kpitch is automatically scaled by the ratio of the sample rate of the sound file and the orchestra, so that the file will always be played at the original pitch if kpitch is 1. However, the sample rate conversion is disabled if iwsize is 1.

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.

ar1[] --- output signals, in a-rate array of size N, where N is the number of channels in the file. Arrays are automatically allocated to the correct size.

	Note
	It is more efficient to read a single file with many channels, than many files with only a single channel, especially with high iwsize settings.

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, which is the default value). 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.

Examples

Here is an example of the diskin2 opcode. It uses the file diskin2.csd, beats.wav.

<CsoundSynthesizer>
<CsOptions>
; Select audio/midi flags here according to platform
-odac     ;;;RT audio out
;-iadc    ;;;uncomment -iadc if RT audio input is needed too
; For Non-realtime ouput leave only the line below:
; -o diskin2.wav -W ;;; for file output any platform
</CsOptions>
<CsInstruments>

sr     = 44100
ksmps  = 32
nchnls = 2
0dbfs  = 1

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 diskin

Credits

New in version 5.00

kpitch optional in version 6.06