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

@c Copyright (C) 1996-2023 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 signal @var{y} can be a vector (mono audio) or a two-dimensional array
(multi-channel audio).

The optional arguments @var{nbits} and @var{id} specify the number of bits
per sample and player device ID, respectively.  Device IDs may be found
using the @code{audiodevinfo} function.

Given an audiorecorder object @var{recorder}, use the data from the object
to initialize the player.

The list of actions for an audioplayer object are shown below.  All
methods require an audioplayer object as the first argument.

@multitable @columnfractions 0.2 0.75
@headitem Method @tab Description
@item get @tab Read audioplayer property values
@item isplaying @tab Return true if audioplayer is playing
@item pause @tab Pause audioplayer playback
@item play @tab Play audio stored in audioplayer object w/o blocking
@item playblocking @tab Play audio stored in audioplayer object
@item resume @tab Resume playback after pause
@item set @tab Write audioplayer property values
@item stop @tab Stop playback
@end multitable

Example

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
@xseealso{@ref{XREF@@audioplayer/get,,@@audioplayer/get}, @ref{XREF@@audioplayer/isplaying,,@@audioplayer/isplaying}, @ref{XREF@@audioplayer/pause,,@@audioplayer/pause}, @ref{XREF@@audioplayer/play,,@@audioplayer/play}, @ref{XREF@@audioplayer/playblocking,,@@audioplayer/playblocking}, @ref{XREF@@audioplayer/resume,,@@audioplayer/resume}, @ref{XREF@@audioplayer/set,,@@audioplayer/set}, @ref{XREF@@audioplayer/stop,,@@audioplayer/stop}, @ref{XREFaudiodevinfo,,audiodevinfo}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}, @ref{XREFsound,,sound}, @ref{XREFsoundsc,,soundsc}}
@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{start}, @var{end}])
Play audio stored in the audioplayer object @var{player} without blocking.

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

If the optional argument @var{end} is provided, stop playing at
@var{end} samples into the recording.
@xseealso{@ref{XREF@@audioplayer/playblocking,,@@audioplayer/playblocking}, @ref{XREF@@audioplayer/pause,,@@audioplayer/pause}, @ref{XREF@@audioplayer/stop,,@@audioplayer/stop}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@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{start}, @var{end}])
Play audio stored in the audioplayer object @var{player} with blocking
(synchronous I/O).

If the optional argument @var{start} is provided, begin playing
@var{start} samples into the recording.

If the optional argument @var{end} is provided, stop playing at
@var{end} samples into the recording.
@xseealso{@ref{XREF@@audioplayer/play,,@@audioplayer/play}, @ref{XREF@@audioplayer/pause,,@@audioplayer/pause}, @ref{XREF@@audioplayer/stop,,@@audioplayer/stop}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@end deftypefn


@c @audioplayer/pause scripts/audio/@audioplayer/pause.m
@anchor{XREF@@audioplayer/pause}
@deftypefn {} {} pause (@var{player})
Pause playback of audioplayer @var{player}.
@xseealso{@ref{XREF@@audioplayer/resume,,@@audioplayer/resume}, @ref{XREF@@audioplayer/stop,,@@audioplayer/stop}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@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}.
@xseealso{@ref{XREF@@audioplayer/pause,,@@audioplayer/pause}, @ref{XREF@@audioplayer/stop,,@@audioplayer/stop}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@end deftypefn


@c @audioplayer/stop scripts/audio/@audioplayer/stop.m
@anchor{XREF@@audioplayer/stop}
@deftypefn {} {} stop (@var{player})
Stop playback of the audioplayer @var{player} and reset relevant variables
to their initial values.
@xseealso{@ref{XREF@@audioplayer/pause,,@@audioplayer/pause}, @ref{XREF@@audioplayer/resume,,@@audioplayer/resume}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@end deftypefn


@c @audioplayer/isplaying scripts/audio/@audioplayer/isplaying.m
@anchor{XREF@@audioplayer/isplaying}
@deftypefn {} {@var{tf} =} isplaying (@var{player})
Return true if the audioplayer object @var{player} is currently playing back
audio and false otherwise.
@xseealso{@ref{XREF@@audioplayer/pause,,@@audioplayer/pause}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@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}, @lbracechar{}@var{name1}, @var{name2}, @dots{}@rbracechar{})
@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 for all properties of
@var{player}.  The field names of the structure correspond to the property
names.
@xseealso{@ref{XREF@@audioplayer/set,,@@audioplayer/set}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@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{name_cell}, @var{value_cell})
@deftypefnx {} {} set (@var{player}, @var{properties_struct})
@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 properties with fields
corresponding to property names, set the value of those properties to the
corresponding field values.  Given only an audioplayer object, return a
structure of configurable properties (i.e., writeable properties).
@xseealso{@ref{XREF@@audioplayer/get,,@@audioplayer/get}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}}
@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{nchannels})
@deftypefnx {} {@var{recorder} =} audiorecorder (@var{fs}, @var{nbits}, @var{nchannels}, @var{id})
Create an audiorecorder object recording 8-bit mono audio at 8000 Hz
sample rate.

The optional arguments @var{fs}, @var{nbits}, @var{nchannels}, and @var{id}
specify the sample rate, number of bits per sample, number of channels, and
recording device ID, respectively.  Device IDs may be found using the
@code{audiodevinfo} function.

The list of actions for an audiorecorder object are shown below.  All
methods require an audiorecorder object as the first argument.

@multitable @columnfractions 0.22 0.73
@headitem Method @tab Description
@item get @tab Read audiorecorder property values
@item getaudiodata @tab Return audio data as a numeric matrix
@item getplayer @tab Return audioplayer loaded with data from audiorecorder
@item isrecording @tab Return true if audiorecorder is recording
@item pause @tab Pause recording
@item play @tab Play audio stored in audiorecorder object
@item record @tab Record audio in audiorecorder object w/o blocking
@item recordblocking @tab Record audio in audiorecorder object
@item resume @tab Resume recording after pause
@item set @tab Write audiorecorder property values
@item stop @tab Stop recording
@end multitable
@end deftypefn
@xseealso{@ref{XREF@@audiorecorder/get,,@@audiorecorder/get}, @ref{XREF@@audiorecorder/getaudiodata,,@@audiorecorder/getaudiodata}, @ref{XREF@@audiorecorder/getplayer,,@@audiorecorder/getplayer}, @ref{XREF@@audiorecorder/isrecording,,@@audiorecorder/isrecording}, @ref{XREF@@audiorecorder/pause,,@@audiorecorder/pause}, @ref{XREF@@audiorecorder/play,,@@audiorecorder/play}, @ref{XREF@@audiorecorder/record,,@@audiorecorder/record}, @ref{XREF@@audiorecorder/recordblocking,,@@audiorecorder/recordblocking}, @ref{XREF@@audioplayer/resume,,@@audioplayer/resume}, @ref{XREF@@audiorecorder/set,,@@audiorecorder/set}, @ref{XREF@@audiorecorder/stop,,@@audiorecorder/stop}, @ref{XREFaudiodevinfo,,audiodevinfo}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}, @ref{XREFrecord,,record}}


@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 paused or stopped by the @var{pause} or @var{stop}
methods.

Given the optional argument @var{length}, record for @var{length} seconds.
@xseealso{@ref{XREF@@audiorecorder/recordblocking,,@@audiorecorder/recordblocking}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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.
@xseealso{@ref{XREF@@audiorecorder/record,,@@audiorecorder/record}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@end deftypefn


@c @audiorecorder/pause scripts/audio/@audiorecorder/pause.m
@anchor{XREF@@audiorecorder/pause}
@deftypefn {} {} pause (@var{recorder})
Pause recording for audiorecorder @var{recorder}.
@xseealso{@ref{XREF@@audiorecorder/resume,,@@audiorecorder/resume}, @ref{XREF@@audiorecorder/stop,,@@audiorecorder/stop}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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}.
@xseealso{@ref{XREF@@audiorecorder/pause,,@@audiorecorder/pause}, @ref{XREF@@audiorecorder/stop,,@@audiorecorder/stop}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@end deftypefn


@c @audiorecorder/stop scripts/audio/@audiorecorder/stop.m
@anchor{XREF@@audiorecorder/stop}
@deftypefn {} {} stop (@var{recorder})
Stop recording with audiorecorder object @var{recorder} and clean up any
audio streams.
@xseealso{@ref{XREF@@audiorecorder/pause,,@@audiorecorder/pause}, @ref{XREF@@audiorecorder/resume,,@@audiorecorder/resume}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@end deftypefn


@c @audiorecorder/isrecording scripts/audio/@audiorecorder/isrecording.m
@anchor{XREF@@audiorecorder/isrecording}
@deftypefn {} {@var{tf} =} isrecording (@var{recorder})
Return true if the audiorecorder object @var{recorder} is currently
recording audio and false otherwise.
@xseealso{@ref{XREF@@audiorecorder/pause,,@@audiorecorder/pause}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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 audio data from audiorecorder object @var{recorder} as a double
matrix with values between -1.0 and 1.0 and with as many columns as there
are channels in @var{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"}.
@xseealso{@ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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}.
@xseealso{@ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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} without blocking and return a
corresponding audioplayer object.

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

If the optional argument @var{end} is provided, stop playing at
@var{end} seconds into the recording.
@xseealso{@ref{XREF@@audiorecorder/getplayer,,@@audiorecorder/getplayer}, @ref{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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}, @lbracechar{}@var{name1}, @var{name2}, @dots{}@rbracechar{})
@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
identified by the elements of the cell array.  Given only the recorder
object, return a scalar structure with values for all properties of
@var{recorder}.  The field names of the structure correspond to the property
names.
@xseealso{@ref{XREF@@audiorecorder/set,,@@audiorecorder/set}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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{name_cell}, @var{value_cell})
@deftypefnx {} {} set (@var{recorder}, @var{properties_struct})
@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, set each property to a
corresponding value.  Given a structure of properties with fields
corresponding to property names, set the value of those properties to the
corresponding field values.  Given only a recorder object, return a
structure of configurable properties (i.e., writeable properties).
@xseealso{@ref{XREF@@audiorecorder/get,,@@audiorecorder/get}, @ref{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}}
@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})
@deftypefnx {} {@var{y} =} lin2mu (@var{x}, @var{n})
Convert audio data from linear to mu-law.

Linear values use floating point values in the range -1 @leq{} @var{x}
@leq{} 1 if @var{n} is 0 (default), or @var{n}-bit signed integers if @var{n}
is 8 or 16.  Mu-law values are 8-bit unsigned integers in the range
0 @leq{} @var{y} @leq{} 255.
@xseealso{@ref{XREFmu2lin,,mu2lin}}
@end deftypefn


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

Mu-law values are 8-bit unsigned integers in the range 0 @leq{} @var{y}
@leq{} 255.  Linear values use floating point values in the range
-@var{linmax} @leq{} @var{x} @var{linmax} (where
@code{@var{linmax} = 32124/32768 =~ 0.98}) when @var{n} is zero (default).
If @var{n} is 8 or 16 then @var{n}-bit signed integers are used instead.

Programming Note: @code{mu2lin} maps maximum mu-law inputs to values
slightly below the maximum ([-0.98, +0.98]) representable with a linear
scale.  Because of this, @code{mu2lin (lin2mu (@var{x}))} might not
reproduce the original input.
@xseealso{@ref{XREFlin2mu,,lin2mu}}
@end deftypefn


@c record scripts/audio/record.m
@anchor{XREFrecord}
@deftypefn  {} {@var{data} =} record (@var{sec})
@deftypefnx {} {@var{data} =} 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{XREF@@audiorecorder/audiorecorder,,@@audiorecorder/audiorecorder}, @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{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}, @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{XREF@@audioplayer/audioplayer,,@@audioplayer/audioplayer}, @ref{XREFrecord,,record}}
@end deftypefn

