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 per channel, 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.

Options

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. Valid values are 1 through 4294967295. If omitted, this defaults to 44100 samples per second (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.

Option noise=truefalse specifies that the audio Array is to be initialized with random (white) noise. Passing initial data is meaningless if this option is true, as it will be overwritten by the generated noise.

The following two options do not affect the internal format used to represent audio data (always an Array with datatype=float[8]), but instead control the form in which the data will be written to a file when using the AudioTools[Write] command:

The float=truefalse option specifies whether the audio data will be written to a file as integer (float=false) or floating point (float=true) values. The default is integer.

The bits=integer option specifies the number of bits per sample that are written when the audio data is eventually written to a file. If not specified, the default is 16 (CD quality) if float=false, or 32 if float=true.

All parameters and options to Create are optional. If called with no arguments, Create returns one channel containing one second of silence, 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.

$\mathrm{with}\left(\mathrm{AudioTools}\right)\:$

$\mathrm{aud}≔\mathrm{Create}\left(\mathrm{duration}=5.0\right)$

$\mathrm{aud}≔\left[\begin{array}{cc}''Sample\; Rate''& 44100\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 16\\ ''Channels''& 1\\ ''Samples/Channel''& 220500\\ ''Duration''& 5.00000s\end{array}\right]$

$\mathrm{attributes}\left(\mathrm{aud}\right)$

$44100,16,1$

$\mathrm{aud}≔\mathrm{Create}\left(7.5\,\mathrm{channels}=2\,\mathrm{rate}=11025\,8\,\mathrm{order}=\mathrm{C\_order}\right)$

$\mathrm{aud}≔\left[\begin{array}{cc}''Sample\; Rate''& 11025\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 16\\ ''Channels''& 2\\ ''Samples/Channel''& 82688\\ ''Duration''& 7.50005s\end{array}\right]$

$\mathrm{attributes}\left(\mathrm{aud}\right)$

$11025,16,1$

$\mathrm{aud}≔\mathrm{Create}\left(x\mapsto \mathrm{evalhf}\left(\sin \left(\frac{x}{4}-\frac{1}{4}\right)\right)\right)$

$\mathrm{aud}≔\left[\begin{array}{cc}''Sample\; Rate''& 44100\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 16\\ ''Channels''& 1\\ ''Samples/Channel''& 44100\\ ''Duration''& 1.00000s\end{array}\right]$

$\mathrm{printf}\left(''\%1.2f\backslash n''\,\mathrm{aud}\left[1..8\right]\right)$

0.00 0.25 0.48 0.68 0.84 0.95 1.00 0.98

$\mathrm{aud}≔\mathrm{Create}\left(\right)$

$\mathrm{aud}≔\left[\begin{array}{cc}''Sample\; Rate''& 44100\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 16\\ ''Channels''& 1\\ ''Samples/Channel''& 44100\\ ''Duration''& 1.00000s\end{array}\right]$

$\mathrm{attributes}\left(\mathrm{aud}\right)$

$44100,16,1$

The AudioTools[Create] command was updated in Maple 2020.

The noise and float options were introduced in Maple 2020.

For more information on Maple 2020 changes, see Updates in Maple 2020.