catori 0.2.5

data/ext/audiofile/audiofile.rd

@@ -0,0 +1,265 @@
+=begin RD
+
+= ruby-audiofile
+== a ruby binding to the audiofile library
+== The underlying library
+
+The ((<"http://dreamscape.68k.org/~michael/audiofile"|audiofile library>))
+was originally proprietary to SGI, and was used in Irix to read and
+write audio files of various types: wav, aiff, au, etc. After a bit of coding
+by Michael Pruett, and a few more things, it's no longer proprietary, though 
+some parts are not yet in existence. We'll talk about that later. But here's 
+
+=== What audiofile does:
+
+* Reads audio files of various types 
+* Supports mu-law and A-law compression and uncompressed files
+* Provides information on them, such as sampling rate, sample type, etc.
+* Can switch byte order on the fly while reading, for user convenience
+* Writes audio files
+* Supports weird extensions (e.g. instruments in AIFF files, loops in WAV files)
+
+=== But audiofile doesn't:
+
+* Read MP3's
+* Read Vorbis files (see ((<"http://www.xiph.org/ogg/vorbis/">)) for that)
+* Write either of these
+* Resample files on the fly while writing or reading (yet)
+* Change sample formats or compression on the fly (yet)
+* Support multitrack files (yet). It does support multiple ((*channels*)),
+  i.e. stereo and whatnot, but doesn't support any formats yet that can store
+  multiple ((*tracks*)).
+
+== This binding
+
+This extension is a binding of the audiofile library to the Ruby language. With
+the aid of this super-wonderful extension, you can do everything you could do
+with audiofile in Ruby, except:
+
+=== Things supported by audiofile, but not ruby-audiofile
+
+* reading non-raw files in a raw way
+* handling errors elegantly (error handling works fairly well, but may
+  need changes)
+* querying the capabilities of the library itself (afQuery)
+* messing with loops, instruments, text data, or anything but the audio itself
+* doing anything that audiofile has API for, but doesn't actually support
+
+The last item may need a small bit of explanation: there are a number of 
+functions declared in audiofile.h (or commented out) which show that the
+author has a clear idea of what it will look like to the user of the library
+to use these not-yet-supported features, but there's not actually any code
+behind these declarations. 
+
+== ruby-audiofile version 0.2.1
+
+Version 0.2 adds file writing support, and fixes a bug with #read where
+it returned half the data it was supposed to. Also the API has changed
+some; the real_ prefixes no longer exist and there is a new virtual_
+prefix. This makes code using ruby-audiofile shorter and more succinct.
+
+Version 0.2.1 takes out a couple of debugging printf's i accidentally left in,
+and changes the width/width= methods to bits/bits= to fit better with
+Linux::SoundDSP. Minor documentation changes as well.
+
+Version 0.2.2 has more documentation changes, and an update to my email
+address.
+
+== How to install
+  ruby extconf.rb
+  make
+  sudo make install
+
+== How to use
+
+In your scripts,
+  require 'audiofile'
+This defines the AudioFile class, which has the following methods:
+
+=== AudioFile class
+
+--- AudioFile.new( filename, [mode] )
+--- AudioFile.open( filename, [mode] )
+Open a new AudioFile and return it. The mode is either "r" or "w" - for read or
+write.
+
+If you open a file for writing, you must set the following properties before
+writing to the file:
+
+* rate
+* bits
+* channels
+* byte_order
+* compression
+* file_format
+* sample_format
+
+If you do not set these properties before calling the #write method, the
+results are unspecified.
+
+--- AudioFile#close
+Close the file.
+
+--- AudioFile#read( [frames] )
+Read frames frames from the file. A ((:frame:)) is one sample for each channel.
+So in a 44100Hz, 16-bit, stereo file, a frame would take four bytes: two for 
+the left channel, and two for the right. (Two bytes is 16 bits of course.)
+This returns a new string every time, so if you're reading many times from an
+audio file, read_into is suggested. That way your script will not grow huge in
+memory.
+
+--- AudioFile#read_into( string )
+Read into string from the file. This replaces the contents of the string by 
+reading the largest number of frames that will fit into the current length of
+the string. It returns the number of bytes actually read. Example:
+  string = " " * 32
+  file.read_into(string)
+
+--- AudioFile#write( string )
+Write the string to the file. See the note under #open: in short, you must set
+the properties of the file before writing to it.
+
+Also note that both #read_into and #write round to the frame. That is,
+read_into will only read as many whole frames as fit into the string you give
+it, and write will only write as many whole frames as are contained in the
+string you pass to it.
+
+--- AudioFile#flush
+Flush the write buffers for the file.
+
+--- AudioFile#pos
+Returns the current position inside the file, in frames. (See #read about
+what frames are.)
+
+--- AudioFile#pos=( [new_pos] )
+Move to a new position inside the file. The position is specified in frames.
+You cannot move backwards inside the file; #pos= will throw an exception if you
+do. 
+
+--- AudioFile#frame_count
+Returns how many frames are in this file.
+
+--- AudioFile#virtual_byte_order=( [new_byte_order] )
+Sets the virtual byte order. new_byte_order should be either
+AudioFile::BIG_ENDIAN or AudioFile::LITTLE_ENDIAN. 
+
+When you read from the file, this byte order is the one the results will come
+back in. So if you are reading a little-endian file and you use
+#virtual_byte_order= AudioFile::BIG_ENDIAN, then #read, the data you get will
+be in big-endian byte order, because the library will switch the bytes on the
+fly.
+
+Conversely, if you are writing a file, and you set the virtual byte order,
+audiofile will take the bytes you give it in the virtual byte order, and swap
+them if needed in order to get them into the file in the real byte order.
+
+--- AudioFile#virtual_byte_order
+Returns the virtual byte order. This will be one of:
+* AudioFile::BIG_ENDIAN
+* AudioFile::LITTLE_ENDIAN
+
+--- AudioFile#byte_order
+Returns the real byte order. See the constants above. This is the byte
+order in which the file is stored and does not change when you use
+#virtual_byte_order=.
+
+--- AudioFile#byte_order=
+Sets the byte order in which the file will be written. For use when writing
+files only. Use before actually writing to the file.
+
+--- AudioFile#compression
+Returns the compression type, which will be one of:
+* AudioFile::UNKNOWN
+* AudioFile::NONE
+* AudioFile::G722
+* AudioFile::G711_ULAW
+* AudioFile::G711_ALAW
+
+Or one of these, which are detected but unsupported by the audiofile library:
+* AudioFile::APPLE_ACE2
+* AudioFile::APPLE_ACE8
+* AudioFile::APPLE_MAC3
+* AudioFile::APPLE_MAC6
+* AudioFile::G726
+* AudioFile::G728
+* AudioFile::DVI_AUDIO
+* AudioFile::GSM
+* AudioFile::FS1016
+
+--- AudioFile#compression=
+Sets the compression type. See the constants above. For use when
+writing files only. Use before actually writing to the file.
+
+--- AudioFile#sample_format
+Returns the sample format, which will be one of:
+* AudioFile::TWOS_COMPLEMENT
+* AudioFile::UNSIGNED
+* AudioFile::FLOAT
+* AudioFile::DOUBLE
+
+--- AudioFile#sample_format=
+Sets the sample format. See the constants above. For use when
+writing files only. Use before actually writing to the file.
+
+--- AudioFile#bits
+Returns the number of bits in a sample. Commonly, this is 8 or 16. Some of the
+file formats supported support sample widths greater than 16, which are usually
+24 or 32. The default behavior is to pad 24-bit samples to 32 bits for speed of
+handling (and to expect padded samples when writing, thus throwing away every
+fourth byte). To change this, look for the EXPAND_3TO4 define in the source
+(audiofile.c, around line 90), change and recompile.
+
+--- AudioFile#bits=
+Sets the number of bits in a sample. For use when writing files only. Use
+before actually writing to the file.
+
+--- AudioFile#rate
+Returns the number of samples per second. (commonly 44100, 22050, etc.)
+
+--- AudioFile#rate=
+Sets the number of samples per second. For use when writing files
+only. Use before actually writing to the file.
+
+--- AudioFile#channels
+Returns the number of channels. (commonly 1 or 2)
+
+--- AudioFile#channels=
+Sets the number of channels. For use when writing files only. Use before
+actually writing to the file.
+
+--- AudioFile#pcm_mapping
+Returns an array containing four floats. See below.
+
+--- AudioFile#pcm_mapping=( param )
+param is an array containing four floats, corresponding to the slope, 
+intercept, minimum clip and maximum clip values. This alters how the library
+sees the samples. Example:
+  file.real_pcm_mapping = [0.0, 1.0, -1.0, 1.0]
+The numbers define a piecewise linear function through which sample values are
+mapped. By changing this, you can do things like make audiofile double all the
+sample values it reads on the fly before you see them.
+
+== About the virtual_ prefix on method names
+The audiofile library (ideally) supports complete virtualization of all
+parameters of a sound file (sampling frequency, sample type, compresson...)
+such that the library would translate on the fly from the format in the file to
+the format the user of the library wishes to see. All of this support isn't in
+place yet: in fact, the only thing that is virtualized right now is the byte
+order. So when complete virtualization is supported, this binding will have
+#virtual_sample_rate=, #virtual_sample_format=, etc. methods. Right now there's
+only #virtual_byte_order and #virtual_byte_order=.
+
+== Have fun with it!
+If you have any more questions about ruby-audiofile, you can look at the source
+(by the way, many thanks to matz for writing extensions before I did; I copied
+the structure of my extension from gdbm, which he wrote). Or you can ask me
+questions at ((<"mailto:jjenning@fastmail.fm"|jjenning@fastmail.fm>)).
+
+If you use this extension, I'd love to know! Email me and tell me.
+
+== Possible future features
+* querying the library for its capabilities. 
+* reading and writing non-strictly-audio data parts like instruments and loops.
+
+The methods that return constants will hopefully end up more elegant in
+some way.

data/ext/audiofile/extconf.rb

@@ -0,0 +1,8 @@
+require 'mkmf'
+
+dir_config("audiofile")
+if have_library("audiofile", "afOpenFile") and have_header("audiofile.h")
+    create_makefile("audiofile")
+else
+    print "*** ERROR: need to have all of this to compile this module\n"
+end

data/ext/audiofile/fail.rb

@@ -0,0 +1,22 @@
+require 'audiofile'
+
+# Version 0.2: This script now works OK and does not fail.
+# In an older version it caused Ruby to segfault (inside audiofile).
+
+# change for your setup.
+WORKING_AUDIO_FILE = "/home/jaredj/plasmoid.wav"
+
+begin
+    bytes_read = 10000
+    while bytes_read > 0
+        print bytes_read, " "
+        bytes_read = bytes_read - 1
+    end
+rescue
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    f.close
+rescue
+end

data/ext/audiofile/mkmf.log

@@ -0,0 +1,34 @@
+have_library: checking for afOpenFile() in -laudiofile... -------------------- yes
+
+"i686-pc-linux-gnu-gcc -o conftest -I. -I/usr/lib/ruby/1.8/i686-linux -I.  -O2 -march=athlon-xp -m3dnow -msse -mfpmath=sse -mmmx -pipe -fno-strict-aliasing  -fPIC conftest.c  -L'.' -L'/usr/lib' -Wl,-R'/usr/lib' -L.  -rdynamic -Wl,-export-dynamic     -lruby18-static -laudiofile  -ldl -lcrypt -lm   -lc"
+conftest.c: En la función ‘t’:
+conftest.c:3: error: ‘afOpenFile’ no se declaró aquí (primer uso en esta función)
+conftest.c:3: error: (Cada identificador no declarado solamente se reporta una vez
+conftest.c:3: error: ara cada funcion en la que aparece.)
+checked program was:
+/* begin */
+1: /*top*/
+2: int main() { return 0; }
+3: int t() { void ((*volatile p)()); p = (void ((*)()))afOpenFile; return 0; }
+/* end */
+
+"i686-pc-linux-gnu-gcc -o conftest -I. -I/usr/lib/ruby/1.8/i686-linux -I.  -O2 -march=athlon-xp -m3dnow -msse -mfpmath=sse -mmmx -pipe -fno-strict-aliasing  -fPIC conftest.c  -L'.' -L'/usr/lib' -Wl,-R'/usr/lib' -L.  -rdynamic -Wl,-export-dynamic     -lruby18-static -laudiofile  -ldl -lcrypt -lm   -lc"
+checked program was:
+/* begin */
+1: /*top*/
+2: int main() { return 0; }
+3: int t() { afOpenFile(); return 0; }
+/* end */
+
+--------------------
+
+have_header: checking for audiofile.h... -------------------- yes
+
+"i686-pc-linux-gnu-gcc -E -I. -I/usr/lib/ruby/1.8/i686-linux -I.  -O2 -march=athlon-xp -m3dnow -msse -mfpmath=sse -mmmx -pipe -fno-strict-aliasing  -fPIC  conftest.c -o conftest.i"
+checked program was:
+/* begin */
+1: #include <audiofile.h>
+/* end */
+
+--------------------
+

data/ext/audiofile/test.rb

@@ -0,0 +1,229 @@
+require './audiofile'
+
+# change for your setup.
+WORKING_AUDIO_FILE = "/home/jaredj/plasmoid.wav"
+WRITING_AUDIO_FILE = "/home/jaredj/plasmoid-new.wav"
+
+# this should be nonexistent, or try files with the wrong format, etc
+BOGUS_AUDIO_FILE = "/home/jaredj/wuhwiuthw4otwoti"
+
+begin 
+    one = AudioFile.new
+rescue
+    print "OK    ! illegal # parameters to AudioFile.new fails\n"
+    print "    ", $!, "\n\n"
+end
+
+begin
+    two = AudioFile.new WORKING_AUDIO_FILE
+    two.close
+    three = AudioFile.new WORKING_AUDIO_FILE,"r"
+    three.close
+rescue
+    print "FAILED! Opening #{WORKING_AUDIO_FILE} for reading\n"
+    print "    ", $!, "\n\n"
+end
+
+begin
+    three_half = AudioFile.open WORKING_AUDIO_FILE
+    three_half.close
+rescue
+    print "FAILED! AudioFile.open doesn't work\n"
+    print "    ", $!, "\n\n"
+end
+
+begin
+    AudioFile.open(WORKING_AUDIO_FILE) do |file|
+        a = 4
+    end
+rescue
+    print "FAILED! AudioFile.open with block doesn't work\n"
+    print "    ", $!, "\n\n"
+end
+
+
+
+
+begin 
+    four = AudioFile.new WORKING_AUDIO_FILE,"w"
+    four.close
+rescue
+    print "OK    ! Writing doesn't work without a FileSetup\n"
+    print "        (In this version, writing doesn't work at all)\n"
+    print "    ", $!, "\n\n"
+end
+
+begin
+    five = AudioFile.new WORKING_AUDIO_FILE,"foo"
+    five.close
+rescue
+    print "OK    ! AudioFile.new with nonsense mode fails\n"
+    print "    ", $!, "\n\n"
+end
+
+begin
+    six = AudioFile.new BOGUS_AUDIO_FILE
+rescue
+    print "OK    ! Opening nonexistent or unsupported files doesn't work\n"
+    print "    ", $!, "\n\n"
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    [
+     "pos",
+     "rate",
+     "bits",
+     "channels",
+     "byte_order", 
+     "compression", 
+     "file_format",
+     "sample_format",
+     "virtual_byte_order", 
+     "file_format_version",
+     "frame_count",
+     "frame_size",
+    ].each { |method|
+        print "    ", method, " = ", f.instance_eval(method), "\n"
+    }
+rescue
+    print "FAILED! Getting info about #{WORKING_AUDIO_FILE} doesn't work\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+end
+
+# take these $stdout.flush'es out and Ruby crashes when you run this script
+# for minimum case that causes the error, see fail.rb
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    string = " " * 10000;
+    bytes_read = 1
+    print "Reading from #{WORKING_AUDIO_FILE}... "
+    $stdout.flush
+    while bytes_read > 0
+        bytes_read = f.read_into(string)
+        print bytes_read, " "
+        $stdout.flush
+    end
+    print "\n"
+rescue
+    print "FAILED! Couldn't read #{WORKING_AUDIO_FILE} properly.\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    f.pos
+    f.pos=100
+rescue
+    print "FAILED! Couldn't seek/tell within #{WORKING_AUDIO_FILE}.\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    f.pos=100
+    f.pos=0
+rescue
+    print "OK    ! Couldn't seek backwards within #{WORKING_AUDIO_FILE}.\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    f.pcm_mapping= [0.1,0.9,0.1,0.9]
+rescue
+    print "FAILED! Changing PCM mapping doesn't work\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+end
+
+
+
+
+# writing tests
+
+begin
+    g = AudioFile.new WRITING_AUDIO_FILE, "w"
+rescue
+    print "FAILED! Couldn't open #{WRITING_AUDIO_FILE} for writing.\n"
+    print "    ", $!, "\n\n"
+ensure
+    g.close
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    g = AudioFile.new WRITING_AUDIO_FILE, "w"
+
+    g.rate= f.rate
+    g.bits= f.bits
+    g.channels= f.channels
+    g.byte_order= f.byte_order
+    g.compression= f.compression
+    g.file_format= f.file_format
+    g.sample_format= f.sample_format
+
+rescue
+    print "FAILED! Couldn't change things about #{WRITING_AUDIO_FILE} while writing.\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+    g.close
+end
+
+begin
+    g = AudioFile.new WRITING_AUDIO_FILE, "w"
+
+    g.rate= 44100
+    g.write "poit"
+    g.bits= 16
+rescue 
+    print "OK    ! Couldn't set things about a file after opening it for writing\n"
+    print "    ", $!, "\n\n"
+ensure
+    g.close
+end
+
+begin
+    f = AudioFile.new WORKING_AUDIO_FILE
+    g = AudioFile.new WRITING_AUDIO_FILE, "w"
+
+    g.rate= f.rate
+    g.bits= f.bits
+    g.channels= f.channels
+    g.byte_order= f.byte_order
+    g.compression= f.compression
+    g.file_format= f.file_format
+    g.sample_format= f.sample_format
+
+    print "Copying: "
+    bytes_read = 1
+    while(bytes_read != 0)
+        str = f.read 10000
+        bytes_read = str.length
+        print "read #{bytes_read} - "
+        $stdout.flush
+        bytes_written = g.write str
+        print "wrote #{bytes_written} - "
+    end
+    print "done!\n"
+rescue
+    print "FAILED! Couldn't write #{WRITING_AUDIO_FILE}\n"
+    print "    ", $!, "\n\n"
+ensure
+    f.close
+    g.close
+end
+
+puts "Now play #{WORKING_AUDIO_FILE} and #{WRITING_AUDIO_FILE}."
+puts "They should sound the same"