Cl-Out123

About cl-out123

This is a bindings library to libout123 which allows easy cross-platform audio playback.

How To

Precompiled versions of the underlying library are included in this. If you want to build it manually however, refer to the mpg123 page.

Load the system through ASDF or Quicklisp:

(ql:quickload :cl-out123)

Create a new output object:

(defvar *out* (make-instance 'cl-out123:output))

This will initialise a standard output handler object for you, based on some hopefully sane defaults. We can now look at a list of possible drivers:

(cl-out123:drivers *out*)

If we're fine with the automatic default or now have a backend we know we want to use, we can connect to it:

(cl-out123:connect *out* :driver "pulse")

Now that we have a stable connection to the sound system, we can query it for possible output formats:

(cl-out123:formats *out* '(44100) 1 2)

Finally once we have figured out a proper format to use, or again are fine with the default, we can start playback to the device:

(cl-out123:start *out* :rate 44100 :channels 2 :encoding :int16)

Now buffered audio data that conforms to the format we picked can be sent to be played back using play or play-directly:

(cl-out123:play *out* #(...))

It will return you the amount of bytes it actually managed to play back. If need be, playback can also be paused, resumed, and stopped. Currently buffered data can be dropped, or drained too to allow you to synchronise things.

Once we're done, simply stop the output object:

(cl-out123:stop *out*)

If for some reason you find yourself needing to change output format or device after having initialised your output already, you can reconfigure it using reinitialize-instance. This will cause your current playback to end if it is currently running, but should otherwise phase over smoothly.

(reinitialize-instance *out* :driver "alsa")

There is no need to explicitly deallocate or clean up data. As soon as the output object is garbage collected, the cleanup will be handled for you automatically. If you would like to explicitly close the connection anyway:

(cl-out123:disconnect *out*)

And that's pretty much all there is to it. The heavy burden falls onto you to get the audio data ready in the proper format for it to be played back. The actual transfer process to the sound system should be easy with this library.

Copyright

cl-out123 is licensed under the Artistic license. © Nicolas Hafner <shinmera@tymoon.eu> . This library can be obtained on https://github.com/Shirakumo/cl-out123.

Package Index

CL-OUT123-CFFI (ORG.SHIRAKUMO.FRAF.OUT123.CFFI)
- special
  *STATIC*
```
Variable containing a pathname to the static directory.
```
- class
  FMT
  
  No docstring provided.
- class
  HANDLE
  
  No docstring provided.
- condition
  ERROR
  
  No docstring provided.
- accessor (
  FMT-CHANNELS
  POINTER-TO-FMT)
  
  No docstring provided.
- accessor (
  FMT-ENCODING
  POINTER-TO-FMT)
  
  No docstring provided.
- accessor (
  FMT-RATE
  POINTER-TO-FMT)
  
  No docstring provided.
- function (
  BUFFERED
  HANDLE)
  
  No docstring provided.
- function (
  CLOSE
  HANDLE)
  
  No docstring provided.
- function (
  CONTINUE
  HANDLE)
  
  No docstring provided.
- function (
  DEL
  HANDLE)
  
  No docstring provided.
- function (
  DRAIN
  HANDLE)
  
  No docstring provided.
- function (
  DRIVER-INFO
  HANDLE DRIVER DEVICE)
  
  No docstring provided.
- function (
  DRIVERS
  HANDLE NAMES DESCR)
  
  No docstring provided.
- function (
  DROP
  HANDLE)
  
  No docstring provided.
- function (
  ENC-BYNAME
  NAME)
  
  No docstring provided.
- function (
  ENC-LIST
  ENCLIST)
  
  No docstring provided.
- function (
  ENC-LONGNAME
  ENCODING)
  
  No docstring provided.
- function (
  ENC-NAME
  ENCODING)
  
  No docstring provided.
- function (
  ENCODINGS
  HANDLE RATE CHANNELS)
  
  No docstring provided.
- function (
  ENCSIZE
  ENCODING)
  
  No docstring provided.
- function (
  ERRCODE
  HANDLE)
  
  No docstring provided.
- function (
  ERROR
  DATUM &REST ARGUMENTS)
```
Invoke the signal facility on a condition formed from DATUM and ARGUMENTS.
  If the condition is not handled, the debugger is invoked.
```
- function (
  FORMATS
  HANDLE RATES RATECOUNT MINCHANNELS MAXCHANNELS FMTLIST)
  
  No docstring provided.
- function (
  GETFORMAT
  HANDLE RATE CHANNELS ENCODING FRAMESIZE)
  
  No docstring provided.
- function (
  GETPARAM
  HANDLE CODE RET-VALUE RET-FVALUE RET-SVALUE)
  
  No docstring provided.
- function (
  GETPARAM-FLOAT
  HANDLE CODE VALUE)
  
  No docstring provided.
- function (
  GETPARAM-INT
  HANDLE CODE VALUE)
  
  No docstring provided.
- function (
  GETPARAM-STRING
  HANDLE CODE VALUE)
  
  No docstring provided.
- function (
  NDRAIN
  HANDLE BYTES)
  
  No docstring provided.
- function (
  NEW
  )
  
  No docstring provided.
- function (
  OPEN
  HANDLE DRIVER DEVICE)
  
  No docstring provided.
- function (
  PARAM
  HANDLE CODE VALUE FVALUE SVALUE)
  
  No docstring provided.
- function (
  PARAM-FLOAT
  HANDLE CODE VALUE)
  
  No docstring provided.
- function (
  PARAM-FROM
  HANDLE HANDLE-FROM)
  
  No docstring provided.
- function (
  PARAM-INT
  HANDLE CODE VALUE)
  
  No docstring provided.
- function (
  PARAM-STRING
  HANDLE CODE VALUE)
  
  No docstring provided.
- function (
  PAUSE
  HANDLE)
  
  No docstring provided.
- function (
  PLAIN-STRERROR
  ERRCODE)
  
  No docstring provided.
- function (
  PLAY
  HANDLE BUFFER BYTES)
  
  No docstring provided.
- function (
  SET-BUFFER
  HANDLE BUFFER-BYTES)
  
  No docstring provided.
- function (
  START
  HANDLE RATE CHANNELS ENCODING)
  
  No docstring provided.
- function (
  STOP
  HANDLE)
  
  No docstring provided.
- function (
  STRERROR
  HANDLE)
  
  No docstring provided.

CL-OUT123 (ORG.SHIRAKUMO.FRAF.OUT123)

class

`OUTPUT`

Class representing an output to a sound playback device.

This holds all the necessary state and information in order to connect and
play back audio data to a device.

Some options can only be changed by closing and opening a new connection to
the backend. In order to do this, you can use REINITIALIZE-INSTANCE. It will
attempt to preserve state across reinitialisation, but pending sound data
will be disposed off immediately as to not block.

See HANDLE
See PLAYING
See CONNECTED
See DRIVER
See DEVICE
See RATE
See CHANNELS
See ENCODING
See OUTPUT-TO
See PRELOAD
See GAIN
See DEVICE-BUFFER
See NAME
See OUTPUT-LOCK

condition

`ALREADY-CONNECTED`

Condition signalled if an attempt is made to connect again while the output is still connected.

See OUTPUT-ERROR

condition

`BUFFER-SET-FAILED`

Condition signalled if the setting of the background buffer fails.

See ERROR-STRING-ERROR
See BYTES

condition

`CONNECTION-FAILED`

Condition signalled if the connection of an output to its device fails.

See ERROR-STRING-ERROR
See DRIVER
See DEVICE

condition

`CREATION-FAILURE`

Condition signalled in the case the allocation of the output handler fails.

See OUTPUT-ERROR

condition

`ERROR-STRING-ERROR`

Error condition superclass for errors that have an error-string from the out123 library.

See ERROR-STRING
See OUTPUT-ERROR

condition
FAILED-DRIVER-INFO

No docstring provided.

condition

`FAILED-DRIVER-LISTING`

Condition signalled if the listing of available drivers fails for some reason.

See OUTPUT-ERROR

condition

`FAILED-FORMAT-LISTING`

Condition signalled if the listing of available formats fails for some reason.

See OUTPUT-ERROR

condition
FAILED-PLAYBACK-FORMAT

No docstring provided.

condition

`NOT-CONNECTED`

Condition signalled if an operation is attempted that requires the output to be connected, but it isn't.

See OUTPUT-ERROR

condition

`OUTPUT-ERROR`

Error condition superclass for all errors related to this library.

See OUTPUT

condition

`PLAYBACK-FAILED`

Condition signalled if the playback of a buffer fails.

See ERROR-STRING-ERROR
See BYTES

condition

`START-FAILED`

Condition signalled if starting the device fails.

See ERROR-STRING-ERROR
See RATE
See CHANNELS
See ENCODING

accessor (

`BUFFERED`

OUTPUT)

Returns the number of bytes that currently reside in the internal buffer.

This number changes constantly as audio is played back.

This is setfable. Once set, a fork occurs to spawn a
"thread" to process the buffer in in the background.
See the <out123.h> file for more information.

See OUTPUT

function (

`CONNECT`

OUTPUT &KEY (DRIVER (DRIVER OUTPUT)) (DEVICE (DEVICE OUTPUT)))

Connects the output to the requested driver and device.

The output must not be connected already.

If the connection was successful, the output's DRIVER and DEVICE
are updated to reflect the ones that were actually chosen by the
backend. This might differ from what you requested.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See OUTPUT
See DRIVER
See DEVICE
See CONNECTED

function (

`DEVICE-DEFAULT-NAME`

&OPTIONAL (IDENT (PACKAGE-NAME *PACKAGE*)))

Attempts to return a somewhat sensible name to use for our application.

function (

`DISCONNECT`

OUTPUT)

Disconnects the output from its driver and device.

If the output is already disconnected, this does nothing.

If there is still audio data to be played on the buffer, then this
will block until it is finished. If you wish to abort immediately,

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.
call DROP first.

See OUTPUT
See DROP
See CONNECTED

function (

`DRAIN`

OUTPUT)

Blocks until all output in the buffer has been played back.

Implicitly resumes playback if it is paused first and then
pauses it again once it finishes.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See PLAYING
See OUTPUT
See NDRAIN

function (

`DRIVER-INFO`

OUTPUT)

Returns the current driver and device the output uses, if any.

This might differ from DRIVER and DEVICE if the handle was not yet
CONNECTed, was connected by non-standard means, or something else
went wrong.

See OUTPUT
See CONNECT

function (

`DRIVERS`

OUTPUT)

Returns a list of drivers with their name and description.

You can use this to determine the available drivers and pick a suitable backend based on that.

See OUTPUT

function (

`DROP`

OUTPUT)

Drops all remaining output from the internal buffers.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See OUTPUT

function (

`ENCODINGS`

OUTPUT RATE CHANNELS)

Returns a list of the possible encodings for the output rate and channel count you specified.

The output must be connected and will be stopped if it is playing.

See OTUPUT

function (

`FORMATS`

OUTPUT RATES MIN-CHANNELS MAX-CHANNELS)

Returns a list of possible formats for the requested rates and channels.

RATES should be a list of integers.

The output must be connected and will be stopped if it is playing.

Each item in the list is a plist with :RATE, :CHANNELS, and :ENCODINGS as keys.

function (
MAKE-OUTPUT
DRIVER &REST ARGS &KEY &ALLOW-OTHER-KEYS)

No docstring provided.

function (

`NDRAIN`

OUTPUT BYTES)

Blocks until either all or bytes number of bytes have been played back.

Implictly resumes playback if it is paused first and then
pauses it again if there are no remaining bytes to be played
back.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See PLAYING
See OUTPUT
See DRAIN

function (

`PAUSE`

OUTPUT)

Pauses playback.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See OUTPUT
See PLAYING

function (

`PLAY`

OUTPUT BYTES &OPTIONAL (COUNT (LENGTH BYTES)))

Send the octet-vector or array-pointer to out123 to be played back on the output.

If you need low latency, then this is definitely not the
function for you. The buffer is converted into a foreign
byte array before being sent off.

Returns the number of bytes that were actually played back.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See PLAY-DIRECTLY
See OUTPUT

function (

`PLAY-DIRECTLY`

OUTPUT BUFFER BYTES)

Directly sends the given buffer to out123 to be played back on the output.

BUFFER must be a pointer to a foreign byte array of at least
BYTES size. Returns the number of bytes that were actually
played back.

This does not catch errors. If you need to check for errors,
see CL-OUT123-CFFI:ERRCODE.

This does not care for synchronisation or mutual exclusion.
If you call this simultaneously from multiple threads, things
/will/ crash and burn horribly.

See CL-OUT123-CFFI:ERRCODE
See HANDLE
See OUTPUT

function (

`PLAYBACK-FORMAT`

OUTPUT)

Returns the current rate, channels, encoding, and framesize used by the output, if any.

This might differ from RATE, CHANNELS, ENCODING, and FRAMESIZE
if the handle has not yet been STARTed, was started by
non-standard means, or something else went wrong.

See OUTPUT
See START

function (

`RESUME`

OUTPUT)

Resumes playback.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See OUTPUT
See PLAYING

function (

`START`

OUTPUT &KEY (RATE (RATE OUTPUT)) (CHANNELS (CHANNELS OUTPUT))
 (ENCODING (ENCODING OUTPUT))

)

Starts playback to the connected output.

The output must be connected and must not have been started before.

If the start was successful, the output's RATE, CHANNELS, ENCODING,
and FRAMESIZE are updated to reflect the values that were actually
chosen by the backend. This might differ from what you requested.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See OUTPUT
See RATE
See CHANNELS
See ENCODING
See FRAMESIZE
See PLAYING

function (

`STOP`

OUTPUT)

Stops playback.

If there is still audio data to be played on the buffer, then this
will block until it is finished. If you wish to abort immediately,
call DROP first.

This function is safe to be called from multiple threads,
as it will mutually exclude them through a lock.

See OUTPUT
See PLAYING

generic (
BYTES
CONDITION)

No docstring provided.

generic (

`CHANNELS`

CONDITION)

Returns the number of audio channels the backend uses to process the buffer data.

Can be set as an initarg on the output.

See OUTPUT
See START

generic (

`CONNECTED`

OBJECT)

Returns T if the output is connected to a device.

generic (

`DEVICE`

CONDITION)

Returns the string naming the device used to play back sound or NIL if unknown.

Can be set as an initarg on the output.

See OUTPUT
See CONNECT

generic (

`DEVICE-BUFFER`

OBJECT)

Returns the number of seconds that the device buffer should hold.

Can be set as an initarg on the output.

Allowed values are:
T    for the default that the backend will choose for itself. 
REAL for the approximate amount of seconds of buffering. Should
     not be more than 0.5.

See OUTPUT

generic (

`DRIVER`

CONDITION)

Returns the string naming the driver used to play back sound or NIL if unknown.

Can be set as an initarg on the output.

In order to get a listing of all possible drivers, see DRIVERS.

See OUTPUT
See DRIVERS
See CONNECT

generic (

`ENCODING`

CONDITION)

Returns the encoding the backend uses to decode the buffer data.

Can be set as an initarg on the output.

See ENCODINGS for a list of possible encodings.

See OUTPUT
See START
See ENCODINGS

generic (

`ERROR-STRING`

CONDITION)

Returns the error string from the out123 library for the error we encountered.

See ERROR-STRING-ERROR

generic (

`GAIN`

OBJECT)

Returns an integer representing the output device gain. This is driver-specific.

Can be set as an initarg on the output.

See OUTPUT

generic (

`HANDLE`

OBJECT)

Returns the pointer to the actual handle object that the output object encapsulates.

You should not need this unless you are working with the internals of the library.

See OUTPUT

generic (

`NAME`

OBJECT)

Returns the name used to identify the output in the audio playback device, if permitted.

Can be set as an initarg on the otuput.

The default value is calculated by DEVICE-DEFAULT-NAME

See OUTPUT
See DEVICE-DEFAULT-NAME

generic (

`OUTPUT`

CONDITION)

Returns the output object associated with the condition.

See OUTPUT-ERROR

generic (

`OUTPUT-TO`

OBJECT)

Returns a list of special flags that tell the backend (if possible) where to output to.

Can be set as an initarg on the output.

The flags in the list can be one of :HEADPHONES :INTERNAL-SPEAKER :LINE-OUT

See OUTPUT

generic (

`PLAYING`

OBJECT)

Returns T if the output is currently playing audio.

generic (

`PRELOAD`

OBJECT)

Returns the percentage of data that is preloaded into the device buffer.

Can be set as an initarg on the output.

Allowed values are:
T    for the default that the backend will choose for itself.
NIL  for no preloading, aka 0.0.
REAL for the approximate fraction that should be preloaded [0,1].

See OUTPUT

generic (

`RATE`

CONDITION)

Returns the sampling rate the backend uses to process the buffer data.

Can be set as an initarg on the output.

See OUTPUT
See START

macro (

`WITH-PLAYBACK`

(OUTPUT &KEY (RATE) (CHANNELS) (ENCODING)) &BODY BODY)

Ensures a clean playback environment for the body.

First calls START with the given options, then evaluates the body
forms in an unwind-protect that calls STOP on exit.

See START
See STOP

About cl-out123

How To

Copyright

Package Index

CL-OUT123-CFFI (ORG.SHIRAKUMO.FRAF.OUT123.CFFI)

CL-OUT123 (ORG.SHIRAKUMO.FRAF.OUT123)