cl out123

Table of Contents

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.

System Information

Definition Index

• CL-OUT123-CFFI

  • ORG.SHIRAKUMO.FRAF.OUT123.CFFI

  No documentation provided.

  • EXTERNAL SPECIAL-VARIABLE

    *STATIC*

    Source

    Variable containing a pathname to the static directory.

  • EXTERNAL CLASS

    FMT

    Source

    No documentation provided.
  • EXTERNAL CLASS

    HANDLE

    Source

    No documentation provided.
  • EXTERNAL CONDITION

    ERROR

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    BUFFERED

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    CLOSE

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    CONTINUE

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    DEL

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    DRAIN

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    DRIVER-INFO

    • HANDLE
    • DRIVER
    • DEVICE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    DRIVERS

    • HANDLE
    • NAMES
    • DESCR
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    DROP

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ENC-BYNAME

    • NAME
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ENC-LIST

    • ENCLIST
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ENC-LONGNAME

    • ENCODING
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ENC-NAME

    • ENCODING
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ENCODINGS

    • HANDLE
    • RATE
    • CHANNELS
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ENCSIZE

    • ENCODING
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ERRCODE

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    ERROR

    • DATUM
    • &REST
    • ARGUMENTS
    • &REST

    Source

    Invoke the signal facility on a condition formed from DATUM and ARGUMENTS.
      If the condition is not handled, the debugger is invoked.

  • EXTERNAL FUNCTION

    FMT-CHANNELS

    • POINTER-TO-FMT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    (SETF FMT-CHANNELS)

    • VALUE
    • POINTER-TO-FMT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    FMT-ENCODING

    • POINTER-TO-FMT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    (SETF FMT-ENCODING)

    • VALUE
    • POINTER-TO-FMT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    FMT-RATE

    • POINTER-TO-FMT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    (SETF FMT-RATE)

    • VALUE
    • POINTER-TO-FMT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    FORMATS

    • HANDLE
    • RATES
    • RATECOUNT
    • MINCHANNELS
    • MAXCHANNELS
    • FMTLIST
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    GETFORMAT

    • HANDLE
    • RATE
    • CHANNELS
    • ENCODING
    • FRAMESIZE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    GETPARAM

    • HANDLE
    • CODE
    • RET-VALUE
    • RET-FVALUE
    • RET-SVALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    GETPARAM-FLOAT

    • HANDLE
    • CODE
    • VALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    GETPARAM-INT

    • HANDLE
    • CODE
    • VALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    GETPARAM-STRING

    • HANDLE
    • CODE
    • VALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    NDRAIN

    • HANDLE
    • BYTES
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    NEW

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    OPEN

    • HANDLE
    • DRIVER
    • DEVICE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PARAM

    • HANDLE
    • CODE
    • VALUE
    • FVALUE
    • SVALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PARAM-FLOAT

    • HANDLE
    • CODE
    • VALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PARAM-FROM

    • HANDLE
    • HANDLE-FROM
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PARAM-INT

    • HANDLE
    • CODE
    • VALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PARAM-STRING

    • HANDLE
    • CODE
    • VALUE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PAUSE

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PLAIN-STRERROR

    • ERRCODE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    PLAY

    • HANDLE
    • BUFFER
    • BYTES
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    SET-BUFFER

    • HANDLE
    • BUFFER-BYTES
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    START

    • HANDLE
    • RATE
    • CHANNELS
    • ENCODING
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    STOP

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    STRERROR

    • HANDLE
    • &REST

    Source

    No documentation provided.
  • EXTERNAL OPTIMIZER

    ERROR

    No documentation provided.
  • EXTERNAL TRANSFORM

    ERROR

    Source

    No documentation provided.

• CL-OUT123

  • ORG.SHIRAKUMO.FRAF.OUT123

  No documentation provided.

  • EXTERNAL CLASS

    OUTPUT

    Source

    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

  • EXTERNAL CONDITION

    ALREADY-CONNECTED

    Source

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

  • EXTERNAL CONDITION

    BUFFER-SET-FAILED

    Source

    Condition signalled if the setting of the background buffer fails.
    
    See ERROR-STRING-ERROR
    See BYTES

  • EXTERNAL CONDITION

    CONNECTION-FAILED

    Source

    Condition signalled if the connection of an output to its device fails.
    
    See ERROR-STRING-ERROR
    See DRIVER
    See DEVICE

  • EXTERNAL CONDITION

    CREATION-FAILURE

    Source

    Condition signalled in the case the allocation of the output handler fails.
    
    See OUTPUT-ERROR

  • EXTERNAL CONDITION

    ERROR-STRING-ERROR

    Source

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

  • EXTERNAL CONDITION

    FAILED-DRIVER-INFO

    Source

    No documentation provided.
  • EXTERNAL CONDITION

    FAILED-DRIVER-LISTING

    Source

    Condition signalled if the listing of available drivers fails for some reason.
    
    See OUTPUT-ERROR

  • EXTERNAL CONDITION

    FAILED-FORMAT-LISTING

    Source

    Condition signalled if the listing of available formats fails for some reason.
    
    See OUTPUT-ERROR

  • EXTERNAL CONDITION

    FAILED-PLAYBACK-FORMAT

    Source

    No documentation provided.
  • EXTERNAL CONDITION

    NOT-CONNECTED

    Source

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

  • EXTERNAL CONDITION

    OUTPUT-ERROR

    Source

    Error condition superclass for all errors related to this library.
    
    See OUTPUT

  • EXTERNAL CONDITION

    PLAYBACK-FAILED

    Source

    Condition signalled if the playback of a buffer fails.
    
    See ERROR-STRING-ERROR
    See BYTES

  • EXTERNAL CONDITION

    START-FAILED

    Source

    Condition signalled if starting the device fails.
    
    See ERROR-STRING-ERROR
    See RATE
    See CHANNELS
    See ENCODING

  • EXTERNAL FUNCTION

    BUFFERED

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    (SETF BUFFERED)

    • BYTES
    • OUTPUT
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    CONNECT

    • OUTPUT
    • &KEY
    • DRIVER
    • DEVICE
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    DEVICE-DEFAULT-NAME

    • &OPTIONAL
    • IDENT
    • &REST

    Source

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

  • EXTERNAL FUNCTION

    DISCONNECT

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    DRAIN

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    DRIVER-INFO

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    DRIVERS

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    DROP

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    ENCODINGS

    • OUTPUT
    • RATE
    • CHANNELS
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    FORMATS

    • OUTPUT
    • RATES
    • MIN-CHANNELS
    • MAX-CHANNELS
    • &REST

    Source

    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.

  • EXTERNAL FUNCTION

    MAKE-OUTPUT

    • DRIVER
    • &REST
    • ARGS
    • &KEY
    • &ALLOW-OTHER-KEYS
    • &REST

    Source

    No documentation provided.
  • EXTERNAL FUNCTION

    NDRAIN

    • OUTPUT
    • BYTES
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    PAUSE

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    PLAY

    • OUTPUT
    • BYTES
    • &OPTIONAL
    • COUNT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    PLAY-DIRECTLY

    • OUTPUT
    • BUFFER
    • BYTES
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    PLAYBACK-FORMAT

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    RESUME

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    START

    • OUTPUT
    • &KEY
    • RATE
    • CHANNELS
    • ENCODING
    • &REST

    Source

    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

  • EXTERNAL FUNCTION

    STOP

    • OUTPUT
    • &REST

    Source

    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

  • EXTERNAL GENERIC-FUNCTION

    BYTES

    • CONDITION
    • &REST

    No documentation provided.
  • EXTERNAL GENERIC-FUNCTION

    CHANNELS

    • CONDITION
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    CONNECTED

    • OBJECT
    • &REST

    Returns T if the output is connected to a device.

  • EXTERNAL GENERIC-FUNCTION

    DEVICE

    • CONDITION
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    DEVICE-BUFFER

    • OBJECT
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    DRIVER

    • CONDITION
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    ENCODING

    • CONDITION
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    ERROR-STRING

    • CONDITION
    • &REST

    Returns the error string from the out123 library for the error we encountered.
    
    See ERROR-STRING-ERROR

  • EXTERNAL GENERIC-FUNCTION

    GAIN

    • OBJECT
    • &REST

    Returns an integer representing the output device gain. This is driver-specific.
    
    Can be set as an initarg on the output.
    
    See OUTPUT

  • EXTERNAL GENERIC-FUNCTION

    HANDLE

    • OBJECT
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    NAME

    • OBJECT
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    OUTPUT

    • CONDITION
    • &REST

    Returns the output object associated with the condition.
    
    See OUTPUT-ERROR

  • EXTERNAL GENERIC-FUNCTION

    OUTPUT-TO

    • OBJECT
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    PLAYING

    • OBJECT
    • &REST

    Returns T if the output is currently playing audio.

  • EXTERNAL GENERIC-FUNCTION

    PRELOAD

    • OBJECT
    • &REST

    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

  • EXTERNAL GENERIC-FUNCTION

    RATE

    • CONDITION
    • &REST

    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

  • EXTERNAL MACRO

    WITH-PLAYBACK

    • OUTPUT
    • &KEY
    • RATE
    • CHANNELS
    • ENCODING
    • &REST
    • &BODY
    • BODY
    • &REST

    Source

    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