channels = integer, set of integers, or integer range

This option specifies the subset of channels to read from a multi-channel audio file. Only channels 1 through 64 can be specified. If the channels option is not given, or channelSet is an empty set, all channels will be read.

format = fmtdesc

If the format=fmtDesc option is specified, fmtDesc must correspond to one of the values in AudioTools[Formats]. If not specified, the Read attempts to determine the format from the fileName.

mapping = one of min, max, or range

This option specifies how the audio data in an integer format audio file is to be mapped to floating point (which is how audio data is represented in memory in Maple):

mapping=max specifies that the maximum (most positive) integer value will map to 1.0, and the negation of that value will map to -1.0. For example, -32767 to +32767 will map to -1.0 to +1.0. If the largest negative integer value (-32768 for 16-bit format) is encountered, it will be mapped to a value proportionally less than -1.0 (e.g. -32768 will map to -1.000030519), and a warning will be issued.

mapping=min specifies that the minimum (most negative) integer value will map to -1.0, and the most positive to a value proportionally less than +1.0 (e.g. +32767 will map to 0.9999694819 for 16-bit audio).

mapping=range specifies that the entire range of integer values (e.g. -32768 to +32767 for 16-bit integer format) will be mapped to the floating-point range -1.0 to +1.0. This is the default, but is asymmetrical because there is one more negative value than positive value.

Using a mapping other than the one with which the file was originally written, perhaps by another application, will introduce a tiny amount of distortion in the signal. The AudioTools:-Write command has a corresponding option. If the same option is used when both writing and reading, no extra distortion will be introduced (unless clipping occurs).

order = one of C_order or Fortran_order

The order option specifies whether the Array allocated by Read will have C (row-major) or Fortran (column-major) storage order. The default is Fortran order. If an Array is given via the optArray parameter, the order option is ignored and the storage order of the given Array is used.

samples = integer .. integer

The option samples=sampleRange where sampleRange is an integer range, will read only the specified range of samples.

The Read command reads an audio file in one of the supported formats and returns an Array containing the audio.

If optArray is specified, it must be a dense, rectangular, one or two dimensional Array, Vector, or Matrix with datatype=float[8]. If not specified, the Read command will allocate an Array appropriate for the audio data being read.

If the audio data has a single channel, the Array will have only one dimension. If the audio data has more than one channel, the Array will have two dimensions.  The second dimension will range from 1 to C where C is the number of channels, 1 for mono, 2 for stereo, and so on.

The first dimension of the Array corresponds to the length, in samples, of the audio data. A single channel occupies a single column in the Array.

When Read is passed an Array, Vector, or Matrix, it must be writable and have one or two dimensions. The size of the first dimension must correspond to the length of the audio data, or to the length specified by the samples option if used. The size of the second dimension must correspond to the number of channels in the data, or the number of channels specified by the channels option if used.

If the second (possibly omitted) dimension does not correspond to the number of channels in the audio data, it will be converted appropriately while being read. For example, reading Stereo audio into a Vector or one-dimensional Array will produce Mono audio data.

Sample values are stored in the audio Array, Vector, or Matrix as floating-point values ranging from -1.0 to 1.0.

On return from Read, the returned Array, Vector, or Matrix will have three numeric attributes describing the data. The first is the sample rate, in samples per second. The second is the number of bits per sample that were recorded in the file. The third is the sub-format of the file, if applicable (or zero otherwise - some file formats, like ".WAV", have a number of sub-formats, like PCM, ADPCM, or IEEE_FLOAT, represented by an integer from 1 to 3).

For compressed formats such as an ADPCM ".WAV" file, Read decompresses the data. The resulting Array, Vector, or Matrix will contain the decompressed data, although the attributes will still reflect the origin of the data. For example, an ADPCM file sampled at 11.025kHz will have attributes $11025,4,2$, since ADPCM records 4 bits per sample, and is sub-format 2.

$\mathrm{audiofile}≔\mathrm{cat}\left(\mathrm{kernelopts}\left(\mathrm{datadir}\right)\,''/audio/stereo.wav''\right)\:$

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

$\mathrm{aud}≔\mathrm{Read}\left(\mathrm{audiofile}\right)$

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

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

$22050,8,1$

$\mathrm{aud}\left[2000\right]$

$\left[\begin{array}{cc}\mathrm{-0.312500000000000}& 0.771653543307087\end{array}\right]$

$\mathrm{mono}≔\mathrm{ToMono}\left(\mathrm{aud}\right)$

$\mathrm{mono}≔\left[\begin{array}{cc}''Sample\; Rate''& 22050\\ ''File\; Format''& \mathrm{PCM}\\ ''File\; Bit\; Depth''& 8\\ ''Channels''& 1\\ ''Samples/Channel''& 19962\\ ''Duration''& 0.90531s\end{array}\right]$

$\mathrm{mono}\left[2000\right]$

$0.229576771653543$

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

The channels, mapping, order and samples options were introduced in Maple 2020.

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