This is the cl-portaudio Reference Manual, version 1.0.0, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 15:34:50 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
cl-portaudioThis package contains bindings to @a[http://portaudio.com/]{PortAudio}. PortAudio is a free, cross-platform, open-source, audio I/O library.
Michael Filonenko <filonenko.mikhail@gmail.com>
MIT
1.0.0
cffi (system).
ffa (system).
src (module).
Modules are listed depth-first from the system components tree.
cl-portaudio/srccl-portaudio (system).
package.lisp (file).
portaudio.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
cl-portaudio/src/portaudio.lisppackage.lisp (file).
src (module).
abort-stream (function).
close-stream (function).
device-info (class).
device-info-default-high-input-latency (generic reader).
device-info-default-high-output-latency (generic reader).
device-info-default-low-input-latency (generic reader).
device-info-default-low-output-latency (generic reader).
device-info-default-sample-rate (generic reader).
device-info-host-api (generic reader).
device-info-max-input-channels (generic reader).
device-info-max-output-channels (generic reader).
device-info-name (generic reader).
free-translated-object (method).
get-default-host-api (function).
get-default-input-device (function).
get-default-output-device (function).
get-device-count (function).
get-device-info (function).
get-host-api-count (function).
get-host-api-info (function).
get-sample-size (function).
get-stream-info (function).
get-stream-read-available (function).
get-stream-time (function).
get-stream-write-available (function).
get-version (function).
get-version-text (function).
host-api-device-index-to-device-index (function).
host-api-info (class).
host-api-info-default-input-device (generic reader).
host-api-info-default-output-device (generic reader).
host-api-info-device-count (generic reader).
host-api-info-name (generic reader).
host-api-info-type (generic reader).
host-api-type-id-to-host-api-index (function).
host-error-info (class).
host-error-info-error-code (generic reader).
host-error-info-error-text (generic reader).
host-error-info-host-api-type (generic reader).
initialize (function).
initialize-instance (method).
initialize-instance (method).
initialize-instance (method).
initialize-instance (method).
is-stream-active (function).
is-stream-stopped (function).
make-stream-parameters (function).
merge-channels-into-array (function).
open-default-stream (function).
open-stream (function).
pa-sleep (function).
pa-stream (class).
pa-stream-frames-per-buffer (generic reader).
pa-stream-input-channels (generic reader).
pa-stream-input-sample-format (generic reader).
pa-stream-output-channels (generic reader).
pa-stream-output-sample-format (generic reader).
print-devices (function).
read-stream (function).
read-stream-into-array (function).
separate-array-to-channels (function).
start-stream (function).
stream-info (class).
stream-info-input-latency (generic reader).
stream-info-output-latency (generic reader).
stream-info-sample-rate (generic reader).
stream-parameters (class).
stream-parameters-channel-count (generic reader).
(setf stream-parameters-channel-count) (writer method).
stream-parameters-device (generic reader).
(setf stream-parameters-device) (writer method).
stream-parameters-sample-format (generic reader).
(setf stream-parameters-sample-format) (writer method).
stream-parameters-suggested-latency (generic reader).
(setf stream-parameters-suggested-latency) (writer method).
terminate (function).
translate-from-foreign (method).
translate-from-foreign (method).
translate-from-foreign (method).
translate-from-foreign (method).
translate-from-foreign (method).
translate-to-foreign (method).
translate-to-foreign (method).
with-audio (macro).
with-audio-stream (macro).
with-default-audio-stream (macro).
write-stream (function).
%abort-stream (function).
%close-stream (function).
%get-default-host-api (function).
%get-default-input-device (function).
%get-default-output-device (function).
%get-device-count (function).
%get-device-info (function).
%get-error-text (function).
%get-host-api-count (function).
%get-host-api-info (function).
%get-last-host-error-info (function).
%get-sample-size (function).
%get-stream-info (function).
%get-stream-read-available (function).
%get-stream-time (function).
%get-stream-write-available (function).
%get-version (function).
%get-version-text (function).
%host-api-device-index-to-device-index (function).
%host-api-type-id-to-host-api-index (function).
%initialize (function).
%is-format-supported (function).
%is-stream-active (function).
%is-stream-stopped (function).
%open-default-stream (function).
%open-stream (function).
%pa-sleep (function).
%read-stream (function).
%start-stream (function).
%stop-stream (function).
%terminate (function).
%write-stream (function).
+format-is-supported+ (constant).
+frames-per-buffer-unspecified+ (constant).
+no-device+ (constant).
+use-host-api-specific-device-specification (constant).
cffi-type-to-lisp (function).
device-info-struct-version (reader method).
device-info-tclass (class).
get-last-host-error-info (function).
host-api-info-struct-version (reader method).
host-api-info-tclass (class).
host-error-info-tclass (class).
is-format-supported (function).
make-errors (macro).
p-device-info (class).
p-host-api-info (class).
p-host-error-info (class).
p-pa-stream (class).
p-stream-info (class).
p-stream-parameters (class).
pa-stream-handle (reader method).
(setf pa-stream-handle) (writer method).
print-supported-standard-sample-rates (function).
raise-if-error (function).
stop-stream (function).
stream-info-struct-version (reader method).
stream-info-tclass (class).
stream-parameters-tclass (class).
Packages are listed by definition order.
portaudioThis package contains bindings to @a[http://portaudio.com/]{PortAudio}. PortAudio is a free, cross-platform, open-source, audio I/O library.
Binary PortAudio packages can be founded here:
@a{http://planet.plt-scheme.org/display.ss?package=portaudio.plt&owner=clements} -> source browse -> directories lib
@begin[Installation and Usage]{section}
@begin{pre}
git clone –depth 1 https://github.com/filonenko-mikhail/cl-portaudio.git
emacs
M+x slime
(ql:quickload :cl-portaudio)
(ql:quickload :cl-portaudio-tests)
(portaudio-tests:test-read-write-echo)
@end{pre}
@end{section}
@begin[Example]{section}
@begin{pre}
(use-package :portaudio)
(defconstant +frames-per-buffer+ 1024)
(defconstant +sample-rate+ 44100d0)
(defconstant +seconds+ 15)
(defconstant +sample-format+ :float)
(defconstant +num-channels+ 2)
(defun test-read-write-converted-echo ()
"Record input into an array; Separate array to channels; Merge channels into array; Play last array."
(with-audio
(format t "~%=== Wire on. Will run ~D seconds . ===~%" +seconds+)
(with-default-audio-stream (astream +num-channels+ +num-channels+ :sample-format +sample-format+ :sample-rate +sample-rate+ :frames-per-buffer +frames-per-buffer+)
(dotimes (i (round (/ (* +seconds+ +sample-rate+) +frames-per-buffer+)))
(write-stream astream
(merge-channels-into-array astream
(separate-array-to-channels astream
(read-stream astream))))))))
@end{pre}
@aboutfun{with-audio}
@aboutfun{with-default-audio-stream}
@aboutfun{read-stream}
@aboutfun{separate-array-to-channels}
@aboutfun{merge-channels-into-array}
@aboutfun{write-stream}
@b{Note}
ignore-errors is used for ignoring output-underflowed error.
@end{section}
@begin[Introduction]{section}
PortAudio provides a uniform application programming interface (API) across all supported platforms. You can think of the PortAudio library as a wrapper that converts calls to the PortAudio API into calls to platform-specific native audio APIs. Operating systems often offer more than one native audio API and some APIs (such as JACK) may be available on multiple target operating systems. PortAudio supports all the major native audio APIs on each supported platform. The diagram below illustrates the relationship between your application, PortAudio, and the supported native audio APIs:
@a[./img/portaudio-external-architecture-diagram.png]{Image}
PortAudio provides a uniform interface to native audio APIs. However, it doesn’t always provide totally uniform functionality. There are cases where PortAudio is limited by the capabilities of the underlying native audio API. For example, PortAudio doesn’t provide sample rate conversion if you request a sample rate that is not supported by the native audio API. Another example is that the ASIO SDK only allows one device to be open at a time, so PortAudio/ASIO doesn’t currently support opening multiple ASIO devices simultaneously.
@end{section}
@begin[Key abstractions: Host APIs, Devices and Streams]{section}
The PortAudio processing model includes three main abstractions: Host APIs, audio Devices and audio Streams.
Host APIs represent platform-specific native audio APIs. Some examples of Host APIs are Core Audio on Mac OS, WMME and DirectSound on Windows and OSS and ALSA on Linux. The diagram in the previous section shows many of the supported native APIs. Sometimes it’s useful to know which Host APIs you’re dealing with, but it is easy to use PortAudio without ever interacting directly with the Host API abstraction.
Devices represent individual hardware audio interfaces or audio ports on the host platform. Devices have names and certain capabilities such as supported sample rates and the number of supported input and output channels. PortAudio provides functions to enumerate available Devices and to query for Device capabilities.
Streams manage active audio input and output from and to Devices. Streams may be half duplex (input or output) or full duplex (simultaneous input and output). Streams operate at a specific sample rate with particular sample formats, buffer sizes and internal buffering latencies. You specify these parameters when you open the Stream. Audio data is communicated between a Stream and your application via a user provided asynchronous callback function or by invoking synchronous read and write functions.
PortAudio supports audio input and output in a variety of sample formats: 8, 16, 24 and 32 bit integer formats and 32 bit floating point, irrespective of the formats supported by the native audio API. PortAudio also supports multichannel buffers in both interleaved and non-interleaved (separate buffer per channel) formats and automatically performs conversion when necessary. If requested, PortAudio can clamp out-of range samples and/or dither to a native format.
The PortAudio API offers the following functionality:
@begin{itemize}
@item{Initialize and terminate the library}
@item{Enumerate available Host APIs}
@item{Enumerate available Devices either globally, or within each Host API}
@item{Discover default or recommended Devices and Device settings}
@item{Discover Device capabilities such as supported audio data formats and sample rates}
@item{Create and control audio Streams to acquire audio from and output audio to Devices}
@item{Provide Stream timing information to support synchronising audio with other parts of your application}
@item{Retrieve version and error information.}
@end{itemize}
These functions are described in more detail below.
@end{section}
@begin[Initialisation, termination and utility functions]{section}
The PortAudio library must be initialized before it can be used and terminated to clean up afterwards. You initialize PortAudio by calling @fun{initialize} and clean up by calling @fun{terminate}. There is @fun{with-audio} macro that does environment.
You can query PortAudio for version information using @fun{get-version} to get a numeric version number and @fun{get-version-text} to get a string.
The size in bytes of the various sample formats represented by the sample-format enumeration can be obtained using @fun{get-sample-size}.
@fun{pa-sleep} sleeps for a specified number of milliseconds. This isn’t intended for use in production systems; it’s provided only as a simple portable way to implement tests and examples where the main thread sleeps while audio is acquired or played by an asynchronous callback function.
@end{section}
@begin[Host APIs]{section}
A Host API acts as a top-level grouping for all of the Devices offered by a single native platform audio API. Each Host API has a unique type identifier, a name, zero or more Devices, and nominated default input and output Devices.
Host APIs are usually referenced by index: an integer of type host-api-index that ranges between zero and @code{(- (@fun{get-host-api-count}) 1)}. You can enumerate all available Host APIs by counting across this range.
You can retrieve the index of the default Host API by calling @fun{get-default-host-api}.
Information about a Host API, such as it’s name and default devices, is stored in a @class{host-api-info} structure. You can retrieve a pointer to a particular Host API’s @class{host-api-info} structure by calling @fun{get-host-api-info} with the Host API’s index as a parameter.
Most PortAudio functions reference Host APIs by @fun{host-api-index} indices. Each Host API also has a unique type identifier defined in the host-api-type-id enumeration. You can call @fun{host-api-type-id-to-host-api-index} to retrieve the current host-api-index for a particular host-api-type-id.
@end{section}
@begin[Devices]{section}
A Device represents an audio endpoint provided by a particular native audio API. This usually corresponds to a specific input or output port on a hardware audio interface, or to the interface as a whole. Each Host API operates independently, so a single physical audio port may be addressable via different Devices exposed by different Host APIs.
A Device has a name, is associated with a Host API, and has a maximum number of supported input and output channels. PortAudio provides recommended default latency values and a default sample rate for each Device. To obtain more detailed information about device capabilities you can call @fun{is-format-supported} to query whether it is possible to open a Stream using particular Devices, parameters and sample rate.
Although each Device conceptually belongs to a specific Host API, most PortAudio functions and data structures refer to Devices using a global, Host API-independent index of type device-index – an integer of that ranges between zero and @code{(- (@fun{get-device-count}) 1)}. The reasons for this are partly historical but it also makes it easy for applications to ignore the Host API abstraction and just work with Devices and Streams.
If you want to enumerate Devices belonging to a particular Host API you can count between 0 and @code{(- (@fun{host-api-info-device-count}) 1)}. You can convert this Host API-specific index value to a global device-index value by calling @fun{host-api-device-index-to-device-index}.
Information about a Device is stored in a PaDeviceInfo structure. You can retrieve @class{device-info} structure by calling @fun{get-device-info} with the Device’s index as a parameter.
You can retrieve the indices of the global default input and output devices using @fun{get-default-input-device} and @fun{get-default-output-device}. Default Devices for each Host API are stored in the Host API’s @class{host-api-info} structures.
For an example of enumerating devices and printing information about their capabilities see the @fun{print-devices} function.
@end{section}
@begin[Streams]{section}
A Stream represents an active flow of audio data between your application and one or more audio Devices. A Stream operates at a specific sample rate with specific sample formats and buffer sizes.
@end{section}
@begin[Opening and Closing Streams]{section}
You call @fun{open-stream} to open a Stream, specifying the Device(s) to use, the number of input and output channels, sample formats, suggested latency values and flags that control dithering, clipping and overflow handling. You specify many of these parameters in two @class{stream-parameters} structures, one for input and one for output.
Devices may be full duplex (supporting simultaneous input and output) or half duplex (supporting input or output) – usually this reflects the structure of the underlying native audio API. When opening a Stream you can specify one full duplex Device for both input and output, or two different Devices for input and output. Some Host APIs only support full-duplex operation with a full-duplex device (e.g. ASIO) but most are able to aggregate two half duplex devices into a full duplex Stream. PortAudio requires that all devices specified in a call to @fun{open-stream} belong to the same Host API.
A successful call to @fun{open-stream} creates a pointer to a @class{pa-stream} – an opaque handle representing the open Stream. All PortAudio API functions that operate on open Streams take a pointer to a @class{pa-stream} as their first parameter.
PortAudio also provides @fun{open-default-stream} – a simpler alternative to @fun{open-stream} which you can use when you want to open the default audio Device(s) with default latency parameters.
You call @fun{close-stream} close a Stream when you’ve finished using it.
There are two macros to simplify work with stream: @fun{with-audio-stream} and @fun{with-default-audio-stream}. These macros open and start stream at the beginning and stop and close stream at the end. Body is protected by unwind-protect.
@end{section}
@begin[Starting and Stopping Streams]{section}
Newly opened Streams are initially stopped. You call @fun{start-stream} to start a Stream. You can stop a running Stream using @fun{stop-stream} or @fun{abort-stream} (the Stop function plays out all internally queued audio data, while Abort tries to stop as quickly as possible). An open Stream can be started and stopped multiple times. You can call @fun{is-stream-stopped} to query whether a Stream is running or stopped.
@end{section}
@begin[The Read/Write I/O Method]{section}
PortAudio provides a synchronous read/write interface for acquiring and playing audio.
To write audio data to a Stream call @fun{write-stream} and to read data call @fun{read-stream}. These functions will block if the internal buffers are full, making them safe to call in a tight loop. If you want to avoid blocking you can query the amount of available read or write space using @fun{get-stream-read-available} or @fun{get-stream-write-available}.
For examples of the read/write I/O method see the following examples in the /t directory of the PortAudio distribution: tests.lisp (@fun{portaudio-tests:test-read-write-converted-echo}).
@end{section}
@begin[Retreiving Stream Information]{section}
You can retrieve information about an open Stream by calling @fun{get-stream-info}. This returns a @class{stream-info} structure containing the actual input and output latency and sample rate of the stream. It’s possible for these values to be different from the suggested values passed to @fun{open-stream}.
@end{section}
@begin[Error Handling]{section}
Most PortAudio functions invokes signal. Possible conditions are described in pa-error enum. Some functions return values greater than or equal to zero for normal results.
PortAudio usually tries to translate error conditions into portable pa-error error codes. However if an unexpected error is encountered the unanticipated-host-error code may be returned. In this case a further mechanism is provided to query for Host API-specific error information. If PortAudio throws unanticipated-host-error you can call @fun{get-last-host-error-info} to retrieve a @class{host-error-info} structure that provides more information, including the Host API that encountered the error, a native API error code and error text.
@end{section}
@begin[Conditions]{section}
There are conditions, that are translated from PaError.
@begin{itemize}
@item{not-anticipated}
@item{unanticipated-host-error}
@item{invalid-channel-count}
@item{invalid-sample-rate}
@item{invalid-device}
@item{invalid-flag}
@item{sample-format-not-supported}
@item{bad-i-o-device-combination}
@item{insufficient-memory}
@item{buffer-too-big}
@item{buffer-too-small}
@item{null-callback}
@item{bad-stream-ptr}
@item{timed-out}
@item{internal-error}
@item{device-unavailable}
@item{incompatible-host-api-specific-stream-info}
@item{stream-is-stopped}
@item{stream-is-not-stopped}
@item{input-overflowed}
@item{output-underflowed}
@item{host-api-not-found}
@item{invalid-host-api}
@item{can-not-read-from-a-callback-stream}
@item{can-not-write-to-a-callback-stream}
@item{can-not-read-from-an-output-only-stream}
@item{can-not-write-to-an-input-only-stream}
@item{incompatible-stream-host-api}
@item{bad-buffer-ptr}
@end{itemize}
@end{section}
@begin[Bitfields]{section}
@b{sample-format}
@begin{itemize}
@item{:float}
@end{itemize}
@b{stream-flags}
@begin{itemize}
@item{:no-flag}
@item{:clip-off}
@item{:dither-off}
@end{itemize}
@end{section}
@begin[Enums]{section}
@b{host-api-type-id}
@begin{itemize}
@item{:in-development}
@item{:direct-sound}
@item{:mme}
@item{:asio}
@item{:sound-manager}
@item{:core-audio}
@item{:oss}
@item{:alsa}
@item{:al}
@item{:be-os}
@item{:wdmks}
@item{:jack}
@item{:wasapi}
@item{:audio-science-hpi}
@end{itemize}
@end{section}
pa
cffi.
common-lisp.
ffa.
abort-stream (function).
close-stream (function).
device-info (class).
device-info-default-high-input-latency (generic reader).
device-info-default-high-output-latency (generic reader).
device-info-default-low-input-latency (generic reader).
device-info-default-low-output-latency (generic reader).
device-info-default-sample-rate (generic reader).
device-info-host-api (generic reader).
device-info-max-input-channels (generic reader).
device-info-max-output-channels (generic reader).
device-info-name (generic reader).
get-default-host-api (function).
get-default-input-device (function).
get-default-output-device (function).
get-device-count (function).
get-device-info (function).
get-host-api-count (function).
get-host-api-info (function).
get-sample-size (function).
get-stream-info (function).
get-stream-read-available (function).
get-stream-time (function).
get-stream-write-available (function).
get-version (function).
get-version-text (function).
host-api-device-index-to-device-index (function).
host-api-info (class).
host-api-info-default-input-device (generic reader).
host-api-info-default-output-device (generic reader).
host-api-info-device-count (generic reader).
host-api-info-name (generic reader).
host-api-info-type (generic reader).
host-api-type-id-to-host-api-index (function).
host-error-info (class).
host-error-info-error-code (generic reader).
host-error-info-error-text (generic reader).
host-error-info-host-api-type (generic reader).
initialize (function).
is-stream-active (function).
is-stream-stopped (function).
make-stream-parameters (function).
merge-channels-into-array (function).
open-default-stream (function).
open-stream (function).
pa-sleep (function).
pa-stream (class).
pa-stream-frames-per-buffer (generic reader).
pa-stream-input-channels (generic reader).
pa-stream-input-sample-format (generic reader).
pa-stream-output-channels (generic reader).
pa-stream-output-sample-format (generic reader).
print-devices (function).
read-stream (function).
read-stream-into-array (function).
separate-array-to-channels (function).
start-stream (function).
stream-info (class).
stream-info-input-latency (generic reader).
stream-info-output-latency (generic reader).
stream-info-sample-rate (generic reader).
stream-parameters (class).
stream-parameters-channel-count (generic reader).
(setf stream-parameters-channel-count) (generic writer).
stream-parameters-device (generic reader).
(setf stream-parameters-device) (generic writer).
stream-parameters-sample-format (generic reader).
(setf stream-parameters-sample-format) (generic writer).
stream-parameters-suggested-latency (generic reader).
(setf stream-parameters-suggested-latency) (generic writer).
terminate (function).
with-audio (macro).
with-audio-stream (macro).
with-default-audio-stream (macro).
write-stream (function).
%abort-stream (function).
%close-stream (function).
%get-default-host-api (function).
%get-default-input-device (function).
%get-default-output-device (function).
%get-device-count (function).
%get-device-info (function).
%get-error-text (function).
%get-host-api-count (function).
%get-host-api-info (function).
%get-last-host-error-info (function).
%get-sample-size (function).
%get-stream-info (function).
%get-stream-read-available (function).
%get-stream-time (function).
%get-stream-write-available (function).
%get-version (function).
%get-version-text (function).
%host-api-device-index-to-device-index (function).
%host-api-type-id-to-host-api-index (function).
%initialize (function).
%is-format-supported (function).
%is-stream-active (function).
%is-stream-stopped (function).
%open-default-stream (function).
%open-stream (function).
%pa-sleep (function).
%read-stream (function).
%start-stream (function).
%stop-stream (function).
%terminate (function).
%write-stream (function).
+format-is-supported+ (constant).
+frames-per-buffer-unspecified+ (constant).
+no-device+ (constant).
+use-host-api-specific-device-specification (constant).
cffi-type-to-lisp (function).
device-info-struct-version (generic reader).
device-info-tclass (class).
get-last-host-error-info (function).
host-api-info-struct-version (generic reader).
host-api-info-tclass (class).
host-error-info-tclass (class).
is-format-supported (function).
make-errors (macro).
p-device-info (class).
p-host-api-info (class).
p-host-error-info (class).
p-pa-stream (class).
p-stream-info (class).
p-stream-parameters (class).
pa-stream-handle (generic reader).
(setf pa-stream-handle) (generic writer).
print-supported-standard-sample-rates (function).
raise-if-error (function).
stop-stream (function).
stream-info-struct-version (generic reader).
stream-info-tclass (class).
stream-parameters-tclass (class).
Definitions are sorted by export status, category, package, and then by lexicographic order.
Execute body in PortAudio initialize/terminate environment.
Execute body with opened and started stream VAR and shut down
the stream after it is done. It is required use these macro in with-audio or initialize/terminate environment.
Execute body with opened and started stream VAR and shut down
the stream after it is done. It is required use these macro in with-audio or initialize/terminate environment.
Terminates audio processing immediately without waiting for pending buffers to complete.
Closes an audio stream. If the audio stream is active it discards any pending buffers as if @fun{abort-stream} had been called.
Retrieve the index of the default host API. The default host API will be the lowest common denominator host API on
the current platform and is unlikely to provide the best performance.
@begin{return}
A non-negative value ranging from 0 to @code{(- (@fun{get-host-api-count}) 1)} indicating the default host API index or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Retrieve the index of the default input device. The result can be used in the inputDevice parameter to @fun{open-stream}.
@begin{return}
The default input device index for the default host API, or raise no-device if no default input device is available or an error was encountered.
@end{return}
Retrieve the index of the default output device. The result can be used in the outputDevice parameter to @fun{open-stream}.
@b{Note}
On the PC, the user can specify a default device by setting an environment variable. For example, to use device #1.
@pre{set PA_RECOMMENDED_OUTPUT_DEVICE=1}
The user should first determine the available device ids by using @code{(@fun{print-devices})}.
@begin{return}
The default output device index for the default host API, or raise no-device if no default output device is available or an error was encountered.
@end{return}
Retrieve the number of available devices.The number of available devices may be zero.
@begin{return}
A non-negative value indicating the number of available devices or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Retrieve @class{device-info} structure containing information about the specified device.
@begin{return}
A object of @class{device-info}. If the device parameter is out of range the function returns NIL.
@end{return}
@arg[device]{A valid device index in the range 0 to @code{(- (@fun{get-device-count}) 1)}}
Retrieve the number of available host APIs. Even if a host API is available it may have no devices available.
@begin{return}
A non-negative value indicating the number of available host APIs or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Retrieve a pointer to a structure containing information about a specific host Api.
@begin[host-api]{arg}
A valid host API index ranging from 0 to @code{(- (@fun{get-host-api-count}) 1)}
@end{arg}
@begin{return}
An object of @class{host-api-info} describing a specific host API. If the hostApi parameter is out of range or an error is encountered, the function returns NIL.
@end{return}
Retrieve the size of a given sample format in bytes.
@result{The size in bytes of a single sample in the specified format, or paSampleFormatNotSupported if the format is not supported.}
Retrieve a object of class @class{stream-info} containing information about the specified stream.
@begin{return}
A object of @class{stream-info} structure. If the stream parameter invalid, or an error is encountered, the function returns NIL.
@end{return}
@arg[pa-stream]{A object of stream previously created with @fun{open-stream}.}
Retrieve the number of frames that can be read from the stream without waiting.
@begin{return}
Returns a non-negative value representing the maximum number of frames that can be read from the stream without blocking or busy waiting or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Returns valid time values for the entire life of the stream, from when the stream is opened until it is closed. Starting and stopping the stream does not affect the passage of time returned by get-stream-time.
This time may be used for synchronizing other events to the audio stream, for example synchronizing audio to MIDI.
@result{The stream’s current time in seconds, or 0 if an error occurred.}
Retrieve the number of frames that can be written to the stream without waiting.
@begin{return}
A non-negative value representing the maximum number of frames that can be written to the stream without blocking or busy waiting or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Retrieve the release number of the currently running PortAudio build, eg 1900.
Retrieve a textual description of the current PortAudio build, eg "PortAudio V19-devel 13 October 2002".
Convert a host-API-specific device index to standard PortAudio device index. This function may be used in conjunction with the deviceCount field of PaHostApiInfo to enumerate all devices for the specified host API.
@arg[host-api]{A valid host API index ranging from 0 to @code{(- (@fun{get-host-api-count}) 1)}}
@arg[host-api-device-index]{A valid per-host device index in the range 0 to @code{(- (@fun{host-api-info-device-count} (@fun{get-host-api-info} host-api)) 1)}}
@begin{return}
A non-negative index ranging from 0 to @code{(- (@fun{get-device-count}) 1)} or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
A invalid-host-api error indicates that the host API index specified by the hostApi parameter is out of range.
A invalid-device error indicates that the host-api-device-index parameter is out of range.
Convert a static host API unique identifier, into a runtime host API index.
@arg[type]{A unique host API identifier belonging to the PaHostApiTypeId enumeration.}
@begin{return}
A valid host-api-idnex ranging from 0 to @code{(- (@fun{get-host-api-count}) 1)} or, raises an error if PortAudio is not initialized or
@end{return}
The host-api-not-found error indicates that the host API specified by the type parameter is not available.
Library initialization function - call this before using PortAudio. This function initializes internal data structures and prepares underlying host APIs for use. With the exception of @fun{get-version}, @fun{get-version-text}, and @fun{get-error-text}, this function MUST be called before using any other PortAudio API functions.
If initialize is called multiple times, each successful call must be matched with a corresponding call to @fun{terminate}. Pairs of calls to initialize/@fun{terminate} may overlap, and are not required to be fully nested.
Note that if initialize raises an error, @fun{terminate} should NOT be called.
@result{NIL if successful, otherwise raises an error indicating the cause of failure.}
Determine whether the stream is active. A stream is active after a successful call to @fun{start-stream}, until it becomes inactive either as a result of a call to @fun{stop-stream} or @fun{abort-stream}. In the latter case, the stream is considered inactive after the last buffer has finished playing.
@begin{return}
Returns one (1) when the stream is active (ie playing or recording audio), zero (0) when not playing or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Determine whether the stream is stopped. A stream is considered to be stopped prior to a successful call to @fun{start-stream} and after a successful call to @fun{stop-stream} or @fun{abort-stream}.
@begin{return}
Returns one (1) when the stream is stopped, zero (0) when the stream is running or, raises an error if PortAudio is not initialized or an error is encountered.
@end{return}
Make stream-parameters object
Merge subarrays of (channelcount)-dimensional array to flat array.
@arg[pa-stream]{A object of stream previously created with @fun{open-stream}.} @arg[channels]{Vector of vectors of floats, that contains data for all sound channels.}
@begin{return}
Vector of data, that can be used with @fun{write-stream}.
@end{return}
A simplified version of @fun{open-stream} that opens the default input and/or output devices.
@arg[num-input-channels]{The number of channels of sound that will be returned by @fun{read-stream}. It can range from 1 to the value of max-input-channels in the @class{device-info} class for the default input device. If 0 the stream is opened as an output-only stream.}
@arg[num-output-channels]{The number of channels of sound to be passed to @fun{write-stream}. It can range from 1 to the value of max-output-channels in the @class{device-info} class for the default output device. If 0 the stream is opened as an output-only stream.}
@arg[sample-format]{The sample format of both the input and output buffers passed to and from @fun{read-stream} and @fun{write-stream}. sample-format may be any of the formats described by the sample-format enumeration.}
@arg[sample-rate]{Same as @fun{open-stream} parameter of the same name.}
@arg[frames-per-buffer]{Same as @fun{open-stream} parameter of the same name.}
@result{As for @fun{open-stream}}
Opens a stream for either input, output or both.
@arg[input-parameters]{A structure that describes the input parameters used by the opened stream. See @class{stream-parameters} for a description of these parameters. input-parameters must be NIL for output-only streams.}
@arg[output-parameters]{A structure that describes the output parameters used by the opened stream. See @class{stream-parameters} for a description of these parameters. output-parameters must be NIL for input-only streams.}
@arg[sample-rate]{The desired sample-rate. For full-duplex streams it is the sample rate for both input and output}
@arg[frames-per-buffer]{Preferred block granularity for a blocking read/write stream.}
@arg[stream-flags]{List of flags which modify the behavior of the streaming process. Some flags may only be relevant to certain buffer formats.}
@begin{return}
Upon success pen-stream returns object of @class{pa-stream} class. The stream is inactive (stopped). If a call to open-stream fails, an error code is raised and the value of stream is NIL.
@end{return}
Put the caller to sleep for at least ’msec’ milliseconds. This function is provided only as a convenience for authors of portable code (such as the tests and examples in the PortAudio distribution.)
The function may sleep longer than requested so don’t rely on this for accurate musical timing.
List available sound devices, including device information.
Read samples from an input stream. The function doesn’t return until the entire buffer has been filled - this may involve waiting for the operating system to supply the data. Size of returned array equal to @code{(* frames-per-buffer channel-count)}.
@arg[pa-stream]{A object of stream previously created with @fun{open-stream}.}
@begin{return}
On success array of data will be returned, or :input-overflowed if input data was discarded by PortAudio after the previous call and before this call.
@end{return}
Read samples from an input stream. The function doesn’t return until the entire buffer has been filled - this may involve waiting for the operating system to supply the data.
@arg[pa-stream]{A object of stream previously created with @fun{open-stream}.}
@arg[array]{Simple array with has element-type equal to sample-format from @fun{open-stream}. Size of array equal to @code{(* frames-per-buffer channel-count)}.}
@begin{return}
On success NIL will be returned, or :input-overflowed if input data was discarded by PortAudio after the previous call and before this call.
@end{return}
Separate flat array
@arg[pa-stream]{A object of stream previously created with @fun{open-stream}.}
@arg[array]{Flat array, that is received from @fun{read-stream}.}
@begin{return}
(channelcount)-dimensional array of single-floats
@end{return}
Commences audio processing.
Library termination function - call this when finished using PortAudio. This function deallocates all resources allocated by PortAudio since it was initialized by a call to @fun{initialize}. In cases where @fun{initialize} has been called multiple times, each call must be matched with a corresponding call to terminate. The final matching call to terminate will automatically close any PortAudio streams that are still open.
terminate MUST be called before exiting a program which uses PortAudio. Failure to do so may result in serious resource leaks, such as audio devices not being available until the next reboot.
@begin{return}
NIL if successful, otherwise raises an error indicating the cause of failure.
@end{return}
Write samples to an output stream. This function doesn’t return until the entire buffer has been consumed - this may involve waiting for the operating system to consume the data. Size of buffer should be equal to @code{(* frames-per-buffer channel-count)}.
@arg[pa-stream]{A object of stream previously created with @fun{open-stream}.}
@arg[buffer]{A array of sample frames. The buffer contains samples in the format specified by the @code{(stream-parameters-sample-format output-parameters)} field used to open the stream, and the number of channels specified by @code{(stream-parameters-num-channels output-parameters)}.}
@begin{return}
On success NIL will be returned, or :output-underflowed if additional output data was inserted after the previous call and before this call.
@end{return}
Default latency values for robust non-interactive applications (eg. playing sound files).
device-info)) ¶Default latency values for robust non-interactive applications (eg. playing sound files).
device-info)) ¶Default latency values for interactive performance.
device-info)) ¶Default latency values for interactive performance.
device-info)) ¶Sample rate
device-info)) ¶Sample rate
note this is a host API index, not a type id.
device-info)) ¶note this is a host API index, not a type id.
maximum number of input channels
device-info)) ¶maximum number of output channels
device-info)) ¶automatically generated reader method
device name
device-info)) ¶Device name.
name.
The default input device for this host API. The value will be a device index ranging from 0 to (- (get-device-count) 1), or no-device if no default input device is available.
host-api-info)) ¶The default input device for this host API. The value will be a device index ranging from 0 to (- (get-device-count) 1), or no-device if no default input device is available.
The default output device for this host API. The value will be a device index ranging from 0 to (- (get-device-count) 1), or paNoDevice if no default output device is available.
host-api-info)) ¶The default output device for this host API. The value will be a device index ranging from 0 to (- (get-device-count) 1), or paNoDevice if no default output device is available.
The number of devices belonging to this host API. This field may be used in conjunction with host-api-device-index-to-device-index to enumerate all devices for this host API.
host-api-info)) ¶The number of devices belonging to this host API. This field may be used in conjunction with host-api-device-index-to-device-index to enumerate all devices for this host API.
A textual description of the host API for display on user interfaces.
host-api-info)) ¶A textual description of the host API for display on user interfaces.
name.
The well known unique identifier of this host API.
host-api-info)) ¶The well known unique identifier of this host API.
type.
the error code returned
host-error-info)) ¶the error code returned
a textual description of the error if available, otherwise a zero-length string
host-error-info)) ¶a textual description of the error if available, otherwise a zero-length string
the host API which returned the error code
host-error-info)) ¶the host API which returned the error code
Frames per buffer for current stream
Number of input channels
value of sample-format for input channel
Number of output channels
value of sample-format for output channel
The input latency of the stream in seconds. This value provides the most accurate estimate of input latency available to the implementation. It may differ significantly from the suggestedLatency value passed to open-stream. The value of this field will be zero (0.) for output-only streams.
stream-info)) ¶The input latency of the stream in seconds. This value provides the most accurate estimate of input latency available to the implementation. It may differ significantly from the suggestedLatency value passed to open-stream. The value of this field will be zero (0.) for output-only streams.
The output latency of the stream in seconds. This value provides the most accurate estimate of output latency available to the implementation. It may differ significantly from the suggestedLatency value passed to open-stream. The value of this field will be zero (0.) for input-only streams.
stream-info)) ¶The output latency of the stream in seconds. This value provides the most accurate estimate of output latency available to the implementation. It may differ significantly from the suggestedLatency value passed to open-stream. The value of this field will be zero (0.) for input-only streams.
The sample rate of the stream in Hertz (samples per second). In cases where the hardware sample rate is inaccurate and PortAudio is aware of it, the value of this field may be different from the sample-rate parameter passed to open-stream. If information about the actual hardware sample rate is not available, this field will have the same value as the sample-rate parameter passed to open-stream.
stream-info)) ¶The sample rate of the stream in Hertz (samples per second). In cases where the hardware sample rate is inaccurate and PortAudio is aware of it, the value of this field may be different from the sample-rate parameter passed to open-stream. If information about the actual hardware sample rate is not available, this field will have the same value as the sample-rate parameter passed to open-stream.
The number of channels of sound to be delivered to the stream callback.
stream-parameters)) ¶The number of channels of sound to be delivered to the stream callback.
stream-parameters)) ¶The number of channels of sound to be delivered to the stream callback.
A valid device index in the range 0 to @code{(- (@fun{get-device-count}) 1)} specifying the device to be used. This field must not be set to paNoDevice.
stream-parameters)) ¶A valid device index in the range 0 to (- get-device-count 1) specifying the device to be used. This field must not be set to paNoDevice.
stream-parameters)) ¶A valid device index in the range 0 to (- get-device-count 1) specifying the device to be used. This field must not be set to paNoDevice.
The sample format of the buffer provided to read-stream or write-stream.
stream-parameters)) ¶The sample format of the buffer provided to read-stream or write-stream.
stream-parameters)) ¶The sample format of the buffer provided to read-stream or write-stream.
The desired latency in seconds. Where practical, implementations should configure their latency based on these parameters, otherwise they may choose the closest viable latency instead. Unless the suggested latency is greater than the absolute upper limit for the device implementations should round the suggestedLatency up to the next practical value - ie to provide an equal or higher latency than suggestedLatency wherever possible.
stream-parameters)) ¶The desired latency in seconds. Where practical, implementations should configure their latency based on these parameters, otherwise they may choose the closest viable latency instead. Unless the suggested latency is greater than the absolute upper limit for the device implementations should round the suggestedLatency up to the next practical value - ie to provide an equal or higher latency than suggestedLatency wherever possible.
stream-parameters)) ¶The desired latency in seconds. Where practical, implementations should configure their latency based on these parameters, otherwise they may choose the closest viable latency instead. Unless the suggested latency is greater than the absolute upper limit for the device implementations should round the suggestedLatency up to the next practical value - ie to provide an equal or higher latency than suggestedLatency wherever possible.
p-stream-parameters) param) ¶cffi.
device-info) &key pointer) ¶host-error-info) &key pointer) ¶stream-info) &key pointer) ¶host-api-info) &key pointer) ¶p-stream-info)) ¶cffi.
p-host-error-info)) ¶cffi.
p-stream-parameters)) ¶cffi.
p-host-api-info)) ¶cffi.
p-device-info)) ¶cffi.
p-stream-parameters)) ¶cffi.
p-pa-stream)) ¶cffi.
A structure providing information and capabilities of PortAudio devices. Devices may support input, output or both input and output.
device-info-default-high-input-latency.
device-info-default-high-output-latency.
device-info-default-low-input-latency.
device-info-default-low-output-latency.
device-info-default-sample-rate.
device-info-host-api.
device-info-max-input-channels.
device-info-max-output-channels.
device-info-name.
device-info-struct-version.
initialize-instance.
Structure version.
This slot is read-only.
Device name.
This slot is read-only.
note this is a host API index, not a type id.
This slot is read-only.
This slot is read-only.
This slot is read-only.
Default latency values for interactive performance.
This slot is read-only.
This slot is read-only.
Default latency values for robust non-interactive applications (eg. playing sound files).
This slot is read-only.
This slot is read-only.
Sample rate
This slot is read-only.
A structure containing information about a particular host API.
Struct version.
This slot is read-only.
The well known unique identifier of this host API.
common-lisp.
This slot is read-only.
A textual description of the host API for display on user interfaces.
This slot is read-only.
The number of devices belonging to this host API. This field may be used in conjunction with host-api-device-index-to-device-index to enumerate all devices for this host API.
This slot is read-only.
The default input device for this host API. The value will be a device index ranging from 0 to (- (get-device-count) 1), or no-device if no default input device is available.
This slot is read-only.
The default output device for this host API. The value will be a device index ranging from 0 to (- (get-device-count) 1), or paNoDevice if no default output device is available.
This slot is read-only.
Structure used to return information about a host error condition.
the host API which returned the error code
This slot is read-only.
the error code returned
This slot is read-only.
a textual description of the error if available, otherwise a zero-length string
This slot is read-only.
A single PaStream can provide multiple channels of real-time streaming audio input and output to a client application. A stream provides access to audio hardware represented by one or more devices. Depending on the underlying Host API, it may be possible to open multiple streams using the same device, however this behavior is implementation defined. Portable applications should assume that a device may be simultaneously used by at most one stream.
Foreign pointer to pa-stream
(cffi-sys:null-pointer)
:handle
Format of input samples
:input-sample-format
This slot is read-only.
Number of input channels
:input-channels
This slot is read-only.
Format of output samples
:output-sample-format
This slot is read-only.
Number of output channels
:output-channels
This slot is read-only.
Frames per buffer
:frames-per-buffer
This slot is read-only.
A structure containing unchanging information about an open stream.
Struct version
This slot is read-only.
The input latency of the stream in seconds. This value provides the most accurate estimate of input latency available to the implementation. It may differ significantly from the suggestedLatency value passed to open-stream. The value of this field will be zero (0.) for output-only streams.
This slot is read-only.
The output latency of the stream in seconds. This value provides the most accurate estimate of output latency available to the implementation. It may differ significantly from the suggestedLatency value passed to open-stream. The value of this field will be zero (0.) for input-only streams.
This slot is read-only.
The sample rate of the stream in Hertz (samples per second). In cases where the hardware sample rate is inaccurate and PortAudio is aware of it, the value of this field may be different from the sample-rate parameter passed to open-stream. If information about the actual hardware sample rate is not available, this field will have the same value as the sample-rate parameter passed to open-stream.
This slot is read-only.
Parameters for one direction (input or output) of a stream.
A valid device index in the range 0 to (- get-device-count 1) specifying the device to be used. This field must not be set to paNoDevice.
The number of channels of sound to be delivered to the stream callback.
The sample format of the buffer provided to read-stream or write-stream.
The desired latency in seconds. Where practical, implementations should configure their latency based on these parameters, otherwise they may choose the closest viable latency instead. Unless the suggested latency is greater than the absolute upper limit for the device implementations should round the suggestedLatency up to the next practical value - ie to provide an equal or higher latency than suggestedLatency wherever possible.
Return information about the last host error encountered. The error information returned by @fun{get-last-host-error-info} will never be modified asynchronously by errors occurring in other PortAudio owned threads.
This function is provided as a last resort, primarily to enhance debugging by providing clients with access to all available error information.
@begin{return}
A structure constraining information about the host error. The values in this structure will only be valid if a PortAudio function has previously raise the unanticipated-host-error error code.
@end{return}
Determine whether it would be possible to open a stream with the specified parameters.
@arg[input-parameters]{A structure that describes the input parameters used to open a stream. The suggested-latency slot is ignored. See @class{stream-parameters} for a description of these parameters. input-parameters must be NIL for output-only streams.}
@arg[output-parameters]{A structure that describes the output parameters used to open a stream. The suggested-latency field is ignored. See @class{stream-parameters} for a description of these parameters. output-parameters must be NIL for input-only streams.}
@arg[sample-rate]{The required sampleRate. For full-duplex streams it is the sample rate for both input and output.}
@begin{return}
Returns 0 if the format is supported, and raises an error indicating why the format is not supported otherwise. The constant @variable{+format-is-supported+} is provided to compare with the return value for success.
@end{return}
Check err and raise condition if it is needed
Terminates audio processing. It waits until all pending audio buffers have been played before it returns.
device-info)) ¶Structure version.
host-api-info)) ¶Struct version.
stream-info)) ¶Struct version
foreign-struct-type.
translatable-foreign-type.
foreign-struct-type.
translatable-foreign-type.
foreign-struct-type.
translatable-foreign-type.
enhanced-foreign-type.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
enhanced-foreign-type.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
enhanced-foreign-type.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
enhanced-foreign-type.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
enhanced-foreign-type.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
enhanced-foreign-type.
| Initarg | Value |
|---|---|
:actual-type | (quote (pointer)) |
foreign-struct-type.
translatable-foreign-type.
foreign-struct-type.
translatable-foreign-type.
| Jump to: | %
(
A C D F G H I M O P R S T W |
|---|
| Jump to: | %
(
A C D F G H I M O P R S T W |
|---|
| Jump to: | +
C D E F H I M N O P S T |
|---|
| Jump to: | +
C D E F H I M N O P S T |
|---|
| Jump to: | C D F H M P S |
|---|
| Jump to: | C D F H M P S |
|---|