taglib-ruby 0.4.0-x86-mingw32
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- data/.yardopts +9 -0
- data/CHANGES.md +53 -0
- data/Gemfile +4 -0
- data/Guardfile +8 -0
- data/LICENSE.txt +22 -0
- data/README.md +87 -0
- data/Rakefile +29 -0
- data/docs/default/fulldoc/html/css/common.css +1 -0
- data/docs/taglib/base.rb +202 -0
- data/docs/taglib/id3v1.rb +5 -0
- data/docs/taglib/id3v2.rb +444 -0
- data/docs/taglib/mpeg.rb +120 -0
- data/docs/taglib/ogg.rb +77 -0
- data/docs/taglib/vorbis.rb +62 -0
- data/ext/extconf_common.rb +29 -0
- data/ext/taglib_base/extconf.rb +4 -0
- data/ext/taglib_base/includes.i +115 -0
- data/ext/taglib_base/taglib_base.i +139 -0
- data/ext/taglib_base/taglib_base_wrap.cxx +5153 -0
- data/ext/taglib_id3v1/extconf.rb +4 -0
- data/ext/taglib_id3v1/taglib_id3v1.i +11 -0
- data/ext/taglib_id3v1/taglib_id3v1_wrap.cxx +3110 -0
- data/ext/taglib_id3v2/extconf.rb +4 -0
- data/ext/taglib_id3v2/relativevolumeframe.i +35 -0
- data/ext/taglib_id3v2/taglib_id3v2.i +112 -0
- data/ext/taglib_id3v2/taglib_id3v2_wrap.cxx +9033 -0
- data/ext/taglib_mpeg/extconf.rb +4 -0
- data/ext/taglib_mpeg/taglib_mpeg.i +75 -0
- data/ext/taglib_mpeg/taglib_mpeg_wrap.cxx +4726 -0
- data/ext/taglib_ogg/extconf.rb +4 -0
- data/ext/taglib_ogg/taglib_ogg.i +36 -0
- data/ext/taglib_ogg/taglib_ogg_wrap.cxx +3631 -0
- data/ext/taglib_vorbis/extconf.rb +4 -0
- data/ext/taglib_vorbis/taglib_vorbis.i +48 -0
- data/ext/taglib_vorbis/taglib_vorbis_wrap.cxx +3083 -0
- data/ext/valgrind-suppressions.txt +170 -0
- data/ext/win.cmake +5 -0
- data/lib/libtag.dll +0 -0
- data/lib/taglib.rb +14 -0
- data/lib/taglib/base.rb +19 -0
- data/lib/taglib/id3v1.rb +1 -0
- data/lib/taglib/id3v2.rb +20 -0
- data/lib/taglib/mpeg.rb +7 -0
- data/lib/taglib/ogg.rb +1 -0
- data/lib/taglib/version.rb +10 -0
- data/lib/taglib/vorbis.rb +7 -0
- data/lib/taglib_base.so +0 -0
- data/lib/taglib_id3v1.so +0 -0
- data/lib/taglib_id3v2.so +0 -0
- data/lib/taglib_mpeg.so +0 -0
- data/lib/taglib_ogg.so +0 -0
- data/lib/taglib_vorbis.so +0 -0
- data/taglib-ruby.gemspec +122 -0
- data/tasks/docs_coverage.rake +26 -0
- data/tasks/ext.rake +81 -0
- data/tasks/gemspec_check.rake +19 -0
- data/tasks/swig.rake +43 -0
- data/test/data/Makefile +15 -0
- data/test/data/add-relative-volume.cpp +40 -0
- data/test/data/crash.mp3 +0 -0
- data/test/data/globe_east_540.jpg +0 -0
- data/test/data/id3v1-create.cpp +31 -0
- data/test/data/id3v1.mp3 +0 -0
- data/test/data/relative-volume.mp3 +0 -0
- data/test/data/sample.mp3 +0 -0
- data/test/data/unicode.mp3 +0 -0
- data/test/data/vorbis-create.cpp +42 -0
- data/test/data/vorbis.oga +0 -0
- data/test/fileref_open_test.rb +32 -0
- data/test/fileref_properties_test.rb +21 -0
- data/test/fileref_write_test.rb +62 -0
- data/test/helper.rb +10 -0
- data/test/id3v1_tag_test.rb +36 -0
- data/test/id3v2_frames_test.rb +115 -0
- data/test/id3v2_memory_test.rb +87 -0
- data/test/id3v2_relative_volume_test.rb +62 -0
- data/test/id3v2_tag_test.rb +59 -0
- data/test/id3v2_unicode_test.rb +47 -0
- data/test/id3v2_write_test.rb +100 -0
- data/test/mpeg_file_test.rb +76 -0
- data/test/tag_test.rb +21 -0
- data/test/unicode_filename_test.rb +29 -0
- data/test/vorbis_file_test.rb +54 -0
- data/test/vorbis_tag_test.rb +79 -0
- metadata +191 -0
data/.yardopts
ADDED
data/CHANGES.md
ADDED
@@ -0,0 +1,53 @@
|
|
1
|
+
Changes in Releases of taglib-ruby
|
2
|
+
==================================
|
3
|
+
|
4
|
+
## 0.4.0 (2012-03-18)
|
5
|
+
|
6
|
+
* Pre-compiled binary gem for Windows (Ruby 1.9) with TagLib 1.7.1
|
7
|
+
* Unicode filename support on Windows
|
8
|
+
* Add `open` class method to `FileRef` and `File` classes (use it
|
9
|
+
instead of `new` and `close`):
|
10
|
+
|
11
|
+
```ruby
|
12
|
+
title = TagLib::FileRef.open("file.mp3") do |file|
|
13
|
+
tag = file.tag
|
14
|
+
tag.title
|
15
|
+
end
|
16
|
+
```
|
17
|
+
|
18
|
+
## 0.3.1 (2012-01-22)
|
19
|
+
|
20
|
+
* Fix ObjectPreviouslyDeleted exception after calling
|
21
|
+
TagLib::ID3v2::Tag#add_frame (#8)
|
22
|
+
* Make installation under MacPorts work out of the box (#7)
|
23
|
+
|
24
|
+
## 0.3.0 (2012-01-02)
|
25
|
+
|
26
|
+
* Add support for Ogg Vorbis
|
27
|
+
* Add support for ID3v1 (#2)
|
28
|
+
* Add #close to File classes for explicitly releasing resources
|
29
|
+
* Fix compilation on Windows
|
30
|
+
|
31
|
+
## 0.2.1 (2011-11-05)
|
32
|
+
|
33
|
+
* Fix compilation error due to missing typedef on some systems (#5)
|
34
|
+
|
35
|
+
## 0.2.0 (2011-10-22)
|
36
|
+
|
37
|
+
* API documentation
|
38
|
+
* Add support for:
|
39
|
+
* TagLib::AudioProperties and TagLib::MPEG::Properties (#4)
|
40
|
+
* TagLib::ID3v2::RelativeVolumeFrame
|
41
|
+
|
42
|
+
## 0.1.1 (2011-09-17)
|
43
|
+
|
44
|
+
* Add installation instructions and clean up description
|
45
|
+
|
46
|
+
## 0.1.0 (2011-09-17)
|
47
|
+
|
48
|
+
* Initial release
|
49
|
+
* Coverage of the following API:
|
50
|
+
* TagLib::FileRef
|
51
|
+
* TagLib::MPEG::File
|
52
|
+
* TagLib::ID3v2::Tag
|
53
|
+
* TagLib::ID3v2::Frame and subclasses
|
data/Gemfile
ADDED
data/Guardfile
ADDED
data/LICENSE.txt
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
Copyright (c) 2010-2012 Robin Stocker
|
2
|
+
|
3
|
+
MIT License
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining
|
6
|
+
a copy of this software and associated documentation files (the
|
7
|
+
"Software"), to deal in the Software without restriction, including
|
8
|
+
without limitation the rights to use, copy, modify, merge, publish,
|
9
|
+
distribute, sublicense, and/or sell copies of the Software, and to
|
10
|
+
permit persons to whom the Software is furnished to do so, subject to
|
11
|
+
the following conditions:
|
12
|
+
|
13
|
+
The above copyright notice and this permission notice shall be
|
14
|
+
included in all copies or substantial portions of the Software.
|
15
|
+
|
16
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
17
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
18
|
+
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
19
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
|
20
|
+
LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
|
21
|
+
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
22
|
+
WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,87 @@
|
|
1
|
+
taglib-ruby
|
2
|
+
===========
|
3
|
+
|
4
|
+
Ruby interface for the [TagLib C++ library][taglib].
|
5
|
+
|
6
|
+
In contrast to other libraries, this one wraps the full C++ API, not
|
7
|
+
only the minimal C API. This means that all tag data can be accessed,
|
8
|
+
e.g. cover art of ID3v2 or custom fields of Ogg Vorbis comments.
|
9
|
+
|
10
|
+
taglib-ruby is work in progress, but the following is already available:
|
11
|
+
|
12
|
+
* Reading/writing common tag data of all formats that TagLib supports
|
13
|
+
* Reading/writing ID3v1 and ID3v2 including ID3v2.4 and Unicode
|
14
|
+
* Reading/writing Ogg Vorbis comments
|
15
|
+
* Reading audio properties (e.g. bitrate) of the above formats
|
16
|
+
|
17
|
+
Some things are still left to do (contributors very welcome):
|
18
|
+
|
19
|
+
* More coverage of the library
|
20
|
+
|
21
|
+
[![Build status][travis-img]][travis-link]
|
22
|
+
|
23
|
+
[![flattr this project][flattr-img]][flattr-link]
|
24
|
+
|
25
|
+
Installation
|
26
|
+
------------
|
27
|
+
|
28
|
+
Before you install the gem, make sure to have [taglib][taglib] installed
|
29
|
+
with header files (and a C++ compiler of course):
|
30
|
+
|
31
|
+
* Debian/Ubuntu: `sudo apt-get install libtag1-dev`
|
32
|
+
* Fedora/RHEL: `sudo yum install taglib-devel`
|
33
|
+
* Brew: `brew install taglib`
|
34
|
+
* MacPorts: `sudo port install taglib`
|
35
|
+
|
36
|
+
Then do:
|
37
|
+
|
38
|
+
gem install taglib-ruby
|
39
|
+
|
40
|
+
Usage
|
41
|
+
-----
|
42
|
+
|
43
|
+
Complete API documentation can be found here:
|
44
|
+
|
45
|
+
http://rubydoc.info/gems/taglib-ruby/frames
|
46
|
+
|
47
|
+
Begin with the {TagLib} namespace.
|
48
|
+
|
49
|
+
Release Notes
|
50
|
+
-------------
|
51
|
+
|
52
|
+
See {file:CHANGES.md}.
|
53
|
+
|
54
|
+
Contributing
|
55
|
+
------------
|
56
|
+
|
57
|
+
* Check out the latest master to make sure the feature hasn't been
|
58
|
+
implemented or the bug hasn't been fixed yet
|
59
|
+
* Check out the issue tracker to make sure someone already hasn't
|
60
|
+
requested it and/or contributed it
|
61
|
+
* Fork the project
|
62
|
+
* Start a feature/bugfix branch
|
63
|
+
* Commit and push until you are happy with your contribution
|
64
|
+
* Make sure to add tests for it. This is important so I don't break it
|
65
|
+
in a future version unintentionally.
|
66
|
+
* Please try not to mess with the Rakefile, version, or history. If you
|
67
|
+
want to have your own version, or is otherwise necessary, that is
|
68
|
+
fine, but please isolate to its own commit so I can cherry-pick around
|
69
|
+
it.
|
70
|
+
|
71
|
+
License
|
72
|
+
-------
|
73
|
+
|
74
|
+
Copyright (c) 2010-2012 Robin Stocker.
|
75
|
+
|
76
|
+
taglib-ruby is distributed under the MIT License,
|
77
|
+
see LICENSE.txt for details.
|
78
|
+
|
79
|
+
In the binary gem for Windows, a compiled [TagLib][taglib] is bundled as
|
80
|
+
a DLL. TagLib is distributed under the GNU Lesser General Public License
|
81
|
+
version 2.1 (LGPL) and Mozilla Public License (MPL).
|
82
|
+
|
83
|
+
[taglib]: http://developer.kde.org/~wheeler/taglib.html
|
84
|
+
[travis-img]: https://secure.travis-ci.org/robinst/taglib-ruby.png
|
85
|
+
[travis-link]: http://travis-ci.org/robinst/taglib-ruby
|
86
|
+
[flattr-img]: http://api.flattr.com/button/flattr-badge-large.png
|
87
|
+
[flattr-link]: https://flattr.com/submit/auto?user_id=robinst&url=https://github.com/robinst/taglib-ruby&title=taglib-ruby&tags=github&category=software
|
data/Rakefile
ADDED
@@ -0,0 +1,29 @@
|
|
1
|
+
# encoding: utf-8
|
2
|
+
|
3
|
+
require 'bundler/gem_tasks'
|
4
|
+
begin
|
5
|
+
Bundler.setup(:default, :development)
|
6
|
+
rescue Bundler::BundlerError => e
|
7
|
+
$stderr.puts e.message
|
8
|
+
$stderr.puts "Run `bundle install` to install missing gems"
|
9
|
+
exit e.status_code
|
10
|
+
end
|
11
|
+
|
12
|
+
require 'rake/testtask'
|
13
|
+
Rake::TestTask.new(:test) do |test|
|
14
|
+
test.libs << 'test'
|
15
|
+
test.pattern = 'test/**/*_test.rb'
|
16
|
+
end
|
17
|
+
|
18
|
+
task :default => [:compile, :test]
|
19
|
+
|
20
|
+
require 'yard'
|
21
|
+
YARD::Rake::YardocTask.new do |t|
|
22
|
+
version = TagLib::Version::STRING
|
23
|
+
t.options = ['--title', "taglib-ruby #{version}"]
|
24
|
+
end
|
25
|
+
|
26
|
+
# Change to Bundler::GemHelper.gemspec when it's released
|
27
|
+
$gemspec = Bundler.load_gemspec('taglib-ruby.gemspec')
|
28
|
+
|
29
|
+
FileList['tasks/**/*.rake'].each { |task| import task }
|
@@ -0,0 +1 @@
|
|
1
|
+
.showSource { display: none; }
|
data/docs/taglib/base.rb
ADDED
@@ -0,0 +1,202 @@
|
|
1
|
+
# This is the top-level module of taglib-ruby.
|
2
|
+
#
|
3
|
+
# Where to find what:
|
4
|
+
#
|
5
|
+
# * Reading/writing basic tag and audio properties without having to
|
6
|
+
# know the tagging format: {TagLib::FileRef}
|
7
|
+
# * Reading properties of MPEG files: {TagLib::MPEG::File}
|
8
|
+
# * Reading/writing ID3v2 tags: {TagLib::MPEG::File} and
|
9
|
+
# {TagLib::ID3v2::Tag}
|
10
|
+
# * Reading/writing Ogg Vorbis tags: {TagLib::Ogg::Vorbis::File}.
|
11
|
+
#
|
12
|
+
# ## String Encodings
|
13
|
+
#
|
14
|
+
# Sometimes, it is necessary to specify which encoding should be used to
|
15
|
+
# store strings in tags. For this, the following constants are defined:
|
16
|
+
#
|
17
|
+
# * `TagLib::String::Latin1`
|
18
|
+
# * `TagLib::String::UTF16`
|
19
|
+
# * `TagLib::String::UTF16BE`
|
20
|
+
# * `TagLib::String::UTF8`
|
21
|
+
# * `TagLib::String::UTF16LE`
|
22
|
+
#
|
23
|
+
# For ID3v2 frames, you can also set a default text encoding globally
|
24
|
+
# using the {TagLib::ID3v2::FrameFactory}.
|
25
|
+
module TagLib
|
26
|
+
|
27
|
+
# This class allows to read basic tagging and audio properties from
|
28
|
+
# files, without having to know what the file type is. Thus, it works
|
29
|
+
# for all tagging formats that taglib supports, but only provides a
|
30
|
+
# minimal API.
|
31
|
+
#
|
32
|
+
# Should you need more, use the file type specific classes, see
|
33
|
+
# subclasses of {TagLib::File}.
|
34
|
+
#
|
35
|
+
# @example Reading tags
|
36
|
+
# TagLib::FileRef.open("foo.flac") do |file|
|
37
|
+
# tag = file.tag
|
38
|
+
# puts tag.artist
|
39
|
+
# puts tag.title
|
40
|
+
# end
|
41
|
+
#
|
42
|
+
# @example Reading audio properties
|
43
|
+
# TagLib::FileRef.open("bar.oga") do |file|
|
44
|
+
# prop = file.audio_properties
|
45
|
+
# puts prop.length
|
46
|
+
# puts prop.bitrate
|
47
|
+
# end
|
48
|
+
#
|
49
|
+
class FileRef
|
50
|
+
|
51
|
+
# Creates a new file and passes it to the provided block,
|
52
|
+
# closing the file automatically at the end of the block.
|
53
|
+
#
|
54
|
+
# Note that after the block is done, the file is closed and
|
55
|
+
# all memory is released for objects read from the file
|
56
|
+
# (basically everything from the `TagLib` namespace).
|
57
|
+
#
|
58
|
+
# Using `open` is preferable to using `new` and then
|
59
|
+
# manually `close`.
|
60
|
+
#
|
61
|
+
# @example Reading a title
|
62
|
+
# title = TagLib::FileRef.open("file.oga") do |file|
|
63
|
+
# tag = file.tag
|
64
|
+
# tag.title
|
65
|
+
# end
|
66
|
+
#
|
67
|
+
# @param (see #initialize)
|
68
|
+
# @yield [file] the {FileRef} object, as obtained by {#initialize}
|
69
|
+
# @return the return value of the block
|
70
|
+
#
|
71
|
+
# @since 0.4.0
|
72
|
+
def self.open(filename, read_audio_properties=true,
|
73
|
+
audio_properties_style=TagLib::AudioProperties::Average)
|
74
|
+
end
|
75
|
+
|
76
|
+
# Create a FileRef from a file name.
|
77
|
+
#
|
78
|
+
# @param [String] filename
|
79
|
+
# @param [Boolean] read_audio_properties
|
80
|
+
# true if audio properties should be read
|
81
|
+
# @param [TagLib::AudioProperties constants] audio_properties_style
|
82
|
+
# how accurately the audio properties should be read, e.g.
|
83
|
+
# {TagLib::AudioProperties::Average}
|
84
|
+
def initialize(filename, read_audio_properties=true,
|
85
|
+
audio_properties_style=TagLib::AudioProperties::Average)
|
86
|
+
end
|
87
|
+
|
88
|
+
# @return [TagLib::AudioProperties] the audio properties
|
89
|
+
def audio_properties
|
90
|
+
end
|
91
|
+
|
92
|
+
# @return [Boolean] if the file is null (i.e. it could not be read)
|
93
|
+
def null?
|
94
|
+
end
|
95
|
+
|
96
|
+
# Saves the file
|
97
|
+
#
|
98
|
+
# @return [Boolean] whether saving was successful
|
99
|
+
def save
|
100
|
+
end
|
101
|
+
|
102
|
+
# @return [TagLib::Tag] the tag
|
103
|
+
def tag
|
104
|
+
end
|
105
|
+
|
106
|
+
# Closes the file and releases all objects that were read from the
|
107
|
+
# file.
|
108
|
+
#
|
109
|
+
# @see TagLib::File#close
|
110
|
+
#
|
111
|
+
# @return [void]
|
112
|
+
def close
|
113
|
+
end
|
114
|
+
end
|
115
|
+
|
116
|
+
# @abstract Base class for files, see subclasses.
|
117
|
+
class File
|
118
|
+
# Closes the file and releases all objects that were read from the
|
119
|
+
# file (basically everything from the TagLib namespace).
|
120
|
+
#
|
121
|
+
# After this method has been called, no other methods on this object
|
122
|
+
# may be called. So it's a good idea to always use it like this:
|
123
|
+
#
|
124
|
+
# file = TagLib::MPEG::File.new("file.mp3")
|
125
|
+
# # ...
|
126
|
+
# file.close
|
127
|
+
# file = nil
|
128
|
+
#
|
129
|
+
# This method should always be called as soon as you're finished
|
130
|
+
# with a file. Otherwise the file will only be closed when GC is
|
131
|
+
# run, which may be much later. On Windows, this is especially
|
132
|
+
# important as the file is locked until it is closed.
|
133
|
+
#
|
134
|
+
# As a better alternative to this, use the `open` class method:
|
135
|
+
#
|
136
|
+
# TagLib::MPEG::File.open("file.mp3") do |file|
|
137
|
+
# # ...
|
138
|
+
# end
|
139
|
+
#
|
140
|
+
# @return [void]
|
141
|
+
def close
|
142
|
+
end
|
143
|
+
end
|
144
|
+
|
145
|
+
# @abstract Base class for tags.
|
146
|
+
#
|
147
|
+
# This is a unified view which provides basic tag information, which
|
148
|
+
# is common in all tag formats. See subclasses for functionality that
|
149
|
+
# goes beyond this interface.
|
150
|
+
class Tag
|
151
|
+
# @return [String] the album
|
152
|
+
# @return [nil] if not present
|
153
|
+
attr_accessor :album
|
154
|
+
|
155
|
+
# @return [String] the artist/interpret
|
156
|
+
# @return [nil] if not present
|
157
|
+
attr_accessor :artist
|
158
|
+
|
159
|
+
# @return [String] the comment
|
160
|
+
# @return [nil] if not present
|
161
|
+
attr_accessor :comment
|
162
|
+
|
163
|
+
# @return [String] the genre
|
164
|
+
# @return [nil] if not present
|
165
|
+
attr_accessor :genre
|
166
|
+
|
167
|
+
# @return [String] the title
|
168
|
+
# @return [nil] if not present
|
169
|
+
attr_accessor :title
|
170
|
+
|
171
|
+
# @return [Integer] the track number
|
172
|
+
# @return [0] if not present
|
173
|
+
attr_accessor :track
|
174
|
+
|
175
|
+
# @return [Integer] the year
|
176
|
+
# @return [0] if not present
|
177
|
+
attr_accessor :year
|
178
|
+
|
179
|
+
# @return [Boolean]
|
180
|
+
def empty?; end
|
181
|
+
end
|
182
|
+
|
183
|
+
# @abstract Base class for audio properties.
|
184
|
+
class AudioProperties
|
185
|
+
|
186
|
+
Fast = 0
|
187
|
+
Average = 1
|
188
|
+
Accurate = 2
|
189
|
+
|
190
|
+
# @return [Integer] length of the file in seconds
|
191
|
+
attr_reader :length
|
192
|
+
|
193
|
+
# @return [Integer] bit rate in kb/s (kilobit per second)
|
194
|
+
attr_reader :bitrate
|
195
|
+
|
196
|
+
# @return [Integer] sample rate in Hz
|
197
|
+
attr_reader :sample_rate
|
198
|
+
|
199
|
+
# @return [Integer] number of channels
|
200
|
+
attr_reader :channels
|
201
|
+
end
|
202
|
+
end
|
@@ -0,0 +1,444 @@
|
|
1
|
+
module TagLib::ID3v2
|
2
|
+
# An ID3v2 tag. A tag consists of a list of frames, identified by IDs.
|
3
|
+
#
|
4
|
+
# ## Encoding
|
5
|
+
#
|
6
|
+
# By default, taglib stores ID3v2 text frames as ISO-8859-1 (Latin-1) if the
|
7
|
+
# text contains only characters that are available in that encoding. If
|
8
|
+
# not (e.g. with Cyrillic, Chinese, Japanese), it prints a warning and
|
9
|
+
# stores the text as UTF-8.
|
10
|
+
#
|
11
|
+
# When you already know that you want to store the text as UTF-8, you can
|
12
|
+
# change the default text encoding:
|
13
|
+
#
|
14
|
+
# frame_factory = TagLib::ID3v2::FrameFactory.instance
|
15
|
+
# frame_factory.default_text_encoding = TagLib::String::UTF8
|
16
|
+
#
|
17
|
+
# Another option is using the frame API directly:
|
18
|
+
#
|
19
|
+
# title = tag.frame_list('TIT2').first
|
20
|
+
# title.text = "Joga"
|
21
|
+
# title.text_encoding = TagLib::String::UTF8
|
22
|
+
#
|
23
|
+
# @example Read ID3v2 frames from a file
|
24
|
+
# TagLib::MPEG::File.new("wake_up.mp3") do |file|
|
25
|
+
# tag = file.id3v2_tag
|
26
|
+
#
|
27
|
+
# # Read basic attributes
|
28
|
+
# tag.title #=> "Wake Up"
|
29
|
+
# tag.artist #=> "Arcade Fire"
|
30
|
+
# tag.track #=> 7
|
31
|
+
#
|
32
|
+
# # Access all frames
|
33
|
+
# tag.frame_list.size #=> 13
|
34
|
+
#
|
35
|
+
# # Track frame
|
36
|
+
# track = tag.frame_list('TRCK').first
|
37
|
+
# track.to_s #=> "7/10"
|
38
|
+
#
|
39
|
+
# # Attached picture frame
|
40
|
+
# cover = tag.frame_list('APIC').first
|
41
|
+
# cover.mime_type #=> "image/jpeg"
|
42
|
+
# cover.picture #=> "\xFF\xD8\xFF\xE0\x00\x10JFIF..."
|
43
|
+
# end
|
44
|
+
#
|
45
|
+
# @example Add frames and save file
|
46
|
+
# TagLib::MPEG::File.new("joga.mp3") do |file|
|
47
|
+
# tag = file.id3v2_tag
|
48
|
+
#
|
49
|
+
# # Write basic attributes
|
50
|
+
# tag.artist = "Björk"
|
51
|
+
# tag.title = "Jóga"
|
52
|
+
#
|
53
|
+
# # Add attached picture frame
|
54
|
+
# apic = TagLib::ID3v2::AttachedPictureFrame.new
|
55
|
+
# apic.mime_type = "image/jpeg"
|
56
|
+
# apic.description = "Cover"
|
57
|
+
# apic.type = TagLib::ID3v2::AttachedPictureFrame::FrontCover
|
58
|
+
# apic.picture = File.open("cover.jpg", 'rb'){ |f| f.read }
|
59
|
+
#
|
60
|
+
# tag.add_frame(apic)
|
61
|
+
#
|
62
|
+
# file.save
|
63
|
+
# end
|
64
|
+
class Tag < TagLib::Tag
|
65
|
+
# Get a list of frames. Note that the frames returned are subclasses
|
66
|
+
# of {TagLib::ID3v2::Frame}, depending on the frame ID.
|
67
|
+
#
|
68
|
+
# @overload frame_list()
|
69
|
+
# Returns all frames.
|
70
|
+
#
|
71
|
+
# @overload frame_list(frame_id)
|
72
|
+
# Returns frames matching ID.
|
73
|
+
#
|
74
|
+
# @param [String] frame_id Specify this parameter to get only the
|
75
|
+
# frames matching a frame ID (e.g. "TIT2").
|
76
|
+
#
|
77
|
+
# @return [Array<TagLib::ID3v2::Frame>]
|
78
|
+
def frame_list
|
79
|
+
end
|
80
|
+
|
81
|
+
# Add a frame to the tag.
|
82
|
+
#
|
83
|
+
# @param [Frame] frame
|
84
|
+
# @return [void]
|
85
|
+
def add_frame(frame)
|
86
|
+
end
|
87
|
+
|
88
|
+
# Remove the passed frame from the tag.
|
89
|
+
#
|
90
|
+
# **Note:** You can and shall not call any methods on the frame
|
91
|
+
# object after you have passed it to this method, because the
|
92
|
+
# underlying C++ object has been deleted.
|
93
|
+
#
|
94
|
+
# @param [Frame] frame to remove
|
95
|
+
# @return [void]
|
96
|
+
def remove_frame(frame)
|
97
|
+
end
|
98
|
+
|
99
|
+
# Remove all frames with the specified ID from the tag.
|
100
|
+
#
|
101
|
+
# **Note:** If you have obtained any frame objects with the same ID
|
102
|
+
# from the tag before calling this method, you should not touch them
|
103
|
+
# anymore. The reason is that the C++ objects may have been deleted.
|
104
|
+
#
|
105
|
+
# @param [String] id
|
106
|
+
# @return [void]
|
107
|
+
def remove_frames(id)
|
108
|
+
end
|
109
|
+
end
|
110
|
+
|
111
|
+
# Frame factory for ID3v2 frames. Useful for setting the default text
|
112
|
+
# encoding.
|
113
|
+
class FrameFactory
|
114
|
+
# @return [FrameFactory] the default frame factory
|
115
|
+
def self.instance
|
116
|
+
end
|
117
|
+
|
118
|
+
# Get/set the default text encoding for new ID3v2 frames. See the
|
119
|
+
# section _String Encodings_ in {TagLib}.
|
120
|
+
#
|
121
|
+
# @return [TagLib::String constant] default text encoding
|
122
|
+
attr_accessor :default_text_encoding
|
123
|
+
end
|
124
|
+
|
125
|
+
# The base class for all ID3v2 frames.
|
126
|
+
#
|
127
|
+
# In ID3v2 all frames are identified by a {#frame_id frame ID}, such
|
128
|
+
# as `TIT2` or `APIC`. The data in the frames is different depending
|
129
|
+
# on the frame type, which is why there is a subclass for each type.
|
130
|
+
#
|
131
|
+
# The most common frame type is the text identification frame. All
|
132
|
+
# frame IDs of this type begin with `T`, for example `TALB` for the
|
133
|
+
# album. See {TextIdentificationFrame}.
|
134
|
+
#
|
135
|
+
# Then there are the URL link frames, which begin with `W`, see
|
136
|
+
# {UrlLinkFrame}.
|
137
|
+
#
|
138
|
+
# Finally, there are some specialized frame types and their
|
139
|
+
# corresponding classes:
|
140
|
+
#
|
141
|
+
# * `APIC`: {AttachedPictureFrame}
|
142
|
+
# * `COMM`: {CommentsFrame}
|
143
|
+
# * `GEOB`: {GeneralEncapsulatedObjectFrame}
|
144
|
+
# * `POPM`: {PopularimeterFrame}
|
145
|
+
# * `PRIV`: {PrivateFrame}
|
146
|
+
# * `RVAD`: {RelativeVolumeFrame}
|
147
|
+
# * `TXXX`: {UserTextIdentificationFrame}
|
148
|
+
# * `UFID`: {UniqueFileIdentifierFrame}
|
149
|
+
# * `USLT`: {UnsynchronizedLyricsFrame}
|
150
|
+
# * `WXXX`: {UserUrlLinkFrame}
|
151
|
+
#
|
152
|
+
class Frame
|
153
|
+
# @return [String] frame ID
|
154
|
+
attr_reader :frame_id
|
155
|
+
|
156
|
+
# @return [String] a subclass-specific string representation
|
157
|
+
def to_string
|
158
|
+
end
|
159
|
+
end
|
160
|
+
|
161
|
+
# Attached picture frame (`APIC`), e.g. for cover art.
|
162
|
+
#
|
163
|
+
# The constants in this class are used for the {#type} attribute.
|
164
|
+
class AttachedPictureFrame < Frame
|
165
|
+
# Other
|
166
|
+
Other = 0x00
|
167
|
+
# 32x32 file icon (PNG only)
|
168
|
+
FileIcon = 0x01
|
169
|
+
OtherFileIcon = 0x02
|
170
|
+
FrontCover = 0x03
|
171
|
+
BackCover = 0x04
|
172
|
+
LeafletPage = 0x05
|
173
|
+
Media = 0x06
|
174
|
+
LeadArtist = 0x07
|
175
|
+
Artist = 0x08
|
176
|
+
Conductor = 0x09
|
177
|
+
Band = 0x0A
|
178
|
+
Composer = 0x0B
|
179
|
+
Lyricist = 0x0C
|
180
|
+
RecordingLocation = 0x0D
|
181
|
+
DuringRecording = 0x0E
|
182
|
+
DuringPerformance = 0x0F
|
183
|
+
MovieScreenCapture = 0x10
|
184
|
+
ColouredFish = 0x11
|
185
|
+
Illustration = 0x12
|
186
|
+
BandLogo = 0x13
|
187
|
+
PublisherLogo = 0x14
|
188
|
+
|
189
|
+
def initialize()
|
190
|
+
end
|
191
|
+
|
192
|
+
# @return [String]
|
193
|
+
attr_accessor :description
|
194
|
+
|
195
|
+
# MIME type (e.g. `"image/png"`)
|
196
|
+
# @return [String]
|
197
|
+
attr_accessor :mime_type
|
198
|
+
|
199
|
+
# {include:GeneralEncapsulatedObjectFrame#object}
|
200
|
+
#
|
201
|
+
# @return [binary String]
|
202
|
+
attr_accessor :picture
|
203
|
+
|
204
|
+
# {include:TextIdentificationFrame#text_encoding}
|
205
|
+
#
|
206
|
+
# @return [TagLib::String constant]
|
207
|
+
attr_accessor :text_encoding
|
208
|
+
|
209
|
+
# Type of the attached picture, see constants.
|
210
|
+
# @return [AttachedPictureFrame constant]
|
211
|
+
attr_accessor :type
|
212
|
+
end
|
213
|
+
|
214
|
+
# Comments frame (`COMM`) for full text information that doesn't fit in
|
215
|
+
# any other frame.
|
216
|
+
class CommentsFrame < Frame
|
217
|
+
# @return [String] content description, which together with language
|
218
|
+
# should be unique per tag
|
219
|
+
attr_accessor :description
|
220
|
+
|
221
|
+
# @return [String] alpha-3 language code of text (ISO-639-2),
|
222
|
+
# e.g. "eng"
|
223
|
+
attr_accessor :language
|
224
|
+
|
225
|
+
# @return [String] the actual comment text
|
226
|
+
attr_accessor :text
|
227
|
+
|
228
|
+
# {include:TextIdentificationFrame#text_encoding}
|
229
|
+
#
|
230
|
+
# @return [TagLib::String constant]
|
231
|
+
attr_accessor :text_encoding
|
232
|
+
end
|
233
|
+
|
234
|
+
# General encapsulated object frame (`GEOB`).
|
235
|
+
class GeneralEncapsulatedObjectFrame < Frame
|
236
|
+
# @return [String] content description
|
237
|
+
attr_accessor :description
|
238
|
+
|
239
|
+
# @return [String] file name
|
240
|
+
attr_accessor :file_name
|
241
|
+
|
242
|
+
# @return [String] MIME type
|
243
|
+
attr_accessor :mime_type
|
244
|
+
|
245
|
+
# Binary data string.
|
246
|
+
#
|
247
|
+
# Be sure to use a binary string when setting this attribute. In
|
248
|
+
# Ruby 1.9, this means reading from a file with `"b"` mode to get a
|
249
|
+
# string with encoding `BINARY` / `ASCII-8BIT`.
|
250
|
+
#
|
251
|
+
# @return [binary String]
|
252
|
+
attr_accessor :object
|
253
|
+
|
254
|
+
# {include:TextIdentificationFrame#text_encoding}
|
255
|
+
#
|
256
|
+
# @return [String]
|
257
|
+
attr_accessor :text_encoding
|
258
|
+
end
|
259
|
+
|
260
|
+
# Popularimeter frame (`POPM`).
|
261
|
+
class PopularimeterFrame < Frame
|
262
|
+
# @return [Integer] play counter
|
263
|
+
attr_accessor :counter
|
264
|
+
|
265
|
+
# @return [String] e-mail address
|
266
|
+
attr_accessor :email
|
267
|
+
|
268
|
+
# @return [Integer] rating
|
269
|
+
attr_accessor :rating
|
270
|
+
end
|
271
|
+
|
272
|
+
# Private frame (`PRIV`).
|
273
|
+
class PrivateFrame < Frame
|
274
|
+
# {include:GeneralEncapsulatedObjectFrame#object}
|
275
|
+
#
|
276
|
+
# @return [binary String]
|
277
|
+
attr_accessor :data
|
278
|
+
|
279
|
+
# @return [String] owner identifier
|
280
|
+
attr_accessor :owner
|
281
|
+
end
|
282
|
+
|
283
|
+
# Relative volume adjustment frame (`RVAD` or `RVA2`).
|
284
|
+
class RelativeVolumeFrame < Frame
|
285
|
+
Other = 0x00
|
286
|
+
MasterVolume = 0x01
|
287
|
+
FrontRight = 0x02
|
288
|
+
FrontLeft = 0x03
|
289
|
+
BackRight = 0x04
|
290
|
+
BackLeft = 0x05
|
291
|
+
FrontCentre = 0x06
|
292
|
+
BackCentre = 0x07
|
293
|
+
Subwoofer = 0x08
|
294
|
+
|
295
|
+
# @return [Array<TagLib::ID3v2::RelativeVolumeFrame constant>]
|
296
|
+
# the channel types for which volume adjustment information is
|
297
|
+
# stored in this frame
|
298
|
+
def channels
|
299
|
+
end
|
300
|
+
|
301
|
+
# @return [String] relative volume identification
|
302
|
+
attr_accessor :identification
|
303
|
+
|
304
|
+
# Returns peak volume for channel type.
|
305
|
+
#
|
306
|
+
# @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
|
307
|
+
# @return [TagLib::ID3v2::PeakVolume]
|
308
|
+
def peak_volume(type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
|
309
|
+
end
|
310
|
+
|
311
|
+
# Sets peak volume for channel type.
|
312
|
+
#
|
313
|
+
# @param [TagLib::ID3v2::PeakVolume] peak peak volume
|
314
|
+
# @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
|
315
|
+
# @return [void]
|
316
|
+
def set_peak_volume(peak, type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
|
317
|
+
end
|
318
|
+
|
319
|
+
# Returns volume adjustment in decibels for a specific channel type.
|
320
|
+
# Internally, this is stored as an index, see
|
321
|
+
# {#volume_adjustment_index}.
|
322
|
+
#
|
323
|
+
# @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
|
324
|
+
# @return [Float]
|
325
|
+
def volume_adjustment(type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
|
326
|
+
end
|
327
|
+
|
328
|
+
# Sets volume adjustment in decibels for a specific channel type.
|
329
|
+
# Internally, this is stored as an index, see
|
330
|
+
# {#set_volume_adjustment_index}.
|
331
|
+
#
|
332
|
+
# @param [Float] adjustment
|
333
|
+
# @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
|
334
|
+
# @return [void]
|
335
|
+
def set_volume_adjustment(adjustment, type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
|
336
|
+
end
|
337
|
+
|
338
|
+
# Returns volume adjustment index for a specific channel type. When
|
339
|
+
# dividing the index by 512, it corresponds to the volume adjustment
|
340
|
+
# in decibel.
|
341
|
+
#
|
342
|
+
# @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
|
343
|
+
# @return [Integer]
|
344
|
+
def volume_adjustment_index(type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
|
345
|
+
end
|
346
|
+
|
347
|
+
# Sets volume adjustment index for a specific channel type. When
|
348
|
+
# dividing the index by 512, it corresponds to the volume adjustment
|
349
|
+
# in decibel.
|
350
|
+
#
|
351
|
+
# @param [Integer] index
|
352
|
+
# @param [TagLib::ID3v2::RelativeVolumeFrame constant] type
|
353
|
+
# @return [void]
|
354
|
+
def set_volume_adjustment_index(index, type=TagLib::ID3v2::RelativeVolumeFrame::MasterVolume)
|
355
|
+
end
|
356
|
+
end
|
357
|
+
|
358
|
+
# Peak volume used for {RelativeVolumeFrame}. The two attributes of
|
359
|
+
# this class must always read/written together, as they are used to
|
360
|
+
# describe one concept, the peak volume number.
|
361
|
+
#
|
362
|
+
# Note that due to how SWIG works, this is not a nested class of
|
363
|
+
# RelativeVolumeFrame as in taglib. That doesn't affect its usage
|
364
|
+
# though.
|
365
|
+
class PeakVolume
|
366
|
+
# @return [Integer] the number of bits of the {#peak_volume} that
|
367
|
+
# represent the peak volume (0 to 255)
|
368
|
+
attr_accessor :bits_representing_peak
|
369
|
+
|
370
|
+
# @return [binary String] the (byte-padded) bits used for the peak
|
371
|
+
# volume
|
372
|
+
attr_accessor :peak_volume
|
373
|
+
end
|
374
|
+
|
375
|
+
# Text identification frame (`T???`).
|
376
|
+
class TextIdentificationFrame < Frame
|
377
|
+
# Encoding for storing the text in the tag, e.g.
|
378
|
+
# `TagLib::String::UTF8`. See the section _String Encodings_ in
|
379
|
+
# {TagLib}.
|
380
|
+
#
|
381
|
+
# @return [TagLib::String constant]
|
382
|
+
attr_accessor :text_encoding
|
383
|
+
|
384
|
+
# @return [Array<String>] list of text strings in this frame
|
385
|
+
attr_accessor :field_list
|
386
|
+
|
387
|
+
# @param [String] text simple text to set
|
388
|
+
attr_writer :text
|
389
|
+
end
|
390
|
+
|
391
|
+
# User text identification frame (`TXXX`).
|
392
|
+
class UserTextIdentificationFrame < TextIdentificationFrame
|
393
|
+
# @return [String] description of content
|
394
|
+
attr_accessor :description
|
395
|
+
end
|
396
|
+
|
397
|
+
# Unique file identifier frame (`UFID`).
|
398
|
+
class UniqueFileIdentifierFrame < Frame
|
399
|
+
# @return [String] identifier
|
400
|
+
attr_accessor :identifier
|
401
|
+
|
402
|
+
# @return [String] owner
|
403
|
+
attr_accessor :owner
|
404
|
+
end
|
405
|
+
|
406
|
+
# Unsynchronized lyrics frame (`USLT`).
|
407
|
+
class UnsynchronizedLyricsFrame < Frame
|
408
|
+
# @return [String] frame description
|
409
|
+
attr_accessor :description
|
410
|
+
|
411
|
+
# @return [String] alpha-3 language code of text (ISO-639-2),
|
412
|
+
# e.g. "eng"
|
413
|
+
attr_accessor :language
|
414
|
+
|
415
|
+
# @return [String] text
|
416
|
+
attr_accessor :text
|
417
|
+
|
418
|
+
# {include:TextIdentificationFrame#text_encoding}
|
419
|
+
#
|
420
|
+
# @return [String]
|
421
|
+
attr_accessor :text_encoding
|
422
|
+
end
|
423
|
+
|
424
|
+
# URL link frame (`W???`), e.g. `WOAR` for "official artist/performer
|
425
|
+
# webpage".
|
426
|
+
class UrlLinkFrame < Frame
|
427
|
+
# @param [String] text simple text to set
|
428
|
+
attr_writer :text
|
429
|
+
|
430
|
+
# @param [String] URL
|
431
|
+
attr_accessor :url
|
432
|
+
end
|
433
|
+
|
434
|
+
# User URL link frame (`WXXX`).
|
435
|
+
class UserUrlLinkFrame < UrlLinkFrame
|
436
|
+
# @return [String] description
|
437
|
+
attr_accessor :description
|
438
|
+
|
439
|
+
# {include:TextIdentificationFrame#text_encoding}
|
440
|
+
#
|
441
|
+
# @return [String]
|
442
|
+
attr_accessor :text_encoding
|
443
|
+
end
|
444
|
+
end
|