Scorched End Audio Library
Seal is a C library with Ruby binding for audio rendering and manipulation, such as direction and distance attenuation, the simulation of the Doppler effect and reverberation, in a 3D space. It is built on top of OpenAL.
Why Seal? Why not Simply Use OpenAL?
- Seal has a Ruby binding and many syntactic sugars.
- Seal supports audio formats like Ogg Vorbis, MPEG Audio and WAVE.
- Seal abstracts automatic audio streaming (also preventing problems like discontinued stream due to I/O stress).
- More stuff in the future...
Basic Usage
Initialize Seal:
Seal.startup
include Seal
Use a source object to represent a sound source, and attach an audio buffer:
source = Source.new
source.buffer = Buffer.new("audio.ogg")
Change the position of the source:
source.position = 3, 2, -4
Or change the position of the source based on velocity:
source.velocity = 1, 2, -1
source.move # automatically add the velocity vector to the position vector
Change the position of the listener (a singleton of Seal::Listener):
Seal.listener.position = -1, -1, 0
# ...
Seal.listener.velocity = 3, 1, -1
seal.listener.move
Play the source:
source.play
In case of massive audio resource, use of buffer will eat all the memory, so we can use streams:
source.stream = Stream.open("background_music.ogg")
Make sure to detach the audio from the source before switching from a buffer to a stream or vice-versa:
source.buffer = ...
# ...
source.buffer = nil
source.stream = ...
# ...
source.stream = nil
source.buffer = ...
Apply a reverberation effect to the sound source:
# Allocate an effect slot and associate a specific reverb object.
# Here we are using a predefined reverb effect. See doc for `Reverb::Preset`.
slot = EffectSlot.new(Reverb.new(Reverb::Preset::FOREST))
# Start feeding the slot.
source.feed(slot, 0)
Uninitialize Seal:
seal.cleanup
You can find detailed documentations in the header files under include/seal
for each of the modules.
The C interface is very similar to the Ruby binding, except that some of the Seal objects are abbreviated (but still more verbose than Ruby in general):
src -> Source
buf -> Buffer
rvb -> Reverb
efs -> EffectSlot
For example:
seal_src_t src;
seal_buf_t buf;
seal_startup(0);
seal_init_src(&src);
seal_init_buf(&buf);
seal_load2buf(&buf, "audio.ogg", SEAL_UNKNOWN_FMT);
seal_set_src_buf(&src, &buf);
seal_play_src(&src);
// Wait to hear.
_seal_sleep(3000);
seal_destroy_src(&src);
seal_destroy_buf(&buf);
seal_destroy_efs(&efs);
seal_destroy_rvb(&rvb);
seal_cleanup();
For detailed documentation, refer to:
http://rubydoc.info/gems/seal
zhang.su/seal
Platforms
Linux, Windows and Mac OS X are officially tested and supported. Seal should run on all Unix-like operating systems where OpenAL, libogg, libvorbis and libmpg123 can run, but those platforms are never tested. The Makefiles are generated specifically for MSVC and GCC (MinGW or native Unix-like systems).
Installation
Prerequisite
Seal has native dependencies; you need to have OpenAL installed on your system.
You need CMake 2.4 or later to install libopenal as follows:
git clone git://repo.or.cz/openal-soft.git openal-soft
cd openal-soft/build
cmake -DCMAKE_BUILD_TYPE=Release ..
make
make install
Note: There has been issues compiling OpenAL on some versions of OS X because LLVM is the default compiler. I haven't had luck compiling OpenAL with LLVM, so I explicitly specified GCC instead:
...
CC=/usr/bin/gcc-4.2 cmake -DCMAKE_BUILD_TYPE=Release ..
...
After OpenAL is installed, you can start building Seal. Seal will dynamically link OpenAL.
Note that depending on where OpenAL's make install
installs the actual
shared library, you may need to add the lib path to LD_LIBRARY_PATH
in
order for Seal to find the shared libopenal.so
file.
Install as a Gem (in a sane environment)
gem install seal
GCC + GNU Make + Unix-like operating systems + UN*X shell
From Seal directory:
cd make/unix-like
make
GCC + GNU Make + MinGW + UN*X shell
cd make/win32
make
MSVC + Microsoft Visual Studio 2010
use the solution and project files under /msvc.
Ruby extension
bundle install
rake compile
The default output is lib/seal.{so,dll,bundle}
, which is a dynamic library
that could be required by Ruby at runtime.
Demos
Use rake demo:<demo_name>
to run the demos under the demo/
directory.
playback
Basic playback of audio.
control
Various controls of audio like play, pause, stop.
pitch
Audio pitch shifting.
walk
3D audio positioning (attenuation).
doppler
Doppler Effect demonstration.
reverb
Audio reverberation. There are lots of built-in reverb presets, but this demo only simulates a large room in ice palace.
Running Tests
Tests are written on top of the Ruby binding, using RSpec. You need to build Seal as a Ruby extension to run the tests:
bundle install
rake compile
rspec
Thread Safety
Seal can be safely used in a multi-threaded environment so long as no Seal source, buffer or stream instance is accessed by different threads at the same time , which is similar to libvorbis' thread-safety conditions described here.
Exceptions are the two functions seal_startup
and seal_cleanup
, which are
NOT thread-safe. Refer to the documentation for these two functions for
details.
Character Encoding
UTF-8 should be used to encode the source code or at least the path strings so that Seal can properly input audio files using paths that contain multi-byte (Chinese, Japanese, etc.) characters.
Etymology
The phrase "Scorched end" (Chinese: 焦尾; Pinyin: Jiao Wei) is a direct translation of the name of a Guqin[1] existed in China in the second century CE. The name literally means that one end of the Qin is scorched.
This Qin was found by Cai Yong.[2] According to the "History of the Later Han",[3] Cai Yong once heard very loud sound of someone burning Firmiana simplex[4] wood for cooking and realized that it is a good material for making Qin soundboards. He then asked for the wood and cut it into a Qin, and the sound it produced was pleasant to hear as expected. However, one end of the wood had already been scorched by the time Cai Yong got it, hence the name "Scorched end".
Seal was named so with the hope that it will be more useful than it seems and will be discovered by the right people who need the right tool.
[1] http://en.wikipedia.org/wiki/Guqin
[2] http://en.wikipedia.org/wiki/Cai_Yong
[3] http://en.wikipedia.org/wiki/History_of_the_Later_Han
[4] http://en.wikipedia.org/wiki/Firmiana_simplex