ruby-shout 2.2.0 → 2.2.1

data/README.textile

@@ -1,5 +1,9 @@
 h1. Ruby-Shout
 
+h2. Compatibility note
+
+If you have installed a previous version of ruby-shout you have to make shure the shout.o files aren't there any more. Otherwise the build will fail.
+
 h2. Purpose
 
 ruby-shout lets you send compressed audio over the network to an "Icecast":http://www.icecast.org/ streaming media server.
@@ -16,11 +20,73 @@ h2. Usage
 
 See example.rb. Run it like
 
-  ./example.rb test/test.mp3
+<pre><code>./example.rb spec/test.mp3
+</code></pre>
+
+h2. Ruby 1.9 and encoding
+
+Ruby 1.9 features really good encoding support: Each string has it's own explicit encoding. The default encoding for Icecast is ISO-8859-1 for station data and meta data.
+
+In order to make ruby-shout play nice with ruby 1.9 I added a Shout#charset setter and all string accessors for station data are wrapped:
+
+* setters convert the given string to the given charset
+* and store the original string, available under #original_..., for example #original_description. This is done because converting may alter your string (characters incompatible with conversion are just swallowed). That way you are able to get your original string back (should you need it) and the getter is enabled to:
+* getters convert the value back to the original encoding, determined by the #original_... method.
+
+The idea is: We want to guaranty that strings keep their encoding when assigning them via a Shout accessor. In case strings are not compatible with Icecasts charset we want to degrade as gracefully as possible. IMHO just dropping incompatible characters does this best (when being listed in an external YP directory these "???br?" things just look awful). If you want to make sure this doesn't happen you have to compare the value before and after assigning it (or just compare for example #description with #original_description).
+
+h3. Synopsis:
+
+<pre><code>s = Shout.new
+s.charset = 'UTF-8'
+s.description = 'dikşîne MUSłϾ'
+puts s.description              # => 'dikşîne MUSłϾ'
+
+s = Shout.new
+s.charset = 'ISO-8859-1'        # this is the default
+s.description = 'dikşîne MUSłϾ'
+puts s.description              # => 'dikîne MUSłϾ'
+puts s.original_description     # => 'dikşîne MUSłϾ'
+</code></pre>
+
+h3. Icecast charset config
+
+If you use s/th else than ISO-8859-1 you should configure your icecast accordingly: In the mount section set the charset:
+
+<pre><code><mount>
+  <mount-name>/your_station</mount-name>
+  <charset>UTF-8</charset>
+  ...
+</mount>
+</code></pre>
+
+or (in the latest icecast builds)
+
+<pre><code><mount>
+  <mount-name>/*</mount-name>
+  <charset>UTF-8</charset>
+  ...
+</mount>
+</code></pre>
+
+to set UTF-8 for all mountpoints.
+
+h2. Running the spec
+
+h3. General note: use rake spec:build
+
+Before each run you have to run the build specs first as the other specs use its output (the built gem).
+
+<pre><code>rake spec:build && rake spec
+</code></pre>
+
+h3. For the integration spec
+
+You need to have an icecast server running. Perhaps you want to adopt the server setting quite at the top of the intergration_spec.rb
 
 h2. Todo
 
-* proper unit tests (blush)
+* proper unit tests (blush) ; working on that
 
 h2. History & Credits
 
@@ -35,9 +101,9 @@ h2. Recent Changes
 * Included the "ruby 1.9 patch":http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/dev-ruby/ruby-shout/files/ruby-shout-2.1%2Bruby-1.9.patch?revision=1.1&view=markup although it seems to have "some issues":http://sources.gentoo.org/cgi-bin/viewvc.cgi/gentoo-x86/dev-ruby/ruby-shout/files/ruby-shout-2.1%2Bruby-1.9.patch?view=log. I hope to have fixed the issues with this:
 * Replaced STR2CSTR for StringValuePtr as STR2CSTR doesn't work for 1.9 any more
 * Added format = Shout::MP3 to the example as this is absolutely needed by the latest versions of libshout.
-* Added an integration test which builds and installs the gem and plays some sound on a local icecast server. I mainly did that because the old version of ruby-shout didn't even compile for ruby 1.9. Run with:
+* Added a build test which builds and installs the gem and an integration test that plays some sound on a local icecast server. Be sure to adopt the server setting before running. I mainly did that because the old version of ruby-shout didn't even compile for ruby 1.9.
 
-  rake test:integration
+* Added Ruby 1.9 encoding support.
 
 h2. State
 

data/Rakefile

@@ -1,13 +1,19 @@
 require 'rubygems'
 require 'rake/gempackagetask'
+require 'spec/rake/spectask'
 
-task :default => [:test]
+desc "Run spec with specdoc output"
+Spec::Rake::SpecTask.new do |t|
+  spec_files = Dir.glob('spec/*_spec.rb')
+  spec_files.delete 'spec/build_spec.rb'
+  t.spec_files = spec_files
+  t.spec_opts << '--format specdoc -c'
+end
 
-namespace :test do
-  desc "run the build integration test"
-  task :integration do
-    ruby "test/integration-test.rb"
-  end
+desc "Run the build spec"
+Spec::Rake::SpecTask.new 'spec:build' do |t|
+  t.spec_files = ['spec/build_spec.rb']
+  t.spec_opts << '--format specdoc -c'
 end
 
 begin
@@ -21,7 +27,7 @@ begin
     s.authors     = ["Jared Jennings", "Niko Dittmann"]
     s.require_paths = ["lib"]
     s.rubyforge_project = 'ruby-shout'
-    s.files       = FileList["[A-Z]*", "{ext}/*"]
+    s.files       = FileList["[A-Z]*", "{ext}/*", "{lib}/**/*"]
     
   end
 rescue LoadError

data/VERSION

@@ -1 +1 @@
-2.2.0
+2.2.1

data/ext/extconf.rb

@@ -1,11 +1,20 @@
 require 'mkmf'
 
+case 
+when RUBY_VERSION >= '1.9' then $CFLAGS += ' -DRUBY_1_9_x'
+when RUBY_VERSION <  '1.9' then $CFLAGS += ' -DRUBY_1_8_x'
+end
+
+if have_func('rb_thread_blocking_region')
+  $CFLAGS += " -DHAVE_RB_THREAD_BLOCKING_REGION"
+end
+
 dir_config("shout")
 have_library("ogg", "oggpack_writeinit")
 have_library("vorbis", "vorbis_dsp_clear")
 have_library("pthread", "pthread_create")
 if find_library("shout", "shout_init","/usr","/usr/local") and have_header("shout/shout.h")
-    create_makefile("shout")
+  create_makefile("shout_ext")
 else
-    print "*** ERROR: need to have libshout and shout/shout.h to compile this module\n"
+  print "*** ERROR: need to have libshout and shout/shout.h to compile this module\n"
 end

data/ext/{shout.c → shout_ext.c}

@@ -42,8 +42,8 @@
 #define DEFAULT_MOUNTPOINT "/default"
 
 #ifndef RSTRING_LEN
-#define RSTRING_LEN(str)	RSTRING(str)->len
-#define RSTRING_PTR(str)	RSTRING(str)->ptr
+#define RSTRING_LEN(str)        RSTRING(str)->len
+#define RSTRING_PTR(str)        RSTRING(str)->ptr
 #endif
 
 /*
@@ -74,10 +74,11 @@ static void Init_shout_error() {
                         INT2NUM(SHOUTERR_MALLOC));
         rb_define_const(cShoutError, "METADATA",
                         INT2NUM(SHOUTERR_METADATA));
-	rb_define_const(cShoutError, "BUSY",
-			INT2NUM(SHOUTERR_BUSY));
+        rb_define_const(cShoutError, "BUSY",
+                        INT2NUM(SHOUTERR_BUSY));
 }
 
+
 static void raise_shout_error(shout_t *conn) {
         rb_raise(cShoutError, "%d: %s", shout_get_errno(conn),
                                         shout_get_error(conn));
@@ -87,7 +88,7 @@ static void raise_shout_error(shout_t *conn) {
  * use shout_get_errno or shout_get_error on them.
  */
 static void raise_nonspecific_shout_error(int errno) {
-	rb_raise(cShoutError, "%d", errno);
+        rb_raise(cShoutError, "%d", errno);
 }
 
 /*
@@ -117,7 +118,7 @@ static VALUE _sh_metadata_add(VALUE self, VALUE name, VALUE value) {
         err = shout_metadata_add(m, StringValuePtr(name), StringValuePtr(value));
 
         if(err != SHOUTERR_SUCCESS) {
-		raise_nonspecific_shout_error(err);
+                raise_nonspecific_shout_error(err);
         }
 
         return value;
@@ -201,6 +202,17 @@ static VALUE _sh_connect(VALUE self) {
         return Qtrue;
 }
 
+
+#if HAVE_RB_THREAD_BLOCKING_REGION
+/* The new _sh_connect_non_blocking function (aka #connect_non_blocking method)
+ * wrapping _sh_connect in a rb_thread_blocking_region call.
+ */
+static VALUE _sh_connect_non_blocking(VALUE self) {
+        return rb_thread_blocking_region(_sh_connect, self, RUBY_UBF_IO, NULL);
+}
+#endif
+
+
 /* Disconnect from the server. */
 static VALUE _sh_disconnect(VALUE self) {
         int err;
@@ -214,22 +226,22 @@ static VALUE _sh_disconnect(VALUE self) {
         return Qtrue;
 }
 
-/* Returns true if connected, false otherwise, 
- * nil if something really crazy happened. 
+/* Returns true if connected, false otherwise,
+ * nil if something really crazy happened.
  */
 static VALUE _sh_connectedp(VALUE self) {
-	int err;
-	shout_connection *s;
-	GET_SC(self, s);
+        int err;
+        shout_connection *s;
+        GET_SC(self, s);
 
-	err = shout_get_connected(s->conn);
-	if(err == SHOUTERR_CONNECTED) {
-		return Qtrue;
-	} else if(err == SHOUTERR_UNCONNECTED) {
-		return Qfalse;
-	} else {
-		return Qnil;
-	}
+        err = shout_get_connected(s->conn);
+        if(err == SHOUTERR_CONNECTED) {
+                return Qtrue;
+        } else if(err == SHOUTERR_UNCONNECTED) {
+                return Qfalse;
+        } else {
+                return Qnil;
+        }
 }
 
 /* Send some data. to_send is a String containing the data to send. */
@@ -247,6 +259,33 @@ static VALUE _sh_send(VALUE self, VALUE to_send) {
         return Qtrue;
 }
 
+
+#if HAVE_RB_THREAD_BLOCKING_REGION
+/* The struct into which the arguments of _sh_send get packed
+ * to be able to wrap _sh_send in a rb_thread_blocking_region call. */
+typedef struct {
+        VALUE *self;
+        unsigned char *to_send;
+} SHOUT_SEND_ARGS;
+
+/* The function to unpack the arguments out of the struct after
+ * having been wrapped in the rb_thread_blocking_region call. */
+static VALUE _sh_send_non_block_unpack(SHOUT_SEND_ARGS *send_args) {
+        return _sh_send(send_args->self, send_args->to_send);
+}
+
+/* The new _sh_send_non_blocking function (aka #send_non_blocking method)
+ * packing the arguments of _sh_send in a struct and wrapping the _sh_send
+ * call into a rb_thread_blocking_region call. */
+static VALUE _sh_send_non_blocking(VALUE self, VALUE to_send) {
+        SHOUT_SEND_ARGS send_args;
+        send_args.self    = self;
+        send_args.to_send = (unsigned char *) to_send;
+        return rb_thread_blocking_region(_sh_send_non_block_unpack, &send_args, RUBY_UBF_IO, NULL);
+}
+#endif
+
+
 /* Sleep the necessary amount of time to play back the audio data sent since
  * the last call to #sync. After calling this, it's time to send more data. */
 static VALUE _sh_sync(VALUE self) {
@@ -398,6 +437,15 @@ VALUE _sh_description(VALUE self) {
         return rb_str_new2(value);
 }
 
+VALUE _sh_bitrate(VALUE self) {
+  const char *value;
+
+  shout_connection *s; GET_SC(self, s);
+
+  value = shout_get_audio_info(s->conn, SHOUT_AI_BITRATE);
+  return rb_str_new2(value);
+}
+
 /* Unimplemented: audio_info */
 
 /* audio_info and metadata should both be objects that always exist, and have
@@ -623,13 +671,25 @@ VALUE _sh_metadata_eq(VALUE self, VALUE meta) {
         return meta;
 }
 
+/* Set the 'bitrate' in the audio_info of the stream. */
+VALUE _sh_bitrate_eq(VALUE self, VALUE value) {
+        int err;
+        shout_connection *s; GET_SC(self, s);
+
+        Check_Type(value, T_STRING);
+        err = shout_set_audio_info(s->conn, SHOUT_AI_BITRATE, RSTRING_PTR(value));
+        if(err != SHOUTERR_SUCCESS) {
+                raise_shout_error(s->conn);
+        }
+        return value;
+}
 
 
 /*
 ----------------------------------------------------------------
 */
 
-void Init_shout()
+void Init_shout_ext()
 {
         cShout = rb_define_class("Shout", rb_cObject);
 
@@ -640,12 +700,22 @@ void Init_shout()
 
         rb_define_method(cShout, "initialize", _sh_initialize, -1);
         rb_define_method(cShout, "connect", _sh_connect, 0);
+
+        #if defined(HAVE_RB_THREAD_BLOCKING_REGION)
+        rb_define_method(cShout, "connect_non_blocking", _sh_connect_non_blocking, 0);
+        #endif
+
         rb_define_method(cShout, "open", _sh_connect, 0);
         rb_define_method(cShout, "disconnect", _sh_disconnect, 0);
         rb_define_method(cShout, "close", _sh_disconnect, 0);
-	rb_define_method(cShout, "connected?", _sh_connectedp, 0);
+        rb_define_method(cShout, "connected?", _sh_connectedp, 0);
 
         rb_define_method(cShout, "send", _sh_send, 1);
+
+        #if defined(HAVE_RB_THREAD_BLOCKING_REGION)
+        rb_define_method(cShout, "send_non_blocking", _sh_send_non_blocking, 1);
+        #endif
+
         rb_define_method(cShout, "sync", _sh_sync, 0);
         rb_define_method(cShout, "delay", _sh_delay, 0);
 
@@ -667,7 +737,8 @@ void Init_shout()
         rb_define_method(cShout, "url",       _sh_url,         0);
         rb_define_method(cShout, "genre",     _sh_genre,       0);
         rb_define_method(cShout, "description",_sh_description,0);
-	/* metadata getting is still unsupported. */
+        rb_define_method(cShout, "bitrate",   _sh_bitrate,     0);
+        /* metadata getting is still unsupported. */
         /* audio info thingy. */
         /* leave for version 2.2 */
 
@@ -690,10 +761,11 @@ void Init_shout()
         rb_define_method(cShout, "genre=",      _sh_genre_eq,       1);
         rb_define_method(cShout, "description=", _sh_description_eq,1);
         rb_define_method(cShout, "metadata=",   _sh_metadata_eq,    1);
+        rb_define_method(cShout, "bitrate=",    _sh_bitrate_eq,     1);
 
-	rb_define_const(cShout, "HTTP", INT2FIX(SHOUT_PROTOCOL_HTTP));
-	rb_define_const(cShout, "XAUDIOCAST", INT2FIX(SHOUT_PROTOCOL_XAUDIOCAST));
-	rb_define_const(cShout, "ICY", INT2FIX(SHOUT_PROTOCOL_ICY));
+        rb_define_const(cShout, "HTTP", INT2FIX(SHOUT_PROTOCOL_HTTP));
+        rb_define_const(cShout, "XAUDIOCAST", INT2FIX(SHOUT_PROTOCOL_XAUDIOCAST));
+        rb_define_const(cShout, "ICY", INT2FIX(SHOUT_PROTOCOL_ICY));
 
         rb_define_const(cShout, "MP3", INT2FIX(SHOUT_FORMAT_MP3));
         rb_define_const(cShout, "OGG", INT2FIX(SHOUT_FORMAT_OGG));

data/lib/shout.rb

@@ -0,0 +1,55 @@
+$LOAD_PATH << File.expand_path(File.dirname(__FILE__))
+require 'shout_ext'
+
+class Shout
+  attr_writer :charset
+
+  INT_ACCESSORS    = :port, :format
+  STRING_ACCESSORS = :host, :user, :username, :pass, :password, :protocol, :mount, :dumpfile,
+                     :agent, :user_agent, :public, :name, :url, :genre, :description, :bitrate
+
+  alias :ext_initialize :initialize
+  def initialize(opts={})
+    ext_initialize
+
+    (STRING_ACCESSORS + INT_ACCESSORS + [:charset]).each do |a|
+      self.__send__ :"#{a}=", opts[a] if opts[a]
+    end
+  end
+
+  STRING_ACCESSORS.each do |accessor|
+    attr_accessor :"original_#{accessor}"
+
+    alias :"raw_#{accessor}"  :"#{accessor}"
+    define_method accessor do
+      return nil unless orig_acc = self.__send__("original_#{accessor}")
+
+      decode self.__send__(:"raw_#{accessor}"), orig_acc
+    end
+
+    alias :"raw_#{accessor}=" :"#{accessor}="
+    define_method :"#{accessor}=" do |value|
+      self.__send__ "original_#{accessor}=", value
+
+      self.__send__ :"raw_#{accessor}=", encode(value)
+    end
+  end
+
+  def charset
+    @charset || ((format && format==Shout::MP3) ? 'ISO-8859-1' : 'UTF-8')
+  end
+
+  private
+    def encode(s)
+      return s unless s.is_a? String
+
+      s.encode(charset, :invalid => :replace, :undef => :replace, :replace => '')
+    end
+    def decode(s, orig_string)
+      return s unless s.is_a? String
+
+      orig_charset = orig_string.encoding.name
+      s.encode(orig_charset, charset, :invalid => :replace, :undef => :replace, :replace => '')
+    end
+
+end

metadata

@@ -1,70 +1,54 @@
---- !ruby/object:Gem::Specification 
+--- !ruby/object:Gem::Specification
 name: ruby-shout
-version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 2
-  - 2
-  - 0
-  version: 2.2.0
+version: !ruby/object:Gem::Version
+  version: 2.2.1
+  prerelease: 
 platform: ruby
-authors: 
+authors:
 - Jared Jennings
 - Niko Dittmann
 autorequire: 
 bindir: bin
 cert_chain: []
-
-date: 2010-09-05 00:00:00 +02:00
-default_executable: 
+date: 2011-11-15 00:00:00.000000000Z
 dependencies: []
-
-description: Ruby bindings for libshout 2, a "Library which can be used to write a source client like ices" for Icecast (http://www.icecast.org/download.php).
+description: Ruby bindings for libshout 2, a "Library which can be used to write a
+  source client like ices" for Icecast (http://www.icecast.org/download.php).
 email: mail@niko-dittmann.com
 executables: []
-
-extensions: 
+extensions:
 - ext/extconf.rb
-extra_rdoc_files: 
+extra_rdoc_files:
 - README.textile
-files: 
+files:
 - README.textile
 - Rakefile
 - VERSION
 - ext/extconf.rb
-- ext/shout.c
-- test/integration-test.rb
-has_rdoc: true
+- ext/shout_ext.c
+- lib/shout.rb
 homepage: http://github.com/niko/ruby-shout
 licenses: []
-
 post_install_message: 
-rdoc_options: 
-- --charset=UTF-8
-require_paths: 
+rdoc_options: []
+require_paths:
 - lib
-required_ruby_version: !ruby/object:Gem::Requirement 
+required_ruby_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
-required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
-  requirements: 
-  - - ">="
-    - !ruby/object:Gem::Version 
-      segments: 
-      - 0
-      version: "0"
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
 requirements: []
-
 rubyforge_project: ruby-shout
-rubygems_version: 1.3.7
+rubygems_version: 1.8.10
 signing_key: 
 specification_version: 3
 summary: Send audio over the network to an Icecast server
-test_files: 
-- test/integration-test.rb
+test_files: []

data/test/integration-test.rb

@@ -1,90 +0,0 @@
-# This test builds the gem (there where build errors on 1.9 without the patch),
-# installs it and starts a station on mountpoint /test.
-# You should have an icecast-server listening on 8000 (that's the default)
-# for incoming source connections.
-# Point your radio client to http://localhost:8000/test.
-# Look for the metadata being correctly set ('gromozek - melange').
-
-# test.mp3 is 'melange' by 'gromozek' http://ccmixter.org/files/gromozek/20114
-# licensed CC Attribution Noncommercial (3.0) http://creativecommons.org/licenses/by-nc/3.0/
-
-def base_dir
-  File.expand_path File.join(File.dirname(__FILE__), '..')
-end
-
-def version
-  File.open(File.join(base_dir, 'VERSION')).readline.strip
-end
-
-def remove_pkg
-  puts '=> removing pkg/'
-  command = %Q{
-    cd #{base_dir}
-    rm -rf pkg
-  }
-  `#{command}`
-end
-
-def clean_test_gem
-  puts '=> removing test/test_gem_installation/'
-  command = %Q{
-    cd #{base_dir}
-    rm -rf test/test_gem_installation
-  }
-  `#{command}`
-end
-
-def install_gem
-  puts '=> building the gem into pkg/ and installing into test/test_gem_installation/'
-  command = %Q{
-    cd #{base_dir}
-    rake build
-    gem install --no-test --no-rdoc --no-ri --install-dir test/test_gem_installation --bindir test/test_gem_installation pkg/ruby-shout-#{version}.gem
-  }
-  `#{command}`
-end
-
-clean_test_gem
-install_gem
-remove_pkg
-
-$LOAD_PATH.clear
-$LOAD_PATH << File.join(base_dir, "test/test_gem_installation/gems/ruby-shout-#{version}/lib")
-require 'shout'
-
-def test_all
-  blocksize = 16384
-
-  s = Shout.new
-  s.host = "localhost"
-  s.port = 8000
-  s.mount = "/test"
-  s.user = "source"
-  s.pass = "hackme"
-  s.format = Shout::MP3
-
-  s.connect
-
-  filename = File.join(File.dirname(__FILE__), 'test.mp3')
-
-  File.open(filename) do |file|
-    puts "=> sending data from #{filename}...\n     go check http://localhost:8000/test"
-    m = ShoutMetadata.new
-    m.add 'filename', filename
-    m.add 'artist', 'gromozek'
-    m.add 'title', 'melange'
-    s.metadata = m
-
-    while data = file.read(blocksize)
-      s.send data
-      print '.'
-      s.sync
-    end
-  end
-
-  s.disconnect
-ensure
-  clean_test_gem
-end
-
-test_all