@c Copyright (C) 1996-2012 Kurt Hornik
@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 the
@c Free Software Foundation; either version 3 of the License, or (at
@c your option) any later version.
@c 
@c Octave is distributed in the hope that it will be useful, but WITHOUT
@c ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
@c FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
@c 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 <http://www.gnu.org/licenses/>.

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

@node Audio Processing

@chapter 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.

@DOCSTRING(audioinfo)
@DOCSTRING(audioread)
@DOCSTRING(audiowrite)

@chapter Audio Device Information

@DOCSTRING(audiodevinfo)

@chapter 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.

@DOCSTRING(@audioplayer/audioplayer)

@section Playback

The following methods are used to control player playback.

@DOCSTRING(@audioplayer/play)
@DOCSTRING(@audioplayer/playblocking)
@DOCSTRING(@audioplayer/pause)
@DOCSTRING(@audioplayer/resume)
@DOCSTRING(@audioplayer/stop)
@DOCSTRING(@audioplayer/isplaying)

@section Properties

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

@DOCSTRING(@audioplayer/get)
@DOCSTRING(@audioplayer/set)

@chapter 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.

@DOCSTRING(@audiorecorder/audiorecorder)

@section Recording

The following methods control the recording process.

@DOCSTRING(@audiorecorder/record)
@DOCSTRING(@audiorecorder/recordblocking)
@DOCSTRING(@audiorecorder/pause)
@DOCSTRING(@audiorecorder/resume)
@DOCSTRING(@audiorecorder/stop)
@DOCSTRING(@audiorecorder/isrecording)

@section Data Retrieval

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

@DOCSTRING(@audiorecorder/getaudiodata)
@DOCSTRING(@audiorecorder/getplayer)
@DOCSTRING(@audiorecorder/play)

@section Properties

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

@DOCSTRING(@audiorecorder/get)
@DOCSTRING(@audiorecorder/set)

@chapter Audio 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 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}.

@DOCSTRING(lin2mu)

@DOCSTRING(mu2lin)

@DOCSTRING(loadaudio)

@DOCSTRING(saveaudio)

The following functions for audio I/O require special A/D hardware and
operating system support.  It is assumed that audio data in linear
encoding can be played and recorded by reading from and writing to
@file{/dev/dsp}, and that similarly @file{/dev/audio} is used for mu-law
encoding.  These file names are system-dependent.  Improvements so that
these functions will work without modification on a wide variety of
hardware are welcome.

@DOCSTRING(playaudio)

@DOCSTRING(record)

@DOCSTRING(setaudio)

@DOCSTRING(wavread)

@DOCSTRING(wavwrite)