lllibrary 0.0.1 → 0.0.2

data/README.md

@@ -1,85 +1,21 @@
-#lllibrary
+# lllibrary
 
 `lllibrary` is a Ruby library that manages music libraries. It stores tracks (with metadata) and playlists in a database (using ActiveRecord), and gives you a sort of DSL to build complex playlists with ease.
 
 ## Install
 
-    $ gem install lllibrary
-
-## Usage
-
-This gives you an idea. Better documentation coming soon.
-
-    # Lllibrary
-    library = Lllibrary.new(File.join(ENV["HOME"], "music.sqlite3"), "sqlite3") do |t|
-      # provide a block like this if the database doesn't exist yet.
-      # the location, created_at, and updated_at fields are always
-      # created, the rest must be specified like so.
+First, you need [taglib](http://taglib.github.com/). Get it from there and install it, or [install it with a package manager](https://github.com/robinst/taglib-ruby#installation). (Apparently Windows users don't have to do this, as the taglib DLL is bundled with the taglib-ruby gem.)
 
-      # adds database fields for title, artist, etc.
-      t.default_metadata
+Then, just type:
 
-      # adds all the database fields that iTunes uses
-      t.itunes_metadata
-
-      # you can also specify your own custom fields
-      t.string :five_word_review
-      t.integer :popularity, null: false, default: 0
-    end
-    library.tracks
-    library.playlists
-    library.add(Dir["Music/**/*.{mp3,m4a,ogg}"], &blk)
-    library.add_playlist(:favourites, library.select { rating 100 })
-    library.import(:itunes, "/path/to/iTunes Music Library.xml", &blk)
-    library.clear_playlists
-    library.clear_all
-
-    # Lllibrary::Track
-    track.playlists
-    track.location
-    track.created_at
-    track.updated_at
-    track.send(metadata_field)
-
-    # Lllibrary::Playlist
-    playlist.name
-    playlist.tracks
-    playlist.empty?
-    playlist.length
-    playlist.add(track_or_tracks, index = nil)
-    playlist.remove(track_or_tracks)
-    playlist.total_length
-    playlist.sort(&blk)
-    playlist.shuffle
-    playlist.playlist_items
-    playlist.created_at
-    playlist.updated_at
-    playlist.clear
+    $ gem install lllibrary
 
-    # Lllibrary::PlaylistItem
-    playlist_item.position
-    playlist_item.track
-    playlist_item.playlist
-    playlist_item.created_at
-    playlist_item.updated_at
+## Usage
 
-    # Selectors DSL
-    library.select do
-      title("blackout")                # equivalent to library.tracks.where("title LIKE '%blackout%'").all
-      title("blackout", match: :left)  # equivalent to library.tracks.where("title LIKE 'blackout%'").all
-      title("blackout", match: :exact) # equivalent to library.tracks.where("title LIKE 'blackout'").all
-      length("1:00".."2:00")           # equivalent to library.tracks.where(length: 60000...120000).all
-      rating(gte: 80)                  # equivalent to library.tracks.where("rating >= 80").all
-      none                             # []
-      all                              # library.tracks.all
-    end
+Erm... read the inline docs.
 
 ## TODO
 
 * Better error reporting
-* Fix bug with time selectors
-* Get metadata from tags in audio files without requiring a C library to be installed (like taglib)
-* Allow blocks to be passed to Lllibrary#add and Lllibrary#import
-* Figure out how to handle multiple database connections
 * Tests, documentation, the like
 

data/lib/lllibrary.rb

@@ -1,5 +1,6 @@
 require "active_record"
 require "plist"
+require "taglib"
 
 require "lllibrary/track"
 require "lllibrary/playlist"
@@ -8,7 +9,66 @@ require "lllibrary/playlist_item"
 require "lllibrary/database"
 require "lllibrary/dsl"
 
+# A Lllibrary represents a database of tracks and playlists. It helps you manage
+# and query this database by automatically pulling metadata from the audio files
+# you add, being able to import music libraries from other programs like iTunes,
+# and providing a DSL for selecting songs from your music library with ease.
 class Lllibrary
+  attr_reader :dsl
+
+  # These are the fields that taglib can pull from audio files. The keys are
+  # taglib's names for them, the values are the column names that lllibrary uses
+  # by default.
+  TAGLIB_METADATA = {
+    tag: {
+      album: "album",
+      artist: "artist",
+      comment: "comments",
+      genre: "genre",
+      title: "title",
+      track: "track_number",
+      year: "year"
+    },
+    audio_properties: {
+      length: "total_time",
+      bitrate: "bit_rate",
+      channels: "channels",
+      sample_rate: "sample_rate"
+    }
+  }
+
+  # Create a new Lllibrary object. Takes the path to the database and the
+  # database adapter (e.g. "sqlite3"). It also takes a block which specifies
+  # the schema of the database. Without this block, the tracks table will only
+  # have three fields: location, created_at, and updated_at. You need to
+  # provide a block if you want your tracks table to have fields for metadata.
+  # Here's an example:
+  #
+  #     library = Lllibrary.new("songs.sqlite3", "sqlite3") do |t|
+  #       t.string :title
+  #       t.string :artist
+  #       t.string :album
+  #       t.integer :year
+  #     end
+  #
+  # There are also a couple aliases that automatically add a bunch of metadata
+  # fields for you. These are t.default_metadata and t.itunes_metadata.
+  #
+  # t.default_metadata adds these fields: album, artist, comments, genre, title,
+  # track_number, year, total_time, bit_rate, channels, sample_rate. These are
+  # the fields that taglib is able to fill in by examining the audio files you
+  # add.
+  #
+  # t.itunes_metadata add almost all of the metadata fields that iTunes uses,
+  # and will be filled in when you import your iTunes library. These fields are:
+  # original_id, title, artist, composer, album, album_artist, genre, total_time,
+  # disc_number, disc_count, track_number, track_count, year, date_modified,
+  # date_added, bit_rate, sample_rate, comments, play_count, play_date, skip_count,
+  # skip_date, rating.
+  #
+  # Note: ActiveRecord doesn't seem to allow you to connect to multiple databases
+  # at the same time. Please only instantiate one Lllibrary per process.
+  #
   def initialize(db_path, db_adapter, &schema_blk)
     @db = Lllibrary::Database.new(db_path, db_adapter)
     if schema_blk
@@ -22,26 +82,77 @@ class Lllibrary
     @dsl = Lllibrary::DSL.new(self)
   end
 
+  # Takes a block, and evaluates that block in the context of the Lllibrary's DSL.
+  # Inside the block, every database field on the tracks table becomes a method
+  # called a selector. Each selector takes a value to match tracks against, and
+  # returns an Array of those tracks. String-like fields have string selectors,
+  # and number-like fields have numeric selectors. There is also an all selector,
+  # a none selector, and a playlist selector. See dsl.rb for a detailed
+  # description of these.
+  #
+  #     library.select do
+  #       composer(:rachmanino)    # example of string selector
+  #       year(2010..2012)         # example of numeric selector
+  #       total_time(gt: "6:00")   # example of time selector
+  #       playlist(:energetic)     # example of playlist selector
+  #       all                      # returns array of all tracks
+  #       none                     # returns empty array
+  #     end
+  #
   def select(&blk)
     @dsl.instance_eval &blk
   end
 
+  # Returns a bare Relation of the Track model.
   def tracks
     Lllibrary::Track.scoped
   end
 
+  # Returns a bare Relation of the Playlist model.
   def playlists
     Lllibrary::Playlist.scoped
   end
 
+  # Adds one or more tracks to the library. Takes a path to the audio file you
+  # wanted added, or array of multiple paths. Uses taglib to fill in metadata
+  # for each track, if the corresponding database fields exist. After filling in
+  # the metadata, if a block was given, it yields the Track object to this block.
+  # If the block returns a Track object (with possible modifications of your own),
+  # it then saves the Track and goes on to the next one. If the block doesn't
+  # return a Track, the track is not saved.
+  #
+  # For example, here's how you would use the filename as the title of the track
+  # if the title is missing from the audio file's metadata:
+  #
+  #     library.add(Dir["Music/**/*.mp3"]) do |track|
+  #       track.title ||= File.basename(track.location, ".mp3")
+  #       track
+  #     end
+  #
   def add(paths_to_tracks, &blk)
     Array(paths_to_tracks).each do |path|
-      track = tracks.new(location: path)
+      track = tracks.new(location: File.expand_path(path))
+
+      TagLib::FileRef.open(path) do |audio_file|
+        TAGLIB_METADATA.each do |tag_or_audio_properties, properties|
+          if audio_file.send(tag_or_audio_properties)
+            properties.each do |property, column|
+              value = audio_file.send(tag_or_audio_properties).send(property)
+              value *= 1000 if property == :length # convert seconds to milliseconds
+              value = nil if value == 0
+              track.send("#{column}=", value) if Track.column_names.include? column
+            end
+          end
+        end
+      end
+
       track = blk.call(track) if blk
       track.save! if track.is_a?(Track)
     end
   end
 
+  # Creates a new playlist and saves it. Takes a name for the playlist and an
+  # Array of Tracks. The order of the Tracks is preserved, of course.
   def add_playlist(name, tracks)
     playlist = playlists.new(name: name)
     playlist.save!
@@ -54,7 +165,14 @@ class Lllibrary
     end
   end
 
-  def import(type, path, options = {})
+  # Imports a music library from another program, such as iTunes. Incidentally,
+  # iTunes is the only such program supported right now. Here's an example:
+  #
+  #     library.import :itunes, "path/to/iTunes Music Library.xml", logger: method(:puts)
+  #
+  # I will probably redesign this method to be more flexible and such, so I'll
+  # curb my documenting of it any further till then.
+  def import(type, path, options = {}, &blk)
     logger = options[:logger]
     if type == :itunes
       logger.("Parsing XML...") if logger
@@ -93,7 +211,8 @@ class Lllibrary
         end
 
         track = tracks.new(attributes)
-        if track.save
+        track = blk.call(track)
+        if track && track.save
           num_tracks += 1
         end
       end
@@ -125,10 +244,12 @@ class Lllibrary
     end
   end
 
+  # Deletes all your playlists.
   def clear_playlists
     playlists.destroy_all
   end
 
+  # Deletes all tracks and playlists.
   def clear_all
     tracks.destroy_all
     clear_playlists

data/lib/lllibrary/database.rb

@@ -1,12 +1,19 @@
 class Lllibrary
+  # Handles connecting to the database, and initializing the schema.
   class Database
     def initialize(path, adapter)
       @path, @adapter = path, adapter
+      connect
+    end
+
+    def connect
       ActiveRecord::Base.establish_connection(adapter: @adapter, database: @path)
+      @connected = true
     end
 
     def disconnect
       ActiveRecord::Base.remove_connection
+      @connected = false
     end
 
     def exists?
@@ -18,64 +25,74 @@ class Lllibrary
     end
 
     def connected?
-      ActiveRecord::Base.connected?
+      @connected &&= ActiveRecord::Base.connected?
     end
 
     def generate_schema(&blk)
       ActiveRecord::Schema.define do
-        create_table :tracks do |t|
-          t.string :location
-          t.timestamps
+        unless table_exists? :tracks
+          create_table :tracks do |t|
+            def t.default_metadata
+              # tag info supported by taglib
+              string :title
+              string :artist
+              string :album
+              string :genre
+              text :comments
+              integer :year
+              integer :track_number
 
-          def t.default_metadata
-            string :title
-            string :artist
-            string :album
-            string :genre
-            integer :length
-            integer :track_number
-            integer :year
-          end
+              # audio properties supported by taglib
+              integer :total_time
+              integer :bit_rate
+              integer :sample_rate
+              integer :channels
+            end
 
-          def t.itunes_metadata
-            integer :original_id
-            string :title
-            string :artist
-            string :composer
-            string :album
-            string :album_artist
-            string :genre
-            integer :total_time
-            integer :disc_number
-            integer :disc_count
-            integer :track_number
-            integer :track_count
-            integer :year
-            datetime :date_modified, null: false
-            datetime :date_added, null: false
-            integer :bit_rate
-            integer :sample_rate
-            text :comments
-            integer :play_count, null: false, default: 0
-            datetime :play_date
-            integer :skip_count, null: false, default: 0
-            datetime :skip_date
-            integer :rating, null: false, default: 0
-          end
+            def t.itunes_metadata
+              integer :original_id
+              string :title
+              string :artist
+              string :composer
+              string :album
+              string :album_artist
+              string :genre
+              integer :total_time
+              integer :disc_number
+              integer :disc_count
+              integer :track_number
+              integer :track_count
+              integer :year
+              datetime :date_modified, null: false
+              datetime :date_added, null: false
+              integer :bit_rate
+              integer :sample_rate
+              text :comments
+              integer :play_count, null: false, default: 0
+              datetime :play_date
+              integer :skip_count, null: false, default: 0
+              datetime :skip_date
+              integer :rating, null: false, default: 0
+            end
 
-          blk.call(t)
+            blk.call(t)
+          end
         end
 
-        create_table :playlists do |t|
-          t.string :name
-          t.datetime :created_at
-          t.datetime :updated_at
+        unless table_exists? :playlists
+          create_table :playlists do |t|
+            t.string :name
+            t.datetime :created_at
+            t.datetime :updated_at
+          end
         end
 
-        create_table :playlist_items do |t|
-          t.references :playlist, null: false
-          t.references :track, null: false
-          t.integer :position
+        unless table_exists? :playlist_items
+          create_table :playlist_items do |t|
+            t.references :playlist, null: false
+            t.references :track, null: false
+            t.integer :position
+          end
         end
       end
     end

data/lib/lllibrary/dsl.rb

@@ -1,9 +1,14 @@
 class Lllibrary
+  # Contains all the selectors used in Lllibrary's DSL. See Lllibrary#select for
+  # how to access the DSL.
   class DSL
     def initialize(library)
       @library = library
     end
 
+    # Turns all the columns on the tracks table into methods that I call selectors.
+    # Based on the column's type in the database, this either delegates to
+    # DSL#numeric_selector or DSL#string_selector.
     def method_missing(field, *args)
       if Lllibrary::Track.column_names.include? field.to_s
         type = Lllibrary::Track.columns_hash[field.to_s].type
@@ -30,15 +35,21 @@ class Lllibrary
       []
     end
 
-    # Makes a playlist out of tracks that match the string query on the given
+    # Returns an Array of tracks that match the string query on the given
     # column. It's SQL underneath, so you can use % and _ as wildcards in the
     # query. By default, % wildcards are inserted on the left and right of your
     # query. Use the :match option to change this:
     #
-    #   :match => :middle   "%query%"   (default)
-    #   :match => :left     "query%"
-    #   :match => :right    "%query"
-    #   :match => :exact    "query"
+    #     :match => :middle   "%query%"   (default)
+    #     :match => :left     "query%"
+    #     :match => :right    "%query"
+    #     :match => :exact    "query"
+    #
+    # Here are some examples:
+    #
+    #     genre(:electronic, :edm)    # matches "Electronic", "Electronica", "EDM", etc.
+    #     genre(:tmbg, match: :exact) # only matches "TMBG" (but case-insensitively)
+    #     composer(:rachmanino, match: :left) # matches "Rachmaninov", "Rachmaninoff", but not "Sergei Rachmaninov"
     #
     def string_selector(column, *queries)
       options = queries.last.is_a?(Hash) ? queries.pop : {}
@@ -57,23 +68,33 @@ class Lllibrary
       end.flatten
     end
 
-    # Makes a playlist out of tracks that satisfy certain conditions on the given
+    # Returns an Array of tracks that satisfy certain conditions on the given
     # numeric column. You can pass an exact value to check for equality, a range,
-    # or a hash that specifies greater-than and less-than options like this:
-    #
-    #   numeric_selector :year, greater_than: 2000
+    # or a hash that specifies greater-than and less-than operators.
     #
     # The possible operators, with their shortcuts, are:
     #
-    #   :greater_than / :gt
-    #   :less_than / :lt
-    #   :greater_than_or_equal / :gte
-    #   :less_than_or_equal / :lte
-    #   :not_equal / :ne
+    #     :greater_than / :gt
+    #     :less_than / :lt
+    #     :greater_than_or_equal / :gte
+    #     :less_than_or_equal / :lte
+    #     :not_equal / :ne
     #
     # Note: You can only use one of these operators at a time. If you want a
     # range, use a Range.
     #
+    # Time strings like "1:23" can be given, and will be converted to a Range of
+    # milliseconds. For example, "1:00" will be treated like 60000..60999.
+    # Obviously, any field this is used on should be storing time in milliseconds.
+    #
+    # Here's some examples:
+    #
+    #     year(2010..2012)           # equivalent to year(2010, 2011, 2012)
+    #     year(2011)                 # only matches 2011
+    #     year(gte: 2000)            # matches 2000 and up
+    #     total_time("2:30")         # matches 150000..150999 milliseconds
+    #     total_time("1:00".."2:00") # matches 60000..120999 milliseconds
+    #
     def numeric_selector(column, *values_or_hash)
       parse = lambda do |x|
         if x.is_a? String
@@ -86,6 +107,7 @@ class Lllibrary
         elsif x.is_a? Range
           left = x.begin.is_a?(String) ? Lllibrary.parse_time(x.begin) : x.begin
           right = x.end.is_a?(String) ? Lllibrary.parse_time(x.end) : x.end
+          right += 999 if right % 1000 == 0 && !x.exclude_end?
           Range.new(left, right, x.exclude_end?)
         else
           x
@@ -127,10 +149,15 @@ class Lllibrary
           raise ArgumentError, "'#{operator}' isn't a valid operator"
         end
       else
-        @library.tracks.where(column => parse.(values_or_hash)).all
+        values_or_hash.map do |value|
+          @library.tracks.where(column => parse.(value)).all
+        end.flatten
       end
     end
 
+    # Returns an Array of all tracks that are in a Playlist whose name matches
+    # one of the strings given to this selector. It's kind of ugly, I will
+    # probably be changing this.
     def playlist(*names)
       names.map do |name|
         playlists = @library.playlists.arel_table

data/lib/lllibrary/playlist.rb

@@ -1,8 +1,12 @@
 class Lllibrary
+  # A Playlist is a list of Tracks in a particular order and with possible
+  # repeats of Tracks. A Playlist has a name, and that's about it.
   class Playlist < ActiveRecord::Base
     has_many :playlist_items, order: "playlist_items.position ASC", dependent: :destroy
     has_many :tracks, through: :playlist_items, order: "playlist_items.position ASC"
 
+    # Adds the given Track or Array of Tracks to the end of the Playlist. If
+    # an index is given, the track(s) are inserted at that position.
     def add(track_or_tracks, at = nil)
       base_position = nil
       if at
@@ -24,35 +28,57 @@ class Lllibrary
       reload
     end
 
+    # Removes the Track or Array of Tracks from the Playlist.
     def remove(track_or_tracks)
       playlist_items.where(track_id: track_or_tracks).destroy_all
       reload
     end
 
+    # Removes the Track at the given index. If a number is given in the
+    # second argument, removes that number of tracks starting from index.
+    def remove_at(index, n = 1)
+      playlist_items.offset(index).limit(n).all.each(&:destroy)
+      reload
+    end
+
+    # Returns true if the playlist is empty.
     def empty?
       playlist_items.empty?
     end
 
+    # Gets the number of items in the playlist.
     def length
       playlist_items.count
     end
 
+    # Calculates the total length of the playlist by summing the tracks'
+    # total_time column by default, which stores milliseconds by default.
+    # You can provide a different column using the :field option, like so:
+    #
+    #     playlist.total_length(field: :length)
+    #
+    # If the given field stores time in milliseconds, this method returns
+    # milliseconds. If it stores time in seconds, this returns seconds.
+    # And so on.
     def total_length(options = {})
-      tracks.sum(options[:field] || :length)
+      tracks.sum(options[:field] || :total_time)
     end
 
+    # Sorts the playlist using the given block, then saves. See Array#sort.
     def sort(&blk)
       sorted_tracks = tracks.sort(&blk)
       clear
       add(sorted_tracks)
     end
 
+    # Shuffles the playlist and saves.
     def shuffle
       shuffled_tracks = tracks.shuffle
       clear
       add(shuffled_tracks)
     end
 
+    # Clears the playlist and saves.
     def clear
       playlist_items.destroy_all
       reload

data/lib/lllibrary/playlist_item.rb

@@ -1,4 +1,6 @@
 class Lllibrary
+  # Joins the Playlist and Track tables. Contains a position column to keep
+  # track of the order, as well as created_at and updated_at columns.
   class PlaylistItem < ActiveRecord::Base
     belongs_to :playlist
     belongs_to :track

data/lib/lllibrary/track.rb

@@ -1,8 +1,17 @@
 class Lllibrary
+  # A Track represents an audio file. At minimum, it contains a location field
+  # which stores the path to the audio file it represents.
   class Track < ActiveRecord::Base
     has_many :playlist_items, dependent: :destroy
     has_many :playlists, through: :playlist_items
 
     validates :location, presence: true, uniqueness: true
+
+    # By default, Tracks are sorted by their file path.
+    #
+    # TODO: have a way of specifying sorting by parsing a Symbol like :artist_asc_album_asc_track_number_asc
+    def <=>(other)
+      location <=> other.location
+    end
   end
 end

data/lllibrary.gemspec

@@ -1,7 +1,7 @@
 Gem::Specification.new do |s|
   s.name = "lllibrary"
-  s.version = "0.0.1"
-  s.date = "2012-12-17"
+  s.version = "0.0.2"
+  s.date = "2012-02-02"
   s.summary = "A library for managing and querying a music library."
   s.description = "lllibrary is a Ruby library for managing and querying a music library."
   s.author = "Jeremy Ruten"
@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.files = ["Gemfile", "Gemfile.lock", "LICENSE", "lllibrary.gemspec", "README.md"]
   s.files += Dir["lib/**/*.rb"]
 
-  %w(bundler plist sqlite3 activerecord activesupport).each do |gem_name|
+  %w(bundler plist sqlite3 activerecord activesupport taglib-ruby).each do |gem_name|
     s.add_runtime_dependency gem_name
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lllibrary
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-12-17 00:00:00.000000000 Z
+date: 2012-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -91,6 +91,22 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: taglib-ruby
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement