@c DO NOT EDIT!  Generated automatically by munge-texi.pl.

@c Copyright (C) 1996-2022 The Octave Project Developers
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@c Written by Kurt Hornik <Kurt.Hornik@wu-wien.ac.at> on 1996/05/14

@node Audio Processing
@chapter Audio Processing

@menu
* Audio File Utilities::
* Audio Device Information::
* Audio Player::
* Audio Recorder::
* Audio Data Processing::
@end menu

@node Audio File Utilities
@section Audio File Utilities

The following functions allow you to read, write and retrieve
information about audio files.  Various formats are supported including
wav, flac and ogg vorbis.

@c audioinfo libinterp/dldfcn/audioread.cc
@anchor{XREFaudioinfo}
@deftypefn {} {@var{info} =} audioinfo (@var{filename})
Return information about an audio file specified by @var{filename}.

The output @var{info} is a structure containing the following fields:

@table @samp
@item Filename
Name of the audio file.

@item CompressionMethod
Audio compression method.  Unused, only present for compatibility with
@sc{matlab}.

@item NumChannels
Number of audio channels.

@item SampleRate
Sample rate of the audio, in Hertz.

@item TotalSamples
Number of samples in the file.

@item Duration
Duration of the audio, in seconds.

@item BitsPerSample
Number of bits per sample.

@item BitRate
Audio bit rate.  Unused, only present for compatibility with @sc{matlab}.

@item Title
@qcode{"Title"} audio metadata value as a string, or empty if not present.

@item Artist
@qcode{"Artist"} audio metadata value as a string, or empty if not present.

@item Comment
@qcode{"Comment"} audio metadata value as a string, or empty if not present.
@end table
@xseealso{@ref{XREFaudioread,,audioread}, @ref{XREFaudiowrite,,audiowrite}}
@end deftypefn


@c audioread libinterp/dldfcn/audioread.cc
@anchor{XREFaudioread}
@deftypefn  {} {[@var{y}, @var{fs}] =} audioread (@var{filename})
@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples})

@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{datatype})
@deftypefnx {} {[@var{y}, @var{fs}] =} audioread (@var{filename}, @var{samples}, @var{datatype})
Read the audio file @var{filename} and return the audio data @var{y} and
sampling rate @var{fs}.

The audio data is stored as matrix with rows corresponding to audio frames
and columns corresponding to channels.

The optional two-element vector argument @var{samples} specifies starting
and ending frames.

The optional argument @var{datatype} specifies the datatype to return.
If it is @qcode{"native"}, then the type of data depends on how the data
is stored in the audio file.
@xseealso{@ref{XREFaudiowrite,,audiowrite}, @ref{XREFaudioformats,,audioformats}, @ref{XREFaudioinfo,,audioinfo}}
@end deftypefn


@c audiowrite libinterp/dldfcn/audioread.cc
@anchor{XREFaudiowrite}
@deftypefn  {} {} audiowrite (@var{filename}, @var{y}, @var{fs})
@deftypefnx {} {} audiowrite (@var{filename}, @var{y}, @var{fs}, @var{name}, @var{value}, @dots{})

Write audio data from the matrix @var{y} to @var{filename} at sampling rate
@var{fs} with the file format determined by the file extension.

Additional name/value argument pairs may be used to specify the
following options:

@table @samp
@item BitsPerSample
Number of bits per sample.  Valid values are 8, 16, 24, and 32.  Default is
16.

@item BitRate
Valid argument name, but ignored.  Left for compatibility with @sc{matlab}.

@item Quality
Quality setting for the Ogg Vorbis compressor.  Values can range between 0
and 100 with 100 being the highest quality setting.  Default is 75.

@item Title
Title for the audio file.

@item Artist
Artist name.

@item Comment
Comment.
@end table
@xseealso{@ref{XREFaudioread,,audioread}, @ref{XREFaudioformats,,audioformats}, @ref{XREFaudioinfo,,audioinfo}}
@end deftypefn


@c audioformats libinterp/dldfcn/audioread.cc
@anchor{XREFaudioformats}
@deftypefn  {} {} audioformats ()
@deftypefnx {} {} audioformats (@var{format})
Display information about all supported audio formats.

If the optional argument @var{format} is given, then display only formats
with names that start with @var{format}.
@xseealso{@ref{XREFaudioread,,audioread}, @ref{XREFaudiowrite,,audiowrite}}
@end deftypefn


@node Audio Device Information
@section Audio Device Information

@c audiodevinfo libinterp/dldfcn/audiodevinfo.cc
@anchor{XREFaudiodevinfo}
@deftypefn {} {@var{devinfo} =} audiodevinfo ()

@deftypefnx {} {@var{devs} =} audiodevinfo (@var{io})
@deftypefnx {} {@var{name} =} audiodevinfo (@var{io}, @var{id})
@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{name})
@deftypefnx {} {@var{driverversion} =} audiodevinfo (@var{io}, @var{id}, "DriverVersion")
@deftypefnx {} {@var{id} =} audiodevinfo (@var{io}, @var{rate}, @var{bits}, @var{chans})
@deftypefnx {} {@var{supports} =} audiodevinfo (@var{io}, @var{id}, @var{rate}, @var{bits}, @var{chans})

Return a structure describing the available audio input and output devices.

The @var{devinfo} structure has two fields @qcode{"input"} and
@qcode{"output"}.  The value of each field is a structure array with fields
@qcode{"Name"}, @nospell{@qcode{"DriverVersion"}} and @qcode{"ID"} describing
an audio device.

If the optional argument @var{io} is 1, return information about input devices
only.  If it is 0, return information about output devices only.  If @var{io}
is the only argument supplied, return the number of input or output devices
available.

If the optional argument @var{id} is provided, return information about the
corresponding device.

If the optional argument @var{name} is provided, return the ID of the named
device.

If the optional argument @nospell{@qcode{"DriverVersion"}} is given, return the
name of the driver for the specified device.

Given a sampling rate, bits per sample, and number of channels for an input or
output device, return the ID of the first device that supports playback or
recording using the specified parameters.

If also given a device ID, return true if the device supports playback or
recording using those parameters.
@end deftypefn


@node Audio Player
@section Audio Player

The following methods are used to create and use audioplayer
objects.  These objects can be used to play back audio data stored in
Octave matrices and arrays.  The audioplayer object supports playback
from various devices available to the system, blocking and non-blocking
playback, convenient pausing and resuming and much more.

@c @audioplayer/audioplayer scripts/audio/@audioplayer/audioplayer.m
@anchor{XREF@@audioplayer/audioplayer}
@deftypefn  {} {@var{player} =} audioplayer (@var{y}, @var{fs})
@deftypefnx {} {@var{player} =} audioplayer (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {} {@var{player} =} audioplayer (@var{y}, @var{fs}, @var{nbits}, @var{id})
@deftypefnx {} {@var{player} =} audioplayer (@var{recorder})
@deftypefnx {} {@var{player} =} audioplayer (@var{recorder}, @var{id})
Create an audioplayer object that will play back data @var{y} at sample
rate @var{fs}.

The optional arguments @var{nbits}, and @var{id} specify the bit depth and
player device id, respectively.  Device IDs may be found using the
audiodevinfo function.  Given an audioplayer object, use the data from the
object to initialize the player.

The signal @var{y} can be a vector or a two-dimensional array.

The following example will create an audioplayer object that will play
back one second of white noise at 44100 sample rate using 8 bits per
sample.

@example
@group
y = 0.25 * randn (2, 44100);
player = audioplayer (y, 44100, 8);
play (player);
@end group
@end example
@end deftypefn


@menu
* Playback::
* Player Properties::
@end menu

@node Playback
@subsection Playback

The following methods are used to control player playback.

@c @audioplayer/play scripts/audio/@audioplayer/play.m
@anchor{XREF@@audioplayer/play}
@deftypefn  {} {} play (@var{player})
@deftypefnx {} {} play (@var{player}, @var{start})
@deftypefnx {} {} play (@var{player}, @var{limits})
Play audio stored in the audioplayer object @var{player} without blocking.

Given optional argument start, begin playing at @var{start} samples in the
recording.  Given a two-element vector @var{limits}, begin and end playing
at the number of samples specified by the elements of the vector.
@end deftypefn


@c @audioplayer/playblocking scripts/audio/@audioplayer/playblocking.m
@anchor{XREF@@audioplayer/playblocking}
@deftypefn  {} {} playblocking (@var{player})
@deftypefnx {} {} playblocking (@var{player}, @var{start})
@deftypefnx {} {} playblocking (@var{player}, @var{limits})
Play audio stored in the audioplayer object @var{player} with blocking.

Given optional argument start, begin playing at @var{start} samples in the
recording.  Given a two-element vector @var{limits}, begin and end playing
at the number of samples specified by the elements of the vector.
@end deftypefn


@c @audioplayer/pause scripts/audio/@audioplayer/pause.m
@anchor{XREF@@audioplayer/pause}
@deftypefn {} {} pause (@var{player})
Pause the audioplayer @var{player}.
@end deftypefn


@c @audioplayer/resume scripts/audio/@audioplayer/resume.m
@anchor{XREF@@audioplayer/resume}
@deftypefn {} {} resume (@var{player})
Resume playback for the paused audioplayer object @var{player}.
@end deftypefn


@c @audioplayer/stop scripts/audio/@audioplayer/stop.m
@anchor{XREF@@audioplayer/stop}
@deftypefn {} {} stop (@var{player})
Stop the playback for the audioplayer @var{player} and reset the
relevant variables to their starting values.
@end deftypefn


@c @audioplayer/isplaying scripts/audio/@audioplayer/isplaying.m
@anchor{XREF@@audioplayer/isplaying}
@deftypefn {} {} isplaying (@var{player})
Return true if the audioplayer object @var{player} is currently playing back
audio and false otherwise.
@end deftypefn


@node Player Properties
@subsection Properties

The remaining couple of methods are used to get and set various
properties of the audioplayer object.

@c @audioplayer/get scripts/audio/@audioplayer/get.m
@anchor{XREF@@audioplayer/get}
@deftypefn  {} {@var{value} =} get (@var{player}, @var{name})
@deftypefnx {} {@var{values} =} get (@var{player})
Return the @var{value} of the property identified by @var{name}.

If @var{name} is a cell array return the values of the properties
identified by the elements of the cell array.  Given only the player
object, return a scalar structure with values of all properties of
@var{player}.  The field names of the structure correspond to property
names.
@end deftypefn


@c @audioplayer/set scripts/audio/@audioplayer/set.m
@anchor{XREF@@audioplayer/set}
@deftypefn  {} {} set (@var{player}, @var{name}, @var{value})
@deftypefnx {} {} set (@var{player}, @var{properties})
@deftypefnx {} {@var{properties} =} set (@var{player})
Set the value of property specified by @var{name} to a given @var{value}.

If @var{name} and @var{value} are cell arrays, set each property to the
corresponding value.  Given a structure of @var{properties} with fields
corresponding to property names, set the value of those properties to the
field values.  Given only the audioplayer object, return a structure of
settable properties.
@end deftypefn


@node Audio Recorder
@section Audio Recorder

The following methods are used to create and use audiorecorder
objects.  These objects can be used to record audio data from various
devices available to the system.  You can use convenient methods to
retrieve that data or audioplayer objects created from that
data.  Methods for blocking and non-blocking recording, pausing and
resuming recording and much more is available.

@c @audiorecorder/audiorecorder scripts/audio/@audiorecorder/audiorecorder.m
@anchor{XREF@@audiorecorder/audiorecorder}
@deftypefn  {} {@var{recorder} =} audiorecorder ()
@deftypefnx {} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{channels})
@deftypefnx {} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{channels}, @var{id})
Create an audiorecorder object recording 8 bit mono audio at 8000 Hz
sample rate.

The optional arguments @var{fs}, @var{nbits}, @var{channels}, and @var{id}
specify the sample rate, bit depth, number of channels and recording
device id, respectively.  Device IDs may be found using the audiodevinfo
function.
@end deftypefn


@menu
* Recording::
* Data Retrieval::
* Recorder Properties::
@end menu

@node Recording
@subsection Recording

The following methods control the recording process.

@c @audiorecorder/record scripts/audio/@audiorecorder/record.m
@anchor{XREF@@audiorecorder/record}
@deftypefn  {} {} record (@var{recorder})
@deftypefnx {} {} record (@var{recorder}, @var{length})
Record audio without blocking using the audiorecorder object
@var{recorder} until stopped or paused by the @var{stop} or @var{pause}
method.

Given the optional argument @var{length}, record for @var{length} seconds.
@end deftypefn


@c @audiorecorder/recordblocking scripts/audio/@audiorecorder/recordblocking.m
@anchor{XREF@@audiorecorder/recordblocking}
@deftypefn {} {} recordblocking (@var{recorder}, @var{length})
Record audio with blocking (synchronous I/O).

The length of the recording in seconds (@var{length}) must be specified.
@end deftypefn


@c @audiorecorder/pause scripts/audio/@audiorecorder/pause.m
@anchor{XREF@@audiorecorder/pause}
@deftypefn {} {} pause (@var{recorder})
Pause recording with audiorecorder object @var{recorder}.
@end deftypefn


@c @audiorecorder/resume scripts/audio/@audiorecorder/resume.m
@anchor{XREF@@audiorecorder/resume}
@deftypefn {} {} resume (@var{recorder})
Resume recording with the paused audiorecorder object @var{recorder}.
@end deftypefn


@c @audiorecorder/stop scripts/audio/@audiorecorder/stop.m
@anchor{XREF@@audiorecorder/stop}
@deftypefn {} {} stop (@var{recorder})
Stop the audiorecorder object @var{recorder} and clean up any audio streams.
@end deftypefn


@c @audiorecorder/isrecording scripts/audio/@audiorecorder/isrecording.m
@anchor{XREF@@audiorecorder/isrecording}
@deftypefn {} {} isrecording (@var{recorder})
Return true if the audiorecorder object @var{recorder} is currently
recording audio and false otherwise.
@end deftypefn


@node Data Retrieval
@subsection Data Retrieval

The following methods allow you to retrieve recorded audio data in
various ways.

@c @audiorecorder/getaudiodata scripts/audio/@audiorecorder/getaudiodata.m
@anchor{XREF@@audiorecorder/getaudiodata}
@deftypefn  {} {@var{data} =} getaudiodata (@var{recorder})
@deftypefnx {} {@var{data} =} getaudiodata (@var{recorder}, @var{datatype})
Return recorder audio data as a matrix with values between -1.0 and 1.0
and with as many columns as there are channels in the recorder.

Given the optional argument @var{datatype}, convert the recorded data
to the specified type, which may be one of @qcode{"double"},
@qcode{"single"}, @qcode{"int16"}, @qcode{"int8"} or @qcode{"uint8"}.
@end deftypefn


@c @audiorecorder/getplayer scripts/audio/@audiorecorder/getplayer.m
@anchor{XREF@@audiorecorder/getplayer}
@deftypefn {} {@var{player} =} getplayer (@var{recorder})
Return an audioplayer object with data recorded by the audiorecorder object
@var{recorder}.
@end deftypefn


@c @audiorecorder/play scripts/audio/@audiorecorder/play.m
@anchor{XREF@@audiorecorder/play}
@deftypefn  {} {@var{player} =} play (@var{recorder})
@deftypefnx {} {@var{player} =} play (@var{recorder}, @var{start})
@deftypefnx {} {@var{player} =} play (@var{recorder}, [@var{start}, @var{end}])
Play the audio recorded in @var{recorder} and return a corresponding
audioplayer object.

If the optional argument @var{start} is provided, begin playing
@var{start} seconds in to the recording.

If the optional argument @var{end} is provided, stop playing at
@var{end} seconds in the recording.
@end deftypefn


@node Recorder Properties
@subsection Properties

The remaining two methods allow you to read or alter the properties of
audiorecorder objects.

@c @audiorecorder/get scripts/audio/@audiorecorder/get.m
@anchor{XREF@@audiorecorder/get}
@deftypefn  {} {@var{value} =} get (@var{recorder}, @var{name})
@deftypefnx {} {@var{values} =} get (@var{recorder})
Return the @var{value} of the property identified by @var{name}.

If @var{name} is a cell array, return the values of the properties
corresponding to the elements of the cell array.  Given only the recorder
object, return a scalar structure with values of all properties of
@var{recorder}.  The field names of the structure correspond to property
names.
@end deftypefn


@c @audiorecorder/set scripts/audio/@audiorecorder/set.m
@anchor{XREF@@audiorecorder/set}
@deftypefn  {} {} set (@var{recorder}, @var{name}, @var{value})
@deftypefnx {} {} set (@var{recorder}, @var{properties})
@deftypefnx {} {@var{properties} =} set (@var{recorder})
Set the value of property specified by @var{name} to a given @var{value}.

If @var{name} and @var{value} are cell arrays of the same size, set each
property to a corresponding value.  Given a structure with fields
corresponding to property names, set the value of those properties to the
corresponding field values.  Given only the recorder object, return a
structure of settable properties.
@end deftypefn


@node Audio Data Processing
@section Audio Data Processing

Octave provides a few functions for dealing with audio data.  An audio
`sample' is a single output value from an A/D converter, i.e., a small
integer number (usually 8 or 16 bits), and audio data is just a series
of such samples.  It can be characterized by three parameters: the
sampling rate (measured in samples per second or Hz, e.g., 8000 or
44100), the number of bits per sample (e.g., 8 or 16), and the number of
channels (1 for mono, 2 for stereo, etc.).

There are many different formats for representing such data.  Currently,
only the two most popular, @emph{linear encoding} and @emph{mu-law
encoding}, are supported by Octave.  There is an excellent FAQ on audio
formats by @nospell{Guido van Rossum} @email{guido@@cwi.nl} which can be
found at any FAQ ftp site, in particular in the directory
@file{/pub/usenet/news.answers/audio-fmts} of the archive site
@code{rtfm.mit.edu}.

Octave simply treats audio data as vectors of samples (non-mono data are
not supported yet).  It is assumed that audio files using linear
encoding have one of the extensions @file{lin} or @file{raw}, and that
files holding data in mu-law encoding end in @file{au}, @file{mu}, or
@file{snd}.

@c lin2mu scripts/audio/lin2mu.m
@anchor{XREFlin2mu}
@deftypefn {} {@var{y} =} lin2mu (@var{x}, @var{n})
Convert audio data from linear to mu-law.

Mu-law values use 8-bit unsigned integers.  Linear values use @var{n}-bit
signed integers or floating point values in the range -1 @leq{} @var{x}
@leq{} 1 if @var{n} is 0.

If @var{n} is not specified it defaults to 0, 8, or 16 depending on
the range of values in @var{x}.
@xseealso{@ref{XREFmu2lin,,mu2lin}}
@end deftypefn


@c mu2lin scripts/audio/mu2lin.m
@anchor{XREFmu2lin}
@deftypefn {} {@var{y} =} mu2lin (@var{x}, @var{n})
Convert audio data from mu-law to linear.

Mu-law values are 8-bit unsigned integers.  Linear values use @var{n}-bit
signed integers or floating point values in the range -1 @leq{} @var{y}
@leq{} 1 if @var{n} is 0.

If @var{n} is not specified it defaults to 0.
@xseealso{@ref{XREFlin2mu,,lin2mu}}
@end deftypefn


@c record scripts/audio/record.m
@anchor{XREFrecord}
@deftypefn  {} {} record (@var{sec})
@deftypefnx {} {} record (@var{sec}, @var{fs})
Record @var{sec} seconds of audio from the system's default audio input at
a sampling rate of 8000 samples per second.

If the optional argument @var{fs} is given, it specifies the sampling rate
for recording.

For more control over audio recording, use the @code{audiorecorder} class.
@xseealso{@ref{XREFsound,,sound}, @ref{XREFsoundsc,,soundsc}}
@end deftypefn


@c sound scripts/audio/sound.m
@anchor{XREFsound}
@deftypefn  {} {} sound (@var{y})
@deftypefnx {} {} sound (@var{y}, @var{fs})
@deftypefnx {} {} sound (@var{y}, @var{fs}, @var{nbits})
Play audio data @var{y} at sample rate @var{fs} to the default audio
device.

The audio signal @var{y} can be a vector or a two-column array, representing
mono or stereo audio, respectively.

If @var{fs} is not given, a default sample rate of 8000 samples per second
is used.

The optional argument @var{nbits} specifies the bit depth to play to the
audio device and defaults to 8 bits.

For more control over audio playback, use the @code{audioplayer} class.
@xseealso{@ref{XREFsoundsc,,soundsc}, @ref{XREFrecord,,record}}
@end deftypefn


@c soundsc scripts/audio/soundsc.m
@anchor{XREFsoundsc}
@deftypefn  {} {} soundsc (@var{y})
@deftypefnx {} {} soundsc (@var{y}, @var{fs})
@deftypefnx {} {} soundsc (@var{y}, @var{fs}, @var{nbits})
@deftypefnx {} {} soundsc (@dots{}, [@var{ymin}, @var{ymax}])
Scale the audio data @var{y} and play it at sample rate @var{fs} to the
default audio device.

The audio signal @var{y} can be a vector or a two-column array, representing
mono or stereo audio, respectively.

If @var{fs} is not given, a default sample rate of 8000 samples per second
is used.

The optional argument @var{nbits} specifies the bit depth to play to the
audio device and defaults to 8 bits.

By default, @var{y} is automatically normalized to the range [-1, 1].  If
the range [@var{ymin}, @var{ymax}] is given, then elements of @var{y}
that fall within the range @var{ymin} @leq{} @var{y} @leq{} @var{ymax}
are scaled to the range [-1, 1] instead.

For more control over audio playback, use the @code{audioplayer} class.
@xseealso{@ref{XREFsound,,sound}, @ref{XREFrecord,,record}}
@end deftypefn

