audio_glue 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 1c31ccdeefe481d8de76901107ceba5892ddbaac
+  data.tar.gz: 2b91e5f9b841f4a6f6bd19aabe790e227f91e5d0
+SHA512:
+  metadata.gz: c30e801164ff09e7b0295a8f4b84a5e5c10ab9cc7e11d4b8eaa38d0d01439664df941463064b52d133a0adc1a24ac21846adc1297b91ecdcf22e063eaf881dfd
+  data.tar.gz: d1b7c8166a480ae8a67ee2dac987056f25258bfea178476d09a8daf5f80bdc1c26a612ea669f0d159eb2e9fc7057870f775099d277343e51585a547544466da3

data/LICENSE.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2013 TMX Credit, author Potapov Sergey
+
+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.markdown

@@ -0,0 +1,148 @@
+# AudioGlue
+
+[![Build Status](https://travis-ci.org/TMXCredit/audio_glue.png?branch=master)](https://travis-ci.org/TMXCredit/audio_glue)
+
+Audio template engine (aka ERB/HAML for audio).
+
+## Usage
+
+An example:
+
+```ruby
+  require 'audio_glue'
+
+  # We need to use one of the adapters.
+  # This one comes from the audio_glue-sox_adapter gem:
+  require 'audio_glue/sox_adapter'
+
+
+  # Create a template class:
+  class HelloWorldTemplate < AudioGlue::Template
+    # Specify the characteristics of an output audio file:
+    head do
+      format :mp3
+      rate 44100
+      channels 2
+    end
+
+    # Lets concatenate 2 mp3 files:
+    body do
+      - file("/sounds/hello.mp3")                              # Local file
+
+      if @say_name
+        - url("http://some-service.com/my-name-is-glue.mp3")   # Remote file
+      end
+    end
+  end
+
+  # Initialize a template:
+  template = HelloWorldTemplate.new(:say_name => true)
+
+  # Optionally, build using an adapter:
+  adapter = AudioGlue::PlainSoxAdapter.new
+  builder = AudioGlue::Builder.new(adapter)
+
+  # Process a template to get audio data:
+  audio = builder.build(template)  # => audio as a binary string
+
+  # Write the result to a local file:
+  File.binwrite("/hello_world.mp3", audio)
+```
+
+### Templates
+
+A glue template is a template file (e.g. like ERB or HAML) which defines how
+the output audio should be built.
+In Ruby terms, it's a subclass of `AudioGlue::Template`.
+
+#### Glue templates
+
+In the example above, the template inherits from `AudioGlue::Template`.
+But you can also store templates in `.glue` files.
+For example `/path/to/templates/hello_world.glue`:
+
+```ruby
+head {
+  format :mp3
+  rate 44100
+  channels 2
+}
+
+body {
+  - file("/sounds/hello.mp3")
+  if @say_name
+    - url("http://some-service.com/my-name-is-glue.mp3")
+  end
+}
+```
+
+And then we can load it with `AudioGlue::TemplateLoader`:
+
+```ruby
+  # Create an instance of the loader with a basic directory,
+  # where templates are located:
+  loader = TemplateLoader.new("/path/to/templates")
+
+  # Load and cache the template:
+  loader.get("hello_world")  # => anonymous subclass of AudioGlue::Template
+```
+
+#### Glue Syntax
+
+Each glue template has 2 sections:
+
+* `head` - contains the parameters of the output file (`format`, `rate`, `channels`)
+* `body` - specifies how to build the output
+
+The `body` references the audio snippets that will be used to build the output
+audio. There a few types of snippets:
+
+* `file` - points to an audio file in the local file system
+* `url` - contains a URL to a remote audio file
+
+To make a snippet be added to the output it should have a dash prefix (`-`).
+
+
+### Custom adapters
+
+You may want to create your own adapter to concatenate audio files, if you
+think the existing one is not efficient, or if you want to add some caching.
+
+The responsibility of adapters is to build audio data from
+`AudioGlue::SnippetPacket`. The snippet packet is a collection of audio
+snippets and output file characteristics(format, rate, channels).
+
+A very simple adapter could look like this:
+
+```ruby
+  # Doesn't support :url snippets, only files in local file system.
+  # Doesn't handle rate and channels.
+  class SimpleAdapter < AudioGlue::BaseAdapter
+    # Only this method is required to be implemented.
+    def build(snippet_packet)
+      # Extract file paths from snippets.
+      # Ensure only :file snippets are present.
+      file_paths = snippet_packet.snippets.map do |snippet|
+        unless snippet.type == :file
+          raise(AudioGlue::Error, "Only file snippets are supported")
+        end
+        snippets.source
+      end
+
+      # Build cat command
+      command = "cat #{file_paths.join(' ')}"
+
+      # Concatenate files and return result
+      %{command}
+    end
+  end
+```
+
+
+## Credits
+
+* [Sergey Potapov](https://github.com/greyblake)
+
+## Copyright
+
+Copyright (c) 2013 TMX Credit.

data/lib/audio_glue.rb

@@ -0,0 +1,35 @@
+require 'forwardable'
+require 'fileutils'
+require 'tempfile'
+
+require 'audio_glue/snippet'
+require 'audio_glue/snippet_packet'
+require 'audio_glue/template/head_context'
+require 'audio_glue/template'
+require 'audio_glue/base_adapter'
+require 'audio_glue/builder'
+
+require 'audio_glue/template_loader'
+
+
+# AudioGlue is a library to concatenate audio snippets using templates.
+# Consider it like ERB or HAML for audio files, where input is not text
+# snippets, but audio snippets, and output is not text, but audio.
+module AudioGlue
+  # Basic error for AudioGlue errors.
+  class Error < StandardError
+  end
+
+  # Raised on an attempt to call an unimplemented method of an object which
+  # a class inherits from an abstract class.
+  class AbstractMethodCallError < Error
+  end
+
+  # Raised on a failed attempt to load a glue template.
+  class LoadTemplateError < Error
+  end
+
+  # Raised when audio data fails to be built.
+  class BuildError < Error
+  end
+end

data/lib/audio_glue/base_adapter.rb

@@ -0,0 +1,21 @@
+module AudioGlue
+  # Base adapter that specifies interface for all adapters.
+  # The responsibility of an adapter is to build an output audio file
+  # from a {AudioGlue::SnippetPacket snippet packet}, which provides
+  # a collection of input audio sources and some parameters for the output file
+  # (rate, number of channels).
+  #
+  # An adapter can rely on different tools and libraries to process audio
+  # files. Also an adapter is responsible for correctly processing remote files
+  # (e.g. downloading them as temporary files if necessary).
+  class BaseAdapter
+    # Build audio file from a snippet packet and return result as binary string.
+    #
+    # @param snippet_packet [AudioGlue::SnippetPacket]
+    #
+    # @return [String]
+    def build(snippet_packet)
+      raise AbstractMethodCallError, __method__
+    end
+  end
+end

data/lib/audio_glue/builder.rb

@@ -0,0 +1,40 @@
+module AudioGlue
+  # Builds audio from a {AudioGlue::Template template} instance.
+  #
+  # @example
+  #   # Instantiate the builder with an adapter:
+  #   builder = AudioGlue::Builder.new(AudioGlue::PlainSoxAdapter.new)
+  #
+  #   # Create the template instance:
+  #   template = HiTemplate.new(:with_smalltalk => true)
+  #
+  #   # Build the output audio:
+  #   builder.build(template) # => audio as a binary string
+  class Builder
+    # @param adapter [AudioGlue::BaseAdapter] instance of an adapter
+    def initialize(adapter)
+      @adapter = adapter
+    end
+
+    # Build an audio file and return the result as a binary string.
+    #
+    # @param template [AudioGlue::Template]
+    # @param opts [Hash]
+    #
+    # @option opts :format [Symbol, String]
+    # @option opts :rate [Integer, String]
+    # @option opts :channels [Integer, String]
+    #
+    # @return [String]
+    def build(template, opts = {})
+      format, rate, channels = opts[:format], opts[:rate], opts[:channels]
+
+      packet =  template.build_snippet_packet
+      packet.format   = format   if format
+      packet.rate     = rate     if rate
+      packet.channels = channels if channels
+
+      @adapter.build(packet)
+    end
+  end
+end

data/lib/audio_glue/snippet.rb

@@ -0,0 +1,36 @@
+module AudioGlue
+  # Represents an audio partial which will be used to build an output audio.
+  # There are a few types of snippets:
+  # * :file - represents audio file in local file system
+  # * :url  - represents remote audio file
+  #
+  # Other custom types can be created if custom adapter will support them.
+  #
+  # {AudioGlue::BaseAdapter adapters} are responsible for processing every
+  # particular snippet type.
+  class Snippet
+    attr_reader :type, :source, :snippet_packet, :opts
+
+    # @param type [Symbol] :file, :url or anything else that can be handled by
+    #                      the adapter
+    # @param source [String] Can be location, URL, or whatever depending on type
+    # @param snippet_packet [AudioGlue::SnippetPacket] the snippet packet used
+    #   to add the audio snippet to the packet when `-` unary method is called
+    # @param opts [Hash] any specific options which are supported by adapter
+    def initialize(type, source, snippet_packet, opts = {})
+      @type           = type
+      @source         = source
+      @snippet_packet = snippet_packet
+      @opts           = opts
+    end
+
+    # Add self to the snippet packet.
+    # It's used to support dash syntax in +.glue+ files, like:
+    #   - file('/audio.mp3')
+    #
+    # @return [void]
+    def -@
+      @snippet_packet << self
+    end
+  end
+end

data/lib/audio_glue/snippet_packet.rb

@@ -0,0 +1,25 @@
+module AudioGlue
+  # SnippetPacket is a collection of {AudioGlue::Snippet snippets} with
+  # some additional info about the output file
+  # (format, rate, number of channels).
+  #
+  # It's supposed to be built by {AudioGlue::Template}. And then it's passed
+  # to an adapter which builds the audio output.
+  class SnippetPacket
+    extend Forwardable
+    def_delegators :@snippets, :<<
+
+    attr_accessor :format, :rate, :channels
+    attr_reader :snippets
+
+    # @param format [Symbol, String]
+    # @param rate [Numeric, String]
+    # @param channels [Numeric, String]
+    def initialize(format, rate, channels)
+      @format   = format
+      @rate     = rate
+      @channels = channels
+      @snippets = []
+    end
+  end
+end

data/lib/audio_glue/template.rb

@@ -0,0 +1,152 @@
+module AudioGlue
+  # Represents an audio template.
+  # Every particular template is a subclass of {AudioGlue::Template}.
+  # Quite often the classes can be anonymous. (That's why +inspect+ is redefined
+  # to provide more information.)
+  #
+  # The Template class owns +format+, +rate+, +channels+, and also a block used
+  # to create an {AudioGlue::SnippetPacket}
+  # ("render", in terms of the view templates).
+  #
+  # A Template instance differs from the Template class. It has instance
+  # variables, that can be used in the +body+ block.
+  #
+  # @example
+  #   class HiTemplate < AudioGlue::Template
+  #     # Output file information
+  #     head do
+  #       format :mo3
+  #       rate 22050
+  #       channels 2
+  #     end
+  #
+  #     # Block to "render" template
+  #     body do
+  #       - file('/hi.mp3')
+  #       if @with_smalltalk
+  #         - url('http://say.it/how-are-you.mp3')
+  #       end
+  #     end
+  #   end
+  #
+  #   # Create an instance of Template. We wonder how our friend is doing so
+  #   # we pass ":with_smalltalk => true", to add a remote URL snippet.
+  #   template = HiTemplate.new(:with_smalltalk => true)
+  #
+  #   # Let's create a snippet packet:
+  #   packet = template.build_snippet_packet => # <AudioGlue::SnippetPacket ..>
+  #   # Now we can pass a snippet packet to the adapter to build output audio.
+  class Template
+    extend Forwardable
+    def_delegators 'self.class', :format, :rate, :channels, :path, :body_proc
+
+    class << self
+      attr_accessor :format, :rate, :channels, :path, :body_proc
+    end
+
+    # Process the +head+ block in a +.glue+ template.
+    #
+    # @yield block which will be executed in context of
+    #   {AudioGlue::Template::HeadContext} object.
+    #
+    # @return [void]
+    def self.head(&block)
+      HeadContext.new(self).instance_eval(&block)
+    end
+
+    # Process the +body+ block in a +.glue+ template.
+    #
+    # @yield block which will be executed in context of
+    #   {AudioGlue::Template::BodyContext} object. It should define body of
+    #   audio template.
+    # @return [void]
+    def self.body(&block)
+      self.body_proc = block
+    end
+
+    # Redefine the +inspect+ method to provide more information when the
+    # template is an anonymous class.
+    #
+    # @return [String]
+    def self.inspect
+      if self.name
+        super
+      else
+        info = "<AudioGlue::Template(class)"
+        info << " path=#{path.inspect}" if path
+        info << ">"
+      end
+    end
+
+
+    # @param variables [Hash] hash of parameters which can be used as instance
+    #   variables in +body+ statement of +.glue+ template.
+    def initialize(variables = {})
+      variables.each do |var, value|
+        instance_variable_set("@#{var}", value)
+      end
+    end
+
+    # Execute the body of the template to build a snippet packet.
+    #
+    # @return [AudioGlue::SnippetPacket]
+    def build_snippet_packet
+      @__packet__ = SnippetPacket.new(format, rate, channels)
+      instance_eval(&body_proc)
+      @__packet__
+    end
+
+    # Redefine +inspect+ to provide more information if the class of the
+    # template object is anonymous.
+    #
+    # @return [String]
+    def inspect
+      if self.class.name
+        super
+      else
+        info = "<AudioGlue::Template"
+        info << "(path=#{path.inspect})" if path
+
+        instance_variables.each do |var|
+          info << " #{var}="
+          info << instance_variable_get(var).inspect
+        end
+
+        info << ">"
+      end
+    end
+
+
+    # Create a snippet (with the +:file+ type) for the given audio file.
+    #
+    # @param  file_path [String] path to an audio file in local file system
+    #
+    # @return [AudioGlue::Snippet]
+    def file(file_path)
+      create_snippet(:file, file_path)
+    end
+    private :file
+
+    # Create a snippet (with +:url+ type) for the given audio URL.
+    #
+    # @param remote_url [String] remote location of audio file
+    #
+    # @return [AudioGlue::Snippet]
+    def url(remote_url)
+      create_snippet(:url, remote_url)
+    end
+    private :url
+
+    # Create snippet.
+    #
+    # @param type [Symbol] snippet type
+    # @param source [String]
+    # @param opts [Hash] any options supported by adapter
+    #
+    # @return [AudioGlue::Snippet]
+    def create_snippet(type, source, opts = {})
+      Snippet.new(type, source, @__packet__, opts)
+    end
+    private :create_snippet
+  end
+end

data/lib/audio_glue/template/head_context.rb

@@ -0,0 +1,40 @@
+module AudioGlue
+  class Template
+    # The context in which the +head+ statement of a +.glue+ template is
+    # executed. It's used to set the +format+, +rate+ and +channels+ on
+    # the template.
+    class HeadContext
+      # @param template [Class] subclass of {AudioGlue::Template}
+      def initialize(template)
+        @template = template
+      end
+
+      # Set the audio format on the template ("mp3", "ogg", "wav", etc).
+      #
+      # @param format_value [Symbol, String]
+      #
+      # @return [void]
+      def format(format_value)
+        @template.format = format_value
+      end
+
+      # Set the audio bitrate on the template.
+      #
+      # @param rate_value [Integer, String]
+      #
+      # @return [void]
+      def rate(rate_value)
+        @template.rate = rate_value
+      end
+
+      # Set the number of channels on the template.
+      #
+      # @param channels_value [Integer, String]
+      #
+      # @return [void]
+      def channels(channels_value)
+        @template.channels = channels_value
+      end
+    end
+  end
+end

data/lib/audio_glue/template_loader.rb

@@ -0,0 +1,78 @@
+module AudioGlue
+  # Loads +.glue+ templates and caches them.
+  #
+  # @example
+  #  loader = AudioGlue::TemplateLoader.new('/project/audio_templates/')
+  #
+  #  # load and cache "/project/audio_templates/john/hi.glue"
+  #  loader.get('john/hi') # => subclass of AudioGlue::Template
+  class TemplateLoader
+    # Extension of template files.
+    TEMPLATE_EXT = 'glue'
+
+    # @attr_reader base_path [String] path to a directory with templates
+    attr_reader :base_path
+
+    # @attr_reader cache [Hash<String, Class>] cached templates, key is a path
+    #   to a template file, value is a subclass of {AudioGlue::Template}
+    attr_reader :cache
+
+    # @param base_path [String] path to a directory with templates
+    # @param opts [Hash] options
+    # @option opts :helper [Module] module which provides custom methods
+    #                               for templates.
+    def initialize(base_path, opts = {})
+      @base_path = base_path
+      @helper    = opts.delete(:helper)
+      @cache     = {}
+    end
+
+    # Load and cache the template from a +.glue+ template file.
+    #
+    # @param template_name [String] name of template in +base_path+ directory
+    #
+    # @return [Class] a subclass of {AudioGlue::Template}
+    def get(template_name)
+      path = absolute_path(template_name)
+      @cache[path] ||= load_template_from_file(path)
+    end
+
+    # Reset the cache.
+    #
+    # @return [Hash] empty cache
+    def reset_cache!
+      @cache.clear
+    end
+
+
+
+    # Calculate the absolute path to a file from a template name.
+    #
+    # @param template_name [String] name of template in +base_path+ directory
+    #
+    # @return [String] absolute path to a template file
+    def absolute_path(template_name)
+      File.join(@base_path, "#{template_name}.#{TEMPLATE_EXT}")
+    end
+    private :absolute_path
+
+    # Read a +.glue+ template file and create a template class from it.
+    #
+    # @param path [String] absolute path to .glue template file
+    #
+    # @return [Class] a subclass of {AudioGlue::Template}
+    def load_template_from_file(path)
+      Class.new(AudioGlue::Template).tap do |template|
+        content = File.read(path)
+        template.path = path
+        template.send(:include, @helper) if @helper
+        template.instance_eval(content, path)
+      end
+    rescue Errno::ENOENT => err
+      raise AudioGlue::LoadTemplateError, err.message
+    rescue SyntaxError, NameError => err
+      raise AudioGlue::LoadTemplateError, err.message, err.backtrace
+    end
+    private :load_template_from_file
+  end
+end

metadata

@@ -0,0 +1,129 @@
+--- !ruby/object:Gem::Specification
+name: audio_glue
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- TMX Credit
+- Potapov Sergey
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-10-24 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: jeweler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.7
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 1.8.7
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: metric_fu
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Tool to assemble audio files from templates
+email:
+- rubygems@tmxcredit.com
+- blake131313@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE.txt
+- README.markdown
+files:
+- LICENSE.txt
+- README.markdown
+- lib/audio_glue.rb
+- lib/audio_glue/base_adapter.rb
+- lib/audio_glue/builder.rb
+- lib/audio_glue/snippet.rb
+- lib/audio_glue/snippet_packet.rb
+- lib/audio_glue/template.rb
+- lib/audio_glue/template/head_context.rb
+- lib/audio_glue/template_loader.rb
+homepage: http://github.com/TMXCredit/audio_glue
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.3
+signing_key: 
+specification_version: 4
+summary: aka ERB for audio files
+test_files: []
+has_rdoc: