Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-out123 Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Thu Sep 15 04:02:46 2022 GMT+0.
Next: Systems, Previous: The cl-out123 Reference Manual, Up: The cl-out123 Reference Manual [Contents][Index]
This is a bindings library to libout123 which allows easy cross-platform audio playback.
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.
Next: Files, Previous: Introduction, Up: The cl-out123 Reference Manual [Contents][Index]
The main system appears first, followed by any subsystem dependency.
Bindings to libout123, providing cross-platform audio output.
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(GIT https://github.com/Shirakumo/cl-out123.git)
zlib
1.0.0
Next: Packages, Previous: Systems, Up: The cl-out123 Reference Manual [Contents][Index]
Files are sorted by type and then listed depth-first from the systems components trees.
Next: cl-out123/package.lisp, Previous: Lisp, Up: Lisp [Contents][Index]
cl-out123 (system).
Next: cl-out123/toolkit.lisp, Previous: cl-out123/cl-out123.asd, Up: Lisp [Contents][Index]
cl-out123 (system).
Next: cl-out123/conditions.lisp, Previous: cl-out123/package.lisp, Up: Lisp [Contents][Index]
package.lisp (file).
cl-out123 (system).
device-default-name (function).
Next: cl-out123/low-level.lisp, Previous: cl-out123/toolkit.lisp, Up: Lisp [Contents][Index]
toolkit.lisp (file).
cl-out123 (system).
Next: cl-out123/wrapper.lisp, Previous: cl-out123/conditions.lisp, Up: Lisp [Contents][Index]
conditions.lisp (file).
cl-out123 (system).
Next: cl-out123/documentation.lisp, Previous: cl-out123/low-level.lisp, Up: Lisp [Contents][Index]
low-level.lisp (file).
cl-out123 (system).
Previous: cl-out123/wrapper.lisp, Up: Lisp [Contents][Index]
wrapper.lisp (file).
cl-out123 (system).
Next: Definitions, Previous: Files, Up: The cl-out123 Reference Manual [Contents][Index]
Packages are listed by definition order.
org.shirakumo.fraf.out123.cffi
Previous: cl-out123-cffi, Up: Packages [Contents][Index]
org.shirakumo.fraf.out123
Next: Indexes, Previous: Packages, Up: The cl-out123 Reference Manual [Contents][Index]
Definitions are sorted by export status, category, package, and then by lexicographic order.
Next: Internals, Previous: Definitions, Up: Definitions [Contents][Index]
Next: Macros, Previous: Public Interface, Up: Public Interface [Contents][Index]
Variable containing a pathname to the static directory.
Next: Ordinary functions, Previous: Special variables, Up: Public Interface [Contents][Index]
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
Next: Generic functions, Previous: Macros, Up: Public Interface [Contents][Index]
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
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
Attempts to return a somewhat sensible name to use for our application.
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
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
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
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
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
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
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.
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
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
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
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
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
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
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
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
Next: Standalone methods, Previous: Ordinary functions, Up: Public Interface [Contents][Index]
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
automatically generated reader method
Returns T if the output is connected to a device.
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
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
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
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
automatically generated reader method
Returns the error string from the out123 library for the error we encountered.
See ERROR-STRING-ERROR
Returns an integer representing the output device gain. This is driver-specific.
Can be set as an initarg on the output.
See OUTPUT
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
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
Returns the output object associated with the condition.
See OUTPUT-ERROR
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
Returns T if the output is currently playing audio.
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
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
Next: Conditions, Previous: Generic functions, Up: Public Interface [Contents][Index]
Next: Classes, Previous: Standalone methods, Up: Public Interface [Contents][Index]
Condition signalled if an attempt is made to connect again while the output is still connected.
See OUTPUT-ERROR
Condition signalled if the setting of the background buffer fails.
See ERROR-STRING-ERROR
See BYTES
Condition signalled if the connection of an output to its device fails.
See ERROR-STRING-ERROR
See DRIVER
See DEVICE
Condition signalled in the case the allocation of the output handler fails.
See OUTPUT-ERROR
Error condition superclass for errors that have an error-string from the out123 library.
See ERROR-STRING
See OUTPUT-ERROR
common-lisp.
:error
This slot is read-only.
Condition signalled if the listing of available drivers fails for some reason.
See OUTPUT-ERROR
Condition signalled if the listing of available formats fails for some reason.
See OUTPUT-ERROR
Condition signalled if an operation is attempted that requires the output to be connected, but it isn’t.
See OUTPUT-ERROR
Error condition superclass for all errors related to this library.
See OUTPUT
error.
Condition signalled if the playback of a buffer fails.
See ERROR-STRING-ERROR
See BYTES
Condition signalled if starting the device fails.
See ERROR-STRING-ERROR
See RATE
See CHANNELS
See ENCODING
Previous: Conditions, Up: Public Interface [Contents][Index]
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
| Initarg | Value |
|---|---|
| :driver | nil |
| :device | nil |
| :rate | 44100 |
| :channels | 2 |
| :encoding | int16 |
| :output-to | nil |
| :preload | t |
| :gain | nil |
| :device-buffer | t |
| :name | (device-default-name) |
:device-buffer
This slot is read-only.
(cons (bordeaux-threads:current-thread) nil)
This slot is read-only.
(bordeaux-threads:make-lock "output lock")
This slot is read-only.
Previous: Public Interface, Up: Definitions [Contents][Index]
Variable containing the path to this very file, hopefully.
Next: Ordinary functions, Previous: Special variables, Up: Internals [Contents][Index]
Checks the result of FORM against an error and if found, signals a condition according to the spec.
Same as CFFI:WITH-FOREIGN-OBJECTS, but resolves the bindings at the end and returns them as values.
Signals a simple-error if the result of FORM is an error.
See WITH-ERROR
Next: Generic functions, Previous: Macros, Up: Internals [Contents][Index]
Signals an error if the output is not connected.
See OUTPUT
See CONNECTED
See NOT-CONNECTED
Decodes the ORed together encodings into a list of keywords.
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
Previous: Ordinary functions, Up: Internals [Contents][Index]
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
Previous: Definitions, Up: The cl-out123 Reference Manual [Contents][Index]
| Jump to: | (
B C D E F G H M N O P R S W |
|---|
| Jump to: | (
B C D E F G H M N O P R S W |
|---|
Next: Data types, Previous: Functions, Up: Indexes [Contents][Index]
| Jump to: | *
B C D E F G H N O P R S |
|---|
| Jump to: | *
B C D E F G H N O P R S |
|---|
| Jump to: | A B C D E F H L N O P S T W |
|---|
| Jump to: | A B C D E F H L N O P S T W |
|---|