popcap 0.7.2

data/.gitignore

@@ -0,0 +1,4 @@
+coverage/*
+*.swp
+.rbx
+.rbenv-version

data/.rspec

@@ -0,0 +1,4 @@
+--color
+--format doc
+--profile
+--order random

data/Gemfile

@@ -0,0 +1,13 @@
+source 'https://rubygems.org'
+
+group :development do
+  gem 'awesome_print'
+  gem 'pry'
+end
+
+group :test do
+  gem 'cane'
+  gem 'reek'
+  gem 'rspec'
+  gem 'simplecov'
+end

data/Gemfile.lock

@@ -0,0 +1,52 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    awesome_print (1.1.0)
+    cane (2.5.0)
+      parallel
+    coderay (1.0.8)
+    diff-lcs (1.1.3)
+    method_source (0.8.1)
+    multi_json (1.5.0)
+    parallel (0.6.1)
+    pry (0.9.11.3)
+      coderay (~> 1.0.5)
+      method_source (~> 0.8)
+      slop (~> 3.4)
+    reek (1.2.13)
+      ripper_ruby_parser (~> 0.0.7)
+      ruby2ruby (~> 1.2.5)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    ripper_ruby_parser (0.0.8)
+      sexp_processor (~> 3.0)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.2)
+    ruby2ruby (1.2.5)
+      ruby_parser (~> 2.0)
+      sexp_processor (~> 3.0)
+    ruby_parser (2.3.1)
+      sexp_processor (~> 3.0)
+    sexp_processor (3.2.0)
+    simplecov (0.7.1)
+      multi_json (~> 1.0)
+      simplecov-html (~> 0.7.1)
+    simplecov-html (0.7.1)
+    slop (3.4.3)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  awesome_print
+  cane
+  pry
+  reek
+  rspec
+  simplecov

data/LICENSE

@@ -0,0 +1,9 @@
+Copyright (C) 2012 Culley Smith
+
+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.
+
+Released under MIT License.

data/README.md

@@ -0,0 +1,137 @@
+PopCap
+======
+
+PopCap is an audio file management library.  It wraps some functionality from FFmpeg for reading & writing metadata tags, converting between audio file formats, and managing an audio file on the file system.
+
+Getting Started
+---------------
+
+```
+gem install popcap
+require 'popcap'
+
+Song = Class.new(PopCap::AudioFile)
+song = Song.new('path/to/sample.flac')
+```
+
+Read Tags
+---------
+
+Read the metadata tags from an audio file.
+
+```
+audio_file = PopCap::AudioFile.new('sample.flac')
+
+audio_file.raw_tags => Returns a string of the raw output from running ffprobe -show_format.
+    [FORMAT]
+    filename=sample.flac
+    nb_streams=1
+    format_name=flac
+    format_long_name=raw FLAC
+    start_time=N/A
+    duration=1.000000
+    size=18291
+    bit_rate=146328
+    TAG:GENRE=Sample Genre
+    TAG:track=01
+    TAG:ALBUM=Sample Album
+    TAG:DATE=2012
+    TAG:TITLE=Sample Title
+    TAG:ARTIST=Sample Artist
+    [/FORMAT]
+
+audio_file.to_hash => Returns a Ruby hash after sanitizing the raw output of #raw_tags.
+    { filename: 'sample.flac',
+      format_name: 'flac',
+      format_long_name: 'raw FLAC',
+      nb_streams: '1',
+      duration: '1.000000',
+      filesize: '18291',
+      bit_rate: '146328',
+      start_time: 'N/A',
+      genre: 'Sample Genre',
+      track: '01',
+      album: 'Sample Album',
+      date: '2012',
+      title: 'Sample Title',
+      artist: 'Sample Artist' }
+
+audio_file.tags => Returns a tag structure after applying formatters #to_hash.
+    .album             =>  'Sample Album'
+    .artist            =>  'Sample Artist'
+    .bit_rate          =>  '146 kb/s'
+    .date              =>  2012
+    .duration          =>  '1'
+    .filename          =>  'spec/support/sample.flac'
+    .filesize          =>  '17.9K'
+    .format_long_name  =>  'raw FLAC'
+    .format_name       =>  'flac'
+    .genre             =>  'Sample Genre'
+    .nb_streams        =>  '1'
+    .start_time        =>  'N/A'
+    .title             =>  'Sample Title'
+    .track             =>  '01'
+
+audio_file.reload! => Reload an instance of itself, useful when updating tags.
+```
+
+Update Tags
+-----------
+
+This will update the metadata tags for an audio file.  It will also dynamically add any newly provided tags.  It takes a hash of attributes.
+
+```
+audio_file = PopCap::AudioFile.new('sample.flac')
+audio_file.update_tags({artist: 'David Bowie'})
+
+audio_file.update_tags({fancy_new_tag: 'Custom Tag Input'})
+```
+
+Convert
+-------
+
+This will convert between audio file formats.  It is restricted to basic audio formats.  It also takes an optional bitrate for mp3 formats.  The original file is preserved during the conversion.
+
+Supported formats: aac, flac, m4a, mp3, ogg, wav
+Supported mp3 bitrates: 64, 128, 160, 192, 256, 320
+
+```
+audio_file = PopCap::AudioFile.new('sample.flac')
+
+audio_file.convert(:ogg)
+audio_file.convert(:mp3) # => default bitrate is 192k
+audio_file.convert(:mp3, 256)
+```
+
+File Management Options
+-----------------------
+
+Various Ruby File & FileUtils methods are wrapped for convenience.
+
+```
+audio_file = PopCap::AudioFile.new('sample.flac')
+
+audio_file.backup # => default directory is '/tmp'
+audio_file.backup('some/path')
+
+audio_file.backup_path # => returns backup path
+
+audio_file.destroy # => removes file from filesystem
+
+audio_file.directory # => returns directory, excluding filename
+
+audio_file.filename # => returns filename, excluding directory
+
+audio_file.move('destination') # = > moves file to destination
+
+audio_file.rename('new_name.flac') # => renames file
+
+audio_file.restore # => restores file from backup_path, takes an optional path as well
+
+audio_file.tmppath # => returns the temporary path, e.g. '/tmp/sample.flac'
+```
+
+Dependencies
+------------
+
+[FFmpeg](http://ffmpeg.org)

data/lib/pop_cap/audio_file.rb

@@ -0,0 +1,100 @@
+require 'pop_cap/ffmpeg'
+require 'pop_cap/taggable'
+
+module PopCap
+  FileNotFound = Class.new(StandardError)
+  # Public: This is a class for managing audio files on the filesystem.
+  # It is used to read & write metadata tags, convert between audio formats,
+  # and manage a file on the filesystem using standard UNIX file commands.
+  #
+  # Examples
+  #
+  #   filepath = 'spec/support/sample.flac'
+  #   af = AudioFile.new(filepath)
+  #
+  #
+  class AudioFile
+    attr_accessor :filepath
+
+    include Fileable
+    include Taggable
+
+    # Public: Initialize
+    #
+    # filepath - Requires a valid filepath to a file on the local filesystem.
+    #
+    def initialize(filepath, tag_util=FFmpeg)
+      raise(FileNotFound, filepath) unless File.exists?(filepath)
+      @filepath = File.realpath(filepath)
+      @tag_util = tag_util
+    end
+
+    # Public: convert
+    # This method converts an audio file between formats.
+    # It takes an optional bitrate for mp3 formats.
+    #
+    # format - A valid audio file format as string or symbol.
+    # bitrate - An optional bitrate for mp3s.
+    #
+    # Examples
+    #   audio_file = AudioFile.new('spec/support/sample.flac')
+    #   audio_file.convert('mp3', 128)
+    #   # => 'spec/support/sample.mp3'
+    #
+    def convert(format, bitrate=192)
+      @tag_util.new(@filepath).convert(format, bitrate)
+    end
+
+    # Public: raw_tags
+    # This method returns the raw_tags from FFmpeg.
+    #
+    # Examples
+    #   audio_file = AudioFile.new('spec/support/sample.flac')
+    #   audio_file.raw_tags
+    #   # =>
+    #    [FORMAT]
+    #    filename=spec/support/sample.flac
+    #    nb_streams=1
+    #    format_name=flac
+    #    format_long_name=raw FLAC
+    #    start_time=N/A
+    #    duration=1.000000
+    #    size=18291
+    #    bit_rate=146328
+    #    TAG:GENRE=Sample Genre
+    #    TAG:track=01
+    #    TAG:ALBUM=Sample Album
+    #    TAG:DATE=2012
+    #    TAG:TITLE=Sample Title
+    #    TAG:ARTIST=Sample Artist
+    #    [/FORMAT]
+    #
+    def raw_tags
+      @raw ||= @tag_util.new(@filepath).read_tags
+    end
+
+    # Public: This method reloads the current instance.
+    #
+    # Examples
+    #   audio_file.reload!
+    #
+    def reload!
+      @raw = nil
+      super
+    end
+
+    # Public: update_tags(updates)
+    # Updates existing tags, adds a tag if it does not exist.
+    #
+    # updates - This takes a hash of keys matching a tag name with a value.
+    #
+    # Examples
+    #
+    #   audio_file.update_tags({artist: 'New Artist', album: 'New Album'})
+    #
+    def update_tags(updates)
+      @tag_util.new(@filepath).update_tags(updates)
+      self.reload!
+    end
+  end
+end

data/lib/pop_cap/commander.rb

@@ -0,0 +1,64 @@
+require 'open3'
+
+module PopCap
+  # Public: This is a wrapper for the Open3 Ruby Standard Library.
+  #
+  # Examples
+  #
+  #   options = %W{ls} + %W{-lh}
+  #   Commander.new(options).execute.output
+  #   # => <directory contents>
+  #
+  class Commander
+    # Public: Initialize
+    #
+    # args - Arguments should be escaped with an interpolated literal.
+    #
+    def initialize(*args)
+      raise(ArgumentError, error_message) if args.empty?
+      @command = args.inject(%W{}) { |command, arg| command << arg }
+      @executed = []
+    end
+
+    # Public: Execute the command using Open3.capture3.
+    # It will return an instance of Commander, in order
+    # to chain methods.
+    #
+    def execute
+      @executed = Open3.capture3(*@command)
+      self
+    end
+
+    # Public: Open3.capture3 returns an array of three elements.
+    # The first element returned is stdout.
+    #
+    def stdout
+      @executed[0]
+    end
+
+    # Public: Open3.capture3 returns an array of three elements.
+    # The second element returned is stderr.
+    #
+    def stderr
+      @executed[1]
+    end
+
+    # Public: Open3.capture3 returns an array of three elements.
+    # The third element returned is status.  Status can have a
+    # 'success?' of true or false.
+    #
+    # Examples
+    #
+    #   self.success?
+    #   # => true
+    #
+    def success?
+      @executed[2].success?
+    end
+
+    private
+    def error_message
+      'Cannot run command with no args.'
+    end
+  end
+end

data/lib/pop_cap/converter.rb

@@ -0,0 +1,40 @@
+module PopCap
+  # Internal: This module builds a command to convert an audio file
+  # to the specified output format. The module is included in FFmpeg.
+  #
+  module Converter
+    # Internal: This method takes an input format & optional bitrate
+    # in order to supply the ffmpeg command used to convert.
+    #
+    # format - Provide a valid format as a string or symbol.
+    # bitrate - Provide a valid bitrate as a string or integer.
+    #
+    def convert(format, bitrate=192)
+      @bitrate = bitrate
+      @format = format.downcase.to_s
+      input_path + strict_mode + bitrate_options + output_path
+    end
+
+    private
+    def bitrate_options
+      %W{-ab #{@bitrate}k}
+    end
+
+    def input_path
+      %W{ffmpeg -i #{self.filepath}}
+    end
+
+    def output_path
+      %W{#{self.filepath.sub(%r([^.]+\z),@format)}}
+    end
+
+    def strict_mode
+      return %W{} unless use_strict_mode?
+      %W{-strict -2}
+    end
+
+    def use_strict_mode?
+      @format == 'm4a'
+    end
+  end
+end

data/lib/pop_cap/ffmpeg.rb

@@ -0,0 +1,130 @@
+require 'pop_cap/commander'
+require 'pop_cap/converter'
+require 'pop_cap/fileable'
+
+module PopCap
+  MissingDependency = Class.new(Errno::ENOENT)
+  # Internal: This is a wrapper for the FFmpeg C library.
+  #
+  # Examples
+  #
+  #   filepath = 'spec/support/sample.flac'
+  #   ffmpeg = FFmpeg.new(filepath)
+  #
+  class FFmpeg
+    include Converter
+    include Fileable
+
+    attr_accessor :filepath
+
+    # Internal: initialize
+    #
+    # filepath - Requires a valid filepath to a file on the local filesystem.
+    #
+    def initialize(filepath)
+      check_for_ffmpeg_install
+      @filepath = filepath
+    end
+
+    # Internal: convert
+    # This command calls up to Converter@convert.
+    #
+    # format - A valid audio file format as string or symbol.
+    # bitrate = A valid bit rate as string or symbol.
+    #
+    def convert(format, bitrate=192)
+      conversion = super(format,bitrate)
+      Commander.new(*conversion).execute
+    end
+
+    # Internal: read_tags
+    # Returns the raw output of FFProbe's show_format option.
+    #
+    # Examples
+    #
+    #    [FORMAT]
+    #    filename=spec/support/sample.flac
+    #    nb_streams=1
+    #    format_name=flac
+    #    format_long_name=raw FLAC
+    #    start_time=N/A
+    #    duration=1.000000
+    #    size=18291
+    #    bit_rate=146328
+    #    TAG:GENRE=Sample Genre
+    #    TAG:track=01
+    #    TAG:ALBUM=Sample Album
+    #    TAG:DATE=2012
+    #    TAG:TITLE=Sample Title
+    #    TAG:ARTIST=Sample Artist
+    #    [/FORMAT]
+    #
+    def read_tags
+      @stdout ||= encode(read_output)
+    end
+
+    # Internal: update_tags(updates)
+    # This wraps FFmpeg's -metadata command.
+    #
+    # Examples
+    #   filepath = 'spec/support/sample.flac'
+    #   ffmpeg = FFmpeg.new(filepath)
+    #   ffmpeg.update_tags({artist: 'New Artist'})
+    #
+    def update_tags(updates)
+      @updates = updates
+      unless Commander.new(*write_command).execute.success?
+        raise(FFmpegError, write_error_message)
+      end
+      self.restore('/tmp')
+      @stdout = nil
+    end
+
+    private
+    def check_for_ffmpeg_install
+      begin
+        Open3.capture3('ffmpeg')
+      rescue Errno::ENOENT
+        raise MissingDependency, 'FFmpeg is not installed.'
+      end
+    end
+
+    def encode(string)
+      return string if string.valid_encoding?
+      original_encoding = string.encoding.name
+      string.encode!('UTF-16', original_encoding, undef:
+                     :replace, invalid: :replace)
+      string.encode!('UTF-8')
+    end
+
+    def read_command
+      %W{ffprobe -show_format} + %W{#{filepath}}
+    end
+
+    def read_output
+      commander = Commander.new(*read_command).execute
+      raise(FFmpegError, read_error_message) unless commander.success?
+      commander.stdout
+    end
+
+    def read_error_message
+      "Error reading #{self.filepath}"
+    end
+
+    def write_command
+      %W{ffmpeg -i #{filepath}} + write_options + %W{#{self.tmppath}}
+    end
+
+    def write_options
+      @updates.inject(%W{}) do |options,update|
+        options << '-metadata' << update.join('=')
+      end
+    end
+
+    def write_error_message
+      "Error updating #{self.filepath}"
+    end
+  end
+end
+
+FFmpegError = Class.new(StandardError)

data/lib/pop_cap/fileable.rb

@@ -0,0 +1,134 @@
+require 'fileutils'
+
+module PopCap
+  PathError = Class.new(StandardError)
+
+  # Public: This is a wrapper for the File & FileUtils Ruby
+  # Standard Libraries.  The module requires it be included in
+  # a class which has a #filepath method that returns a filepath.
+  #
+  module Fileable
+
+    # Public: This will backup a file to a specified directory.
+    #
+    # backup_dir - path to a directory on the filesystem.
+    # It defaults to '/tmp'.
+    #
+    # Examples
+    #   audio_file.backup('/usr')
+    #   # => file is copied to '/usr'
+    #
+    def backup(backup_dir='/tmp')
+      @backup_dir = backup_dir
+      FileUtils.cp(self.filepath, backup_path)
+    end
+
+    # Public: This will return the backup path.
+    # It will raise an error if file was not backed up previously.
+    #
+    # Examples
+    #   klass = SomeClass.new('path/to/file.txt').backup('/tmp')
+    #   klass.backup_path
+    #   # => '/tmp/file.txt'
+    #
+    def backup_path
+      raise(PathError, backup_path_error_message) unless @backup_dir
+      "#{@backup_dir}/" + filename
+    end
+
+    # Public: This will remove the file from the system.
+    #
+    # Examples
+    #   klass = SomeClass.new('path/to/file.txt')
+    #   klass.destroy
+    #
+    def destroy
+      FileUtils.rm_f(self.filepath)
+      self.filepath = nil
+    end
+
+    # Public: This will return the directory, excluding the filename.
+    #
+    # Examples
+    #   SomeClass.new('path/to/file.txt').directory
+    #   # => 'path/to/'
+    #
+    def directory
+      File.dirname(self.filepath)
+    end
+
+    # Public: This will return the filename, excluding directory.
+    #
+    # Examples
+    #   SomeClass.new('path/to/file.txt').filename
+    #   # => 'file.txt'
+    #
+    def filename
+      File.basename(self.filepath)
+    end
+
+    # Public: This method moves a file to destination.
+    #
+    # destination - The folder/directory to move the file.
+    #
+    # Examples
+    #   klass = SomeClass.new('path/to/file.txt')
+    #   klass.move('/tmp')
+    #   # => '/tmp/file.txt'
+    #
+    def move(destination)
+      FileUtils.mv(self.filepath, destination)
+      self.filepath = destination + '/' + filename
+    end
+
+    # Public: This method renames a file.
+    #
+    # new_name - The new name of the file.
+    #
+    # Examples
+    #   klass = SomeClass.new('path/to/file.txt')
+    #   klass.rename('rename.txt')
+    #   # => 'path/to/rename.txt'
+    #
+    def rename(new_name)
+      new_path = self.directory + '/' + new_name
+      FileUtils.mv(self.filepath, new_path)
+      self.filepath = new_path
+    end
+
+    # Public: This will restore a file from the backup path.
+    # It will raise an error if file has no backup path.
+    #
+    # from_path - The path from which to restore.  It defaults
+    # to the #backup_path.
+    #
+    # Examples
+    #   klass = SomeClass.new('path/to/file.txt').backup('/tmp')
+    #   klass.restore
+    #
+    def restore(from_path=nil)
+      @from_path = from_path
+      FileUtils.mv(restore_path, self.filepath)
+    end
+
+    # Public: This returns a temporary path for the file.
+    #
+    # Examples
+    #   klass = SomeClass.new('path/to/file.txt').tmppath
+    #   # => '/tmp/file.txt'
+    #
+    def tmppath
+      '/tmp/' + filename
+    end
+
+    private
+    def backup_path_error_message
+      'Cannot determine backup path.'
+    end
+
+    def restore_path
+      return backup_path unless @from_path
+      @from_path + '/' + filename
+    end
+  end
+end