ogg_album_tagger 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 677d2faa7f9687d6108fe6b2cdb1ccafb25952ab
+  data.tar.gz: 6c16e194ad9ebb0dc94944b2fe202953e438e365
+SHA512:
+  metadata.gz: 3ed2555d969ad45a4c6e980d4e03013a71e9d473d83d29080248274c64ddb6abc4a341d198e8788d171dec8766c3cc7dcad1f1d8ec8e3c3ea30d9c2ba396e157
+  data.tar.gz: fe70f9f75f0709974804fc044263ea0210d5b39a21a21e440220133158430a1a236b51755e2e606fb3324207c9cd1f85c50c472561df7bca23e6cb6bc85e714e

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+*.swp

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ogg_album_tagger.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Cyrille Faucheux
+
+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,161 @@
+# OggAlbumTagger
+
+OggAlbumTagger is an interactive command line tool that help you tag ogg files. As the name suggest, OggAlbumTagger is able to manage whole albums and compilations.
+
+## Why OggAlbumTagger
+
+I wanted a tool that would give me a full and easy access to all tags and would integrate some logic to quickly tag full albums or compilations.
+
+Current solutions were not satisfying enough to me:
+- No easy way to access non-standard tags.
+- No/limited support for tags with multiple values.
+- No easy way to tag full albums.
+- Unwanted padding of numerical tags.
+- No consistency concerning the case and order of the tags (ok, this point might be a bit excessive).
+
+Therefore, I wrote OggAlbumTagger. It is designed to enforce some good tagging practices (you can read about them in the "How to properly tag your music" section below), but it will let you do whatever you want.
+
+## Usage
+
+    $ ogg-album-tagger [options] files|directories
+    Options:
+        -a, --album    Album mode, treat a single directory as an album.
+        -v, --version  Display version information and exit.
+        -h, --help     Print this help.
+
+When executed, OggAlbumTagger extracts the tags of the ogg files passed as arguments (ogg files will be searched recursively in directories). Once done, you have to use the commands listed below to access and modify the tags.
+
+When the `-a` option is passed, OggAlbumTagger will require album (or compilation) specific tags, will enforce a few more good tagging practices and will allow you to rename the album directory along with the tracks. You have to work on a single directory.
+
+### Preliminary notes
+
+- OggAlbumTagger works like most terminals. Arguments need to be separated by one or more spaces. If your argument contains special characters (spaces, single or double quotes), you can either escape them with a backslash (`\`) or enclose your argument with single or double quotes. Inside a double-quoted argument, you can escape double quotes with a backslash. Single-quoted arguments do not support escaping.
+
+- OggAlbumTagger is capable of autocompletion and autosuggestion. Press the `tab` key to autocomplete your arguments, tag names, tag values and filenames. If you don't know what to do, double press `tab` to get suggestions.
+
+- Tag names are case insensitive, but they will be written uppercase in files.
+
+- Each tag can have multiple values (but in order to enforce good tagging practices, OggAlbumTagger will prevent you to do so for some tags).
+
+- OggAlbumTagger uses UTF-8 (but currently I don't know what happen if your terminal is not in UTF-8).
+
+### Available commands
+
+- `ls`: lists the files you have access to. Files are sorted according to their filename and are indexed by their position in the list. The star at the beginning of a line indicates that the file is selected (see the `select` command for more details).
+
+```
+> ls
+*    1: Queen - 1981 - Greatest Hits I - 01 - Bohemian Rapsody (1975).ogg
+*    2: Queen - 1981 - Greatest Hits I - 02 - Another One Bites The Dust (1980).ogg
+*    3: Queen - 1981 - Greatest Hits I - 03 - Killer Queen (1974).ogg
+...
+```
+
+- `select arg1 [arg2...]`: allow to select a subset of files to work on. The following selectors are available:
+    - `all`: selects all the files.
+    - `i`: selects the file at position `i` in the list.
+    - `i-j`: selects the files from position `i` to position `j` in the list.
+
+  Index-based arguments can be prefixed by a `+` or `-` sign (e.g. `-3` or `+10-20`). In this case your selector will add or remove elements to the current selection.
+
+  Multiple selectors can be specified at once. Order is important.
+
+- `show`: without argument, displays the tags of the selected files. Tags are sorted alphabetically, except for the `metadata_block_picture` which is listed last. The command can be restricted to a single tag XXX by using the `show tag xxx` command.
+
+- `set <tag> value1 [value2...]`: tags each selected files with the specified tag and all specified values. If the tag does not exists, it is created. If it already exists, all previous values are discarded before adding the new ones. Duplicated values are discarded.
+
+  If the tag is `metadata_block_picture` (also aliased as `picture`), you have to provide the path to a jpeg or png file (autocomplete also works here) and optionally a description of the picture. OggAlbumTagger currently only supports the "front cover" type (see http://xiph.org/flac/format.html#metadata_block_picture).
+
+- `add <tag> value1 [value2...]`: like `set`, but previous values are not discarded.
+
+- `rm <tag> [value1...]`: removes the specified values of the specified tag for all selected files. If no value is specified, the tag is deleted.
+
+- `auto tracknumber`: automatically sets the `TRACKNUMBER` tag based on the selection. Numbering starts at 1, there is no padding with zeros.
+
+- `auto rename`: renames the directory and the files based on the tags. Different patterns are used:
+
+  - Single files
+
+    Directory: N/A
+
+    Ogg files: ARTIST - DATE - TITLE.ogg
+
+  - Albums
+
+    Directory: ARTIST - DATE - ALBUM
+
+    Ogg files: ARTIST - DATE - ALBUM - [DISCNUMBER.]TRACKNUMBER - TITLE.ogg
+
+  - Single artist compilations (albums where tracks have different dates, like a best-of)
+
+    Directory: ARTIST - ALBUMDATE - ALBUM
+
+    Ogg files: ARTIST - ALBUMDATE - ALBUM - [DISCNUMBER.]TRACKNUMBER - TITLE - DATE.ogg
+
+  - Compilations
+
+    Directory: ALBUM - ALBUMDATE
+
+    Ogg files: ALBUM - ALBUMDATE - [DISCNUMBER.]TRACKNUMBER - ARTIST - DATE - TITLE.ogg
+
+  `DISCNUMBER` and `TRACKNUMBER` tags are automatically padded with zeros in order to be of equal length and allow alphabetical sort.
+
+  Those characters are not authorized in file names: `\/:*?"<>|`. They will be removed.
+
+  In album mode, all ogg files will be moved to the root of the album.
+
+- `check`: verify that you follow good tagging practices.
+
+- `write`: writes the tags in the files.
+
+- `quit`: discards all modifications and closes OggAlbumTagger.
+
+## How to install
+
+First, you need to install the `exiftool` tool and `libtag` (also called `taglib` on some systems) library (you need the development package, since the ruby gem will be built upon it). For example, on Debian/Ubuntu systems, run `apt-get install libimage-exiftool-perl libtag1-dev` from your terminal.
+
+### From source
+
+If you are planning to contribute, install the `rake` and `bundle` gems: `gem install rake bundle`.
+
+#### Install
+
+Run `bundle install` to install dependencies.
+
+Run `rake install` to install the gem from the sources.
+
+#### Run without installing
+
+From the root of the source folder, run `bundle exec ogg-album-tagger  ...`.
+
+## How to properly tag your music
+
+These good practices apply to Vorbis comments (the type of tags used in ogg files). There is nothing official about them, they only describe an efficient way to tag your music.
+
+Always specify the ARTIST, TITLE and DATE (OggAlbumTagger requires a year) tags.
+
+For albums, best-of (same artist, different dates) and compilations (different artists), specify the ALBUM and TRACKNUMBER. If there is multiple discs, use the DISCNUMBER tag. Do not pad numerical tags (TRACKNUMBER, DISCNUMBER) with zeros (if you media player is unable to know that 2 comes before 10, use another media player). If the tracks of your best-of/compilation are composed at different DATEs, use the ALBUMDATE tag.
+
+On compilations (and only compilations), set the ALBUMARTIST tag to "Various artists". This way, you can easily search for compilations in your audio library.
+
+The ALBUM, ARTIST, ALBUMARTIST and TITLE tags are designed for systems with limited display capabilities. When used, they must contain one single value.
+
+You can specify alternate values using the ALBUMSORT, ARTISTSORT, ALBUMARTISTSORT and TITLESORT tags. The ARTISTSORT is especially usefull if you want to specify the name of all members of a group (so that searching for John Lennon will give you its performances from The Beatles years and from its experimental period with Yoko Ono), or if you want The Beatles to be listed at "B" or Bob Dylan to also be listed as "Dylan, Bob". If your media player does not support these *SORT tags, use another media player.
+
+Its nice to have a GENRE (or several). Don't try to be too precise or too exhaustive, or it might make it harder to search by genre. Use the genres you are able to recognize. You also can split "hybrid" genres like "Pop-Rock".
+
+Other standard tags: see [this page](http://www.xiph.org/vorbis/doc/v-comment.html) and [this one](http://age.hobba.nl/audio/mirroredpages/ogg-tagging.html). But you can achieve pretty good tagging using the tags listed above.
+
+## TODO
+
+Not every functionality in this list has to be implemented. Actually, I don't need most of them. If you have some time to spare, I'll be happy to accept your contributions.
+
+* Support other audio formats: OggalbumTagger is built upon the [TagLib gem](http://robinst.github.io/taglib-ruby/), which support many audio formats. Theoretically, it is possible to support them in oggAlbumTagger (the name can be changed). In practice, I've no desire to play with those ugly ID3 tags and theirs versions and encodings. If you need this, it might be quicker for you to convert your music library to ogg (I've done it, no regret).
+* Make the code modular, so that each available command live in a single class that handle it's own autosuggestion, autocompletion, execution... Ok, it requires to rewrite half of the program, but it would be cool.
+* Fill tags from filenames or from some CDDB/FreeDB/... database. In the meantime, use [lltags](http://home.gna.org/lltag/).
+* Export cover pictures.
+* Whatever you feel useful...
+
+## License
+
+This tool is released under the terms of the MIT License. See the LICENSE.txt file for more details.

data/Rakefile

@@ -0,0 +1,2 @@
+require "bundler/gem_tasks"
+

data/bin/ogg-album-tagger

@@ -0,0 +1,267 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+
+require 'ogg_album_tagger/version'
+require 'ogg_album_tagger/library'
+require 'ogg_album_tagger/picture'
+require 'ogg_album_tagger/tag_container'
+require 'ogg_album_tagger/exceptions'
+
+require 'readline'
+require 'optparse'
+require 'shellwords'
+
+def autocomplete(input)
+	context = Readline.line_buffer.slice(0, Readline.point - input.length)
+	begin
+		args = Shellwords.shellwords(context)
+
+		# If there is no space after a quoted string, no autocompletion,
+		# or we may end up with things like "something"somethingelse
+		return [] if context.size > 0 and Readline.completer_quote_characters.include?(context[-1])
+	rescue ArgumentError => ex
+		# We are autocompleting a quoted string
+		# The quote will be the last item in the context, so we dump it
+		context.slice!(-1) if context.size > 0 and Readline.completer_quote_characters.include?(context[-1])
+		begin
+			args = Shellwords.shellwords(context)
+		rescue ArgumentError => ex
+			return []
+		end
+	end
+
+	props = []
+
+	if args.empty? then props = %w{ls select show set add rm auto check write help exit quit}
+	elsif %w{ls select check help exit quit}.include?(args[0]) then props = []
+	elsif args[0] == 'show'
+		if args.size == 1
+			props = %w{tag}
+		elsif args[1] == 'tag' and args.size == 2
+			props = $library.tags_used
+		end
+	elsif %w{add set}.include? args[0]
+		if args.size == 1
+			props = $library.tags_used
+		elsif %w{METADATA_BLOCK_PICTURE PICTURE}.include? args[1].upcase
+			if args.size == 2
+				props = Readline::FILENAME_COMPLETION_PROC.call(input)
+			end
+		end
+	elsif args[0] == 'rm'
+		if args.size == 1
+			props = $library.tags_used
+		else
+			tag = args[1].upcase
+			if tag == 'METADATA_BLOCK_PICTURE'
+				$stderr.puts
+				$stderr.puts "Autocompletion is not supported for pictures"
+				Readline.refresh_line
+			else props = $library.tag_summary(tag).values.flatten.uniq
+			end
+		end
+	elsif args[0] == 'auto'
+		if args.length == 1
+			props = %w{tracknumber rename}
+		end
+	end
+
+	(props || []).grep(/^#{Regexp.escape(input)}/).map do |v|
+		v.include?(' ') ? "\"#{v}\"" : v
+	end
+end
+
+def print_album_summary(summary)
+	OggAlbumTagger::TagContainer.sorted_tags(summary.keys) do |tag|
+		puts tag
+
+		if (summary[tag].size == $library.selected_files.size) && (summary[tag].values.uniq.length == 1)
+			# If all tracks have only one common value
+			puts "\t" + OggAlbumTagger::TagContainer::pp_tag(summary[tag].first[1])
+		else
+			summary[tag].keys.sort.each do |i|
+				values = summary[tag][i]
+				puts sprintf("\t%4d: %s", i+1, OggAlbumTagger::TagContainer::pp_tag(values))
+			end
+		end
+	end
+end
+
+def show_command(command)
+	case command.length
+	when 0
+		print_album_summary($library.summary)
+	else
+		case command[0]
+		when 'tag'
+			if command.size == 1 then puts 'You need to specify a tag name'
+			else print_album_summary $library.summary(command[1].upcase)
+			end
+		else
+			puts "Unknown command 'show #{command[0]}'"
+		end
+	end
+end
+
+def ls_command
+	$library.ls().each do |f|
+		puts sprintf("%s %4d: %s", (f[:selected] ? '*' : ' '), f[:position], f[:file])
+	end
+end
+
+def handle_picture_args args
+	if %w{METADATA_BLOCK_PICTURE PICTURE}.include? args[0].upcase
+		file = args[1]
+		desc = args.length == 2 ? args[1] : ''
+		args.clear
+		args << 'METADATA_BLOCK_PICTURE'
+		args << OggAlbumTagger::Picture::generate_metadata_block_picture(file, desc)
+	end
+end
+
+def execute_command(command_line)
+	begin
+		command, *args = Shellwords.shellwords(command_line)
+	rescue ::StandardError => ex
+		puts 'Invalid command.'
+		return
+	end
+
+	begin
+		case command
+		when 'ls' then ls_command()
+		when 'select'
+			if args.length < 1
+				puts 'You need to specify the files you want to select. Either enter "all", a single number or a range (ex. "3-5").', 'Number and range based selections can be made cumulative by adding a plus or minus sign in front of the selector (ex. "-1-3").'
+			else
+				$library.select(args)
+				ls_command()
+			end
+		when 'show' then show_command(args)
+		when 'set'
+			if args.length < 2
+				puts 'You need to specify the tag to edit and at least one value.'
+			else
+				handle_picture_args(args)
+				$library.set_tag(*args)
+				show_command(['tag', args[0]])
+			end
+		when 'add'
+			if args.length < 2
+				puts 'You need to specify the tag to edit and at least one value.'
+			else
+				handle_picture_args(args)
+				$library.add_tag(*args)
+				show_command(['tag', args[0]])
+			end
+		when 'rm'
+			if args.length < 1
+				puts 'You need to specify the tag to edit and eventually one or several values.'
+			else
+				$library.rm_tag(*args)
+				show_command(['tag', args[0]])
+			end
+		when 'auto'
+			if args.length < 1
+				puts 'You need to specify the auto command you want to execute.'
+			else
+				case args[0]
+				when 'tracknumber' then $library.auto_tracknumber()
+				when 'rename'
+					$library.auto_rename
+					ls_command()
+				end
+			end
+		when 'check'
+			$library.check
+			puts "OK"
+		when 'write'
+			$library.write
+		when 'help'
+			# TODO
+		else
+			puts "Unknown command \"#{command}\""
+		end
+	rescue OggAlbumTagger::Error => err
+		puts err
+	end
+end
+
+def list_ogg_files dir, with_dir = false
+	Dir.chdir(dir) do
+		Dir.glob("**/*.ogg").map { |f| with_dir ? Pathname.new(dir).join(f) : Pathname.new(f) }
+	end
+end
+
+options = {album: false}
+option_parser = OptionParser.new do |opts|
+	executable_name = File.basename($PROGRAM_NAME)
+	opts.banner = "Interactive edition of ogg tags with album/compilation support.\n" +
+	              "Usage: #{executable_name} [options] files|directories"
+
+	opts.separator "Options:"
+
+	opts.on("-a", "--album", "Album mode: treat a single directory as an album.") do
+		options[:album] = true
+	end
+
+	opts.on("-v", "--version", "Display version information and exit.") do
+		puts "OggAlbumTagger #{OggAlbumTagger::VERSION}"
+		exit
+	end
+
+	opts.on("-h", "--help", "Print this help and exit.") do
+		puts opts
+		exit
+	end
+
+	opts.separator ""
+	opts.separator "OggAlbumTagger is released under the terms of the MIT License."
+	opts.separator "For more informations, updates and bug reports, see https://github.com/Sigill/OggAlbumTagger."
+end.parse!
+
+if ARGV.size == 0
+	puts options_parser
+	exit
+else
+	if options[:album]
+		unless ARGV.size == 1 and File.directory?(ARGV[0])
+			abort "Error: in album mode, you have to provide a single directory as argument."
+		end
+	end
+
+	files = []
+	ARGV.each do |arg|
+		begin
+			if File.directory?(arg)
+				files.concat list_ogg_files(arg, !options[:album])
+			elsif File.file?(arg)
+				files << Pathname.new(arg)
+			else
+				raise Errno::ENOENT
+			end
+		rescue Errno::ENOENT
+			abort "#{arg} does not exists."
+		end
+	end
+
+	begin
+		$library = OggAlbumTagger::Library.new(files, options[:album] ? Pathname.new(ARGV[0]) : nil)
+	rescue OggAlbumTagger::Error => ex
+		abort ex.message
+	end
+end
+
+Readline.completion_append_character = " "
+Readline.completer_quote_characters = "\"'"
+Readline.completion_proc = ->(input) {
+	autocomplete(input)
+}
+
+loop do
+	command = Readline.readline("> ", true)
+	break if command.nil? or command.eql?('exit') or command.eql?('quit')
+
+	execute_command(command.strip)
+end

data/lib/ogg_album_tagger/exceptions.rb

@@ -0,0 +1,9 @@
+module OggAlbumTagger
+
+class Error < ::StandardError; end
+
+class SystemError < Error; end
+class ArgumentError < Error; end
+class MetadataError < Error; end
+
+end

data/lib/ogg_album_tagger/library.rb

@@ -0,0 +1,418 @@
+require 'ogg_album_tagger/version'
+require 'ogg_album_tagger/tag_container'
+require 'ogg_album_tagger/exceptions'
+
+require 'set'
+require 'shellwords'
+require 'pathname'
+require 'open3'
+require 'fileutils'
+
+module OggAlbumTagger
+
+# A Library is just a hash associating each ogg file to a TagContainer.
+# A subset of file can be selected in order to be tagged.
+class Library
+	attr_reader :selected_files
+
+	# Build the library by parsing specified ogg file.
+	# In order to consider the library as a single album, you have to separately provide
+	# the absolute path to the album and relative paths to the ogg files.
+	# Otherwise, use absolute paths.
+	#
+	# Paths must be provided as Pathnames.
+	#
+	# A OggAlbumTagger::SystemError will be raised if vorbiscomment cannot be invoked.
+	# A OggAlbumTagger::ArgumentError will be raised if one of the files is not a valid ogg file.
+	def initialize files, dir = nil
+		@path = dir
+		@files = {}
+
+		files.each do |f|
+			@files[f] = TagContainer.new(fullpath(f))
+		end
+
+		@selected_files = Set.new @files.keys
+	end
+
+	# Return the full path to the file.
+	def fullpath(file)
+		@path.nil? ? file : @path + file
+	end
+
+	# Returns the list of the tags used in the selected files.
+	def tags_used
+		s = Set.new
+		@selected_files.each do |file|
+			s.merge @files[file].tags
+		end
+		s.to_a.map { |v| v.downcase }
+	end
+
+	# Returns an hash of hashes describing the selected files for the specified tag.
+	#
+	# If no tag is specified, all tags are considered.
+	#
+	# The first hash is indexed by the tags used. The second level of hashes is indexed
+	# by the positions of the files in the library and points to a alphabetically sorted list
+	# of values associated to the tag.
+	#
+	# {
+	# 	'TITLE' => {
+	# 		0 => ['Title of track 0'],
+	# 		3 => ['Title of track 3']
+	# 	},
+	# 	...
+	# }
+	def summary(selected_tag = nil)
+		data = Hash.new { |h, k| h[k] = Hash.new }
+
+		positions = Hash[@files.keys.sort.each_with_index.to_a]
+
+		@selected_files.each do |file|
+			@files[file].each do |tag, values|
+				next unless selected_tag.nil? or tag.eql?(selected_tag)
+				data[tag][positions[file]] = values.sort
+			end
+		end
+
+		data
+	end
+
+	# Returns a hash where keys are the positions of the files in the library
+	# and values are sorted lists of values associated to the tag.
+	def tag_summary(tag)
+		summary(tag)[tag]
+	end
+
+	# Pick from the selected files one single value associated to the specified tag.
+	def first_value(tag)
+		tag_summary(tag).first[1].first
+	end
+
+	# Write the tags to the files.
+	def write
+		@selected_files.each do |file|
+			@files[file].write(fullpath(file))
+		end
+	end
+
+	# Tags the selected files with the specified values.
+	#
+	# Any previous value will be removed.
+	def set_tag(tag, *values)
+		tag.upcase!
+		@selected_files.each { |file| @files[file].set_values(tag, *values) }
+	end
+
+	# Tags the selected files with the specified values.
+	def add_tag(tag, *values)
+		tag.upcase!
+		@selected_files.each { |file| @files[file].add_values(tag, *values) }
+	end
+
+	# Remove the specified values from the selected files.
+	#
+	# If no value is specified, the tag will be removed.
+	def rm_tag(tag, *values)
+		tag.upcase!
+		@selected_files.each { |file| @files[file].rm_values(tag, *values) }
+	end
+
+	# Return a list of the files in the library.
+	def ls
+		@files.keys.sort.each_with_index.map do |file, i|
+			{ file: file, position: i+1, selected: @selected_files.include?(file) }
+		end
+	end
+
+	# Modify the list of selected files.
+	#
+	# The available selector are:
+	# * "all": all files.
+	# * "3": the third file.
+	# * "5-7" the files 5, 6 and 7.
+	#
+	# The two last selector can be prefixed by "+" or "-" in order to add or remove items
+	# from the current selection. They are called cumulative selectors.
+	#
+	# You can specify several selectors, but non-cumulative selectors cannot be specified after a cumulative one.
+	def select(args)
+		all_files = @files.keys.sort
+		mode = :absolute
+
+		first_rel = !!(args.first =~ /^[+-]/)
+
+		sel = first_rel ? Set.new(@selected_files) : Set.new
+
+		args.each do |selector|
+			case selector
+			when 'all'
+				raise OggAlbumTagger::ArgumentError, "Cannot use the \"#{selector}\" selector after a cumulative selector (+/-...)" if mode == :cumulative
+				sel.replace all_files
+			when /^([+-]?)([1-9]\d*)$/
+				i = $2.to_i - 1
+				raise OggAlbumTagger::ArgumentError, "Item #{$2} is out of range" if i >= all_files.length
+
+				items = [all_files.slice(i)]
+				case $1
+				when '-'
+					sel.subtract items
+					mode = :cumulative
+				when '+'
+					sel.merge items
+					mode = :cumulative
+				else
+					raise OggAlbumTagger::ArgumentError, "Cannot use the \"#{selector}\" selector after a cumulative selector (+/-...)" if mode == :cumulative
+					sel.merge items
+				end
+			when /^([+-]?)(?:([1-9]\d*)-([1-9]\d*))$/
+				i = $2.to_i - 1
+				j = $3.to_i - 1
+				raise OggAlbumTagger::ArgumentError, "Range #{$2}-#{$3} is invalid" if i >= all_files.length or j >= all_files.length or i > j
+
+				items = all_files.slice(i..j)
+				case $1
+				when '-'
+					sel.subtract items
+					mode = :cumulative
+				when '+'
+					sel.merge items
+					mode = :cumulative
+				else
+					raise OggAlbumTagger::ArgumentError, "Cannot use the \"#{selector}\" selector after a cumulative selector (+/-...)" if mode == :cumulative
+					sel.merge items
+				end
+			else
+				raise OggAlbumTagger::ArgumentError, "Unknown selector \"#{selector}\"."
+			end
+		end
+
+		@selected_files.replace sel
+	end
+
+	# Automatically set the TRACKNUMBER tag of the selected files based on their position in the selection.
+	def auto_tracknumber
+		@selected_files.sort.each_with_index do |file, i|
+			@files[file].set_values('TRACKNUMBER', (i+1).to_s)
+		end
+	end
+
+	# Test if a tag satisfy a predicate on each selected files.
+	def validate_tag(tag)
+		values = @selected_files.map { |file| @files[file][tag] }
+		values.reduce(true) { |r, v| r && yield(v) }
+	end
+
+	# Test if a tag is used at least one time in an ogg file.
+	def tag_used?(tag)
+		values = @selected_files.map { |file| @files[file][tag] }
+		values.reduce(false) { |r, v| r || v.size > 0 }
+	end
+
+	# Test if a tag is used k times on each selected files.
+	def tag_used_k_times?(tag, k)
+		self.validate_tag(tag) { |v| v.size == k }
+	end
+
+	# Test if a tag is used once on each selected files.
+	def tag_used_once?(tag)
+		self.tag_used_k_times?(tag, 1)
+	end
+
+	# Test if a tag has multiple values in a single file.
+	def tag_used_multiple_times?(tag)
+		values = @selected_files.map { |file| @files[file][tag] }
+		values.reduce(false) { |r, v| r || v.size > 1 }
+	end
+
+	# Test if a tag is absent from each selected files.
+	def tag_unused?(tag)
+		self.tag_used_k_times?(tag, 0)
+	end
+
+	# Test if multiple tags satisfy a predicate.
+	def validate_tags(tags)
+		tags.reduce(true) { |result, tag| result && yield(tag) }
+	end
+
+	# Test if a tag has a single value and is uniq across all selected files.
+	def uniq_tag?(tag)
+		values = @selected_files.map { |file| @files[file][tag] }
+		values.reduce(true) { |r, v| r && (v.size == 1) } && (values.map { |v| v.first }.uniq.length == 1)
+	end
+
+	# Test if a tag holds a numerical value > 0.
+	def numeric_tag?(tag)
+		validate_tag(tag) { |v| (v.size == 0) || (v.first.to_s =~ /^[1-9][0-9]*$/) }
+	end
+
+	def date_tag?(tag)
+		validate_tag(tag) { |v| (v.size == 0) || (v.first.to_s =~ /^\d\d\d\d$/) }
+	end
+
+	# Verify that the library is properly tagged.
+	#
+	# * ARTIST, TITLE and DATE must be used once per file.
+	# * TRACKNUMBER must be used once on an album/compilation.
+	# * DATE must be a valid date.
+	# * ALBUM must be uniq.
+	# * ALBUMARTIST should have the value "Various artists" on a compilation.
+	# * ALBUMDATE must be uniq if DATE is not.
+	# * DISCNUMBER must be used at most one time per file.
+	# * TRACKNUMBER and DISCNUMBER must have numerical values.
+	def check
+		%w{ARTIST TITLE DATE ALBUM ALBUMDATE ARTISTALBUM TRACKNUMBER DISCNUMBER}.each do |t|
+			raise OggAlbumTagger::MetadataError, "The #{t} tag cannot be used multiple times in a single track." if tag_used_multiple_times?(t)
+		end
+
+		%w{DISCNUMBER TRACKNUMBER}.each do |t|
+			raise OggAlbumTagger::MetadataError, "If used, the #{t} tag must have a numeric value." unless numeric_tag?(t)
+		end
+
+		%w{DATE ALBUMDATE}.each do |t|
+			raise OggAlbumTagger::MetadataError, "If used, the #{t} tag must be a valid year." unless date_tag?(t)
+		end
+
+		once_tags = %w{ARTIST TITLE DATE}
+		once_tags << "TRACKNUMBER" unless @path.nil?
+		once_tags.each do |t|
+			raise OggAlbumTagger::MetadataError, "The #{t} tag must be used once per track." unless tag_used_once?(t)
+		end
+
+		return if @path.nil?
+
+		raise OggAlbumTagger::MetadataError, "The ALBUM tag must have a single and uniq value among all songs." unless uniq_tag?('ALBUM')
+
+		if uniq_tag?('ARTIST')
+			raise OggAlbumTagger::MetadataError, 'The ALBUMARTIST is only required for compilations.' if tag_used?('ALBUMARTIST')
+		else
+			if not uniq_tag?('ALBUMARTIST') or (first_value('ALBUMARTIST') != 'Various artists')
+				raise OggAlbumTagger::MetadataError, 'This album seems to be a compilation. The ALBUMARTIST tag should have the value "Various artists".'
+			end
+		end
+
+		raise OggAlbumTagger::MetadataError, "The ALBUMDATE tag must have a single and uniq value among all songs." if not uniq_tag?('DATE') and not uniq_tag?('ALBUMDATE')
+	end
+
+	# Auto rename the directory and the ogg files of the library.
+	#
+	# For singles, the format is:
+	# Directory: N/A
+	# Ogg file: ARTIST - DATE - TITLE
+	#
+	# For an album, the format is:
+	# Directory: ARTIST - DATE - ALBUM
+	# Ogg file:  ARTIST - DATE - ALBUM - [DISCNUMBER.]TRACKNUMBER - TITLE
+	#
+	# For a single-artist compilation (an album where tracks have different dates), the format is:
+	# Directory: ARTIST - ALBUMDATE - ALBUM
+	# Ogg file:  ARTIST - ALBUMDATE - ALBUM - [DISCNUMBER.]TRACKNUMBER - TITLE - DATE
+	#
+	# For a compilation, the format is:
+	# Directory: ALBUM - ALBUMDATE
+	# Ogg file:  ALBUM - ALBUMDATE - [DISCNUMBER.]TRACKNUMBER - ARTIST - TITLE - DATE
+	#
+	# Disc and track numbers are padded with zeros.
+	def auto_rename
+		check()
+
+		mapping = {}
+
+		if @path.nil?
+			@selected_files.each do |file|
+				tags = @files[file]
+				mapping[file] = sprintf('%s - %s - %s.ogg', tags.first('ARTIST'), tags.first('DATE'), tags.first('TITLE'))
+			end
+		else
+			tn_maxlength = tag_summary('TRACKNUMBER').values.map { |v| v.first.to_s.length }.max
+			tn_format = '%0' + tn_maxlength.to_s + 'd'
+
+			has_discnumber = tag_used_once?('DISCNUMBER')
+			if has_discnumber
+				dn_maxlength = tag_summary('DISCNUMBER').values.map { |v| v.first.to_s.length }.max
+				dn_format = '%0' + dn_maxlength.to_s + 'd'
+			end
+
+			format_number = lambda do |tags|
+				s = ''
+				if has_discnumber
+					s += sprintf(dn_format, tags.first('DISCNUMBER').to_i) + '.'
+				end
+				s += sprintf(tn_format, tags.first('TRACKNUMBER').to_i)
+			end
+
+			album_date = uniq_tag?('DATE') ? first_value('DATE') : first_value('ALBUMDATE')
+
+			if uniq_tag?('ARTIST')
+				@selected_files.each do |file|
+					tags = @files[file]
+
+					common_tags = [tags.first('ARTIST'), album_date, tags.first('ALBUM'),
+					               format_number.call(tags), tags.first('TITLE')]
+
+					mapping[file] = if uniq_tag?('DATE')
+						sprintf('%s - %s - %s - %s - %s.ogg', *common_tags)
+					else
+						sprintf('%s - %s - %s - %s - %s - %s.ogg', *common_tags, tags.first('DATE'))
+					end
+				end
+
+				albumdir = sprintf('%s - %s - %s',
+				                   first_value('ARTIST'),
+				                   album_date,
+				                   first_value('ALBUM'))
+			else
+				@selected_files.each do |file|
+					tags = @files[file]
+					mapping[file] = sprintf('%s - %s - %s - %s - %s.ogg',
+					                        tags.first('ALBUM'), album_date, format_number.call(tags),
+					                        tags.first('ARTIST'), tags.first('TITLE'), tags.first('DATE'))
+				end
+
+				albumdir = sprintf('%s - %s', first_value('ALBUM'), album_date)
+			end
+
+			albumdir = albumdir.gsub(/[\\\/:*?"<>|]/, '')
+		end
+
+		# TODO Should UTF-8 chars be converted to latin1 in order to have Windows-safe filenames?
+		mapping.each { |k, v| mapping[k] = v.gsub(/[\\\/:*?"<>|]/, '') }
+
+		if mapping.values.uniq.size != @selected_files.size
+			raise OggAlbumTagger::MetadataError, 'Generated filenames are not uniq.'
+		end
+
+		# Renaming the album directory
+		unless @path.nil?
+			begin
+				newpath = @path.dirname + albumdir
+				if @path.expand_path != newpath.expand_path
+					FileUtils.mv(@path, newpath)
+					@path = newpath
+				end
+			rescue Exception => ex
+				raise OggAlbumTagger::SystemError, "Cannot rename \"#{@path}\" to \"#{newpath}\"."
+			end
+		end
+
+		# Renaming the ogg files
+		Set.new(@selected_files).each do |file|
+			begin
+				oldpath = fullpath(file)
+				newpath = (@path.nil? ? file.dirname : @path) + mapping[file]
+				newpath_rel = file.dirname + mapping[file]
+
+				if oldpath != newpath
+					FileUtils.mv(oldpath, newpath)
+					@files[newpath_rel] = @files.delete(file)
+					@selected_files.delete(file).add(newpath_rel)
+				end
+			rescue Exception => ex
+				raise OggAlbumTagger::SystemError, "Cannot rename \"#{file}\" to \"#{mapping[file]}\"."
+			end
+		end
+	end
+end
+
+end

data/lib/ogg_album_tagger/picture.rb

@@ -0,0 +1,46 @@
+require 'base64'
+require 'exiftool'
+require 'ogg_album_tagger/exceptions'
+
+module OggAlbumTagger
+
+class Picture
+	# Embed a picture so that it can be included as a tag.
+	#
+	# See http://xiph.org/flac/format.html#metadata_block_picture
+	# Note: the type of the picture is currently fixed to "Front cover",
+	# as it is the most common type.
+	def self.generate_metadata_block_picture(image, desc = '')
+		begin
+			image = File.expand_path(image)
+			img = Exiftool.new(image)
+			content = IO.binread(image)
+		rescue Exiftool::ExiftoolNotInstalled
+			raise OggAlbumTagger::SystemError, "exiftool (the executable, not the gem) is not in your path, please install it."
+		rescue
+			raise OggAlbumTagger::ArgumentError, "\"#{image}\" cannot be read."
+		end
+
+		meta = img.results[0].to_hash
+		mime = meta[:mime_type]
+
+		raise OggAlbumTagger::ArgumentError, 'Unsupported image type. Use JPEG or PNG.' unless ['image/png', 'image/jpeg'].include?(mime)
+
+		pack = [
+			3, # Front cover
+			mime.length,
+			mime,
+			desc.bytesize,
+			desc,
+			meta[:image_width],
+			meta[:image_height],
+			meta[:color_components] * meta[:bits_per_sample],
+			0, # palette
+			content.length,
+			content
+		].pack(sprintf("L>L>A%dL>a%dL>L>L>L>L>a*", mime.length, desc.bytesize))
+		Base64.strict_encode64(pack)
+	end
+end
+
+end

data/lib/ogg_album_tagger/tag_container.rb

@@ -0,0 +1,142 @@
+require 'shellwords'
+require 'set'
+require 'ogg_album_tagger/exceptions'
+require 'taglib'
+
+module OggAlbumTagger
+
+# Store the tags of an ogg track.
+#
+# Each tag is associated to a Set of values.
+class TagContainer
+	# Initialize a TagContainer from an ogg file.
+	def initialize(file)
+		@hash = Hash.new 
+
+		begin
+			TagLib::Ogg::Vorbis::File.open(file.to_s) do |ogg|
+				ogg.tag.field_list_map.each do |tag, values|
+					prepare_tag(tag.upcase)
+
+					values.each do |value|
+						@hash[tag.upcase].add(value.strip)
+					end
+				end
+			end
+		rescue Exception => ex
+			#STDERR.puts ex
+			raise OggAlbumTagger::ArgumentError, "#{file} does not seems to be a valid ogg file."
+		end
+	end
+
+	# Write the tags in the specified file.
+	def write(file)
+		begin
+			TagLib::Ogg::Vorbis::File.open(file.to_s) do |ogg|
+				tags = ogg.tag
+
+				# Remove old tags
+				tags.field_list_map.keys.each { |t| tags.remove_field(t) }
+
+				# Set new tags (Taglib will write them sorted)
+				@hash.each do |tag, values|
+					values.sort.each do |v|
+						tags.add_field(tag, v, false)
+					end
+				end
+
+				# Save everything
+				ogg.save
+			end
+		rescue Exception => ex
+			#STDERR.puts ex
+			raise OggAlbumTagger::ArgumentError, "#{file} cannot be written."
+		end
+	end
+
+	# Returns a Set containing the values associated to the specified tag.
+	#
+	# If the tag does not exists, returns an empty Set.
+	# Do not use the returned Set to add new tags, use the methods provided by the class.
+	def [](tag)
+		has_tag?(tag) ? @hash[tag.upcase] : Set.new.freeze
+	end
+
+	def first(tag)
+		if has_tag?(tag)
+			return @hash[tag.upcase].first
+		else
+			raise IndexError, "Tag \"#{tag}\" does not exists."
+		end
+	end
+
+	# Check if the specified tag is present in the container.
+	def has_tag? tag
+		@hash.has_key?(tag.upcase)
+	end
+
+	# If the specified tag is absent from the container, associate an it to an empty Set.
+	def prepare_tag tag
+		@hash[tag.upcase] = Set.new unless self.has_tag?(tag)
+	end
+
+	# Add some values to the specified tag.
+	# Any previous values will be removed.
+	def set_values(tag, *values)
+		prepare_tag tag
+		@hash[tag.upcase].replace(values)
+	end
+
+	# Add some values to the specified tag.
+	def add_values(tag, *values)
+		prepare_tag tag
+		@hash[tag.upcase].merge(values)
+	end
+
+	# Remove some tags. If no value is specified, the specified tag is removed.
+	def rm_values(tag, *values)
+		if values.empty? then @hash.delete(tag.upcase)
+		else
+			@hash[tag.upcase].subtract(values)
+			@hash.delete(tag.upcase) if @hash[tag.upcase].empty?
+		end
+	end
+
+	# Returns the list of present tags.
+	def tags
+		@hash.keys
+	end
+
+	# Iterate through the available tags.
+	def each
+		@hash.each { |tag, set| yield(tag, set) }
+	end
+
+	def to_s
+		TagContainer.sorted_tags(@hash.keys).map do |tag|
+			TagContainer.pp_tag(@hash[tag])
+		end.join "\n"
+	end
+
+	# Sort the tag keys alphabetically, but put METADATA_BLOCK_PICTURE at the end.
+	def self.sorted_tags(tags)
+		a = tags.sort
+		a.delete('METADATA_BLOCK_PICTURE') and a.push('METADATA_BLOCK_PICTURE')
+		block_given? ? a.each { |v| yield v } : a
+	end
+
+	# Pretty print an array of values.
+	def self.pp_tag values
+		values_str = values.map { |v| v.to_s.length > 64 ? (v.to_s.slice(0, 64) + '...') : v }
+
+		case values.length
+		when 0 then '- (empty)'
+		when 1 then values_str[0]
+		else sprintf("(%d) [%s]", values.length, values_str.join(', '))
+		end
+	end
+
+	private :prepare_tag
+end
+
+end

data/lib/ogg_album_tagger/version.rb

@@ -0,0 +1,3 @@
+module OggAlbumTagger
+  VERSION = "0.0.1"
+end

data/ogg_album_tagger.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ogg_album_tagger/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "ogg_album_tagger"
+  spec.version       = OggAlbumTagger::VERSION
+  spec.authors       = ["Cyrille Faucheux"]
+  spec.email         = ["cyrille.faucheux@gmail.com"]
+  spec.summary       = "Interactive edition of ogg tags in an album or a compilation."
+  spec.homepage      = "https://github.com/Sigill/OggAlbumTagger"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+
+  spec.add_runtime_dependency "exiftool", ["~> 0.6"]
+  spec.add_runtime_dependency "taglib-ruby", ["~> 0.7"]
+end

metadata

@@ -0,0 +1,113 @@
+--- !ruby/object:Gem::Specification
+name: ogg_album_tagger
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Cyrille Faucheux
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.7'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: exiftool
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: taglib-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.7'
+description: 
+email:
+- cyrille.faucheux@gmail.com
+executables:
+- ogg-album-tagger
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/ogg-album-tagger
+- lib/ogg_album_tagger/exceptions.rb
+- lib/ogg_album_tagger/library.rb
+- lib/ogg_album_tagger/picture.rb
+- lib/ogg_album_tagger/tag_container.rb
+- lib/ogg_album_tagger/version.rb
+- ogg_album_tagger.gemspec
+homepage: https://github.com/Sigill/OggAlbumTagger
+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.2.2
+signing_key: 
+specification_version: 4
+summary: Interactive edition of ogg tags in an album or a compilation.
+test_files: []