AudioTools[Create] - creates an Array suitable for storing audio data
|
Calling Sequence
|
|
Create(data, options)
|
|
Parameters
|
|
data
|
-
|
(optional); data with which to initialize the audio Array
|
options
|
-
|
various options to specify attributes of the created Array
|
|
|
|
|
Description
|
|
•
|
The Create command creates an Array suitable for storing audio data. All parameters are optional and have suitable defaults as described below.
|
•
|
The optional data parameter specifies data that is used to initialize the audio Array. It can be a 1- or 2-D Array, a Matrix, a Vector, a numeric list, a list of numeric lists, a procedure, a set of equations of the form index=value, or a table.
|
•
|
If the data is an Array, Matrix, or Vector (all of which are instances of rtables), the resulting audio rtable will also be an Array, Matrix, or Vector respectively.
|
|
If the passed rtable has datatype=float[8], storage=rectangular, and no indexing functions, that rtable becomes the audio rtable (that is, no copy is made) unless the copy=true option is specified (see below).
|
•
|
If a list of numeric values is passed, a 1-dimensional Array of the same number of entries is produced. Each value in the list becomes one sample in the Array.
|
•
|
If a list of lists of numeric values is passed, the number of elements in the outer list determines the number of samples, and the number of elements in the first inner list determines the number of audio channels.
|
•
|
Passing a procedure, set, or table for data causes an Array to be created according to the other options described below.
|
|
If a procedure was passed, it is called for each location in that array, being passed the sample number and channel number, and is expected to return a value for that location.
|
|
A set must contain equations of the form index=value, where index is a sample number, or a (sample number, channel number) pair, and value is the sample value for that location in the resulting Array. Array entries for which no equation exists will be initialized to zero.
|
|
If a table is passed, entries in the table with indices corresponding to indices in the resulting Array will initialize those entries in the Array. Array entries for which no corresponding table entry exists will be initialized to zero.
|
•
|
A numeric value can be passed for data, in which case the value is not treated as data, but is used in lieu of the duration option described below. The samples will be initialized to zero.
|
•
|
The duration=numeric option specifies the audio length, in seconds, that can be recorded in the Array. If omitted, this defaults to 1 second. If initial data in the form of an Array, Matrix, Vector, or list was passed via the data parameter, this option is ignored.
|
•
|
The channels=integer option specifies the number of channels of audio data. For example, 1 for mono and 2 for stereo. If omitted, this defaults to one channel. If initial data in the form of an Array, Matrix, Vector, or list was passed via the data parameter, this option is ignored.
|
•
|
The rate=integer option specifies the number of samples (rows in the Array) to be allocated per second of duration. If omitted, this defaults to 44100 samples per second (CD quality).
|
•
|
The bits=integer option specifies the number of bits per sample that are recorded when the audio data is written to a file using the AudioTools[Write] command. If omitted, this defaults to 16 bits per sample (CD quality).
|
•
|
The copy=truefalse option specifies what happens when the data parameter is already an rtable of a format suitable for use by AudioTools. If false (the default), that rtable is changed in-place (by adding some attributes to it) to be the audio rtable returned by Create. If true, then a new audio Array is created, and the data is copied into it. If the data is not in a form suitable to being an audio rtable, a new rtable is always created, regardless of the setting of the copy option.
|
•
|
The order=ord option specifies the internal ordering of the created Array, and can be either C_order or Fortran_order. If initial data in the form of an Array, Matrix, Vector, or list was passed via the data parameter, this option is ignored.
|
•
|
All parameters and options to Create are optional. If called with no arguments, Create returns one channel containing one second of silence, sampled at 44100 samples per second, with 16 bits per sample.
|
•
|
The output from the Create command is an Array (unless the initial data was returned as the output, in which case it may be a Matrix or Vector) with dimensions appropriate to the duration, rate, and bits specified. It will also have three numeric attributes describing the data: rate, bits, and sub-format. The latter is currently always 1, corresponding to the PCM sub-format of the WAVE file format.
|
|
|
Examples
|
|
>
|
|
>
|
|
| (1) |
>
|
|
| (2) |
>
|
|
| (3) |
>
|
|
| (4) |
>
|
|
| (5) |
>
|
|
0.00 0.25 0.48 0.68 0.84 0.95 1.00 0.98
| |
>
|
|
| (6) |
>
|
|
| (7) |
|
|