Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/zhangsu/seal
Scorched End Audio Library: a C library (with Ruby binding) for 3D audio rendering.
https://github.com/zhangsu/seal
Last synced: 3 months ago
JSON representation
Scorched End Audio Library: a C library (with Ruby binding) for 3D audio rendering.
- Host: GitHub
- URL: https://github.com/zhangsu/seal
- Owner: zhangsu
- License: wtfpl
- Created: 2011-09-24T22:43:47.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2014-10-12T21:29:58.000Z (about 10 years ago)
- Last Synced: 2024-07-09T14:38:51.569Z (4 months ago)
- Language: C
- Homepage: zhang.su/seal
- Size: 8.93 MB
- Stars: 22
- Watchers: 4
- Forks: 2
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-ruby - seal
README
# 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]
(http://connect.creativelabs.com/openal/default.aspx).
## Why Seal? Why not Simply Use OpenAL?
0. Seal has a Ruby binding and many syntactic sugars.
1. Seal supports audio formats like Ogg Vorbis, MPEG Audio and WAVE.
2. Seal abstracts automatic audio streaming (also preventing problems like
discontinued stream due to I/O stress).
3. More stuff in the future...
## Basic Usage
Initialize Seal:
```ruby
Seal.startup
include Seal
```
Use a source object to represent a sound source, and attach an audio buffer:
```ruby
source = Source.new
source.buffer = Buffer.new("audio.ogg")
```
Change the position of the source:
```ruby
source.position = 3, 2, -4
```
Or change the position of the source based on velocity:
```ruby
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):
```ruby
Seal.listener.position = -1, -1, 0
# ...
Seal.listener.velocity = 3, 1, -1
seal.listener.move
```
Play the source:
```ruby
source.play
```
In case of massive audio resource, use of buffer will eat all the memory, so
we can use streams:
```ruby
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:
```ruby
source.buffer = ...
# ...
source.buffer = nil
source.stream = ...
# ...
source.stream = nil
source.buffer = ...
```
Apply a reverberation effect to the sound source:
```ruby
# 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:
```ruby
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:
```c
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](http://rubydoc.info/gems/seal)
[zhang.su/seal](http://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](http://www.cmake.org/) 2.4 or later to install
[libopenal](http://kcat.strangesoft.net/openal.html) as follows:
```bash
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:
```bash
...
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)
```Bash
gem install seal
```
### GCC + GNU Make + Unix-like operating systems + UN*X shell
From Seal directory:
```bash
cd make/unix-like
make
```
### GCC + GNU Make + MinGW + UN*X shell
```bash
cd make/win32
make
```
### MSVC + Microsoft Visual Studio 2010
use the solution and project files under /msvc.
### Ruby extension
```bash
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:` 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]
(https://github.com/rspec/rspec). You need to build Seal as a Ruby extension
to run the tests:
```Bash
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](http://xiph.org/vorbis/doc/vorbisfile/threads.html).
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