Next: Introduction, Previous: (dir), Up: (dir) [Contents][Index]
This is the harmony Reference Manual, version 2.0.0, generated automatically by Declt version 3.0 "Montgomery Scott" on Fri Jun 26 11:13:28 2020 GMT+0.
| • Introduction | What harmony is all about | |
| • Systems | The systems documentation | |
| • Modules | The modules documentation | |
| • Files | The files documentation | |
| • Packages | The packages documentation | |
| • Definitions | The symbols documentation | |
| • Indexes | Concepts, functions, variables and data types |
Harmony is a library that provides you with audio processing tools as well as an audio server to play back music, sfx, and so forth. It is most suited for use in a game engine, but may feasibly also used for more advanced things such as an audio processing tool.
A very basic sound system can be gained by loading the harmony-simple system and using its predefined audio pipeline and convenience functions.
(ql:quickload :harmony-simple)
Before any audio can be played, the audio server needs to be initialised.
(harmony-simple:initialize)
Once the server is running, we need some files to play. Harmony-simple sets up a pipeline that supports three distinct mixers: :music, :sfx, and :voice. The latter two mixers provide 3D audio, allowing you to place the sources in 3D space. Playing a file simply happens through the play function.
(harmony-simple:play #p"music.mp3" :music :loop T)
(harmony-simple:play #p"explosion.mp3" :sfx)
Returned by play is a source instance, which you can use to control the playback. You can pause, resume, and stop a source. When a source is stopped manually or naturally reaches its end it is removed from the mixer. You can resume and add it again if you want to re-use it. If you would like to smoothly fade a track, you can use the :fade initarg on play, or use the fade function after the fact. You can also directly control the volume with the volume accessor.
For sources on the 3D mixers, you can use the input-location and input-velocity accessors to modify their placement. The velocity will not cause the location to be updated automatically, and is instead used to calculate the intensity of the doppler effect. If you do not want to have a doppler effect, you can simply leave the velocity at its default. The mixer itself also has a few properties that you'll want to control in order to control the listener. Aside from the location and velocity, there's also the direction, up, soundspeed, doppler-factor, min-distance, max-distance, rolloff, and attenuation to control the properties of the 3D space.
If you need to pause the sound playback entirely, you can also use pause and resume without an argument.
Harmony includes support for a variety of playback backends: Out123, OpenAL, WASAPI, ALSA, and PulseAudio. It is recommended to use the native backends (WASAPI, ALSA) where possible as they do not have any C dependencies and should have reduced latency and complexity compared to the other backends (Out123, OpenAL).
You can choose a backend, and customise its options, with the :output-spec initarg on harmony-simple's initialize. For example, to use the PulseAudio backend:
(asdf:load-system :harmony-pulse)
(harmony-simple:initialize :output-spec '(harmony-pulse:pulse-drain))
A number of the backends include extra options like :program-name that allows you to change the appearance of your program in the system's volume mixer.
Certain kinds of audio need to be played back often and with minimal latency. This is where buffering the audio in memory can be very useful. Harmony allows you to do this with the decode function, which constructs a source just like play and runs it in such a way that it decodes everything to its output buffers. The list of buffers is then returned. Once you have the buffers you can store them somewhere, so that when you want to play them back, all you need to do is create a buffer-source with those buffers as the source.
As an example, this is how it might work in your code:
(defvar *explosion* (harmony-simple:decode #p"explosion.mp3"))
(harmony-simple:play 'harmony:buffer-source :sfx :buffers *explosion*)
Since the buffer source merely indexes into the buffers and doesn't change them, you can easily instantiate as many as you need from the same buffers.
If you want a pipeline that is a bit more involved than what harmony-simple gives you, perhaps to add certain effects or other kinds of shenanigans, you can easily build that pipeline. Before you do, though, you should get briefly acquainted with cl-mixed, or at least with the segments it provides. Harmony uses libmixed underneath to do most of the audio processing and mixing, and in itself only provides a sound server, and a convenient way to handle segments and create a pipeline.
Here's an example of a pipeline consisting of an output, a LADSPA plugin, and a basic mixer. You'll need a server beforehand, which you can get by simply instantiating harmony:server.
(let* ((pipeline (make-instance 'harmony:pipeline))
(output (make-instance 'harmony-out123:out123-drain :server server))
(master (make-instance 'harmony:basic-mixer :server server :name :master))
(ladspa (make-instance 'cl-mixed:ladspa :samplerate (harmony:samplerate server)
:file #p"ladspa-plugin.so")))
(harmony:connect pipeline ladspa 0 output 0)
(harmony:connect pipeline ladspa 1 output 1)
(harmony:connect pipeline master 0 output 0)
(harmony:connect pipeline master 1 output 1)
(harmony:compile-pipeline pipeline server))
Once the pipeline has been compiled to the server, you can start by adding segments to the master mixer, similar to before. Most of the other commands remain the same as well, just using a different package.
(harmony:play server #p"something.mp3" :master)
When you construct the pipeline, Harmony takes care of properly allocating the necessary internal buffers, connecting the segments as required, and determining the proper order in which to process them.
Segments are the lifeblood of Harmony. Through segments you get audio data into the pipeline, transform it as you need, and finally even output it to be heard. Being able to define custom and new segments is therefore the primary way in which to extend Harmony's functionality.
One of the easiest things to do is to define a new source. Let's do that with a sine wave generator. As a first step, we'll need to define a class.
(defclass sine (harmony:source cl-mixed:virtual)
((sine-phase :initform 0 :accessor sine-phase)))
The class inherits from source to get useful functionality for fading, pausing, and seeking. We also inherit from cl-mixed:virtual as this segment won't have a segment defined in C to support it underneath. Instead, we can now extend all the functionality of the segment from the lisp side.
As part of the contract of subclassing source, we need to implement a method on seek-to-sample. Let's do that:
(defmethod harmony:seek-to-sample ((source sine) position)
(setf (sine-phase source) (mod position (harmony:samplerate (harmony:context source)))))
We'll be using the sine-phase to track the current phase of our sine wave, so in order to "seek" we'll need to adjust it here. Naturally you won't really be able to hear the effects of seeking on a sine wave generator, but for other sources proper seeking behaviour can be vital.
Another function we need to implement a method for is sample-count which returns the number of samples the source can return. Our sine wave generator can return an unbounded number, so we return T instead of an integer.
(defmethod harmony:sample-count ((source sine)) T)
Finally we need to implement the actual sample generation, which for all sources happens in process:
(defmethod harmony:process ((source sine) samples)
(let* ((buffers (cl-mixed:outputs source))
(phase (sine-phase source))
(samplerate (harmony:samplerate (harmony:context source)))
(factor (* 2 PI 440 (/ samplerate))))
(loop for i from 0 below samples
for sample = (sin (coerce (* factor phase) 'single-float))
do (loop for buffer across buffers
do (setf (cffi:mem-aref (cl-mixed:data buffer) :float i) sample))
(incf phase))
(setf (sine-phase source) (mod phase samplerate))))
First we extract the output buffer vector and the current phase, and calculate the constant factor for the wave. We then iterate over the number of samples we need to generate, and set the sample at the corresponding position in each buffer. Note that buffers contain C arrays and as such we need to use CFFI's mem-aref instead of Lisp's aref. Once we're done with the sample generation we update the phase in our instance.
And that's it. You can now test your sine generator with (harmony-simple:play 'sine :music).
For a lot of sources and drains you will want to interact with other libraries and systems. They will usually have their own idea of how the sample data should be represented. Often times they'll want a single C array where the samples are interleaved, or might even need a different sample format than the floats Harmony uses internally. For this, libmixed offers a good amount of support by taking over the packing and unpacking of samples for you.
In Harmony, you can make use of this with the unpack-source and pack-drain respectively. As an additional contract, they'll have you construct a packed-audio object that encodes the sample representation format, but will in turn handle the conversion for you, so that you just need to write to or read from a buffer using your foreign system. For an example on how this works, see the mp3 and wav sources, or the alsa and pulse drains.
Finally I think it would be worth it to look at an example of an effect segment. We'll be writing a very primitive version of an echo effect with a linear falloff.
As before, we'll first want to create a new class to encapsulate our segment with.
(defclass echo (harmony:segment cl-mixed:virtual)
((buffers :initform NIL :accessor buffers)
(offset :initform 0 :accessor offset)
(delay :initarg :delay :initform 0.2 :accessor delay)
(falloff :initarg :falloff :initform 0.8 :accessor falloff)))
We'll make this work by having internal buffers that keep some of the previous samples that come in and mixes them back into the output with a slight delay added. In order to know the proper size of the buffers, we'll need to know the sample rate ahead of time as well, hence the parameter.
Next we'll need to actually instantiate the buffers on start.
(defmethod cl-mixed:start ((echo echo))
(let ((buffers (make-array 2)))
(setf (buffers echo) buffers)
(dotimes (i (length buffers))
(setf (aref buffers i) (make-array (ceiling (* (delay echo)
(harmony:samplerate
(harmony:context echo))))
:element-type 'single-float
:initial-element 0.0f0)))))
Since we don't need to share these buffers with any C parts, we can just use a CL array for our convenience.
In order for Harmony to be able to assemble the pipeline from the segments properly, it needs to know some information about the segment. We can provide this information with a method on cl-mixed:info:
(defmethod cl-mixed:info ((echo echo))
(list :min-inputs 2 :max-inputs 2 :outputs 2))
There are a few other info fields that are specified by libmixed, but this should be enough for our purposes.
Finally, the actual mixing step. The virtual class provides methods for all of the actions that can be performed on a segment. It already handles the connecting of input and output buffers for us, so we don't need to care about that. All we need to do is handle the mixing logic.
(defmethod cl-mixed:mix (samples (echo echo))
(let ((offset (offset echo))
(falloff (falloff echo)))
(loop for out-buffer across (cl-mixed:outputs echo)
for in-buffer across (cl-mixed:inputs echo)
for out = (cl-mixed:data out-buffer)
for in = (cl-mixed:data in-buffer)
for buf across (buffers echo)
for off = offset
do (loop for i from 0 below samples
for sample = (cffi:mem-aref in :float i)
for echo = (aref buf off)
do (setf (cffi:mem-aref out :float i) (+ sample echo))
(setf (aref buf off) (* (+ sample echo) falloff))
(setf off (mod (1+ off) (length buf)))))
(setf (offset echo) (mod (+ offset samples) (length (aref (buffers echo) 0))))))
This iterates over all channels (in->buf->out), and for each channel does the following: for each sample to compute, output the input sample added to the sample looked up in the echo buffer. Then store the same multiplied by the falloff into the echo buffer. Finally advance the offset into the echo buffer. At the end of the function we have to make sure to store the current offset in the segment for the next time mix is called.
In order to test this we'll create our own pipeline real quick:
(let ((pipeline (make-instance 'harmony:pipeline))
(output (harmony-simple:make-segment 'harmony-out123:out123-drain))
(echo (harmony-simple:make-segment 'echo :name :echo))
(source (harmony-simple:make-segment 'harmony-mp3:mp3-source :file #p"some.mp3")))
(harmony:connect pipeline echo 0 output 0)
(harmony:connect pipeline echo 1 output 1)
(harmony:connect pipeline source 0 echo 0)
(harmony:connect pipeline source 1 echo 1)
(harmony:compile-pipeline pipeline harmony-simple:*server*))
Note that this will perform all the pipeline computation locally, and then switch out the pipeline in the server. If you had something else going on in the previous pipeline, then that will be replaced. You should now hear the song being played back with an echo effect.
For more information on the details of segments and the underlying mechanisms of the mixing, see the documentation of the cl-mixed library.
Next: Modules, Previous: Introduction, Up: Top [Contents][Index]
The main system appears first, followed by any subsystem dependency.
| • The harmony system |
Nicolas Hafner <shinmera@tymoon.eu>
Nicolas Hafner <shinmera@tymoon.eu>
(:git "https://github.com/shirakumo/harmony.git")
zlib
A common lisp sound server and sound processing library.
2.0.0
harmony.asd (file)
Modules are listed depth-first from the system components tree.
| • The harmony/drains module | ||
| • The harmony/sources module |
Next: The harmony/sources module, Previous: Modules, Up: Modules [Contents][Index]
files.lisp (file)
harmony (system)
drains/
buffer.lisp (file)
Previous: The harmony/drains module, Up: Modules [Contents][Index]
drains (module)
harmony (system)
sources/
buffer.lisp (file)
Files are sorted by type and then listed depth-first from the systems components trees.
| • Lisp files |
Next: The harmony/package․lisp file, Previous: Lisp files, Up: Lisp files [Contents][Index]
harmony.asd
harmony (system)
Next: The harmony/toolkit․lisp file, Previous: The harmony․asd file, Up: Lisp files [Contents][Index]
Next: The harmony/mixing-context․lisp file, Previous: The harmony/package․lisp file, Up: Lisp files [Contents][Index]
package.lisp (file)
harmony (system)
toolkit.lisp
Next: The harmony/segment․lisp file, Previous: The harmony/toolkit․lisp file, Up: Lisp files [Contents][Index]
toolkit.lisp (file)
harmony (system)
mixing-context.lisp
Next: The harmony/server․lisp file, Previous: The harmony/mixing-context․lisp file, Up: Lisp files [Contents][Index]
mixing-context.lisp (file)
harmony (system)
segment.lisp
Next: The harmony/mixers․lisp file, Previous: The harmony/segment․lisp file, Up: Lisp files [Contents][Index]
segment.lisp (file)
harmony (system)
server.lisp
Next: The harmony/fadable․lisp file, Previous: The harmony/server․lisp file, Up: Lisp files [Contents][Index]
server.lisp (file)
harmony (system)
mixers.lisp
Next: The harmony/source․lisp file, Previous: The harmony/mixers․lisp file, Up: Lisp files [Contents][Index]
mixers.lisp (file)
harmony (system)
fadable.lisp
Next: The harmony/drain․lisp file, Previous: The harmony/fadable․lisp file, Up: Lisp files [Contents][Index]
fadable.lisp (file)
harmony (system)
source.lisp
Next: The harmony/pipeline․lisp file, Previous: The harmony/source․lisp file, Up: Lisp files [Contents][Index]
source.lisp (file)
harmony (system)
drain.lisp
Next: The harmony/files․lisp file, Previous: The harmony/drain․lisp file, Up: Lisp files [Contents][Index]
drain.lisp (file)
harmony (system)
pipeline.lisp
Next: The harmony/drains/buffer․lisp file, Previous: The harmony/pipeline․lisp file, Up: Lisp files [Contents][Index]
pipeline.lisp (file)
harmony (system)
files.lisp
*filetype-source-map* (special variable)
Next: The harmony/sources/buffer․lisp file, Previous: The harmony/files․lisp file, Up: Lisp files [Contents][Index]
drains (module)
drains/buffer.lisp
Next: The harmony/documentation․lisp file, Previous: The harmony/drains/buffer․lisp file, Up: Lisp files [Contents][Index]
sources (module)
sources/buffer.lisp
Previous: The harmony/sources/buffer․lisp file, Up: Lisp files [Contents][Index]
Next: Definitions, Previous: Files, Up: Top [Contents][Index]
Packages are listed by definition order.
| • The harmony package |
package.lisp (file)
org.shirakumo.fraf.harmony
common-lisp
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 macros | ||
| • Exported functions | ||
| • Exported generic functions | ||
| • Exported classes |
Next: Exported functions, Previous: Exported definitions, Up: Exported definitions [Contents][Index]
Conveniently define a source type mapping.
See SOURCE-TYPE
files.lisp (file)
Shorthand macro to evaluate the body in the mixing context.
See CALL-IN-MIXING-CONTEXT
mixing-context.lisp (file)
Next: Exported generic functions, Previous: Exported macros, Up: Exported definitions [Contents][Index]
Handle the allocation of the necessary buffers for the nodes.
The number of buffers necessary is determined by
looking at the BUFFER attribute of each port and
maximising that.
If OLD-BUFFERS is given, only additional buffers
as necessary are allocated and the buffers in the
old sequence are re-used.
After all buffers have been allocated, the BUFFER
attribute on each port in the nodes list is
replaced by the actual buffer instance.
See FLOW:ATTRIBUTE
See CL-MIXED:MAKE-BUFFER
pipeline.lisp (file)
Cubic-in easing.
X -> X³
toolkit.lisp (file)
Cubic-in-out easing.
X -> (2*x)³/2 | If x < 0.5 1+(2*(x-1))³/2 | otherwise
toolkit.lisp (file)
Cubic-out easing.
X -> 1+(x-1)³
toolkit.lisp (file)
Linear easing.
X -> X
toolkit.lisp (file)
This is a convenience function for unpack sources.
Handling the edge-cases of reaching the output end
and looping properly can be a bit tricky. This
function takes care of properly filling the packed
audio array with data while handling the necessary
wraparound or zeroing in case of stream end.
DIRECT-READ should be a function of three arguments: ARG — The arg passed into the function. BUFFER — A pointer to the C array of data. BYTES — The number of bytes to write into it.
source.lisp (file)
Clear the memory in a region to zero.
This is a tiny wrapper around memset. DEST — A destination array pointer. NUM — The number of bytes to copy.
See MEMSET
toolkit.lisp (file)
Copy memory from one region to another.
This is the libc memcpy().
DEST — A destination array pointer.
SOURCE — A source array pointer.
NUM — The number of bytes to copy.
See memcpy()
toolkit.lisp (file)
Set memory in a region to a particular byte.
This is the libc memset().
DEST — A destination array pointer.
SOURCE — A source byte to set the array with.
NUM — The number of bytes to copy.
See memset()
toolkit.lisp (file)
Accessor to the file type extension to source type mapping.
The name should be a string designating the file
type, and the value a source class name.
See *FILETYPE-SOURCE-MAP*
See DEFINE-SOURCE-TYPE
files.lisp (file)
(setf source-type) (function)
files.lisp (file)
source-type (function)
Next: Exported classes, Previous: Exported functions, Up: Exported definitions [Contents][Index]
Accessor to the sequence of buffers.
The buffers are internal to this object and should
not be touched unless you really, really know what
you’re doing.
See MIXER
See SERVER
(setf buffers) (generic function)
automatically generated reader method
buffer.lisp (file)
automatically generated reader method
buffer.lisp (file)
automatically generated reader method
mixers.lisp (file)
automatically generated reader method
server.lisp (file)
buffers (generic function)
automatically generated writer method
buffer.lisp (file)
automatically generated writer method
buffer.lisp (file)
automatically generated writer method
mixers.lisp (file)
automatically generated writer method
server.lisp (file)
Accessor to the number of samples in a buffer on the context.
This is SETFable, but note that this will only
adapt the buffers constructed through the pipeline.
Buffers, and especially internal data arrays, are
not adjusted and may not be able to hold the
required amount of data if you increase the buffer
size. Use at your own risk.
See MIXING-CONTEXT
(setf buffersize) (generic function)
automatically generated reader method
mixing-context.lisp (file)
buffersize (generic function)
automatically generated writer method
mixing-context.lisp (file)
server.lisp (file)
Returns the number of channel buffers each source should provide.
See MIXER
mixers.lisp (file)
Compile the pipeline into the given server.
This performs a buffer allocation on each of the
inputs and outputs of the segments connected in the
pipeline, flattens the graph topologically to
figure out the proper order to mix the segments in,
and finally constructs a mixer object to configure
the server with.
Once everything has been properly built, the server
is updated with the new device, buffers, and mixer.
The device is taken to be the last segment in the
topological sort.
After everything has been updated, the old mixer
and unneeded buffers are freed. Segments are not
freed, and will instead be garbage-collected
automatically if no longer needed.
This also updates the SEGMENT-MAP in the server, by
clearing it first, and then updating it with all
the segments contained in the pipeline.
See PIPELINE
See SERVER
See ALLOCATE-BUFFERS
See FLOW:ALLOCATE-PORTS
See COMPLETE-SEGMENT
See SEGMENT-MAP
pipeline.lisp (file)
Connects the output location to the input location of the given segments.
The system cannot feasibly figure out how you intend
locations to be connected together, which is why you
must specify them yourself.
See PIPELINE
See DISCONNECT
See SEVER
pipeline.lisp (file)
Accessor to the segment’s context.
See SEGMENT
See MIXING-CONTEXT
(setf context) (generic function)
automatically generated reader method
segment.lisp (file)
context (generic function)
automatically generated writer method
segment.lisp (file)
Conveniently decode a source to a list of buffers.
This allows you to fully store a source as decompressed
samples in-memory, ready for direct playback from the
internal buffers.
Mostly this should be used for small effects and clips
that need minimal latency upon playback.
You can use the BUFFER-SOURCE to play the buffers back
directly.
Note that the source will not get a SERVER instance as
the context, but instead a constructed MIXING-CONTEXT.
It will also not be part of a pipeline, and will instead
just be connected to the output buffers, started, mixed,
and ended in that order. The source should thus be
tricked into thinking it’s playing just like normal,
meaning a source should not require any additional code
to allow being decoded.
See SOURCE
See BUFFER-SOURCE
source.lisp (file)
files.lisp (file)
Accessor to the device segment of the server.
The device segment is like any other segment in
the pipeline, with the exception that the server
uses its PAUSED-P state to determine whether it
should suspend mixing or not. Usually COMPILE-
PIPELINE will ensure that the device is the last
segment in the sorted segments list, and thus
the segment responsible for outputting the audio
data.
See SERVER
(setf device) (generic function)
automatically generated reader method
server.lisp (file)
device (generic function)
automatically generated writer method
server.lisp (file)
Disconnects the output location from the input location of the given segments.
The system cannot feasibly figure out how you intend
locations to be disconnected, which is why you must
specify them yourself.
See PIPELINE
See CONNECT
See SEVER
pipeline.lisp (file)
Accessor to whether the source has reached its end or not.
Once a source has been marked as ended, it is
automatically paused as soon as possible, and then
removed from its mixer if the mixer is known to the
source.
And ended source can be started anew by using
the RESUME function.
See STOP
See RESUME
(setf ended-p) (generic function)
automatically generated reader method
source.lisp (file)
ended-p (generic function)
automatically generated writer method
source.lisp (file)
Either creates or returns the node corresponding to the given segment.
See PIPELINE
See NODES
See MAKE-NODE
pipeline.lisp (file)
pipeline.lisp (file)
Cause the segment to start fading as soon as possible.
TIME should be a float, specifying the duration
of the fade in seconds. If :FROM is not specified,
it is taken to be current volume of the segment.
BY should be a function of one float argument
and one return value.
See EASING-FUNCTION
See FADABLE
fadable.lisp (file)
Accessor to the pathname of the file the file-source reads from.
See FILE-SOURCE
(setf file) (generic function)
automatically generated reader method
files.lisp (file)
file (generic function)
automatically generated writer method
files.lisp (file)
This function should return a packed-audio instance.
The instance should contain a pointer to a C array
of opaque samples, as well as a precise description
of the way in which the samples are laid out, as well
as what their rate and format is.
See CL-MIXED:PACKED-AUDIO
See UNPACK-SOURCE
See PACK-DRAIN
source.lisp (file)
Accessor to whether the source should loop after finishing.
See SOURCE
(setf looping-p) (generic function)
automatically generated reader method
source.lisp (file)
looping-p (generic function)
automatically generated writer method
source.lisp (file)
Construct a new node instance for the given segment.
The segment must support the INFO operation and report
accurately on its number of inputs and outputs.
Otherwise, a proper node cannot be constructed.
See NODE
See SEGMENT
pipeline.lisp (file)
Accessor to the name of the segment.
The name should be a symbol, and can be used to
retrieve the segment from the server after the
pipeline has been compiled for it.
See SEGMENT
automatically generated reader method
segment.lisp (file)
Accessor to the hash table mapping segments to their corresponding nodes.
See PIPELINE
(setf nodes) (generic function)
automatically generated reader method
pipeline.lisp (file)
nodes (generic function)
automatically generated writer method
pipeline.lisp (file)
Accessor to the function pointer for the packer segment’s mix function.
See CL-MIXED:PACKER
See PACK-DRAIN
(setf pack-mix-function) (generic function)
automatically generated reader method
drain.lisp (file)
pack-mix-function (generic function)
automatically generated writer method
drain.lisp (file)
Pause the source or drain.
See SOURCE
See DRAIN
See SERVER
drain.lisp (file)
source.lisp (file)
server.lisp (file)
Accessor to whether the source is paused or not.
See SOURCE
See PAUSE
See RESUME
(setf paused-p) (generic function)
automatically generated reader method
source.lisp (file)
server.lisp (file)
paused-p (generic function)
automatically generated writer method
source.lisp (file)
server.lisp (file)
source.lisp (file)
Conveniently play back a source on the designated mixer of the server.
In general PLAY is responsible for creating or
initialising a source if necessary, adding it to the
specified mixer, and playing it back.
PLAY is supposed to be "smart" about its arguments
and will coerce where possible. For instance, the
SOURCE-ISH can be a symbol, class, source, or
pathname. The mixer can be either a symbol or a
mixer. Additional coercions could be added through
libraries.
The INITARGS are either creation initargs for new
sources, or REINITIALIZE-INSTANCE initargs for
existing sources.
See SOURCE
source.lisp (file)
files.lisp (file)
This function is responsible for invoking the actual sample processing step of a segment.
Note that not all segments will call this function,
and unless you do so yourself, currently only SOURCE
and DRAIN will.
In general a call to this function should result in
samples from the connected input buffers to be read
and samples to the connected output buffers to be
written.
See SOURCE
See DRAIN
source.lisp (file)
buffer.lisp (file)
buffer.lisp (file)
drain.lisp (file)
Returns the conversion factor between the channel’s and the server’s samplerate.
See SOURCE
See DRAIN
(setf remix-factor) (generic function)
automatically generated reader method
drain.lisp (file)
automatically generated reader method
source.lisp (file)
remix-factor (generic function)
automatically generated writer method
drain.lisp (file)
automatically generated writer method
source.lisp (file)
Resume the source or drain from a pause.
If the source was ENDED-P, it is seeked to
position 0 before resuming.
See SOURCE
See DRAIN
See SERVER
drain.lisp (file)
source.lisp (file)
server.lisp (file)
This function is called by the background processing thread of the server.
It is responsible for starting, ending, and mixing
the segments in the pipeline. It is also
responsible for checking the server’s evaluation-
queue, and running any function that appears on it.
Within PROCESS, *IN-PROCESSING-THREAD* is bound to
T.
If the device of the server is PAUSED-P, then
BT:THREAD-YIELD is called.
See SERVER
server.lisp (file)
Return the number of samples the source can play back.
Note that this function may return T instead of
an integer if the number of samples is unbounded.
Every source must implement a method for this
function.
See SOURCE
source.lisp (file)
buffer.lisp (file)
Returns the sample counter for the source.
The sample counter is kept to keep track of the
seeking position. It is not necessarily entirely
accurate.
The samples are counted in the source’s channel
samplerate, rather than the server’s samplerate.
It is updated during mixing.
See SOURCE
(setf sample-position) (generic function)
automatically generated reader method
buffer.lisp (file)
automatically generated reader method
source.lisp (file)
sample-position (generic function)
automatically generated writer method
buffer.lisp (file)
automatically generated writer method
source.lisp (file)
Accessor to the number of samples the context processes each iteration.
See MIXING-CONTEXT
(setf samples) (generic function)
automatically generated reader method
mixing-context.lisp (file)
samples (generic function)
automatically generated writer method
mixing-context.lisp (file)
Seek the source to the requested position.
MODE may be either :ABSOLUTE or :RELATIVE,
where relative denotes the requested position
to be relative to the current position.
BY may be either :SAMPLE or :SECOND, where
:SAMPLE denotes the specific requested sample
position in the source’s stream, and :SECOND
requests the approximate playback time in
seconds.
See SOURCE
See SEEK-TO-SAMPLE
source.lisp (file)
Seek to the specified sample.
This position is absolute. Every source must
implement a method for this function.
You should /not/ call this function yourself.
It is for internal use only, and exported for
the sole purpose of allowing you to define a
method on it for your custom source. To do the
seeking on a source, use SEEK instead.
See SEEK
See SOURCE
source.lisp (file)
buffer.lisp (file)
Accessor to the segment of the given name on the server.
This is useful to retrieve segments at a later
point in time after the pipeline has already been
assembled.
See SEGMENT-MAP
See SERVER
(setf segment) (generic function)
server.lisp (file)
Severs all connections to and from the given segment.
See CONNECT
See DISCONNECT
See PIPELINE
pipeline.lisp (file)
Returns a list of all segments currently connected to the mixer.
Note that these segments are not necessarily of type
SOURCE.
See MIXER
mixers.lisp (file)
Start up the server’s background processing thread.
This in turn causes audio processing to "actually"
happen. If the server is not ready to process audio,
an error is signalled. If the server has already been
started, an error is signalled.
See THREAD
See SERVER
See STARTED-P
See STOP
server.lisp (file)
Returns true if the server has been started already and is currently running.
See SERVER
See START
See STOP
server.lisp (file)
Stops the server or source.
When the server is stopped, its background processing
thread is shut down. If no thread is currently
running, nothing happens.
When a source is stopped, its ENDED-P property is
set to T.
See THREAD
See SERVER
See START
See STARTED-P
See ENDED-P
source.lisp (file)
server.lisp (file)
Accessor to the foreign function pointer for the unpacker segment mix function.
See CL-MIXED:UNPACKER
See UNPACK-SOURCE
(setf unpack-mix-function) (generic function)
automatically generated reader method
source.lisp (file)
unpack-mix-function (generic function)
automatically generated writer method
source.lisp (file)
Previous: Exported generic functions, Up: Exported definitions [Contents][Index]
This mixer simply adds all its sources together.
Note that unless you control the volume of your sources carefully, this can easily result in the clipping of the audio samples, and thus in distortion. No dynamic range compression is applied whatsoever.
By default the mixer is initialised to input and
output two channels. Should you require more or less,
you must specify it via its initarg.
Each source connected to the mixer /must/ have as
many outputs as this mixer has channels.
See CL-MIXED:BASIC-MIXER
See MIXER
mixers.lisp (file)
channels-per-source (method)
| Initarg | Value |
|---|---|
| :channels | 2 |
In-memory buffer drain.
This drain simply copies the data from the input
buffers to its preset buffers as it is mixed.
This is mostly useful for transferring a mixer
pipeline to internal buffers, or for reading a file
source into buffers for in-memory playback through
a buffer-source later.
Note that if the number of written samples exceeds
the size of the first buffer, no further samples
are written and the input data is simply thrown
away. You are responsible for making the buffers be
the appropriate size yourself.
See CL-MIXED:VIRTUAL
See DRAIN
See BUFFER-SOURCE
buffer.lisp (file)
#()
buffers (generic function)
(setf buffers) (generic function)
0
sample-position (generic function)
(setf sample-position) (generic function)
| Initarg | Value |
|---|---|
| :buffers | (error "buffers required.") |
In-memory buffer source.
This source simply copies the data from its preset
buffers to the output buffers as it is mixed.
This is mostly useful for very low-latency effects
that you can keep entirely in memory ahead of time.
For instance, you could decode a wave file into the
corresponding BUFFER instances and then instantiate
buffer-sources from those whenever the effect should
be played.
See CL-MIXED:VIRTUAL
See SOURCE
See BUFFER-DRAIN
buffer.lisp (file)
#()
buffers (generic function)
(setf buffers) (generic function)
| Initarg | Value |
|---|---|
| :buffers | (error "buffers required.") |
Superclass for all drain segments in Harmony.
A drain is a segment that only consumes audio and
sends it off somewhere outside of the pipeline for
further processing.
A class that implements this protocol must implement
a primary method on PROCESS to handle the audio
processing step.
See SEGMENT
See PROCESS
drain.lisp (file)
segment (class)
Mixin class for all segments that support volume fading.
Any implementing class must implement a method for
VOLUME and (SETF VOLUME). Furthermore, the class
must call PERFORM-FADING at the end of each of its
mix iterations.
In order for the fading effect to be nice, the
number of samples processed in each iteration must
be relatively small.
See SEGMENT
See START-VOLUME
See TARGET-VOLUME
See FADE-COUNT
See FADE-END
See EASING-FUNCTION
See FADE
See PERFORM-FADING
fadable.lisp (file)
segment (class)
source (class)
1.0
start-volume (generic function)
(setf start-volume) (generic function)
1.0
target-volume (generic function)
(setf target-volume) (generic function)
0
fade-count (generic function)
(setf fade-count) (generic function)
0
fade-end (generic function)
(setf fade-end) (generic function)
(function harmony:ease-linear)
easing-function (generic function)
(setf easing-function) (generic function)
Superclass for sources that back a file.
See SOURCE
See FILE
files.lisp (file)
source (class)
:file
file (generic function)
(setf file) (generic function)
A port to represent an input location on a segment.
See FLOW:IN-PORT
See FLOW:1-PORT
pipeline.lisp (file)
:optional
optional-p (generic function)
(setf optional-p) (generic function)
| Initarg | Value |
|---|---|
| :optional | nil |
A port to represent a segment’s inputs for a segment that supports arbitrary input locations.
See FLOW:IN-PORT
See FLOW:N-PORT
pipeline.lisp (file)
check-complete (method)
Superclass for all mixer segments.
Mixers are segments that accumulate multiple inputs. They all allow you to add or remove sources to mix from dynamically at runtime without having to re- compile the entire pipeline. Any source dynamically attached to a mixer should /not/ be part of the pipeline, as otherwise it is processed multiple times.
Any class that implements this protocol must implement
a method on CHANNELS-PER-SOURCE which returns the
number of used input buffers for each source that is
added to the mixer.
See SEGMENT
See CL-MIXED:MIXER
See BUFFERS
See SOURCES
See ADD
See WITHDRAW
See CHANNELS-PER-SOURCE
mixers.lisp (file)
buffers (generic function)
(setf buffers) (generic function)
A context that holds information about the global state of a mixing pipeline.
Upon construction the context must know the general
buffer size and the sample rate used throughout the
pipeline. These properties may not change unless
you completely recreate every segment and recompile
the pipeline.
The buffer size defaults to 441 and the sample rate
to 44100. Note that having too high a buffer size
will result in degraded output quality for some
operations like fading. Note that having a sample
rate that differs from your inputs or the output
device will likely result in bad audio quality and
distortions, as the audio data needs to be
resampled.
The number of actual samples being processed each
run is controlled by the SAMPLES field, and can be
changed at runtime. Note however that setting this
to a value higher than BUFFERSIZE will most likely
spawn demons in your pants and crash your Lisp.
See SAMPLES
See BUFFERSIZE
See SAMPLERATE
See CALL-IN-MIXING-CONTEXT
See WITH-BODY-IN-MIXING-CONTEXT
mixing-context.lisp (file)
standard-object (class)
server (class)
:samples
0
samples (generic function)
(setf samples) (generic function)
:buffersize
0
buffersize (generic function)
(setf buffersize) (generic function)
:samplerate
0
samplerate (generic function)
| Initarg | Value |
|---|---|
| :buffersize | 441 |
| :samplerate | 44100 |
A node to represent a segment in the pipeline.
You should construct this through MAKE-NODE.
See FLOW:DYNAMIC-NODE
See MAKE-NODE
See COMPLETE-SEGMENT
See NTH-OUT
See NTH-IN
pipeline.lisp (file)
dynamic-node (class)
A port to represent an output location on a segment.
See FLOW:OUT-PORT
See FLOW:N-PORT
pipeline.lisp (file)
check-complete (method)
Superclass for drains that pack to a compact format first.
This drain performs a preprocessing of the input
buffers by merging them, and possibly converting
or resampling them, into a single C array of
audio samples.
This is convenient for a lot of external libraries
and APIs that expect a singular C buffer of samples
in a specific format.
A class that implements this protocol must implement
a primary method on INITIALIZE-PACKED-AUDIO, which
should return a valid PACKED-AUDIO instance that
holds and describes the expected audio format
properties.
See DRAIN
See REMIX-FACTOR
See PACKED-AUDIO
See INITIALIZE-PACKED-AUDIO
See CL-MIXED:PACKED-AUDIO
drain.lisp (file)
drain (class)
0
remix-factor (generic function)
(setf remix-factor) (generic function)
packed-audio (generic function)
(setf packed-audio) (generic function)
pack-mix-function (generic function)
(setf pack-mix-function) (generic function)
This class holds a collection of nodes during the assembly of an audio pipeline.
It is primarily used to handle the logic of connecting
segments together and finally compiling it all down
to a fully assembled audio pipeline ready for use in
the server.
Among other things it takes care of buffer allocation
and proper buffer assignment.
See CONNECT
See DISCONNECT
See SEVER
See COMPILE-PIPELINE
pipeline.lisp (file)
standard-object (class)
(make-hash-table :test (quote eq))
nodes (generic function)
(setf nodes) (generic function)
Base class for all Harmony segments that can appear in a pipeline.
A segment must carry a reference to the context
that it is running on. This reference can be
supplied through the :CONTEXT initarg.
Segments can have a name, which allows them to be
found again through the server object, when they
appear in the server’s pipeline.
Note that even segments that are not derived
from this class, but rather the underlying class
CL-MIXED:SEGMENT may be used in a pipeline.
See CL-MIXED:SEGMENT
See CONTEXT
See NAME
segment.lisp (file)
segment (class)
:context
context (generic function)
(setf context) (generic function)
:name
name (generic function)
| Initarg | Value |
|---|---|
| :context | (error "context initarg required.") |
| :name | nil |
This class represents a sound server.
The server is responsible for keeping a background thread that constantly processes and outputs sound.
The actual construction of a sound pipeline should
be done through the PIPELINE class, which can then
compile its information down to a format suitable
for the server.
See MIXING-CONTEXT
See SEGMENT-MAP
See SAMPLES
See BUFFERSIZE
See SAMPLESIZE
See DEVICE
See SEGMENT-SEQUENCE
See BUFFERS
See THREAD
See COMPILE-PIPELINE
See EVALUATION-QUEUE-HEAD
See EVALUATION-QUEUE-TAIL
See EVALUATION-LOCK
See SEGMENT
See SEGMENTS
See START
See STARTED-P
See STOP
See RUN
See CALL-IN-SERVER-THREAD
See PAUSED-P
See PAUSE
See RESUME
server.lisp (file)
mixing-context (class)
(make-hash-table :test (quote eql))
segment-map (generic function)
(setf segment-map) (generic function)
:device
device (generic function)
(setf device) (generic function)
segment-sequence (generic function)
(setf segment-sequence) (generic function)
buffers (generic function)
(setf buffers) (generic function)
thread (generic function)
(setf thread) (generic function)
evaluation-queue-head (generic function)
(setf evaluation-queue-head) (generic function)
evaluation-queue-tail (generic function)
(setf evaluation-queue-tail) (generic function)
evaluation-lock (generic function)
(setf evaluation-lock) (generic function)
Superclass for all of Harmony’s source segments.
A source segment does not input any data and
instead directly provides it, either by generating
it on the fly, or by reading it from a file or
some kind of stream.
A class that implements this protocol must implement
a primary method on PROCESS to output samples to its
connected buffers.
Furthermore it must implement the SEEK-TO-SAMPLE
method to provide seeking. If it cannot seek, even
in the most imprecise way, it must implement that
method to signal an error.
See FADABLE
See LOOPING-P
See PAUSED-P
See ENDED-P
See SAMPLE-POSITION
See PROCESS
See PAUSE
See RESUME
See STOP
See SEEK
See SEEK-TO-SAMPLE
See SAMPLE-COUNT
See PLAY
source.lisp (file)
fadable (class)
:loop
looping-p (generic function)
(setf looping-p) (generic function)
:paused
paused-p (generic function)
(setf paused-p) (generic function)
ended-p (generic function)
(setf ended-p) (generic function)
0
sample-position (generic function)
(setf sample-position) (generic function)
This mixer mixes sources as if they were located in 3D space.
Note that unless you control the volume of your
sources carefully, this can easily result in the
clipping of the audio samples, and thus in distortion.
No dynamic range compression is applied whatsoever.
Each source only has to have a single output buffer,
which is then interpreted as a point audio source. If
you require different shapes of sources, you can get
that behaviour by modifying the location of the source
relative to the listener in such a way that the
closest point of the source’s shape is the actual point
the source has. This won’t account for overlapping and
such finer details of sound, but should be good enough
for most cases.
Note that unlike in CL-MIXED, where each source is
independent of the mixer, and you thus have to use the
INPUT-LOCATION/VELOCITY functions to adjust their
parameters, in Harmony the sources are tied to a mixer
and you can thus use the same LOCATION and VELOCITY
functions for sources as you would for the mixer. In
the case of the mixer, the location and velocity are
to be interpreted as those of the listener.
See CL-MIXED:SPACE-MIXER
See MIXER
See LOCATION
See VELOCITY
See DIRECTION
See UP
See SOUNDSPEED
See DOPPLER-FACTOR
See MIN-DISTANCE
See MAX-DISTANCE
See ROLLOFF
See ATTENUATION
mixers.lisp (file)
channels-per-source (method)
Superclass for sources that unpack from a compact format first.
This source performs postprocessing of a data array
by splitting it out to the connected output buffers,
and possibly converting or resampling it as
necessary.
This is convenient for a lot of external libraries
and APIs that provide a singular C buffer of samples
in a specific format.
A class that implements this protocol must implement
a primary method on INITIALIZE-PACKED-AUDIO, which
should return a valid PACKED-AUDIO instance that
holds and describes the provided audio format
properties.
See SOURCE
See REMIX-FACTOR
See PACKED-AUDIO
See INITIALIZE-PACKED-AUDIO
See FILL-FOR-UNPACK-SOURCE
source.lisp (file)
source (class)
0
remix-factor (generic function)
(setf remix-factor) (generic function)
packed-audio (generic function)
(setf packed-audio) (generic function)
unpack-mix-function (generic function)
(setf unpack-mix-function) (generic function)
Previous: Exported definitions, Up: Definitions [Contents][Index]
| • Internal special variables | ||
| • Internal functions | ||
| • Internal generic functions |
Next: Internal functions, Previous: Internal definitions, Up: Internal definitions [Contents][Index]
This map stores the associations of file type extensions to source class names.
See SOURCE-TYPE
files.lisp (file)
If this is T, then the current context is within the server’s processing thread.
See PROCESS
See CALL-IN-SERVER-THREAD
server.lisp (file)
Next: Internal generic functions, Previous: Internal special variables, Up: Internal definitions [Contents][Index]
Perform the computations necessary to adjust the volume to fade.
You should call this function at the end of every
iteration of your primary mixing of the segment.
See FADABLE
fadable.lisp (file)
Previous: Internal functions, Up: Internal definitions [Contents][Index]
Causes the given function to be evaluated in the context.
For a SERVER the following additional arguments are
recognised:
If SYNCHRONIZE is non-NIL, then this function does
not return until the given function has been
evaluated. If additionally VALUES is non-NIL, the
values as produced by the given function are
returned after evaluation.
If TIMEOUT is given, it should be the number of
seconds after which this function gives up waiting
for the given function to be evaluated or to finish
evaluating.
Note that if *IN-PROCESSING-THREAD* is non-NIL, or
if the server has no thread, the function is
evaluated directly and immediately. Otherwise it
is placed onto the server’s evaluation-queue.
See WITH-BODY-IN-MIXING-CONTEXT
See *IN-PROCESSING-THREAD*
mixing-context.lisp (file)
server.lisp (file)
pipeline.lisp (file)
Complete the segment in the node and return it.
Completing it means assigning the buffers to the
inputs and outputs of the segment as appropriate.
The node’s ports must have a BUFFER attribute for
this purpose.
See NODE
See SEGMENT
See CL-MIXED:INPUT
See CL-MIXED:OUTPUT
See FLOW:ATTRIBUTE
pipeline.lisp (file)
Accessor to the function used to ease the volume.
This function should take one float argument in
the range [0,1] and should return another float
value close to the range [0,1]. It must not
necessarily match the range exactly.
See FADABLE
(setf easing-function) (generic function)
automatically generated reader method
fadable.lisp (file)
easing-function (generic function)
automatically generated writer method
fadable.lisp (file)
Accessor to the lock used to secure the evaluation queue.
See SERVER
See EVALUATION-QUEUE
(setf evaluation-lock) (generic function)
automatically generated reader method
server.lisp (file)
evaluation-lock (generic function)
automatically generated writer method
server.lisp (file)
Accessor to the head of the list of functions the server should evaluate.
This list is used to cause functions to be run
inside the server thread, forcing a
synchronisation of the state. This in turn allows
you to evaluate things that might otherwise cause
race conditions or other kinds of problems that
might wreck the system.
See SERVER
See CALL-IN-SERVER-THREAD
See EVALUATION-LOCK
(setf evaluation-queue-head) (generic function)
automatically generated reader method
server.lisp (file)
evaluation-queue-head (generic function)
automatically generated writer method
server.lisp (file)
Accessor to the tail end of the list of functions the server should evaluate.
This always references a CONS whose CDR can be
used to append new functions to the queue.
See SERVER
See CALL-IN-SERVER-THREAD
See EVALUATION-LOCK
(setf evaluation-queue-tail) (generic function)
automatically generated reader method
server.lisp (file)
evaluation-queue-tail (generic function)
automatically generated writer method
server.lisp (file)
Accessor to the current sample count in the fading process.
The fade duration is counted in number of samples
from zero. If this is the same as FADE-END, no
fading is performed. Otherwise this is increased
by the number of samples processed every time
PERFORM-FADING is called.
See FADE-END
See TARGET-VOLUME
See START-VOLUME
See FADABLE
(setf fade-count) (generic function)
automatically generated reader method
fadable.lisp (file)
fade-count (generic function)
automatically generated writer method
fadable.lisp (file)
Accessor to the sample count after which the target-volume is reached.
See FADE-COUNT
See TARGET-VOLUME
See START-VOLUME
See FADABLE
(setf fade-end) (generic function)
automatically generated reader method
fadable.lisp (file)
fade-end (generic function)
automatically generated writer method
fadable.lisp (file)
Return the nth input port of the node.
If no such input port exists, an error is signalled.
Note that IN-PORTS act as if they cover an indefinite
number of locations.
See NODE
pipeline.lisp (file)
Return the nth output port of the node.
If no such output port exists, an error is signalled.
See NODE
pipeline.lisp (file)
automatically generated reader method
pipeline.lisp (file)
automatically generated writer method
pipeline.lisp (file)
Accessor to the hash table associating names to segments.
This map is usually populated by COMPILE-PIPELINE.
See NAME
See SERVER
See SEGMENT
(setf segment-map) (generic function)
automatically generated reader method
server.lisp (file)
segment-map (generic function)
automatically generated writer method
server.lisp (file)
Accessor to the segment-sequence of the server.
This object handles the invocation of the segments
in their proper order. It is usually created and
assigned by COMPILE-PIPELINE.
See CL-MIXED:SEGMENT-SEQUENCE
See SERVER
(setf segment-sequence) (generic function)
automatically generated reader method
server.lisp (file)
segment-sequence (generic function)
automatically generated writer method
server.lisp (file)
Accessor to the starting volume of the fading segment.
See FADABLE
(setf start-volume) (generic function)
automatically generated reader method
fadable.lisp (file)
start-volume (generic function)
automatically generated writer method
fadable.lisp (file)
Accessor to the ending/target volume of the fading segment.
See FADABLE
(setf target-volume) (generic function)
automatically generated reader method
fadable.lisp (file)
target-volume (generic function)
automatically generated writer method
fadable.lisp (file)
Accessor to the background processing thread of the server.
If this is NIL, you may assume that the server
is currently not processing any data.
See START
See STARTED-P
See STOP
See PROCESS
(setf thread) (generic function)
automatically generated reader method
server.lisp (file)
thread (generic function)
automatically generated writer method
server.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: | F H L M |
|---|
| Jump to: | F H L M |
|---|
Next: Variable index, Previous: Concept index, Up: Indexes [Contents][Index]
| Jump to: | (
A B C D E F G I L M N O P R S T U W |
|---|
| Jump to: | (
A B C D E F G I L M N O P R S T U W |
|---|
Next: Data type index, Previous: Function index, Up: Indexes [Contents][Index]
| Jump to: | *
B C D E F L N O P R S T U |
|---|
| Jump to: | *
B C D E F L N O P R S T U |
|---|
Previous: Variable index, Up: Indexes [Contents][Index]
| Jump to: | B C D F H I M N O P S U |
|---|
| Jump to: | B C D F H I M N O P S U |
|---|