Main Page | Namespace List | Class Hierarchy | Class List | Directories | Namespace Members | Class Members

AUDIO_IO Class Reference

Virtual base class for all audio I/O objects. More...

Inheritance diagram for AUDIO_IO:

DYNAMIC_OBJECT< string > ECA_AUDIO_FORMAT ECA_AUDIO_POSITION DYNAMIC_PARAMETERS< string > ECA_OBJECT ECA_SAMPLERATE_AWARE ECA_SAMPLERATE_AWARE AUDIO_IO_BUFFERED AUDIO_IO_PROXY LOOP_DEVICE AAC_FORKED_INTERFACE AUDIO_IO_DEVICE AUDIOFILE_INTERFACE CDRFILE FLAC_FORKED_INTERFACE MIKMOD_INTERFACE MP3FILE NULLFILE OGG_VORBIS_INTERFACE RAWFILE SNDFILE_INTERFACE TIMIDITY_INTERFACE WAVEFILE AUDIO_IO_DB_CLIENT AUDIO_IO_RESAMPLE AUDIO_IO_REVERSE AUDIO_IO_TYPESELECT EWFFILE List of all members.

Public Types

Public type definitions and constants
enum  Io_mode { io_read = 1, io_write = 2, io_readwrite = 4 }
 Input/Output mode. More...

Public Member Functions

Public functions for handling object managers
virtual AUDIO_IO_MANAGER * create_object_manager (void) const
 Creates an object manager for this audio object type.
Constructors and destructors
virtual AUDIO_IO * clone (void) const =0
 Virtual method that clones the current object and returns a pointer to it.
virtual AUDIO_IO * new_expr (void) const =0
 Virtual method that creates a new object of current type.
 AUDIO_IO (const string &name="uninitialized", int mode=io_read)
Attribute functions
virtual int supported_io_modes (void) const
 Returns info about supported I/O modes (bitwise-OR).
virtual bool supports_nonblocking_mode (void) const
 Whether device supports non-blocking I/O mode.
virtual bool supports_seeking (void) const
 Whether device supports non-blocking I/O mode.
virtual bool finite_length_stream (void) const
 Whether audio stream has a distinct length.
virtual bool locked_audio_format (void) const
 Whether audio format is locked.
Configuration
For setting and getting configuration parameters.

virtual void set_buffersize (long int samples)=0
 Sets the sample buffer size in sample frames.
virtual long int buffersize (void) const =0
 Returns the current buffersize in sample frames.
int io_mode (void) const
 Returns info about the current I/O mode.
const string & label (void) const
 Returns the current label.
string format_info (void) const
 Returns a string containing info about sample format parameters.
void set_io_mode (int mode)
 Set object input/output-mode.
void set_label (const string &id_label)
 Sets object label.
void toggle_nonblocking_mode (bool value)
 Enable/disbale nonblocking mode.
virtual string parameter_names (void) const
 A comma-separated list of parameters names.
virtual void set_parameter (int param, string value)
 Sets the parameter value.
virtual string get_parameter (int param) const
 Get parameter value.
Main functionality
virtual void read_buffer (SAMPLE_BUFFER *sbuf)=0
 Reads samples and store them to buffer pointed by 'sbuf'.
virtual void write_buffer (SAMPLE_BUFFER *sbuf)=0
 Writes all data from sample buffer pointed by 'sbuf' to this object.
virtual void open (void) throw (AUDIO_IO::SETUP_ERROR &)
 Opens the audio object (possibly in exclusive mode).
virtual void close (void)
 Closes audio object.
Runtime information
virtual int poll_descriptor (void) const
 Returns a file descriptor id suitable for poll() and select() system calls.
virtual long int samples_available (void) const
 If 'supports_nonblocking_mode() == true', this function returns the number of samples frames that is available for reading, or alternatively, how many sample frames can be written without blocking.
bool is_open (void) const
 Has device been opened (with open())?
virtual bool finished (void) const =0
 Whether all data has been processed? If opened in mode 'io_read', this means that end of stream has been reached.
virtual bool nonblocking_mode (void) const
 Is nonblocking mode is enabled?
virtual bool readable (void) const
 Is the audio object ready for reading?
virtual bool writable (void) const
 Is the audio object ready for writing?
virtual string status (void) const
 Optional status string.
ECA_AUDIO_TIME length (void) const
 If applicable, returns total length of the audio data stored into current audio object.
ECA_AUDIO_TIME position (void) const
 Returns the current position.
Functions overridden and reimplemented from
ECA_AUDIO_POSITION and ECA_AUDIO_FORMAT

SAMPLE_SPECS::sample_rate_t samples_per_second (void) const
 Overrides the non-virtaul function ECA_SAMPLERATE_AWARE::samples_per_second(), that is present (through inheritance) in both ECA_AUDIO_FORMAT and ECA_AUDIO_POSITION.
virtual void set_samples_per_second (SAMPLE_SPECS::sample_rate_t v)
virtual void set_audio_format (const ECA_AUDIO_FORMAT &f_str)
 Sets audio format to that of 'f'.
Functions implemented from ECA_AUDIO_POSITION
virtual void seek_position (void)

Protected Member Functions

Functions provided for subclasses.
void position (const ECA_AUDIO_TIME &v)
 Sets the current position.
void length (const ECA_AUDIO_TIME &v)
 Sets the total length of audio object data.

Classes

class  SETUP_ERROR

Detailed Description

Virtual base class for all audio I/O objects.

Different types of audio objects include files, audio devices, sound producing program modules, audio server clients, and so on.

The class interface is divided into following sections:

Author:
Kai Vehmanen

Member Enumeration Documentation

enum AUDIO_IO::Io_mode
 

Input/Output mode.

See also:
io_mode()
io_read

Device is opened for input. If opening a file, it must exist.

io_write

Device is opened for output. If opening a file and and output exists, it is first truncated.

io_readwrite

Device is opened for both reading and writing. If opening a file, a new file is created if needed. When switching from read to write or vica versa, position should be reset before using the device.

Member Function Documentation

virtual long int AUDIO_IO::buffersize (  void   )  const [pure virtual]
 

Returns the current buffersize in sample frames.

See also:
set_buffersize()

Implemented in AUDIO_IO_BUFFERED, LOOP_DEVICE, and AUDIO_IO_PROXY.

virtual AUDIO_IO* AUDIO_IO::clone (  void   )  const [pure virtual]
 

Virtual method that clones the current object and returns a pointer to it.

This must be implemented by all subclasses!

Implements DYNAMIC_OBJECT< string >.

Implemented in AAC_FORKED_INTERFACE, CDRFILE, AUDIO_IO_DB_CLIENT, EWFFILE, FLAC_FORKED_INTERFACE, LOOP_DEVICE, MIKMOD_INTERFACE, MP3FILE, NULLFILE, OGG_VORBIS_INTERFACE, OSSDEVICE, AUDIO_IO_PROXY, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, REALTIME_NULL, TIMIDITY_INTERFACE, AUDIO_IO_TYPESELECT, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, AUDIO_IO_ALSA_PCM_NAMED, ARTS_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

void AUDIO_IO::close (  void   )  [virtual]
 

Closes audio object.

After calling this routine, all resources (for instance files and devices) must be freed so that they can be used by other processes.

Precondition:
is_open() == true
Postcondition:
readable() != true

writable() != true

Reimplemented in AAC_FORKED_INTERFACE, CDRFILE, AUDIO_IO_DB_CLIENT, EWFFILE, FLAC_FORKED_INTERFACE, MIKMOD_INTERFACE, MP3FILE, NULLFILE, OGG_VORBIS_INTERFACE, OSSDEVICE, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, REALTIME_NULL, TIMIDITY_INTERFACE, AUDIO_IO_TYPESELECT, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, ARTS_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

virtual AUDIO_IO_MANAGER* AUDIO_IO::create_object_manager (  void   )  const [inline, virtual]
 

Creates an object manager for this audio object type.

Returns:
0 if no manager objects are not supported

Reimplemented in AUDIO_IO_JACK.

virtual bool AUDIO_IO::finished (  void   )  const [pure virtual]
 

Whether all data has been processed? If opened in mode 'io_read', this means that end of stream has been reached.

If opened in 'io_write' or 'io_readwrite' modes, finished status usually means that an error has occured (no space left, etc). After finished() has returned 'true', further calls to read_buffer() and/or write_buffer() won't process any data.

For output for which 'finite_length_stream()' is true, when 'finished()' returns true, that means an error has occured. Otherwise 'finished()' just tells that further attempts to do i/o will fail.

Implemented in AAC_FORKED_INTERFACE, CDRFILE, AUDIO_IO_DB_CLIENT, AUDIO_IO_DEVICE, EWFFILE, FLAC_FORKED_INTERFACE, LOOP_DEVICE, MIKMOD_INTERFACE, MP3FILE, NULLFILE, OGG_VORBIS_INTERFACE, AUDIO_IO_PROXY, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, TIMIDITY_INTERFACE, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

bool AUDIO_IO::finite_length_stream (  void   )  const [virtual]
 

Whether audio stream has a distinct length.

It's important to note the difference between this attribute and 'supports_seeking()'. For example, a file read through a pipe mechanism is not seekable and its length is not known until 'finished()´ becomes true, but still, it is of finite length. A sine oscillator on the other hand can go on producing a signal forever, and is thus infinite.

This attributes directly affects how 'finished()' should to be interpreted.

See also:
finished().
By default, audio streams are finite length.

Reimplemented in EWFFILE, AUDIO_IO_PROXY, AUDIO_IO_RESAMPLE, and AUDIO_IO_REVERSE.

string AUDIO_IO::get_parameter (  int  param  )  const [virtual]
 

Get parameter value.

Parameters:
param parameter id, require: param > 0

Implements DYNAMIC_PARAMETERS< string >.

Reimplemented in AAC_FORKED_INTERFACE, FLAC_FORKED_INTERFACE, LOOP_DEVICE, MIKMOD_INTERFACE, MP3FILE, OGG_VORBIS_INTERFACE, AUDIO_IO_PROXY, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, AUDIO_IO_TYPESELECT, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, AUDIO_IO_ALSA_PCM_NAMED, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

const string & AUDIO_IO::label (  void   )  const
 

Returns the current label.

See documentation for label(const string&).

ECA_AUDIO_TIME AUDIO_IO::length (  void   )  const
 

If applicable, returns total length of the audio data stored into current audio object.

In many situations it's impossible enquire the whole length of the object. For instance, if the object is streaming a finite length audio stream audio object from other applications using some type of standard IPC, the actual length won't be known until the whole stream has been read. As a general rule, if 'supports_seeking() == true', length can be known right after initialization. Then again, if 'finite_length_stream() == true', the whole stream must be processed before we know the actual length. In other cases, length is unknown or infinite.

bool AUDIO_IO::locked_audio_format (  void   )  const [virtual]
 

Whether audio format is locked.

If this is true, audio object has a known audio format, and doesn't allow overriding it.

By default, audio format is not locked.

Reimplemented in AAC_FORKED_INTERFACE, CDRFILE, EWFFILE, FLAC_FORKED_INTERFACE, MP3FILE, OGG_VORBIS_INTERFACE, AUDIO_IO_PROXY, WAVEFILE, AUDIOFILE_INTERFACE, ARTS_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

virtual AUDIO_IO* AUDIO_IO::new_expr (  void   )  const [pure virtual]
 

Virtual method that creates a new object of current type.

This must be implemented by all subclasses!

Implements DYNAMIC_OBJECT< string >.

Implemented in AAC_FORKED_INTERFACE, CDRFILE, AUDIO_IO_DB_CLIENT, EWFFILE, FLAC_FORKED_INTERFACE, LOOP_DEVICE, MIKMOD_INTERFACE, MP3FILE, NULLFILE, OGG_VORBIS_INTERFACE, OSSDEVICE, AUDIO_IO_PROXY, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, REALTIME_NULL, TIMIDITY_INTERFACE, AUDIO_IO_TYPESELECT, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, AUDIO_IO_ALSA_PCM_NAMED, ARTS_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

void AUDIO_IO::open (  void   )  throw (AUDIO_IO::SETUP_ERROR &) [virtual]
 

Opens the audio object (possibly in exclusive mode).

This routine is used for initializing external connections (opening files or devices, loading shared libraries, opening IPC connections). As it's impossible to know in advance what might happen, open() may throw an exception. This way it becomes possible to provide more verbose information about the problem that caused open() to fail.

At this point the various audio parameters are used for the first time. Unless locked_audio_format() is 'true', object tries to use the audio format parameters set prior to this call. If object doesn't support the given parameter combination, it can either try adjust them to closest matching, or in the worst case, throw an SETUP_ERROR exception (see above).

Precondition:
is_open() != true
Postcondition:
readable() == true || writable() == true || is_open() != true

Reimplemented in AAC_FORKED_INTERFACE, CDRFILE, AUDIO_IO_DB_CLIENT, EWFFILE, FLAC_FORKED_INTERFACE, MIKMOD_INTERFACE, MP3FILE, NULLFILE, OGG_VORBIS_INTERFACE, OSSDEVICE, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, REALTIME_NULL, TIMIDITY_INTERFACE, AUDIO_IO_TYPESELECT, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, ARTS_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

virtual string AUDIO_IO::parameter_names (  void   )  const [inline, virtual]
 

A comma-separated list of parameters names.

Derived classes must implement this.

Implements DYNAMIC_PARAMETERS< string >.

Reimplemented in AAC_FORKED_INTERFACE, FLAC_FORKED_INTERFACE, LOOP_DEVICE, MIKMOD_INTERFACE, MP3FILE, OGG_VORBIS_INTERFACE, AUDIO_IO_PROXY, RAWFILE, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, AUDIO_IO_TYPESELECT, WAVEFILE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, AUDIO_IO_ALSA_PCM_NAMED, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

virtual int AUDIO_IO::poll_descriptor (  void   )  const [inline, virtual]
 

Returns a file descriptor id suitable for poll() and select() system calls.

If polling is not supported, returns value of '-1'.

virtual void AUDIO_IO::read_buffer (  SAMPLE_BUFFER *  sbuf  )  [pure virtual]
 

Reads samples and store them to buffer pointed by 'sbuf'.

If necessary, the target buffer will be resized.

It's important to note that SAMPLE_BUFFER audio format cannot be changed during processing. This means that audio data must be converted from audio object's internal format to that of 'sbuf' given as argument. SAMPLE_BUFFER class provides tools for all normal conversion operations. If you need direct access to object's data, a lower abstraction level should be used (

See also:
AUDIO_IO_BUFFERED).
Note! The implementations should call set_position_in_samples() or change_position_in_samples() in ECA_AUDIO_POSITION.

Precondition:
io_mode() == io_read || io_mode() == io_readwrite

readable() == true

sbuf != 0

Postcondition:
sbuf->length_in_samples() <= buffersize()

Implemented in AUDIO_IO_BUFFERED, AUDIO_IO_DB_CLIENT, EWFFILE, LOOP_DEVICE, AUDIO_IO_PROXY, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, and SNDFILE_INTERFACE.

virtual long int AUDIO_IO::samples_available (  void   )  const [inline, virtual]
 

If 'supports_nonblocking_mode() == true', this function returns the number of samples frames that is available for reading, or alternatively, how many sample frames can be written without blocking.

This function can be used for implementing nonblocking input and output with devices supporting it.

Note, you should use set_buffersize() for setting how many sample frames read_buffer() will ask from the device.

require: supports_nonblocking_mode() == true

virtual void AUDIO_IO::set_buffersize (  long int  samples  )  [pure virtual]
 

Sets the sample buffer size in sample frames.

When reading data with read_buffer(), buffersize() determines how many sample frames of data is processed per call.

Otherwise buffersize() is only used for initializing devices and data structures.

Device should always be able to write all sample data passed to write_buffer(), independently from current buffersize() value.

See also:
buffersize()

Implemented in AUDIO_IO_BUFFERED, LOOP_DEVICE, and AUDIO_IO_PROXY.

void AUDIO_IO::set_io_mode (  int  mode  ) 
 

Set object input/output-mode.

If the requested mode isn't supported, the nearest supported mode is used. Because of this, it's wise to afterwards check whether the requested mode was accepted.

require: is_open() != true

void AUDIO_IO::set_label (  const string &  id_label  ) 
 

Sets object label.

Label is used to identify the object instance. Unlike ECA_OBJECT::name(), label() is not necessarily unique among different class instances. Device and file names are typical label values.

require: is_open() != true

void AUDIO_IO::set_parameter (  int  param,
string  value
)  [virtual]
 

Sets the parameter value.

Implementations should be able to handle arbitrary values of 'value'. Argument validity can be tested by a combination of set_parameter() and get_parameter() calls. Parameter value is valid, if get_parameter() returns it without changes.

Parameters:
param parameter id, require: param > 0
value new value

Implements DYNAMIC_PARAMETERS< string >.

Reimplemented in MIKMOD_INTERFACE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, AUDIO_IO_ALSA_PCM_NAMED, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

string AUDIO_IO::status (  void   )  const [virtual]
 

Optional status string.

An unformatted text string describing the state and status of the current object.

Reimplemented in AUDIO_IO_DEVICE.

int AUDIO_IO::supported_io_modes (  void   )  const [virtual]
 

Returns info about supported I/O modes (bitwise-OR).

By default, all I/O modes are supported.

Reimplemented in AAC_FORKED_INTERFACE, FLAC_FORKED_INTERFACE, MIKMOD_INTERFACE, MP3FILE, OGG_VORBIS_INTERFACE, OSSDEVICE, AUDIO_IO_PROXY, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, TIMIDITY_INTERFACE, AUDIOFILE_INTERFACE, AUDIO_IO_ALSA_PCM, ARTS_INTERFACE, AUDIO_IO_JACK, and SNDFILE_INTERFACE.

bool AUDIO_IO::supports_nonblocking_mode (  void   )  const [virtual]
 

Whether device supports non-blocking I/O mode.

By default, nonblocking mode is not supported.

Reimplemented in AUDIO_IO_PROXY, and ARTS_INTERFACE.

bool AUDIO_IO::supports_seeking (  void   )  const [virtual]
 

Whether device supports non-blocking I/O mode.

By default, seeking is supported.

Reimplemented in AAC_FORKED_INTERFACE, AUDIO_IO_DEVICE, EWFFILE, FLAC_FORKED_INTERFACE, MIKMOD_INTERFACE, MP3FILE, NULLFILE, OGG_VORBIS_INTERFACE, AUDIO_IO_PROXY, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, TIMIDITY_INTERFACE, and ARTS_INTERFACE.

void AUDIO_IO::toggle_nonblocking_mode (  bool  value  ) 
 

Enable/disbale nonblocking mode.

require: is_open() != true

virtual void AUDIO_IO::write_buffer (  SAMPLE_BUFFER *  sbuf  )  [pure virtual]
 

Writes all data from sample buffer pointed by 'sbuf' to this object.

Notes concerning read_buffer() also apply to this routine.

Note! The implementations should call set_position_in_samples() or change_position_in_samples() in ECA_AUDIO_POSITION.

Precondition:
io_mode() == io_write || io_mode() == io_readwrite

writable() == true

sbuf != 0

Implemented in AUDIO_IO_BUFFERED, AUDIO_IO_DB_CLIENT, EWFFILE, LOOP_DEVICE, AUDIO_IO_PROXY, AUDIO_IO_RESAMPLE, AUDIO_IO_REVERSE, and SNDFILE_INTERFACE.

The documentation for this class was generated from the following files:
Generated on Fri Apr 8 01:37:48 2005 for libecasound by  doxygen 1.4.1