NAME

Audio::ESD - Perl extension for talking to the Enlightened Sound Daemon

SYNOPSIS

  use Audio::ESD;
  my $stream = Audio::ESD->play_stream({ # these are the defaults
                                         sample_rate => 16000,
                                         channels => 1,
                                         fallback => 0,
                                         bits_sample => 16,
                                         encoding => 'linear' })
      or die "Failed to open ESD stream: $!\n";
  print $stream $data; # etcetera

DESCRIPTION

This module provides a Perl wrapper around the Enlightened Sound Daemon's client library. Input, output, and monitoring streams are supported, as well as some (but not all) of the control functions. Samples are supported but untested.

AUDIO STREAMS

Audio streams can be opened for playback, recording, monitoring, or filtering. There are separate `constructor' class methods for doing all of these things. All of these methods accept a single optional argument, which is a reference to a hash possibly containing the following stream parameters (defaults are supplied if the parameters are not present):

sample_rate

The sampling rate for audio written to and/or read from the stream, expressed in samples per second. Defaults to 16000

bits_sample

The sample size in bits. Currently acceptable values are 8 and 16. Defaults to 16.

channels

The number of channels (interleaved). Currently acceptable values are 1 and 2. Defaults to 1.

encoding

The audio encoding format used. The only currently acceptable value is 'linear' (which means linear PCM). Maybe someday Esound will support others.

To open a stream for playback, use play_stream:

  my $stream = Audio::ESD->play_stream(\%opts);

This method also supports an extra option, 'fallback'. If this is true, the Esound library will "fall back" to the local audio device if a connection to the ESD server could not be made (or so the documentation says, at least).

To open a stream for recording, use record_stream:

  my $stream = Audio::ESD->record_stream(\%opts);

This method also supports the 'fallback' option.

To open a stream for monitoring (i.e. capturing the mixed output stream from the server), use monitor_stream:

  my $stream = Audio::ESD->monitor_stream(\%opts);

To open a stream for filtering, use filter_stream:

  my $stream = Audio::ESD->filter_stream(\%opts);

Apparently, this allows you read blocks of data from the output stream, do some transformations on them, then write them back, and have ESD play them.

SERVER CONNECTIONS

To open a general-purpose control connection to the ESD server, use the open_sound class method:

  my $esd = Audio::ESD->open_sound($hostname);

If $hostname is undefined, a local ESD will be contacted via a Unix domain socket.

As with the audio streams, you can read and write to this connection as if it were a normal filehandle (since, in fact, that is what it is...) and thus, if you want to take your chances with the "over-the-wire" protocol you are free to do so.

However, you most likely just want to use this connection to access various parameters in the server, and don't worry, there are some methods for that:

send_auth

  $esd->send_auth();

lock

  $esd->lock();

unlock

  $esd->unlock();

standby

  $esd->standby();

resume

  $esd->resume();

sample_cache

  $esd->sample_cache($format, $rate, $length, $name);

confirm_sample_cache

  $esd->confirm_sample_cache();

sample_getid

  my $sample_id = $esd->sample_getid($name);

sample_play

  $esd->sample_play($sample_id);

sample_loop

  $esd->sample_loop($sample_id);

sample_stop

  $esd->sample_stop($sample_id);

sample_free

  $esd->sample_free($sample_id);

set_stream_pan

  $esd->set_stream_pan($stream_id, $left_scale, $right_scale);

set_default_sample_pan

  $esd->set_default_sample($stream_id, $left_scale, $right_scale);

get_latency

  my $latency = $esd->get_latency();

get_standby_mode

  my $standby = $esd->get_standby_mode();

SERVER INFO

get_server_info

  my $server_info = $esd->get_server_info();

get_all_info

  my $info = $esd->get_all_info();

print_server_info

  $server_info->print_server_info();

print_all_info

  $info->print_all_info();

EXPORTABLE CONSTANTS

The following constants can be imported from Audio::ESD. They are mostly useful for the format argument to some functions. You can import all of them with the :standard tag.

        ESD_ADPCM
        ESD_BITS16
        ESD_BITS8
        ESD_BUF_SIZE
        ESD_DEFAULT_PORT
        ESD_DEFAULT_RATE
        ESD_ENDIAN_KEY
        ESD_KEY_LEN
        ESD_LOOP
        ESD_MASK_BITS
        ESD_MASK_CHAN
        ESD_MASK_FUNC
        ESD_MASK_MODE
        ESD_MONITOR
        ESD_MONO
        ESD_NAME_MAX
        ESD_PLAY
        ESD_RECORD
        ESD_SAMPLE
        ESD_STEREO
        ESD_STOP
        ESD_STREAM
        ESD_VOLUME_BASE

BUGS

It probably leaks file descriptors or worse. Lots of stuff is untested and undocumented, and since the Esound API is full of happy surprises it's likely not to work.

AUTHOR

David Huggins-Daines <dhd@cepstral.com>

SEE ALSO

perl(1), esd(1).

cpanm Audio::ESD

perl -MCPAN -e shell
install Audio::ESD