Audio Processing
****************

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.

 -- INFO =: audioinfo (FILENAME)
     Return information about an audio file specified by FILENAME.

     The output INFO is a structure containing the following fields:

     Filename
          Name of the audio file.

     CompressionMethod
          Audio compression method.  Unused, only present for compatibility with MATLAB.

     NumChannels
          Number of audio channels.

     SampleRate
          Sample rate of the audio, in Hertz.

     TotalSamples
          Number of samples in the file.

     Duration
          Duration of the audio, in seconds.

     BitsPerSample
          Number of bits per sample.

     BitRate
          Audio bit rate.  Unused, only present for compatibility with MATLAB.

     Title
          "Title" audio metadata value as a string, or empty if not present.

     Artist
          "Artist" audio metadata value as a string, or empty if not present.

     Comment
          "Comment" audio metadata value as a string, or empty if not present.

     audioread, audiowrite

 -- [Y, FS] =: audioread (FILENAME)
 -- [Y, FS] =: audioread (FILENAME, SAMPLES)

 -- [Y, FS] =: audioread (FILENAME, DATATYPE)
 -- [Y, FS] =: audioread (FILENAME, SAMPLES, DATATYPE)
     Read the audio file FILENAME and return the audio data Y and sampling rate 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 SAMPLES specifies starting and ending frames.

     The optional argument DATATYPE specifies the datatype to return. If it is "native", then the type of data depends on how the data is stored in the audio file. audiowrite, audioformats, audioinfo

 -- audiowrite: (FILENAME, Y, FS)
 -- audiowrite: (FILENAME, Y, FS, NAME, VALUE, ...)

     Write audio data from the matrix Y to FILENAME at sampling rate FS with the file format determined by the file extension.

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

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

     BitRate
          Valid argument name, but ignored.  Left for compatibility with MATLAB.

     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.

     Title
          Title for the audio file.

     Artist
          Artist name.

     Comment
          Comment.

     audioread, audioformats, audioinfo

 -- audioformats: ()
 -- audioformats: (FORMAT)
     Display information about all supported audio formats.

     If the optional argument FORMAT is given, then display only formats with names that start with FORMAT. audioread, audiowrite

Audio Device Information
========================

 -- DEVINFO =: audiodevinfo ()

 -- DEVS =: audiodevinfo (IO)
 -- NAME =: audiodevinfo (IO, ID)
 -- ID =: audiodevinfo (IO, NAME)
 -- DRIVERVERSION =: audiodevinfo (IO, ID, "DriverVersion")
 -- ID =: audiodevinfo (IO, RATE, BITS, CHANS)
 -- SUPPORTS =: audiodevinfo (IO, ID, RATE, BITS, CHANS)

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

     The DEVINFO structure has two fields "input" and "output".  The value of each field is a structure array with fields "Name", "DriverVersion" and "ID" describing an audio device.

     If the optional argument IO is 1, return information about input devices only.  If it is 0, return information about output devices only.  If IO is the only argument supplied, return the number of input or output devices available.

     If the optional argument ID is provided, return information about the corresponding device.

     If the optional argument NAME is provided, return the ID of the named device.

     If the optional argument "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.

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.

 -- PLAYER =: audioplayer (Y, FS)
 -- PLAYER =: audioplayer (Y, FS, NBITS)
 -- PLAYER =: audioplayer (Y, FS, NBITS, ID)
 -- PLAYER =: audioplayer (RECORDER)
 -- PLAYER =: audioplayer (RECORDER, ID)
     Create an audioplayer object that will play back data Y at sample rate FS.

     The optional arguments NBITS, and 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 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.

          y = 0.25 * randn (2, 44100);
          player = audioplayer (y, 44100, 8);
          play (player);

Playback
--------

The following methods are used to control player playback.

 -- play: (PLAYER)
 -- play: (PLAYER, START)
 -- play: (PLAYER, LIMITS)
     Play audio stored in the audioplayer object PLAYER without blocking.

     Given optional argument start, begin playing at START samples in the recording.  Given a two-element vector LIMITS, begin and end playing at the number of samples specified by the elements of the vector.

 -- playblocking: (PLAYER)
 -- playblocking: (PLAYER, START)
 -- playblocking: (PLAYER, LIMITS)
     Play audio stored in the audioplayer object PLAYER with blocking.

     Given optional argument start, begin playing at START samples in the recording.  Given a two-element vector LIMITS, begin and end playing at the number of samples specified by the elements of the vector.

 -- pause: (PLAYER)
     Pause the audioplayer PLAYER.

 -- resume: (PLAYER)
     Resume playback for the paused audioplayer object PLAYER.

 -- stop: (PLAYER)
     Stop the playback for the audioplayer PLAYER and reset the relevant variables to their starting values.

 -- isplaying: (PLAYER)
     Return true if the audioplayer object PLAYER is currently playing back audio and false otherwise.

Properties
----------

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

 -- VALUE =: get (PLAYER, NAME)
 -- VALUES =: get (PLAYER)
     Return the VALUE of the property identified by NAME.

     If 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 PLAYER.  The field names of the structure correspond to property names.

 -- set: (PLAYER, NAME, VALUE)
 -- set: (PLAYER, PROPERTIES)
 -- PROPERTIES =: set (PLAYER)
     Set the value of property specified by NAME to a given VALUE.

     If NAME and 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 field values.  Given only the audioplayer object, return a structure of settable properties.

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.

 -- RECORDER =: audiorecorder ()
 -- RECORDER =: audiorecorder (FS, NBITS, CHANNELS)
 -- RECORDER =: audiorecorder (FS, NBITS, CHANNELS, ID)
     Create an audiorecorder object recording 8 bit mono audio at 8000 Hz sample rate.

     The optional arguments FS, NBITS, CHANNELS, and ID specify the sample rate, bit depth, number of channels and recording device id, respectively.  Device IDs may be found using the audiodevinfo function.

Recording
---------

The following methods control the recording process.

 -- record: (RECORDER)
 -- record: (RECORDER, LENGTH)
     Record audio without blocking using the audiorecorder object RECORDER until stopped or paused by the STOP or PAUSE method.

     Given the optional argument LENGTH, record for LENGTH seconds.

 -- recordblocking: (RECORDER, LENGTH)
     Record audio with blocking (synchronous I/O).

     The length of the recording in seconds (LENGTH) must be specified.

 -- pause: (RECORDER)
     Pause recording with audiorecorder object RECORDER.

 -- resume: (RECORDER)
     Resume recording with the paused audiorecorder object RECORDER.

 -- stop: (RECORDER)
     Stop the audiorecorder object RECORDER and clean up any audio streams.

 -- isrecording: (RECORDER)
     Return true if the audiorecorder object RECORDER is currently recording audio and false otherwise.

Data Retrieval
--------------

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

 -- DATA =: getaudiodata (RECORDER)
 -- DATA =: getaudiodata (RECORDER, 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 DATATYPE, convert the recorded data to the specified type, which may be one of "double", "single", "int16", "int8" or "uint8".

 -- PLAYER =: getplayer (RECORDER)
     Return an audioplayer object with data recorded by the audiorecorder object RECORDER.

 -- PLAYER =: play (RECORDER)
 -- PLAYER =: play (RECORDER, START)
 -- PLAYER =: play (RECORDER, [START, END])
     Play the audio recorded in RECORDER and return a corresponding audioplayer object.

     If the optional argument START is provided, begin playing START seconds in to the recording.

     If the optional argument END is provided, stop playing at END seconds in the recording.

Properties
----------

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

 -- VALUE =: get (RECORDER, NAME)
 -- VALUES =: get (RECORDER)
     Return the VALUE of the property identified by NAME.

     If 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 RECORDER.  The field names of the structure correspond to property names.

 -- set: (RECORDER, NAME, VALUE)
 -- set: (RECORDER, PROPERTIES)
 -- PROPERTIES =: set (RECORDER)
     Set the value of property specified by NAME to a given VALUE.

     If NAME and 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.

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, linear encoding and mu-law encoding, are supported by Octave.  There is an excellent FAQ on audio formats by Guido van Rossum guido@cwi.nl which can be found at any FAQ ftp site, in particular in the directory /pub/usenet/news.answers/audio-fmts of the archive site 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 lin or raw, and that files holding data in mu-law encoding end in au, mu, or snd.

 -- Y =: lin2mu (X, N)
     Convert audio data from linear to mu-law.

     Mu-law values use 8-bit unsigned integers.  Linear values use N-bit signed integers or floating point values in the range -1 ≤ X ≤ 1 if N is 0.

     If N is not specified it defaults to 0, 8, or 16 depending on the range of values in X. mu2lin

 -- Y =: mu2lin (X, N)
     Convert audio data from mu-law to linear.

     Mu-law values are 8-bit unsigned integers.  Linear values use N-bit signed integers or floating point values in the range -1 ≤ Y ≤ 1 if N is 0.

     If N is not specified it defaults to 0. lin2mu

 -- record: (SEC)
 -- record: (SEC, FS)
     Record SEC seconds of audio from the system's default audio input at a sampling rate of 8000 samples per second.

     If the optional argument FS is given, it specifies the sampling rate for recording.

     For more control over audio recording, use the audiorecorder class. sound, soundsc

 -- sound: (Y)
 -- sound: (Y, FS)
 -- sound: (Y, FS, NBITS)
     Play audio data Y at sample rate FS to the default audio device.

     The audio signal Y can be a vector or a two-column array, representing mono or stereo audio, respectively.

     If FS is not given, a default sample rate of 8000 samples per second is used.

     The optional argument NBITS specifies the bit depth to play to the audio device and defaults to 8 bits.

     For more control over audio playback, use the audioplayer class. soundsc, record

 -- soundsc: (Y)
 -- soundsc: (Y, FS)
 -- soundsc: (Y, FS, NBITS)
 -- soundsc: (..., [YMIN, YMAX])
     Scale the audio data Y and play it at sample rate FS to the default audio device.

     The audio signal Y can be a vector or a two-column array, representing mono or stereo audio, respectively.

     If FS is not given, a default sample rate of 8000 samples per second is used.

     The optional argument NBITS specifies the bit depth to play to the audio device and defaults to 8 bits.

     By default, Y is automatically normalized to the range [-1, 1].  If the range [YMIN, YMAX] is given, then elements of Y that fall within the range YMIN ≤ Y ≤ YMAX are scaled to the range [-1, 1] instead.

     For more control over audio playback, use the audioplayer class. sound, record