ruby-groove 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8b837650a481fa113d43ffb9c2fcb0761e75344c
+  data.tar.gz: 8877ffbc45b368074456838bb975e34dce36bea0
+SHA512:
+  metadata.gz: 3d493bcece4b16e368bd7ebbce5fdc6785e54b9acdfc8180220b8d3fc8d512656501a7f9d3c14b12284721ae69b98c2cbc25a4cd412bcfc6d74748ebf0a19a5c
+  data.tar.gz: b90c52bf94c14c649edd67ec02246554bb54edb22fe91e2012da62d29b13d0976681bab93576192246d3b058a6b5fcb253a0ed0b6dc15ad2955a61996ccc0ccc

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 john muhl
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,68 @@
+ruby bindings to [libgroove][libgroove].
+
+## Installation
+
+First install [libgroove][libgroove] (see below) then:
+
+    gem install ruby-groove
+
+### libgroove
+
+#### Ubuntu, FreeBSD and Debian
+
+Ubuntu, FreeBSD and Debian users can use a [pre-built package][packages].
+
+#### Mac OS X
+
+Install with [Homebrew][brew]
+
+~~~ sh
+brew tap johnmuhl/libgroove
+brew install libgroove
+~~~
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Generating the bindings
+
+[ffi_gen][ffi_gen] automatically creates the bindings from the
+[libgroove][libgroove] header files. Use the included [Vagrantfile][vagrant]
+and the steps below to setup a build environment.
+
+~~~ sh
+# host computer
+cd ruby-groove
+vagrant up
+vagrant ssh
+~~~
+
+~~~ sh
+# virtual machine
+sudo apt-add-repository ppa:andrewrk/libgroove
+sudo apt-get update
+sudo apt-get install libgroove-dev libgrooveplayer-dev libgrooveloudness-dev libgroovefingerprinter-dev ruby ruby-dev clang libclang-dev llvm llvm-dev
+sudo ln -sv /usr/lib/llvm-3.4/lib/libclang.so /usr/lib/libclang.so
+sudo gem install bundler
+cd /vagrant
+bundle install
+rake generate_ffi
+~~~
+
+Bindings are output to `lib`.
+
+## Contributing
+
+1. [Fork it](https://github.com/johnmuhl/ruby-groove/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+[brew]: http://brew.sh/
+[ffi_gen]: https://github.com/neelance/ffi-gen
+[libebur128]: https://github.com/jiixyj/libebur128
+[libgroove]: https://github.com/andrewrk/libgroove
+[packages]: https://github.com/andrewrk/libgroove#pre-built-packages
+[vagrant]: http://www.vagrantup.com/

data/lib/groove.rb

@@ -0,0 +1,5 @@
+require "groove/groove"
+require "groove/fingerprinter"
+require "groove/loudness"
+require "groove/player"
+require "groove/version"

data/lib/groove/fingerprinter.rb

@@ -0,0 +1,184 @@
+# Generated by ffi_gen. Please do not change this file by hand.
+
+require 'ffi'
+
+module Groove::Fingerprinter
+  extend FFI::Library
+  ffi_lib 'groovefingerprinter'
+  
+  def self.attach_function(name, *_)
+    begin; super; rescue FFI::NotFoundError => e
+      (class << self; self; end).class_eval { define_method(name) { |*_| raise e } }
+    end
+  end
+  
+  # (Not documented)
+  # 
+  # = Fields:
+  # :fingerprint ::
+  #   (FFI::Pointer(*Int32T)) raw fingerprint. A fingerprint is an array of signed 32-bit integers.
+  # :fingerprint_size ::
+  #   (Integer) the number of 32-bit integers in the fingerprint array
+  # :duration ::
+  #   (Float) how many seconds long this song is
+  # :item ::
+  #   (FFI::Pointer(*GroovePlaylistItem)) the playlist item that this info applies to.
+  #   When this is NULL this is the end-of-playlist sentinel and
+  #   other properties are undefined.
+  class GrooveFingerprinterInfo < FFI::Struct
+    layout :fingerprint, :pointer,
+           :fingerprint_size, :int,
+           :duration, :double,
+           :item, :pointer
+  end
+  
+  # (Not documented)
+  # 
+  # = Fields:
+  # :info_queue_size ::
+  #   (Integer) maximum number of GrooveFingerprinterInfo items to store in this
+  #   fingerprinter's queue. this defaults to MAX_INT, meaning that
+  #   the fingerprinter will cause the decoder to decode the entire
+  #   playlist. if you want to instead, for example, obtain fingerprints
+  #   at the same time as playback, you might set this value to 1.
+  # :sink_buffer_size ::
+  #   (Integer) how big the sink buffer should be, in sample frames.
+  #   groove_fingerprinter_create defaults this to 8192
+  # :playlist ::
+  #   (FFI::Pointer(*GroovePlaylist)) read-only. set when attached and cleared when detached
+  class GrooveFingerprinter < FFI::Struct
+    layout :info_queue_size, :int,
+           :sink_buffer_size, :int,
+           :playlist, :pointer
+  end
+  
+  # (Not documented)
+  # 
+  # @method fingerprinter_create()
+  # @return [GrooveFingerprinter] 
+  # @scope class
+  attach_function :fingerprinter_create, :groove_fingerprinter_create, [], GrooveFingerprinter
+  
+  # (Not documented)
+  # 
+  # @method fingerprinter_destroy(printer)
+  # @param [GrooveFingerprinter] printer 
+  # @return [nil] 
+  # @scope class
+  attach_function :fingerprinter_destroy, :groove_fingerprinter_destroy, [GrooveFingerprinter], :void
+  
+  # once you attach, you must detach before destroying the playlist
+  # 
+  # @method fingerprinter_attach(printer, playlist)
+  # @param [GrooveFingerprinter] printer 
+  # @param [FFI::Pointer(*GroovePlaylist)] playlist 
+  # @return [Integer] 
+  # @scope class
+  attach_function :fingerprinter_attach, :groove_fingerprinter_attach, [GrooveFingerprinter, :pointer], :int
+  
+  # (Not documented)
+  # 
+  # @method fingerprinter_detach(printer)
+  # @param [GrooveFingerprinter] printer 
+  # @return [Integer] 
+  # @scope class
+  attach_function :fingerprinter_detach, :groove_fingerprinter_detach, [GrooveFingerprinter], :int
+  
+  # returns < 0 on error, 0 on aborted (block=1) or no info ready (block=0),
+  # 1 on info returned.
+  # When you get info you must free it with groove_fingerprinter_free_info.
+  # 
+  # @method fingerprinter_info_get(printer, info, block)
+  # @param [GrooveFingerprinter] printer 
+  # @param [GrooveFingerprinterInfo] info 
+  # @param [Integer] block 
+  # @return [Integer] 
+  # @scope class
+  attach_function :fingerprinter_info_get, :groove_fingerprinter_info_get, [GrooveFingerprinter, GrooveFingerprinterInfo, :int], :int
+  
+  # (Not documented)
+  # 
+  # @method fingerprinter_free_info(info)
+  # @param [GrooveFingerprinterInfo] info 
+  # @return [nil] 
+  # @scope class
+  attach_function :fingerprinter_free_info, :groove_fingerprinter_free_info, [GrooveFingerprinterInfo], :void
+  
+  # returns < 0 on error, 0 on no info ready, 1 on info ready
+  # if block is 1, block until info is ready
+  # 
+  # @method fingerprinter_info_peek(printer, block)
+  # @param [GrooveFingerprinter] printer 
+  # @param [Integer] block 
+  # @return [Integer] 
+  # @scope class
+  attach_function :fingerprinter_info_peek, :groove_fingerprinter_info_peek, [GrooveFingerprinter, :int], :int
+  
+  # get the position of the printer head
+  # both the current playlist item and the position in seconds in the playlist
+  # item are given. item will be set to NULL if the playlist is empty
+  # you may pass NULL for item or seconds
+  # 
+  # @method fingerprinter_position(printer, item, seconds)
+  # @param [GrooveFingerprinter] printer 
+  # @param [FFI::Pointer(**GroovePlaylistItem)] item 
+  # @param [FFI::Pointer(*Double)] seconds 
+  # @return [nil] 
+  # @scope class
+  attach_function :fingerprinter_position, :groove_fingerprinter_position, [GrooveFingerprinter, :pointer, :pointer], :void
+  
+  # Compress and base64-encode a raw fingerprint
+  # 
+  # The caller is responsible for freeing the returned pointer using
+  # groove_fingerprinter_dealloc().
+  # 
+  # Parameters:
+  #  - fp: pointer to an array of signed 32-bit integers representing the raw
+  #        fingerprint to be encoded
+  #  - size: number of items in the raw fingerprint
+  #  - encoded_fp: pointer to a pointer, where the encoded fingerprint will be
+  #                stored
+  # 
+  # Returns:
+  #  - 0 on success, < 0 on error
+  # 
+  # @method fingerprinter_encode(fp, size, encoded_fp)
+  # @param [FFI::Pointer(*Int32T)] fp 
+  # @param [Integer] size 
+  # @param [FFI::Pointer(**CharS)] encoded_fp 
+  # @return [Integer] 
+  # @scope class
+  attach_function :fingerprinter_encode, :groove_fingerprinter_encode, [:pointer, :int, :pointer], :int
+  
+  # Uncompress and base64-decode an encoded fingerprint
+  # 
+  # The caller is responsible for freeing the returned pointer using
+  # groove_fingerprinter_dealloc().
+  # 
+  # Parameters:
+  #  - encoded_fp: Pointer to an encoded fingerprint
+  #  - encoded_size: Size of the encoded fingerprint in bytes
+  #  - fp: Pointer to a pointer, where the decoded raw fingerprint (array
+  #        of signed 32-bit integers) will be stored
+  #  - size: Number of items in the returned raw fingerprint
+  # 
+  # Returns:
+  #  - 0 on success, < 0 on error
+  # 
+  # @method fingerprinter_decode(encoded_fp, fp, size)
+  # @param [String] encoded_fp 
+  # @param [FFI::Pointer(**Int32T)] fp 
+  # @param [FFI::Pointer(*Int)] size 
+  # @return [Integer] 
+  # @scope class
+  attach_function :fingerprinter_decode, :groove_fingerprinter_decode, [:string, :pointer, :pointer], :int
+  
+  # (Not documented)
+  # 
+  # @method fingerprinter_dealloc(ptr)
+  # @param [FFI::Pointer(*Void)] ptr 
+  # @return [nil] 
+  # @scope class
+  attach_function :fingerprinter_dealloc, :groove_fingerprinter_dealloc, [:pointer], :void
+  
+end

data/lib/groove/groove.rb

@@ -0,0 +1,768 @@
+# Generated by ffi_gen. Please do not change this file by hand.
+
+require 'ffi'
+
+module Groove
+  extend FFI::Library
+  ffi_lib 'groove'
+  
+  def self.attach_function(name, *_)
+    begin; super; rescue FFI::NotFoundError => e
+      (class << self; self; end).class_eval { define_method(name) { |*_| raise e } }
+    end
+  end
+  
+  GROOVE_LOG_ERROR = 16
+  
+  GROOVE_LOG_WARNING = 24
+  
+  GROOVE_LOG_INFO = 32
+  
+  GROOVE_CH_FRONT_LEFT = 0x00000001
+  
+  GROOVE_CH_FRONT_RIGHT = 0x00000002
+  
+  GROOVE_CH_FRONT_CENTER = 0x00000004
+  
+  GROOVE_TAG_MATCH_CASE = 1
+  
+  GROOVE_TAG_DONT_OVERWRITE = 16
+  
+  GROOVE_TAG_APPEND = 32
+  
+  GROOVE_EVERY_SINK_FULL = 0
+  
+  GROOVE_ANY_SINK_FULL = 1
+  
+  GROOVE_BUFFER_NO = 0
+  
+  GROOVE_BUFFER_YES = 1
+  
+  GROOVE_BUFFER_END = 2
+  
+  # (Not documented)
+  # 
+  # @method init()
+  # @return [Integer] 
+  # @scope class
+  attach_function :init, :groove_init, [], :int
+  
+  # call at the end of your program to clean up. after calling this
+  # you may no longer use this API.
+  # 
+  # @method finish()
+  # @return [nil] 
+  # @scope class
+  attach_function :finish, :groove_finish, [], :void
+  
+  # enable/disable logging of errors
+  # 
+  # @method set_logging(level)
+  # @param [Integer] level 
+  # @return [nil] 
+  # @scope class
+  attach_function :set_logging, :groove_set_logging, [:int], :void
+  
+  # get the channel count for the channel layout
+  # 
+  # @method channel_layout_count(channel_layout)
+  # @param [Integer] channel_layout 
+  # @return [Integer] 
+  # @scope class
+  attach_function :channel_layout_count, :groove_channel_layout_count, [:ulong], :int
+  
+  # get the default channel layout based on the channel count
+  # 
+  # @method channel_layout_default(count)
+  # @param [Integer] count 
+  # @return [Integer] 
+  # @scope class
+  attach_function :channel_layout_default, :groove_channel_layout_default, [:int], :ulong
+  
+  # (Not documented)
+  # 
+  # <em>This entry is only for documentation and no real method. The FFI::Enum can be accessed via #enum_type(:groove_sample_format).</em>
+  # 
+  # === Options:
+  # :fmt_none ::
+  #   
+  # :fmt_u8 ::
+  #   
+  # :fmt_s16 ::
+  #   unsigned 8 bits
+  # :fmt_s32 ::
+  #   signed 16 bits
+  # :fmt_flt ::
+  #   signed 32 bits
+  # :fmt_dbl ::
+  #   float (32 bits)
+  # :fmt_u8p ::
+  #   double (64 bits)
+  # :fmt_s16p ::
+  #   unsigned 8 bits, planar
+  # :fmt_s32p ::
+  #   signed 16 bits, planar
+  # :fmt_fltp ::
+  #   signed 32 bits, planar
+  # :fmt_dblp ::
+  #   float (32 bits), planar
+  # 
+  # @method _enum_groove_sample_format_
+  # @return [Symbol]
+  # @scope class
+  enum :groove_sample_format, [
+    :fmt_none, -1,
+    :fmt_u8, 0,
+    :fmt_s16, 1,
+    :fmt_s32, 2,
+    :fmt_flt, 3,
+    :fmt_dbl, 4,
+    :fmt_u8p, 5,
+    :fmt_s16p, 6,
+    :fmt_s32p, 7,
+    :fmt_fltp, 8,
+    :fmt_dblp, 9
+  ]
+  
+  # double (64 bits), planar
+  # 
+  # = Fields:
+  # :sample_rate ::
+  #   (Integer) 
+  # :channel_layout ::
+  #   (Integer) 
+  # :sample_fmt ::
+  #   (Symbol from _enum_groove_sample_format_) 
+  class GrooveAudioFormat < FFI::Struct
+    layout :sample_rate, :int,
+           :channel_layout, :ulong,
+           :sample_fmt, :groove_sample_format
+  end
+  
+  # double (64 bits), planar
+  # 
+  # @method sample_format_bytes_per_sample(format)
+  # @param [Symbol from _enum_groove_sample_format_] format 
+  # @return [Integer] 
+  # @scope class
+  attach_function :sample_format_bytes_per_sample, :groove_sample_format_bytes_per_sample, [:groove_sample_format], :int
+  
+  # (Not documented)
+  # 
+  # @method version_major()
+  # @return [Integer] 
+  # @scope class
+  attach_function :version_major, :groove_version_major, [], :int
+  
+  # (Not documented)
+  # 
+  # @method version_minor()
+  # @return [Integer] 
+  # @scope class
+  attach_function :version_minor, :groove_version_minor, [], :int
+  
+  # (Not documented)
+  # 
+  # @method version_patch()
+  # @return [Integer] 
+  # @scope class
+  attach_function :version_patch, :groove_version_patch, [], :int
+  
+  # (Not documented)
+  # 
+  # @method version()
+  # @return [String] 
+  # @scope class
+  attach_function :version, :groove_version, [], :string
+  
+  # GrooveFile
+  # 
+  # = Fields:
+  # :dirty ::
+  #   (Integer) read-only
+  # :filename ::
+  #   (String) read-only
+  class GrooveFile < FFI::Struct
+    layout :dirty, :int,
+           :filename, :string
+  end
+  
+  # If the entry already exists, append to it.  Note that no
+  # delimiter is added, the strings are simply concatenated.
+  class GrooveTag < FFI::Struct
+    layout :dummy, :char
+  end
+  
+  # If the entry already exists, append to it.  Note that no
+  # delimiter is added, the strings are simply concatenated.
+  # 
+  # @method tag_key(tag)
+  # @param [GrooveTag] tag 
+  # @return [String] 
+  # @scope class
+  attach_function :tag_key, :groove_tag_key, [GrooveTag], :string
+  
+  # (Not documented)
+  # 
+  # @method tag_value(tag)
+  # @param [GrooveTag] tag 
+  # @return [String] 
+  # @scope class
+  attach_function :tag_value, :groove_tag_value, [GrooveTag], :string
+  
+  # you are always responsible for calling groove_file_close on the
+  # returned GrooveFile.
+  # 
+  # @method file_open(filename)
+  # @param [String] filename 
+  # @return [GrooveFile] 
+  # @scope class
+  attach_function :file_open, :groove_file_open, [:string], GrooveFile
+  
+  # (Not documented)
+  # 
+  # @method file_close(file)
+  # @param [GrooveFile] file 
+  # @return [nil] 
+  # @scope class
+  attach_function :file_close, :groove_file_close, [GrooveFile], :void
+  
+  # (Not documented)
+  # 
+  # @method file_metadata_get(file, key, prev, flags)
+  # @param [GrooveFile] file 
+  # @param [String] key 
+  # @param [GrooveTag] prev 
+  # @param [Integer] flags 
+  # @return [GrooveTag] 
+  # @scope class
+  attach_function :file_metadata_get, :groove_file_metadata_get, [GrooveFile, :string, GrooveTag, :int], GrooveTag
+  
+  # key entry to add to metadata. will be strdup'd
+  # value entry to add to metadata. will be strdup'd
+  #    passing NULL causes existing entry to be deleted.
+  # return >= 0 on success otherwise an error code < 0
+  # note that this will not save the file; you must call groove_file_save
+  # to do that.
+  # 
+  # @method file_metadata_set(file, key, value, flags)
+  # @param [GrooveFile] file 
+  # @param [String] key 
+  # @param [String] value 
+  # @param [Integer] flags 
+  # @return [Integer] 
+  # @scope class
+  attach_function :file_metadata_set, :groove_file_metadata_set, [GrooveFile, :string, :string, :int], :int
+  
+  # a comma separated list of short names for the format
+  # 
+  # @method file_short_names(file)
+  # @param [GrooveFile] file 
+  # @return [String] 
+  # @scope class
+  attach_function :file_short_names, :groove_file_short_names, [GrooveFile], :string
+  
+  # write changes made to metadata to disk.
+  # return < 0 on error
+  # 
+  # @method file_save(file)
+  # @param [GrooveFile] file 
+  # @return [Integer] 
+  # @scope class
+  attach_function :file_save, :groove_file_save, [GrooveFile], :int
+  
+  # main audio stream duration in seconds. note that this relies on a
+  # combination of format headers and heuristics. It can be inaccurate.
+  # The most accurate way to learn the duration of a file is to use
+  # GrooveLoudnessDetector
+  # 
+  # @method file_duration(file)
+  # @param [GrooveFile] file 
+  # @return [Float] 
+  # @scope class
+  attach_function :file_duration, :groove_file_duration, [GrooveFile], :double
+  
+  # get the audio format of the main audio stream of a file
+  # 
+  # @method file_audio_format(file, audio_format)
+  # @param [GrooveFile] file 
+  # @param [GrooveAudioFormat] audio_format 
+  # @return [nil] 
+  # @scope class
+  attach_function :file_audio_format, :groove_file_audio_format, [GrooveFile, GrooveAudioFormat], :void
+  
+  # GroovePlaylist
+  # 
+  # = Fields:
+  # :file ::
+  #   (GrooveFile) all fields are read-only. modify with methods below.
+  # :gain ::
+  #   (Float) A volume adjustment in float format to apply to the file when it plays.
+  #   This is typically used for loudness compensation, for example ReplayGain.
+  #   To convert from dB to float, use exp(log(10) * 0.05 * dB_value)
+  # :peak ::
+  #   (Float) The sample peak of this playlist item is assumed to be 1.0 in float
+  #   format. If you know for certain that the peak is less than 1.0, you
+  #   may set this value which may allow the volume adjustment to use
+  #   a pure amplifier rather than a compressor. This results in slightly
+  #   better audio quality.
+  # :prev ::
+  #   (FFI::Pointer(*GroovePlaylistItem)) A GroovePlaylist is a doubly linked list. Use these fields to
+  #   traverse the list.
+  # :next_ ::
+  #   (FFI::Pointer(*GroovePlaylistItem)) 
+  class GroovePlaylistItem < FFI::Struct
+    layout :file, GrooveFile,
+           :gain, :double,
+           :peak, :double,
+           :prev, :pointer,
+           :next_, :pointer
+  end
+  
+  # A GroovePlaylist is a doubly linked list. Use these fields to
+  # traverse the list.
+  # 
+  # = Fields:
+  # :head ::
+  #   (GroovePlaylistItem) all fields are read-only. modify using methods below.
+  #   doubly linked list which is the playlist
+  # :tail ::
+  #   (GroovePlaylistItem) 
+  # :gain ::
+  #   (Float) volume adjustment in float format which applies to all playlist items
+  #   and all sinks. defaults to 1.0.
+  class GroovePlaylist < FFI::Struct
+    layout :head, GroovePlaylistItem,
+           :tail, GroovePlaylistItem,
+           :gain, :double
+  end
+  
+  # a playlist keeps its sinks full.
+  # 
+  # @method playlist_create()
+  # @return [GroovePlaylist] 
+  # @scope class
+  attach_function :playlist_create, :groove_playlist_create, [], GroovePlaylist
+  
+  # this will not call groove_file_close on any files
+  # it will remove all playlist items and sinks from the playlist
+  # 
+  # @method playlist_destroy(playlist)
+  # @param [GroovePlaylist] playlist 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_destroy, :groove_playlist_destroy, [GroovePlaylist], :void
+  
+  # (Not documented)
+  # 
+  # @method playlist_play(playlist)
+  # @param [GroovePlaylist] playlist 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_play, :groove_playlist_play, [GroovePlaylist], :void
+  
+  # (Not documented)
+  # 
+  # @method playlist_pause(playlist)
+  # @param [GroovePlaylist] playlist 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_pause, :groove_playlist_pause, [GroovePlaylist], :void
+  
+  # (Not documented)
+  # 
+  # @method playlist_seek(playlist, item, seconds)
+  # @param [GroovePlaylist] playlist 
+  # @param [GroovePlaylistItem] item 
+  # @param [Float] seconds 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_seek, :groove_playlist_seek, [GroovePlaylist, GroovePlaylistItem, :double], :void
+  
+  # once you add a file to the playlist, you must not destroy it until you first
+  # remove it from the playlist.
+  # next: the item to insert before. if NULL, you will append to the playlist.
+  # gain: see GroovePlaylistItem structure. use 1.0 for no adjustment.
+  # peak: see GroovePlaylistItem structure. use 1.0 for no adjustment.
+  # returns the newly created playlist item.
+  # 
+  # @method playlist_insert(playlist, file, gain, peak, next_)
+  # @param [GroovePlaylist] playlist 
+  # @param [GrooveFile] file 
+  # @param [Float] gain 
+  # @param [Float] peak 
+  # @param [GroovePlaylistItem] next_ 
+  # @return [GroovePlaylistItem] 
+  # @scope class
+  attach_function :playlist_insert, :groove_playlist_insert, [GroovePlaylist, GrooveFile, :double, :double, GroovePlaylistItem], GroovePlaylistItem
+  
+  # this will not call groove_file_close on item->file !
+  # item is destroyed and the address it points to is no longer valid
+  # 
+  # @method playlist_remove(playlist, item)
+  # @param [GroovePlaylist] playlist 
+  # @param [GroovePlaylistItem] item 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_remove, :groove_playlist_remove, [GroovePlaylist, GroovePlaylistItem], :void
+  
+  # get the position of the decode head
+  # both the current playlist item and the position in seconds in the playlist
+  # item are given. item will be set to NULL if the playlist is empty
+  # seconds will be set to -1.0 if item is NULL.
+  # you may pass NULL for item or seconds
+  # Note that typically you are more interested in the position of the play
+  # head, not the decode head. For example, if you have a GroovePlayer attached,
+  # groove_player_position will give you the position of the play head.
+  # 
+  # @method playlist_position(playlist, item, seconds)
+  # @param [GroovePlaylist] playlist 
+  # @param [FFI::Pointer(**GroovePlaylistItem)] item 
+  # @param [FFI::Pointer(*Double)] seconds 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_position, :groove_playlist_position, [GroovePlaylist, :pointer, :pointer], :void
+  
+  # return 1 if the playlist is playing; 0 if it is not. 
+  # 
+  # @method playlist_playing(playlist)
+  # @param [GroovePlaylist] playlist 
+  # @return [Integer] 
+  # @scope class
+  attach_function :playlist_playing, :groove_playlist_playing, [GroovePlaylist], :int
+  
+  # remove all playlist items
+  # 
+  # @method playlist_clear(playlist)
+  # @param [GroovePlaylist] playlist 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_clear, :groove_playlist_clear, [GroovePlaylist], :void
+  
+  # return the count of playlist items
+  # 
+  # @method playlist_count(playlist)
+  # @param [GroovePlaylist] playlist 
+  # @return [Integer] 
+  # @scope class
+  attach_function :playlist_count, :groove_playlist_count, [GroovePlaylist], :int
+  
+  # (Not documented)
+  # 
+  # @method playlist_set_gain(playlist, gain)
+  # @param [GroovePlaylist] playlist 
+  # @param [Float] gain 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_set_gain, :groove_playlist_set_gain, [GroovePlaylist, :double], :void
+  
+  # (Not documented)
+  # 
+  # @method playlist_set_item_gain(playlist, item, gain)
+  # @param [GroovePlaylist] playlist 
+  # @param [GroovePlaylistItem] item 
+  # @param [Float] gain 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_set_item_gain, :groove_playlist_set_item_gain, [GroovePlaylist, GroovePlaylistItem, :double], :void
+  
+  # (Not documented)
+  # 
+  # @method playlist_set_item_peak(playlist, item, peak)
+  # @param [GroovePlaylist] playlist 
+  # @param [GroovePlaylistItem] item 
+  # @param [Float] peak 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_set_item_peak, :groove_playlist_set_item_peak, [GroovePlaylist, GroovePlaylistItem, :double], :void
+  
+  # Use this to set the fill mode using the constants above
+  # 
+  # @method playlist_set_fill_mode(playlist, mode)
+  # @param [GroovePlaylist] playlist 
+  # @param [Integer] mode 
+  # @return [nil] 
+  # @scope class
+  attach_function :playlist_set_fill_mode, :groove_playlist_set_fill_mode, [GroovePlaylist, :int], :void
+  
+  # GrooveBuffer
+  # 
+  # = Fields:
+  # :data ::
+  #   (FFI::Pointer(**Uint8T)) all fields read-only
+  #   for interleaved audio, data(0) is the buffer.
+  #   for planar audio, each channel has a separate data pointer.
+  #   for encoded audio, data(0) is the encoded buffer.
+  # :format ::
+  #   (GrooveAudioFormat) 
+  # :frame_count ::
+  #   (Integer) number of audio frames described by this buffer
+  #   for encoded audio, this is unknown and set to 0.
+  # :item ::
+  #   (GroovePlaylistItem) when encoding, if item is NULL, this is a format header or trailer.
+  #   otherwise, this is encoded audio for the item specified.
+  #   when decoding, item is never NULL.
+  # :pos ::
+  #   (Float) 
+  # :size ::
+  #   (Integer) total number of bytes contained in this buffer
+  # :pts ::
+  #   (Integer) presentation time stamp of the buffer
+  class GrooveBuffer < FFI::Struct
+    layout :data, :pointer,
+           :format, GrooveAudioFormat.by_value,
+           :frame_count, :int,
+           :item, GroovePlaylistItem,
+           :pos, :double,
+           :size, :int,
+           :pts, :ulong
+  end
+  
+  # presentation time stamp of the buffer
+  # 
+  # @method buffer_ref(buffer)
+  # @param [GrooveBuffer] buffer 
+  # @return [nil] 
+  # @scope class
+  attach_function :buffer_ref, :groove_buffer_ref, [GrooveBuffer], :void
+  
+  # (Not documented)
+  # 
+  # @method buffer_unref(buffer)
+  # @param [GrooveBuffer] buffer 
+  # @return [nil] 
+  # @scope class
+  attach_function :buffer_unref, :groove_buffer_unref, [GrooveBuffer], :void
+  
+  # use this to get access to a realtime raw audio buffer
+  # for example you could use it to draw a waveform or other visualization
+  # GroovePlayer uses this internally to get the audio buffer for playback
+  # 
+  # = Fields:
+  # :audio_format ::
+  #   (GrooveAudioFormat) set this to the audio format you want the sink to output
+  # :disable_resample ::
+  #   (Integer) Set this flag to ignore audio_format. If you set this flag, the
+  #   buffers you pull from this sink could have any audio format.
+  # :buffer_sample_count ::
+  #   (Integer) If you leave this to its default of 0, frames pulled from the sink
+  #   will have sample count determined by efficiency.
+  #   If you set this to a positive number, frames pulled from the sink
+  #   will always have this number of samples.
+  # :buffer_size ::
+  #   (Integer) how big the buffer queue should be, in sample frames.
+  #   groove_sink_create defaults this to 8192
+  # :gain ::
+  #   (Float) This volume adjustment only applies to this sink.
+  #   It is recommended that you leave this at 1.0 and instead adjust the
+  #   gain of the playlist.
+  #   If you want to change this value after you have already attached the
+  #   sink to the playlist, you must use groove_sink_set_gain.
+  #   float format. Defaults to 1.0
+  # :userdata ::
+  #   (FFI::Pointer(*Void)) set to whatever you want
+  # :flush ::
+  #   (FFI::Pointer(*)) called when the audio queue is flushed. For example, if you seek to a
+  #   different location in the song.
+  # :purge ::
+  #   (FFI::Pointer(*)) called when a playlist item is deleted. Take this opportunity to remove
+  #   all your references to the GroovePlaylistItem.
+  # :pause ::
+  #   (FFI::Pointer(*)) called when the playlist is paused
+  # :play ::
+  #   (FFI::Pointer(*)) called when the playlist is played
+  # :playlist ::
+  #   (GroovePlaylist) read-only. set when you call groove_sink_attach. cleared when you call
+  #   groove_sink_detach
+  # :bytes_per_sec ::
+  #   (Integer) read-only. automatically computed from audio_format when you call
+  #   groove_sink_attach
+  class GrooveSink < FFI::Struct
+    layout :audio_format, GrooveAudioFormat.by_value,
+           :disable_resample, :int,
+           :buffer_sample_count, :int,
+           :buffer_size, :int,
+           :gain, :double,
+           :userdata, :pointer,
+           :flush, :pointer,
+           :purge, :pointer,
+           :pause, :pointer,
+           :play, :pointer,
+           :playlist, GroovePlaylist,
+           :bytes_per_sec, :int
+  end
+  
+  # read-only. automatically computed from audio_format when you call
+  # groove_sink_attach
+  # 
+  # @method sink_create()
+  # @return [GrooveSink] 
+  # @scope class
+  attach_function :sink_create, :groove_sink_create, [], GrooveSink
+  
+  # (Not documented)
+  # 
+  # @method sink_destroy(sink)
+  # @param [GrooveSink] sink 
+  # @return [nil] 
+  # @scope class
+  attach_function :sink_destroy, :groove_sink_destroy, [GrooveSink], :void
+  
+  # before calling this, set audio_format
+  # returns 0 on success, < 0 on error
+  # 
+  # @method sink_attach(sink, playlist)
+  # @param [GrooveSink] sink 
+  # @param [GroovePlaylist] playlist 
+  # @return [Integer] 
+  # @scope class
+  attach_function :sink_attach, :groove_sink_attach, [GrooveSink, GroovePlaylist], :int
+  
+  # returns 0 on success, < 0 on error
+  # 
+  # @method sink_detach(sink)
+  # @param [GrooveSink] sink 
+  # @return [Integer] 
+  # @scope class
+  attach_function :sink_detach, :groove_sink_detach, [GrooveSink], :int
+  
+  # returns < 0 on error, GROOVE_BUFFER_NO on aborted (block=1) or no buffer
+  # ready (block=0), GROOVE_BUFFER_YES on buffer returned, and GROOVE_BUFFER_END
+  # on end of playlist.
+  # buffer is always set to either a valid GrooveBuffer or NULL
+  # 
+  # @method sink_buffer_get(sink, buffer, block)
+  # @param [GrooveSink] sink 
+  # @param [FFI::Pointer(**GrooveBuffer)] buffer 
+  # @param [Integer] block 
+  # @return [Integer] 
+  # @scope class
+  attach_function :sink_buffer_get, :groove_sink_buffer_get, [GrooveSink, :pointer, :int], :int
+  
+  # returns < 0 on error, 0 on no buffer ready, 1 on buffer ready
+  # if block is 1, block until buffer is ready
+  # 
+  # @method sink_buffer_peek(sink, block)
+  # @param [GrooveSink] sink 
+  # @param [Integer] block 
+  # @return [Integer] 
+  # @scope class
+  attach_function :sink_buffer_peek, :groove_sink_buffer_peek, [GrooveSink, :int], :int
+  
+  # See the gain property of GrooveSink. It is recommended that you leave this
+  # at 1.0 and instead adjust the gain of the playlist.
+  # returns 0 on success, < 0 on error
+  # 
+  # @method sink_set_gain(sink, gain)
+  # @param [GrooveSink] sink 
+  # @param [Float] gain 
+  # @return [Integer] 
+  # @scope class
+  attach_function :sink_set_gain, :groove_sink_set_gain, [GrooveSink, :double], :int
+  
+  # (Not documented)
+  # 
+  # = Fields:
+  # :context ::
+  #   (FFI::Pointer(*Void)) 
+  # :cleanup ::
+  #   (FFI::Pointer(*)) // defaults to groove_queue_cleanup_default
+  # :put ::
+  #   (FFI::Pointer(*)) 
+  # :get ::
+  #   (FFI::Pointer(*)) 
+  # :purge ::
+  #   (FFI::Pointer(*)) 
+  class GrooveQueue < FFI::Struct
+    layout :context, :pointer,
+           :cleanup, :pointer,
+           :put, :pointer,
+           :get, :pointer,
+           :purge, :pointer
+  end
+  
+  # (Not documented)
+  # 
+  # @method queue_create()
+  # @return [GrooveQueue] 
+  # @scope class
+  attach_function :queue_create, :groove_queue_create, [], GrooveQueue
+  
+  # (Not documented)
+  # 
+  # @method queue_flush(queue)
+  # @param [GrooveQueue] queue 
+  # @return [nil] 
+  # @scope class
+  attach_function :queue_flush, :groove_queue_flush, [GrooveQueue], :void
+  
+  # (Not documented)
+  # 
+  # @method queue_destroy(queue)
+  # @param [GrooveQueue] queue 
+  # @return [nil] 
+  # @scope class
+  attach_function :queue_destroy, :groove_queue_destroy, [GrooveQueue], :void
+  
+  # (Not documented)
+  # 
+  # @method queue_abort(queue)
+  # @param [GrooveQueue] queue 
+  # @return [nil] 
+  # @scope class
+  attach_function :queue_abort, :groove_queue_abort, [GrooveQueue], :void
+  
+  # (Not documented)
+  # 
+  # @method queue_reset(queue)
+  # @param [GrooveQueue] queue 
+  # @return [nil] 
+  # @scope class
+  attach_function :queue_reset, :groove_queue_reset, [GrooveQueue], :void
+  
+  # (Not documented)
+  # 
+  # @method queue_put(queue, obj)
+  # @param [GrooveQueue] queue 
+  # @param [FFI::Pointer(*Void)] obj 
+  # @return [Integer] 
+  # @scope class
+  attach_function :queue_put, :groove_queue_put, [GrooveQueue, :pointer], :int
+  
+  # // returns -1 if aborted, 1 if got event, 0 if no event ready
+  # 
+  # @method queue_get(queue, obj_ptr, block)
+  # @param [GrooveQueue] queue 
+  # @param [FFI::Pointer(**Void)] obj_ptr 
+  # @param [Integer] block 
+  # @return [Integer] 
+  # @scope class
+  attach_function :queue_get, :groove_queue_get, [GrooveQueue, :pointer, :int], :int
+  
+  # (Not documented)
+  # 
+  # @method queue_peek(queue, block)
+  # @param [GrooveQueue] queue 
+  # @param [Integer] block 
+  # @return [Integer] 
+  # @scope class
+  attach_function :queue_peek, :groove_queue_peek, [GrooveQueue, :int], :int
+  
+  # (Not documented)
+  # 
+  # @method queue_purge(queue)
+  # @param [GrooveQueue] queue 
+  # @return [nil] 
+  # @scope class
+  attach_function :queue_purge, :groove_queue_purge, [GrooveQueue], :void
+  
+  # (Not documented)
+  # 
+  # @method queue_cleanup_default(queue, obj)
+  # @param [GrooveQueue] queue 
+  # @param [FFI::Pointer(*Void)] obj 
+  # @return [nil] 
+  # @scope class
+  attach_function :queue_cleanup_default, :groove_queue_cleanup_default, [GrooveQueue, :pointer], :void
+  
+end