The cl-out123 Reference Manual

Table of Contents

The cl-out123 Reference Manual

This is the cl-out123 Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Sun May 15 04:03:08 2022 GMT+0.

1 Introduction

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.

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 cl-out123

Maintainer

Nicolas Hafner <shinmera@tymoon.eu>

Author

Nicolas Hafner <shinmera@tymoon.eu>

Home Page

https://Shirakumo.github.io/cl-out123/

Source Control

(:git "https://github.com/shirakumo/cl-out123.git")

Bug Tracker

https://github.com/Shirakumo/cl-out123/issues

License

zlib

Description

Bindings to libout123, providing cross-platform audio output.

Version

1.0.0

Dependencies

• cffi
• trivial-features
• trivial-garbage
• documentation-utils
• bordeaux-threads

Source

cl-out123.asd (file)

Components

• package.lisp (file)
• toolkit.lisp (file)
• conditions.lisp (file)
• low-level.lisp (file)
• wrapper.lisp (file)
• documentation.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 cl-out123.asd

Location

cl-out123.asd

Systems

cl-out123 (system)

3.1.2 cl-out123/package.lisp

Parent

cl-out123 (system)

Location

package.lisp

Packages

• cl-out123
• cl-out123-cffi

3.1.3 cl-out123/toolkit.lisp

Dependency

package.lisp (file)

Parent

cl-out123 (system)

Location

toolkit.lisp

Exported Definitions

device-default-name (function)

Internal Definitions

• with-error (macro)
• with-foreign-values (macro)
• with-generic-error (macro)

3.1.4 cl-out123/conditions.lisp

Dependency

toolkit.lisp (file)

Parent

cl-out123 (system)

Location

conditions.lisp

Exported Definitions

• already-connected (condition)
• buffer-set-failed (condition)
• bytes (method)
• bytes (method)
• channels (method)
• connection-failed (condition)
• creation-failure (condition)
• device (method)
• driver (method)
• encoding (method)
• error-string (method)
• error-string-error (condition)
• failed-driver-info (condition)
• failed-driver-listing (condition)
• failed-format-listing (condition)
• failed-playback-format (condition)
• not-connected (condition)
• output (method)
• output-error (condition)
• playback-failed (condition)
• rate (method)
• start-failed (condition)

3.1.5 cl-out123/low-level.lisp

Dependency

conditions.lisp (file)

Parent

cl-out123 (system)

Location

low-level.lisp

Exported Definitions

• *static* (special variable)
• buffered (function)
• close (function)
• continue (function)
• del (function)
• drain (function)
• driver-info (function)
• drivers (function)
• drop (function)
• enc-byname (function)
• enc-list (function)
• enc-longname (function)
• enc-name (function)
• encodings (function)
• encsize (function)
• errcode (function)
• fmt (class)
• fmt-channels (function)
• (setf fmt-channels) (function)
• fmt-encoding (function)
• (setf fmt-encoding) (function)
• fmt-rate (function)
• (setf fmt-rate) (function)
• formats (function)
• getformat (function)
• getparam (function)
• getparam-float (function)
• getparam-int (function)
• getparam-string (function)
• handle (class)
• ndrain (function)
• new (function)
• open (function)
• param (function)
• param-float (function)
• param-from (function)
• param-int (function)
• param-string (function)
• pause (function)
• plain-strerror (function)
• play (function)
• set-buffer (function)
• start (function)
• stop (function)
• strerror (function)

Internal Definitions

• *here* (special variable)
• samplesize (function)

3.1.6 cl-out123/wrapper.lisp

Dependency

low-level.lisp (file)

Parent

cl-out123 (system)

Location

wrapper.lisp

Exported Definitions

• buffered (function)
• (setf buffered) (function)
• channels (method)
• connect (function)
• connected (method)
• device (method)
• device-buffer (method)
• disconnect (function)
• drain (function)
• driver (method)
• driver-info (function)
• drivers (function)
• drop (function)
• encoding (method)
• encodings (function)
• formats (function)
• gain (method)
• handle (method)
• make-output (function)
• name (method)
• ndrain (function)
• output (class)
• output-to (method)
• pause (function)
• play (function)
• play-directly (function)
• playback-format (function)
• playing (method)
• preload (method)
• rate (method)
• resume (function)
• start (function)
• stop (function)
• with-playback (macro)

Internal Definitions

• check-connected (function)
• cthread (method)
• decode-encodings (function)
• dispose-handle (function)
• framesize (method)
• playback-lock (method)
• set-connected (method)
• set-playing (method)

3.1.7 cl-out123/documentation.lisp

Dependency

wrapper.lisp (file)

Parent

cl-out123 (system)

Location

documentation.lisp

4 Packages

Packages are listed by definition order.

4.1 cl-out123

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.out123

Use List

• cffi
• common-lisp

Exported Definitions

• already-connected (condition)
• buffer-set-failed (condition)
• buffered (function)
• (setf buffered) (function)
• bytes (generic function)
• bytes (method)
• bytes (method)
• channels (generic function)
• channels (method)
• channels (method)
• connect (function)
• connected (generic function)
• connected (method)
• connection-failed (condition)
• creation-failure (condition)
• device (generic function)
• device (method)
• device (method)
• device-buffer (generic function)
• device-buffer (method)
• device-default-name (function)
• disconnect (function)
• drain (function)
• driver (generic function)
• driver (method)
• driver (method)
• driver-info (function)
• drivers (function)
• drop (function)
• encoding (generic function)
• encoding (method)
• encoding (method)
• encodings (function)
• error-string (generic function)
• error-string (method)
• error-string-error (condition)
• failed-driver-info (condition)
• failed-driver-listing (condition)
• failed-format-listing (condition)
• failed-playback-format (condition)
• formats (function)
• gain (generic function)
• gain (method)
• handle (generic function)
• handle (method)
• make-output (function)
• name (generic function)
• name (method)
• ndrain (function)
• not-connected (condition)
• output (generic function)
• output (method)
• output (class)
• output-error (condition)
• output-to (generic function)
• output-to (method)
• pause (function)
• play (function)
• play-directly (function)
• playback-failed (condition)
• playback-format (function)
• playing (generic function)
• playing (method)
• preload (generic function)
• preload (method)
• rate (generic function)
• rate (method)
• rate (method)
• resume (function)
• start (function)
• start-failed (condition)
• stop (function)
• with-playback (macro)

Internal Definitions

• check-connected (function)
• cthread (generic function)
• cthread (method)
• decode-encodings (function)
• dispose-handle (function)
• framesize (generic function)
• framesize (method)
• playback-lock (generic function)
• playback-lock (method)
• set-connected (generic function)
• set-connected (method)
• set-playing (generic function)
• set-playing (method)
• with-error (macro)
• with-foreign-values (macro)
• with-generic-error (macro)

4.2 cl-out123-cffi

Source

package.lisp (file)

Nickname

org.shirakumo.fraf.out123.cffi

Use List

• cffi
• common-lisp

Exported Definitions

• *static* (special variable)
• buffered (function)
• close (function)
• continue (function)
• del (function)
• drain (function)
• driver-info (function)
• drivers (function)
• drop (function)
• enc-byname (function)
• enc-list (function)
• enc-longname (function)
• enc-name (function)
• encodings (function)
• encsize (function)
• errcode (function)
• fmt (class)
• fmt-channels (function)
• (setf fmt-channels) (function)
• fmt-encoding (function)
• (setf fmt-encoding) (function)
• fmt-rate (function)
• (setf fmt-rate) (function)
• formats (function)
• getformat (function)
• getparam (function)
• getparam-float (function)
• getparam-int (function)
• getparam-string (function)
• handle (class)
• ndrain (function)
• new (function)
• open (function)
• param (function)
• param-float (function)
• param-from (function)
• param-int (function)
• param-string (function)
• pause (function)
• plain-strerror (function)
• play (function)
• set-buffer (function)
• start (function)
• stop (function)
• strerror (function)

Internal Definitions

• *here* (special variable)
• samplesize (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Exported definitions

5.1.1 Special variables

Special Variable: *static*

Variable containing a pathname to the static directory.

Package

cl-out123-cffi

Source

low-level.lisp (file)

5.1.2 Macros

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

Package

cl-out123

Source

wrapper.lisp (file)

5.1.3 Functions

Function: 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

Package

cl-out123

Source

wrapper.lisp (file)

Writer

(setf buffered) (function)

Function: (setf buffered) BYTES OUTPUT

Package

cl-out123

Source

wrapper.lisp (file)

Reader

buffered (function)

Function: buffered HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: close HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: connect OUTPUT &key DRIVER DEVICE

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: continue HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: del HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: device-default-name &optional IDENT

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

Package

cl-out123

Source

toolkit.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: drain HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: driver-info HANDLE DRIVER DEVICE

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: drivers HANDLE NAMES DESCR

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: drop HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: enc-byname NAME

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: enc-list ENCLIST

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: enc-longname ENCODING

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: enc-name ENCODING

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: encodings HANDLE RATE CHANNELS

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: encsize ENCODING

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: errcode HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: fmt-channels POINTER-TO-FMT

Function: (setf fmt-channels) VALUE POINTER-TO-FMT

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: fmt-encoding POINTER-TO-FMT

Function: (setf fmt-encoding) VALUE POINTER-TO-FMT

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: fmt-rate POINTER-TO-FMT

Function: (setf fmt-rate) VALUE POINTER-TO-FMT

Package

cl-out123-cffi

Source

low-level.lisp (file)

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.

Package

cl-out123

Source

wrapper.lisp (file)

Function: formats HANDLE RATES RATECOUNT MINCHANNELS MAXCHANNELS FMTLIST

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: getformat HANDLE RATE CHANNELS ENCODING FRAMESIZE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: getparam HANDLE CODE RET-VALUE RET-FVALUE RET-SVALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: getparam-float HANDLE CODE VALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: getparam-int HANDLE CODE VALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: getparam-string HANDLE CODE VALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: make-output DRIVER &rest ARGS &key &allow-other-keys

Package

cl-out123

Source

wrapper.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: ndrain HANDLE BYTES

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: new ()

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: open HANDLE DRIVER DEVICE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: param HANDLE CODE VALUE FVALUE SVALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: param-float HANDLE CODE VALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: param-from HANDLE HANDLE-FROM

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: param-int HANDLE CODE VALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: param-string HANDLE CODE VALUE

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: pause HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: plain-strerror ERRCODE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: play OUTPUT BYTES &optional COUNT

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: play HANDLE BUFFER BYTES

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: set-buffer HANDLE BUFFER-BYTES

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: start OUTPUT &key RATE CHANNELS ENCODING

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: start HANDLE RATE CHANNELS ENCODING

Package

cl-out123-cffi

Source

low-level.lisp (file)

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

Package

cl-out123

Source

wrapper.lisp (file)

Function: stop HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

Function: strerror HANDLE

Package

cl-out123-cffi

Source

low-level.lisp (file)

5.1.4 Generic functions

Generic Function: bytes CONDITION

Package

cl-out123

Methods

Method: bytes (CONDITION buffer-set-failed)

Source

conditions.lisp (file)

Method: bytes (CONDITION playback-failed)

Source

conditions.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: channels (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Method: channels (CONDITION start-failed)

Source

conditions.lisp (file)

Generic Function: connected OBJECT

Returns T if the output is connected to a device.

Package

cl-out123

Methods

Method: connected (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: device (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Method: device (CONDITION connection-failed)

Source

conditions.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: device-buffer (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: driver (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Method: driver (CONDITION connection-failed)

Source

conditions.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: encoding (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Method: encoding (CONDITION start-failed)

Source

conditions.lisp (file)

Generic Function: error-string CONDITION

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

See ERROR-STRING-ERROR

Package

cl-out123

Methods

Method: error-string (CONDITION error-string-error)

Source

conditions.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: gain (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: handle (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: name (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: output CONDITION

Returns the output object associated with the condition.

See OUTPUT-ERROR

Package

cl-out123

Methods

Method: output (CONDITION output-error)

Source

conditions.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: output-to (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: playing OBJECT

Returns T if the output is currently playing audio.

Package

cl-out123

Methods

Method: playing (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: preload (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: 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

Package

cl-out123

Methods

Method: rate (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Method: rate (CONDITION start-failed)

Source

conditions.lisp (file)

5.1.5 Conditions

Condition: already-connected ()

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

See OUTPUT-ERROR

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: buffer-set-failed ()

Condition signalled if the setting of the background buffer fails.

See ERROR-STRING-ERROR
See BYTES

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

error-string-error (condition)

Direct methods

bytes (method)

Direct slots

Slot: bytes

Initargs

:bytes

Readers

bytes (generic function)

Condition: connection-failed ()

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

See ERROR-STRING-ERROR
See DRIVER
See DEVICE

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

error-string-error (condition)

Direct methods

• device (method)
• driver (method)

Direct slots

Slot: driver

Initargs

:driver

Readers

driver (generic function)

Slot: device

Initargs

:device

Readers

device (generic function)

Condition: creation-failure ()

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

See OUTPUT-ERROR

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: error-string-error ()

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

See ERROR-STRING
See OUTPUT-ERROR

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Direct subclasses

• connection-failed (condition)
• start-failed (condition)
• playback-failed (condition)
• buffer-set-failed (condition)

Direct methods

error-string (method)

Direct slots

Slot: error

Initargs

:error

Readers

error-string (generic function)

Condition: failed-driver-info ()

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: failed-driver-listing ()

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

See OUTPUT-ERROR

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: failed-format-listing ()

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

See OUTPUT-ERROR

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: failed-playback-format ()

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: not-connected ()

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

See OUTPUT-ERROR

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

output-error (condition)

Condition: output-error ()

Error condition superclass for all errors related to this library.

See OUTPUT

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

error (condition)

Direct subclasses

• creation-failure (condition)
• not-connected (condition)
• failed-driver-listing (condition)
• failed-driver-info (condition)
• failed-format-listing (condition)
• failed-playback-format (condition)
• already-connected (condition)
• error-string-error (condition)

Direct methods

output (method)

Direct slots

Slot: output

Initargs

:output

Readers

output (generic function)

Condition: playback-failed ()

Condition signalled if the playback of a buffer fails.

See ERROR-STRING-ERROR
See BYTES

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

error-string-error (condition)

Direct methods

bytes (method)

Direct slots

Slot: bytes

Initargs

:bytes

Readers

bytes (generic function)

Condition: start-failed ()

Condition signalled if starting the device fails.

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

Package

cl-out123

Source

conditions.lisp (file)

Direct superclasses

error-string-error (condition)

Direct methods

• encoding (method)
• channels (method)
• rate (method)

Direct slots

Slot: rate

Initargs

:rate

Readers

rate (generic function)

Slot: channels

Initargs

:channels

Readers

channels (generic function)

Slot: encoding

Initargs

:encoding

Readers

encoding (generic function)

5.1.6 Classes

Class: fmt ()

Package

cl-out123-cffi

Source

low-level.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

Class: handle ()

Package

cl-out123-cffi

Source

low-level.lisp (file)

Direct superclasses

• translatable-foreign-type (class)
• foreign-struct-type (class)

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

Package

cl-out123

Source

wrapper.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

• reinitialize-instance (method)
• shared-initialize (method)
• print-object (method)
• playback-lock (method)
• cthread (method)
• name (method)
• device-buffer (method)
• gain (method)
• preload (method)
• output-to (method)
• framesize (method)
• encoding (method)
• channels (method)
• rate (method)
• device (method)
• driver (method)
• set-connected (method)
• connected (method)
• set-playing (method)
• playing (method)
• handle (method)

Direct slots

Slot: handle

Readers

handle (generic function)

Slot: playing

Readers

playing (generic function)

Writers

set-playing (generic function)

Slot: connected

Readers

connected (generic function)

Writers

set-connected (generic function)

Slot: driver

Initargs

:driver

Readers

driver (generic function)

Slot: device

Initargs

:device

Readers

device (generic function)

Slot: rate

Initargs

:rate

Readers

rate (generic function)

Slot: channels

Initargs

:channels

Readers

channels (generic function)

Slot: encoding

Initargs

:encoding

Readers

encoding (generic function)

Slot: framesize

Readers

framesize (generic function)

Slot: output-to

Initargs

:output-to

Readers

output-to (generic function)

Slot: preload

Initargs

:preload

Readers

preload (generic function)

Slot: gain

Initargs

:gain

Readers

gain (generic function)

Slot: device-buffer

Initargs

:device-buffer

Readers

device-buffer (generic function)

Slot: name

Initargs

:name

Readers

name (generic function)

Slot: cthread

Initform

(cons (bordeaux-threads:current-thread) nil)

Readers

cthread (generic function)

Slot: playback-lock

Initform

(bordeaux-threads:make-lock "output lock")

Readers

playback-lock (generic function)

Direct Default Initargs

Initarg	Value
:driver	nil
:device	nil
:rate	44100
:channels	2
:encoding	:int16
:output-to	nil
:preload	t
:gain	nil
:device-buffer	t
:name	(cl-out123:device-default-name)

5.2 Internal definitions

5.2.1 Special variables

Special Variable: *here*

Variable containing the path to this very file, hopefully.

Package

cl-out123-cffi

Source

low-level.lisp (file)

5.2.2 Macros

Macro: with-error (ERR DATUM &rest DATUM-ARGS) &body FORM

Checks the result of FORM against an error and if found, signals a condition according to the spec.

Package

cl-out123

Source

toolkit.lisp (file)

Macro: with-foreign-values BINDINGS &body BODY

Same as CFFI:WITH-FOREIGN-OBJECTS, but resolves the bindings at the end and returns them as values.

Package

cl-out123

Source

toolkit.lisp (file)

Macro: with-generic-error FORM

Signals a simple-error if the result of FORM is an error.

See WITH-ERROR

Package

cl-out123

Source

toolkit.lisp (file)

5.2.3 Functions

Function: check-connected OUTPUT

Signals an error if the output is not connected.

See OUTPUT
See CONNECTED
See NOT-CONNECTED

Package

cl-out123

Source

wrapper.lisp (file)

Function: decode-encodings ENCS

Decodes the ORed together encodings into a list of keywords.

Package

cl-out123

Source

wrapper.lisp (file)

Function: dispose-handle HANDLE THREAD &key DELETE

Properly disposes of the handle as quickly as possible.

Performs three steps if the handle is not a null-pointer:
Output is drained by DRAIN, the handle is CLOSEd, and finally DELeted.

See CL-OUT123-CFFI:DRAIN
See CL-OUT123-CFFI:CLOSE
See CL-OUT123-CFFI:DEL

Package

cl-out123

Source

wrapper.lisp (file)

Function: samplesize ENC

Package

cl-out123-cffi

Source

low-level.lisp (file)

5.2.4 Generic functions

Generic Function: cthread OBJECT

Package

cl-out123

Methods

Method: cthread (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: framesize OBJECT

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

This is determined automatically by the backend once the output has STARTed.

See OUTPUT
See START

Package

cl-out123

Methods

Method: framesize (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: playback-lock OBJECT

Package

cl-out123

Methods

Method: playback-lock (OUTPUT output)

automatically generated reader method

Source

wrapper.lisp (file)

Generic Function: set-connected NEW-VALUE OBJECT

Package

cl-out123

Methods

Method: set-connected NEW-VALUE (OUTPUT output)

automatically generated writer method

Source

wrapper.lisp (file)

Generic Function: set-playing NEW-VALUE OBJECT

Package

cl-out123

Methods

Method: set-playing NEW-VALUE (OUTPUT output)

automatically generated writer method

Source

wrapper.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables