format = fmtdesc

If the format=fmtDesc option is specified, fmtDesc must correspond to one of the values in AudioTools[Formats]. Currently, the AudioTools package supports only WAVE files.  If not specified, the Write command attempts to determine the format from the fileName.

mapping= one of min, max, or range

This option specifies how the floating-point audio data in memory is to be mapped to an integer file format:

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

mapping=max specifies that 1.0 will map to the maximum (most positive) integer, and -1.0 will map to the negation of that value. For example, -1.0 to +1.0 will map to -32767 to +32767.

mapping=min specifies that -1.0 will map to the minimum (most negative) integer value. This implies that +1.0 would map to the negation of that value, which can not be represented (e.g. 16-bit integers have the value -32768, but not +32768). Thus, the largest positive floating-point value that can be written in this mode is proportionally less than +1.0. For 16-bit integer format, this is 0.9999694819, which will map to +32767.

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:-Read 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).

If any sample in the audio maps to outside the range of the specified (or default) mapping, a warning will be issued, and the value will be clipped.

The Write command writes audio data from an Array, Matrix, or Vector into a file in one of the supported formats.

The audArray parameter must be a dense, rectangular, one or two dimensional Array, Matrix, or Vector with datatype=float[8].

Write returns the number of bytes written.

If the audArray has one dimension, the audio data is assumed to be monophonic, and is written to the file accordingly. A two-dimensional audArray is written as stereo (or more channels), according to the size of the second dimension.

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.

Samples values in the audArray are assumed to range from -1.0 to 1.0, and are scaled to the sample size when written into the file. Sample values less than -1.0 become the lowest allowed sample value.  Values greater than 1.0 become the highest allowed sample value.

The attributes of the audArray provide additional information on how the data is to be written to the file.

The first attribute specifies the number of samples per second that the data in the audArray represents.

The second attribute specifies the number of bits per sample that should be used when writing to the file, by default, this is set to the number of bits per sample of the file the data was read from originally. For file formats that do not allow the number of bits per sample to be specified, this is ignored.

The third attribute specifies the sub-format to use. For file formats that have no sub-formats, this is ignored.

Write currently does not support writing any compressed formats. Only uncompressed PCM and IEEE_FLOAT WAVE formats are supported. If writing audio data that was originally Read in compressed (ADPCM) WAVE format, Write will save it in uncompressed format, and issue a warning.

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

$\mathrm{audiofile}≔''/maple/cbat/active/268316/data/audio/stereo.wav''$

$\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{Write}\left(\mathrm{cat}\left(\mathrm{FileTools}:-\mathrm{TemporaryDirectory}\left(\right)\,''/copy\_of\_stereo.wav''\right)\,\mathrm{aud}\right)$

$39968$

$\mathrm{aud}≔\mathrm{Resample}\left(\mathrm{ToMono}\left(\mathrm{aud}\right)\,11025\right)$

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

$\mathrm{Write}\left(\mathrm{cat}\left(\mathrm{FileTools}:-\mathrm{TemporaryDirectory}\left(\right)\,''/small\_stereo.wav''\right)\,\mathrm{aud}\right)$

$10025$

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

The mapping option was introduced in Maple 2020.

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