Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the cl-out123 Reference Manual, version 1.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Dec 22 12:37:57 2020 GMT+0.
• Introduction | What cl-out123 is all about | |
• Systems | The systems documentation | |
• Files | The files documentation | |
• Packages | The packages documentation | |
• Definitions | The symbols documentation | |
• Indexes | Concepts, functions, variables and data types |
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 pause
d, resume
d, and stop
ped. Currently buffered data can be drop
ped, or drain
ed 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: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
• The cl-out123 system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shirakumo/cl-out123.git")
zlib
Bindings to libout123, providing cross-platform audio output.
1.0.0
cl-out123.asd (file)
Files are sorted by type and then listed depth-first from the systems components trees.
• Lisp files |
Next: The cl-out123/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
cl-out123.asd
cl-out123 (system)
Next: The cl-out123/toolkit․lisp file, Previous: The cl-out123․asd file, Up: Lisp files [Contents][Index]
cl-out123 (system)
package.lisp
Next: The cl-out123/conditions․lisp file, Previous: The cl-out123/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
cl-out123 (system)
toolkit.lisp
device-default-name (function)
Next: The cl-out123/low-level․lisp file, Previous: The cl-out123/toolkit․lisp file, Up: Lisp files [Contents][Index]
toolkit.lisp (file)
cl-out123 (system)
conditions.lisp
Next: The cl-out123/wrapper․lisp file, Previous: The cl-out123/conditions․lisp file, Up: Lisp files [Contents][Index]
conditions.lisp (file)
cl-out123 (system)
low-level.lisp
Next: The cl-out123/documentation․lisp file, Previous: The cl-out123/low-level․lisp file, Up: Lisp files [Contents][Index]
low-level.lisp (file)
cl-out123 (system)
wrapper.lisp
Previous: The cl-out123/wrapper․lisp file, Up: Lisp files [Contents][Index]
wrapper.lisp (file)
cl-out123 (system)
documentation.lisp
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
• The cl-out123 package | ||
• The cl-out123-cffi package |
Next: The cl-out123-cffi package, Previous: Packages, Up: Packages [Contents][Index]
package.lisp (file)
org.shirakumo.fraf.out123
Previous: The cl-out123 package, Up: Packages [Contents][Index]
package.lisp (file)
org.shirakumo.fraf.out123.cffi
Definitions are sorted by export status, category, package, and then by lexicographic order.
• Exported definitions | ||
• Internal definitions |
Next: Internal definitions, Previous: Definitions, Up: Definitions [Contents][Index]
• Exported special variables | ||
• Exported macros | ||
• Exported functions | ||
• Exported generic functions | ||
• Exported conditions | ||
• Exported classes |
Next: Exported macros, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Variable containing a pathname to the static directory.
low-level.lisp (file)
Next: Exported functions, Previous: Exported special variables, Up: Exported definitions [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
wrapper.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [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
wrapper.lisp (file)
(setf buffered) (function)
wrapper.lisp (file)
buffered (function)
low-level.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
Attempts to return a somewhat sensible name to use for our application.
toolkit.lisp (file)
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
wrapper.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
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.
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
wrapper.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
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
wrapper.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
low-level.lisp (file)
Next: Exported conditions, Previous: Exported functions, Up: Exported definitions [Contents][Index]
conditions.lisp (file)
conditions.lisp (file)
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
wrapper.lisp (file)
conditions.lisp (file)
Returns T if the output is connected to a device.
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
conditions.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
conditions.lisp (file)
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
wrapper.lisp (file)
conditions.lisp (file)
Returns the error string from the out123 library for the error we encountered.
See ERROR-STRING-ERROR
conditions.lisp (file)
Returns an integer representing the output device gain. This is driver-specific.
Can be set as an initarg on the output.
See OUTPUT
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
Returns the output object associated with the condition.
See OUTPUT-ERROR
conditions.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
Returns T if the output is currently playing audio.
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
conditions.lisp (file)
Next: Exported classes, Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
Condition signalled if an attempt is made to connect again while the output is still connected.
See OUTPUT-ERROR
conditions.lisp (file)
output-error (condition)
Condition signalled if the setting of the background buffer fails.
See ERROR-STRING-ERROR
See BYTES
conditions.lisp (file)
error-string-error (condition)
bytes (method)
:bytes
bytes (generic function)
Condition signalled if the connection of an output to its device fails.
See ERROR-STRING-ERROR
See DRIVER
See DEVICE
conditions.lisp (file)
error-string-error (condition)
:driver
driver (generic function)
:device
device (generic function)
Condition signalled in the case the allocation of the output handler fails.
See OUTPUT-ERROR
conditions.lisp (file)
output-error (condition)
Error condition superclass for errors that have an error-string from the out123 library.
See ERROR-STRING
See OUTPUT-ERROR
conditions.lisp (file)
output-error (condition)
error-string (method)
:error
error-string (generic function)
conditions.lisp (file)
output-error (condition)
Condition signalled if the listing of available drivers fails for some reason.
See OUTPUT-ERROR
conditions.lisp (file)
output-error (condition)
Condition signalled if the listing of available formats fails for some reason.
See OUTPUT-ERROR
conditions.lisp (file)
output-error (condition)
conditions.lisp (file)
output-error (condition)
Condition signalled if an operation is attempted that requires the output to be connected, but it isn’t.
See OUTPUT-ERROR
conditions.lisp (file)
output-error (condition)
Error condition superclass for all errors related to this library.
See OUTPUT
conditions.lisp (file)
error (condition)
output (method)
:output
output (generic function)
Condition signalled if the playback of a buffer fails.
See ERROR-STRING-ERROR
See BYTES
conditions.lisp (file)
error-string-error (condition)
bytes (method)
:bytes
bytes (generic function)
Condition signalled if starting the device fails.
See ERROR-STRING-ERROR
See RATE
See CHANNELS
See ENCODING
conditions.lisp (file)
error-string-error (condition)
:rate
rate (generic function)
:channels
channels (generic function)
:encoding
encoding (generic function)
Previous: Exported conditions, Up: Exported definitions [Contents][Index]
low-level.lisp (file)
low-level.lisp (file)
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
wrapper.lisp (file)
standard-object (class)
handle (generic function)
playing (generic function)
set-playing (generic function)
connected (generic function)
set-connected (generic function)
:driver
driver (generic function)
:device
device (generic function)
:rate
rate (generic function)
:channels
channels (generic function)
:encoding
encoding (generic function)
framesize (generic function)
:output-to
output-to (generic function)
:preload
preload (generic function)
:gain
gain (generic function)
:device-buffer
device-buffer (generic function)
:name
name (generic function)
(cons (bordeaux-threads:current-thread) nil)
cthread (generic function)
(bordeaux-threads:make-lock "output lock")
playback-lock (generic function)
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) |
Previous: Exported definitions, Up: Definitions [Contents][Index]
• Internal special variables | ||
• Internal macros | ||
• Internal functions | ||
• Internal generic functions |
Next: Internal macros, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
Variable containing the path to this very file, hopefully.
low-level.lisp (file)
Next: Internal functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Checks the result of FORM against an error and if found, signals a condition according to the spec.
toolkit.lisp (file)
Same as CFFI:WITH-FOREIGN-OBJECTS, but resolves the bindings at the end and returns them as values.
toolkit.lisp (file)
Signals a simple-error if the result of FORM is an error.
See WITH-ERROR
toolkit.lisp (file)
Next: Internal generic functions, Previous: Internal macros, Up: Internal definitions [Contents][Index]
Signals an error if the output is not connected.
See OUTPUT
See CONNECTED
See NOT-CONNECTED
wrapper.lisp (file)
Decodes the ORed together encodings into a list of keywords.
wrapper.lisp (file)
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
wrapper.lisp (file)
low-level.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
automatically generated reader method
wrapper.lisp (file)
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
automatically generated reader method
wrapper.lisp (file)
automatically generated reader method
wrapper.lisp (file)
automatically generated writer method
wrapper.lisp (file)
automatically generated writer method
wrapper.lisp (file)
Previous: Definitions, Up: Top [Contents][Index]
• Concept index | ||
• Function index | ||
• Variable index | ||
• Data type index |
Next: Function index, Previous: Indexes, Up: Indexes [Contents][Index]
Jump to: | C F L |
---|
Jump to: | C F L |
---|
Next: Variable index, Previous: Concept index, Up: Indexes [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 type index, Previous: Function index, 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 |
---|
Previous: Variable index, Up: Indexes [Contents][Index]
Jump to: | A B C E F H N O P S |
---|
Jump to: | A B C E F H N O P S |
---|