sound (version 1.1)

Sample: Sample Objects

Description

as.Sample creates a Sample object from a given numeric matrix. is.Sample tests if its argument is a Sample object or the name of a wav file.

Usage

as.Sample(sound, rate, bits)
is.Sample(s, argname="'s' ")

Arguments

sound

a channels(s) x sampleLength(s) matrix or a vector of doubles describing the waveform(s) of the sample.

rate

the sampling rate (number of samples per second).

bits

the sampling quality (the number of bits per sample), 8 or 16.

s

an R object to be tested.

argname

a string giving the name of the object that is tested. It is used for creating an error message.

Value

• For as.Sample a Sample object, that is a list with the components $sound, $rate and $bits. is.Sample returns a list with the entries
• test
  a logical indicating whether or not s is a Sample object or the name of a valid wav file.
• error
  a string with one of the messages "Filename must have the extension .wav.", "File not found.", "No read permission for this file.", or "Argument "+ argname + "must be a Sample object or the name of a wav file." If test=TRUE, this list entry doesn't exist.

Details

The rows of the matrix represent the channels of the sample: If sound is a vector or a matrix with only one row, as.Sample will return a mono sample; if sound is a matrix with two rows, as.Sample returns a stereo sample, where the left and the right channel are represented by the first and the second row, respectively. sound can contain any real number, but when the Sample object is played or saved to disk, [-1,1] is regarded as the range of the sample, and any values outside this interval will cause cracks in the sound. A Sample object's waveform can exceed this interval during calculations. It is the task of the programmer to take care of the range of the waveform before saving or playing the sample, for example by using the normalize command. Internally, the sound is saved as a matrix with doubles, independent of the bits parameter that is only used when the Sample object is played or saved to disk. The is.Sample command is used by several other routines that allow both Sample objects and filenames as arguments.

See Also

stereo for creating a stereo Sample object from two mono Sample objects, loadSample for loading a wav file and turning it into a Sample object, saveSample for saving a Sample object as a wav file, sound, bits, rate, channels, sampleLength and duration for access to the basic parameters of a Sample object.

Examples

waveLeft <- 2*((seq(0,80,length=88200)%%1^2)-.5)
s <- as.Sample(waveLeft,44100,16)
play(s) # a mono sample

waveRight <- waveLeft[88200:1]
s <- as.Sample(rbind(waveLeft,waveRight),44100,16)
play(s) # a stereo Sample

# How to use is.Sample to allow both a Sample object and a filename
# as an argument:
x <- anyargument
sampletest <- is.Sample(x, argname="'x' ")
if (!sampletest$test) stop(sampletest$error) #no valid argument
x <- loadSample(x,filecheck=FALSE)
# If x is Sample object, loadSample will return it immediately.
# If x is a string, the Sample object will be loaded from disk.
# No check for existence of the file will be performed since this
# was already tested in is.Sample.
#
# Now x is a Sample object, continue with code.