Sample                 package:sound                 R Documentation

_S_a_m_p_l_e _O_b_j_e_c_t_s

_D_e_s_c_r_i_p_t_i_o_n:

     '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.

_U_s_a_g_e:

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

_A_r_g_u_m_e_n_t_s:

   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 sample 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. 

_D_e_t_a_i_l_s:

     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 about
     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.

_V_a_l_u_e:

     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.

_A_u_t_h_o_r(_s):

     Matthias Heymann

_S_e_e _A_l_s_o:

     '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.

_E_x_a_m_p_l_e_s:

     ## Not run: 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:
     s <- anyargument
     sampletest <- is.Sample(s, argname="s ")
     if (!sampletest$test) stop(sampletest$error) #no valid argument
     t <- loadSample(s,filecheck=FALSE)
     # If s is Sample object, loadSample will return it immediately.
     # If s is a string, the Sample object will be loaded from disk.
     # No check for existance of the file will be performed since this
     # was already tested in is.Sample.
     #
     # Now s is a Sample object, continue with routine.
     ## End(Not run)

