seal 0.1.2 → 0.1.3

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6a4ec328c05b480d1e4771accd5feddc120359f0
+  data.tar.gz: 5006a20741965f24f45f4e0f1d1f5ccc41859956
+SHA512:
+  metadata.gz: be6c6509925a48baddd68cf0089becceaff0d84394c85cae4e68c6b485a5037728dabac4b5492555ea833ad8c0fd95c895bbbf0145ce31b68a6fa33074549806
+  data.tar.gz: 589899ce37a1f214815c3aa5860752cecf1398cf39e0236104bd4ce2d9dc4b0a3d8760e91febd767608c9bd302d80baac74bac7baa69f319773c67edc725bd7f

data/README.md

@@ -3,10 +3,17 @@
 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), adding support for
-audio streaming and audio formats like Ogg Vorbis, MPEG Audio and WAVE.
+(http://connect.creativelabs.com/openal/default.aspx).
 
-## Basic Use
+## 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:
 
@@ -167,6 +174,11 @@ 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

data/ext/seal/extconf.rb

@@ -12,7 +12,7 @@ mpg123_dir = File.join root_dir, 'mpg123'
 mpg123_src_dir = File.join mpg123_dir, 'src'
 mpg123_lib_dir = File.join mpg123_src_dir, 'libmpg123', '.libs'
 
-$defs << '-DNDEBUG'
+$defs << '-DNDEBUG' << '-DMPG123_NO_LARGENAME'
 $LDFLAGS << ' -s'
 
 unless File.exists?(File.join(mpg123_src_dir, 'config.h'))

data/include/seal.h

@@ -1,8 +1,4 @@
 /*
- * seal.h is part of the Scorched End Audio Library (SEAL) and is licensed
- * under the terms of the GNU Lesser General Public License. See COPYING
- * attached with the library.
- *
  * seal.h is the master header file for the Scorched End Audio Library. By
  * including seal.h, there will be no need to include the inidividual modules'
  * header files.

data/include/seal/src.h

@@ -166,10 +166,14 @@ seal_err_t SEAL_API seal_set_src_stream(seal_src_t*, seal_stream_t*);
 seal_err_t SEAL_API seal_feed_efs(seal_src_t*, seal_efs_t*, int /*index*/);
 
 /*
- * Updates a streaming source. If the source is not up-to-date, the playback
- * will end before the end of the stream is reached. Does nothing if the
- * passed-in source is not a streaming source. Also does nothing if auto
- * update is on.
+ * Updates a streaming source by filling up the audio queue until it is full.
+ * If the source is not up-to-date, the playback will end before the end of
+ * the stream is reached. Does nothing if the passed-in source is not a
+ * streaming source. Also does nothing if auto update is on. When auto update
+ * is off, it is the caller's responsibility to handle cases where the consumer
+ * (OpenAL) consumes faster than the producer (the caller) produces and causes
+ * the playback to stop. Automatic sources automatically resume playing in such
+ * cases.
  *
  * @param src       the source to update
  */
@@ -453,6 +457,7 @@ struct seal_src_t
     size_t         queue_size   : 6;
     unsigned int   looping      : 1;
     unsigned int   automatic    : 1;
+    unsigned int   early_stop   : 1;
 };
 
 #endif /* _SEAL_SRC_H_ */

data/spec/seal/core_spec.rb

@@ -1,15 +1,27 @@
 require 'spec_helper'
 
 describe Seal do
-  it 'should initialize and finalize correctly on default device' do
-    expect do
-      Seal.startup
-      Seal.cleanup
-    end.to_not raise_error
-  end
+  context 'initially' do
+    # Examples in this group needs to call Seal.startup themselves instead of
+    # relying on it being implicitly called by the global before hook.
+    # Therefore, Seal must be finalized in order to avoid double startup, which
+    # may fail for some devices due to opening an already opened, busy device.
+    before { Seal.cleanup }
+    # Since there is a global after hook for Seal.cleanup, we insert this after
+    # hook before the global one so the global one will then cleans up
+    # properly.
+    prepend_after { Seal.startup }
+
+    it 'starts up and cleans up properly on default device' do
+      expect do
+        Seal.startup
+        Seal.cleanup
+      end.to_not raise_error
+    end
 
-  it 'should fail when trying to initialize non-existing device' do
-    expect { Seal.startup 'foo42' }.to raise_error SealError
+    it 'fails when trying to start up on non-existing device' do
+      expect { Seal.startup 'foo42' }.to raise_error SealError
+    end
   end
 
   it 'has only one instance of Listener' do

data/spec/seal/effect_slot_spec.rb

@@ -11,7 +11,7 @@ describe EffectSlot do
 
   it_validates 'the boolean attribute', :auto
   it_validates 'the float attribute', :gain, "[0, 1]"
-  it_defines 'boolean reader aliases', [:auto]
+  it_defines 'boolean reader aliases', %i(auto)
 
   it 'can initialize with an effect' do
     reverb = Reverb.new

data/spec/seal/reverb_spec.rb

@@ -30,7 +30,7 @@ describe Reverb do
   it_validates 'the float attribute', :reflections_delay, '[0, 0.3]'
   it_validates 'the float attribute', :reflections_gain, '[0, 3.16]'
   it_validates 'the float attribute', :room_rolloff_factor, '[0, 10]'
-  it_defines 'boolean reader aliases', [:hfdecay_limited]
+  it_defines 'boolean reader aliases', %i(hfdecay_limited)
 
   specify_preset_loading = -> mod do
     mod.constants.each do |const_sym|

data/spec/seal/source_spec.rb

@@ -28,7 +28,7 @@ describe Source do
   it_validates 'the boolean attribute', :auto
   it_validates 'the float attribute', :pitch, "[0, +inf.)"
   it_validates 'the float attribute', :gain, "[0, +inf.)"
-  it_defines 'boolean reader aliases', [:auto, :relative, :looping]
+  it_defines 'boolean reader aliases', %i(auto relative looping)
 
   it 'validates its queue size is in [2, 63]' do
     error_pattern = /Invalid parameter value/

data/src/rubyext.c

@@ -773,9 +773,13 @@ feed_efs(VALUE rsrc, VALUE rslot, VALUE rindex)
  *  call-seq:
  *      source.update   -> source
  *
- * Updates _source_. If _source_ is not up-to-date, the playback will end
- * before the end of the stream is reached. Does nothing if _source_ is not a
- * streaming source. Also does nothing if auto update is on.
+ * Updates a streaming _source_ by filling up the audio queue until it is full.
+ * If _source_ is not up-to-date, the playback will end before the end of the
+ * stream is reached. Does nothing if _source_ is not a streaming source. Also
+ * does nothing if auto update is on. When auto update is off, it is the
+ * caller's responsibility to handle cases where the consumer (OpenAL) consumes
+ * faster than the producer (the caller) produces and causes the playback to
+ * stop. Automatic sources automatically resume playing in such cases.
  */
 static
 VALUE update_src(VALUE rsrc)
@@ -1701,6 +1705,14 @@ get_listener()
     return rb_const_get(mSeal, rb_intern("LISTENER"));
 }
 
+/*
+ *  call-seq:
+ *      listener.move ->  listener
+ *
+ * Moves the listener (changes the position) based on the source velocity. This
+ * is a syntactic sugar for adding the velocity vector and position vector. See
+ * Source#move.
+ */
 static
 VALUE
 move_listener(VALUE rlistener)

data/src/seal/core.c

@@ -31,7 +31,7 @@ const char*
 SEAL_API
 seal_get_version(void)
 {
-    return "0.1.2";
+    return "0.1.3";
 }
 
 static

data/src/seal/src.c

@@ -27,6 +27,9 @@ static const size_t DEFAULT_CHUNK_SIZE = MIN_CHUNK_SIZE << 2;
 static const size_t MAX_CHUNK_SIZE     = CHUNK_STORAGE_CAP -
                                          CHUNK_STORAGE_CAP % MIN_CHUNK_SIZE;
 
+/*
+ * Checks if `val` is in the closed interval [`lower_bound`, `upper_bound`].
+ */
 static
 seal_err_t
 check_val_limit(int val, int lower_bound, int upper_bound)
@@ -39,13 +42,42 @@ check_val_limit(int val, int lower_bound, int upper_bound)
         return SEAL_OK;
 }
 
+/*
+ * Called when the state of a source is preemptively changed by a caller.
+ */
 static
 seal_err_t
-operate(seal_src_t* src, void (*op)(unsigned int))
+on_preemptive_state_change(seal_src_t* src)
 {
+    seal_err_t err;
+    seal_src_state_t state;
+
+    if ((err = seal_get_src_state(src, &state)) != SEAL_OK)
+        return err;
+
+    /* Set `early_stop` to true after playing so it will only be set to false
+     * when playback ended with the end of stream reached or the state is
+     * preemptively changed.
+     */
+    src->early_stop = state == SEAL_PLAYING ? 1 : 0;
+
+    return SEAL_OK;
+}
+
+/*
+ * Changes the source state by calling one of the four operations on a source.
+ */
+static
+seal_err_t
+change_state(seal_src_t* src, void (*op)(unsigned int))
+{
+    seal_err_t err;
+
     op(src->id);
+    if ((err = _seal_get_openal_err()) != SEAL_OK)
+        return err;
 
-    return _seal_get_openal_err();
+    return on_preemptive_state_change(src);
 }
 
 static
@@ -76,6 +108,9 @@ wait4updater(seal_src_t* src)
     }
 }
 
+/*
+ * The main routine for updater threads.
+ */
 static
 void*
 update(void* args)
@@ -85,11 +120,22 @@ update(void* args)
 
     while (alIsSource(src->id)) {
         seal_src_state_t state;
-        err = seal_get_src_state(src, &state);
-        if (err != SEAL_OK || state != SEAL_PLAYING)
-            break;
+
+        /* Check source state before checking if interrupted by caller. */
+        if ((err = seal_get_src_state(src, &state)) != SEAL_OK)
+           break;
+        if (state != SEAL_PLAYING) {
+            /* Early stopping, most likely due to I/O load. Restart playing. */
+            if (src->early_stop) {
+                if ((err = change_state(src, alSourcePlay)) != SEAL_OK)
+                    break;
+            } else {
+                break;
+            }
+        }
         if ((err = seal_update_src(src)) != SEAL_OK)
             break;
+
         _seal_sleep(50);
     }
 
@@ -119,6 +165,10 @@ unqueue_bufs(seal_src_t* src, int nbufs, unsigned int* bufs)
     return queue_op(src, nbufs, bufs, alSourceUnqueueBuffers);
 }
 
+/*
+ * Cleans the queue and free any allocated buffers in the queue. This function
+ * assumes the source is stopped at the time of calling.
+ */
 static
 seal_err_t
 clean_queue(seal_src_t* src)
@@ -151,8 +201,9 @@ clean_queue(seal_src_t* src)
 }
 
 /*
- * Stopping a source will mark all the buffers in its queue processed so that
- * they can be unqueued.
+ * Cleans the queue after stopping the source. A stopped source will have all
+ * the buffers in its queue marked as processed so that they can be unqueued.
+ * This function assumes the source is playing at the time of calling.
  */
 static
 seal_err_t
@@ -160,7 +211,7 @@ stop_then_clean_queue(seal_src_t* src)
 {
     seal_err_t err;
 
-    if ((err = operate(src, alSourceStop)) != SEAL_OK)
+    if ((err = change_state(src, alSourceStop)) != SEAL_OK)
         return err;
 
     return clean_queue(src);
@@ -178,6 +229,10 @@ restart_queuing(seal_src_t* src)
     return seal_rewind_stream(src->stream);
 }
 
+/*
+ * This does the same thing as `stop_then_clean_queue` except it works for
+ * sources in any state at the time of calling.
+ */
 static
 seal_err_t
 empty_queue(seal_src_t* src)
@@ -185,7 +240,7 @@ empty_queue(seal_src_t* src)
     seal_err_t err;
 
     /* Need to be playing first in order to become stopped. */
-    if ((err = operate(src, alSourcePlay)) != SEAL_OK)
+    if ((err = change_state(src, alSourcePlay)) != SEAL_OK)
         return err;
 
     return stop_then_clean_queue(src);
@@ -210,11 +265,13 @@ seal_init_src(seal_src_t* src)
     if (err == SEAL_OK) {
         src->buf = 0;
         src->stream = 0;
+        /* The id of the thread that is updating the source. */
         src->updater = 0;
         src->chunk_size = DEFAULT_CHUNK_SIZE;
         src->queue_size = DEFAULT_QUEUE_SIZE;
         src->looping = 0;
         src->automatic = 1;
+        src->early_stop = 0;
     }
 
     return err;
@@ -257,18 +314,23 @@ seal_play_src(seal_src_t* src)
         /* Stream some data so plackback can start immediately. */
         if ((err = seal_update_src(src)) != SEAL_OK)
             return err;
+        /* Actually start playing. */
+        if ((err = change_state(src, alSourcePlay)) != SEAL_OK)
+            return err;
+        /* Create background updater for automatic sources. */
         if (src->automatic)
             src->updater = _seal_create_thread(update, src);
+        return SEAL_OK;
+    } else {
+        return change_state(src, alSourcePlay);
     }
-
-    return operate(src, alSourcePlay);
 }
 
 seal_err_t
 SEAL_API
 seal_pause_src(seal_src_t* src)
 {
-    return operate(src, alSourcePause);
+    return change_state(src, alSourcePause);
 }
 
 seal_err_t
@@ -277,7 +339,10 @@ seal_stop_src(seal_src_t* src)
 {
     seal_err_t err;
 
-    if ((err = operate(src, alSourceStop)) == SEAL_OK && src->stream != 0)
+    if ((err = change_state(src, alSourceStop)) != SEAL_OK)
+       return err;
+
+    if (src->stream != 0)
         /* Already stopped so all buffers are proccessed. */
         if ((err = clean_queue(src)) == SEAL_OK)
             err = seal_rewind_stream(src->stream);
@@ -299,7 +364,7 @@ seal_rewind_src(seal_src_t* src)
                 return err;
     }
 
-    return operate(src, alSourceRewind);
+    return change_state(src, alSourceRewind);
 }
 
 seal_err_t
@@ -312,13 +377,17 @@ seal_detach_src_audio(seal_src_t* src)
         return err;
 
     /* Sets the state to `SEAL_INITIAL' for consistency. */
-    if ((err = operate(src, alSourceRewind)) != SEAL_OK)
+    if ((err = change_state(src, alSourceRewind)) != SEAL_OK)
         return err;
 
-    if ((err = _seal_seti(src, AL_BUFFER, AL_NONE, alSourcei)) == SEAL_OK) {
-        src->buf = 0;
-        src->stream = 0;
-    }
+    if ((err = _seal_seti(src, AL_BUFFER, AL_NONE, alSourcei)) != SEAL_OK)
+        return err;
+
+    if ((err = on_preemptive_state_change(src)) != SEAL_OK)
+        return err;
+
+    src->buf = 0;
+    src->stream = 0;
 
     return err;
 }
@@ -486,6 +555,7 @@ start_streaming:
             goto start_streaming;
         /* End of stream reached. */
         } else {
+            src->early_stop = 0;
             break;
         }
     } /* for (;;) */

metadata

@@ -1,36 +1,32 @@
 --- !ruby/object:Gem::Specification
 name: seal
 version: !ruby/object:Gem::Version
-  version: 0.1.2
-  prerelease: 
+  version: 0.1.3
 platform: ruby
 authors:
 - Su Zhang
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-01-25 00:00:00.000000000 Z
+date: 2013-06-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -38,7 +34,6 @@ dependencies:
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
@@ -46,55 +41,51 @@ dependencies:
 - !ruby/object:Gem::Dependency
   name: guard-rspec
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
   name: rb-inotify
   requirement: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
-    none: false
     requirements:
-    - - ! '>='
+    - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: ! "    Seal is a library for 3D audio rendering and manipulation, supporting\n
-  \   effects such as direction and distance attenuation, the simulation of the\n
-  \   Doppler effect and reverberation. It is built on top of OpenAL, adding\n    support
-  for audio streaming and audio formats like Ogg Vorbis, MPEG Audio\n    and WAVE.\n"
+description: |2
+      Seal is a library for 3D audio rendering and manipulation, supporting
+      effects such as direction and distance attenuation, the simulation of the
+      Doppler effect and reverberation. It is built on top of OpenAL, adding
+      support for audio streaming and audio formats like Ogg Vorbis, MPEG Audio
+      and WAVE.
 email: me@zhang.su
 executables: []
 extensions:
@@ -525,41 +516,39 @@ files:
 homepage: https://github.com/zhangsu/seal
 licenses:
 - WTFPL
+metadata: {}
 post_install_message: Enjoy!
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ~>
+  - - '>='
     - !ruby/object:Gem::Version
-      version: '1.9'
+      version: 1.9.2
 required_rubygems_version: !ruby/object:Gem::Requirement
-  none: false
   requirements:
-  - - ! '>='
+  - - '>='
     - !ruby/object:Gem::Version
       version: '0'
 requirements:
 - libopenal
 - a sound card
 rubyforge_project: 
-rubygems_version: 1.8.24
+rubygems_version: 2.0.0
 signing_key: 
-specification_version: 3
+specification_version: 4
 summary: An OpenAL-based 3D audio library
 test_files:
 - spec/seal/buffer_spec.rb
 - spec/seal/core_spec.rb
-- spec/seal/stream_spec.rb
+- spec/seal/effect_slot_spec.rb
 - spec/seal/listener_spec.rb
 - spec/seal/reverb_spec.rb
-- spec/seal/effect_slot_spec.rb
 - spec/seal/source_spec.rb
-- spec/support/movable_object.rb
+- spec/seal/stream_spec.rb
+- spec/spec_helper.rb
+- spec/support/attribute_examples.rb
 - spec/support/audio_object_with_format.rb
 - spec/support/boolean_reader_aliases.rb
-- spec/support/attribute_examples.rb
-- spec/spec_helper.rb
-has_rdoc: yard
+- spec/support/movable_object.rb