Class: TagLib::FileRef

Inherits:
Object
  • Object
show all
Defined in:
docs/taglib/base.rb

Overview

This class allows to read basic tagging and audio properties from files, without having to know what the file type is. Thus, it works for all tagging formats that taglib supports, but only provides a minimal API.

Should you need more, use the file type specific classes, see subclasses of File.

Examples:

Reading tags

TagLib::FileRef.open("foo.flac") do |file|
  unless file.null?
    tag = file.tag
    puts tag.artist
    puts tag.title
  end
end

Reading audio properties

TagLib::FileRef.open("bar.oga") do |file|
  unless file.null?
    prop = file.audio_properties
    puts prop.length
    puts prop.bitrate
  end
end

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(filename, read_audio_properties = true, audio_properties_style = TagLib::AudioProperties::Average) ⇒ FileRef

Create a FileRef from a file name.

Parameters:

  • filename (String)
  • read_audio_properties (Boolean) (defaults to: true) —

    true if audio properties should be read

  • audio_properties_style (TagLib::AudioProperties constants) (defaults to: TagLib::AudioProperties::Average) —

    how accurately the audio properties should be read, e.g. AudioProperties::Average



123
124
125
 
# File 'docs/taglib/base.rb', line 123

def initialize(filename, read_audio_properties=true,
               audio_properties_style=TagLib::AudioProperties::Average)
end

Class Method Details

.open(filename, read_audio_properties = true, audio_properties_style = TagLib::AudioProperties::Average) {|file| ... } ⇒ Object

Creates a new file and passes it to the provided block, closing the file automatically at the end of the block.

Note that after the block is done, the file is closed and all memory is released for objects read from the file (basically everything from the TagLib namespace).

Using open is preferable to using new and then manually close.

Examples:

Reading a title

title = TagLib::FileRef.open("file.oga") do |file|
  tag = file.tag
  tag.title
end

Parameters:

  • filename (String)
  • read_audio_properties (Boolean) (defaults to: true) —

    true if audio properties should be read

  • audio_properties_style (TagLib::AudioProperties constants) (defaults to: TagLib::AudioProperties::Average) —

    how accurately the audio properties should be read, e.g. AudioProperties::Average

Yields:

Returns:

  • the return value of the block

Since:

  • 0.4.0



111
112
113
 
# File 'docs/taglib/base.rb', line 111

def self.open(filename, read_audio_properties=true,
               audio_properties_style=TagLib::AudioProperties::Average)
end

Instance Method Details

#audio_properties ⇒ TagLib::AudioProperties

Gets the audio properties. Before accessing it, check if there were problems reading the file using #null?. If the audio properties are accessed anyway, a warning will be printed and it will return nil.

Returns:



133
134
 
# File 'docs/taglib/base.rb', line 133

def audio_properties
end

#close ⇒ void

This method returns an undefined value.

Closes the file and releases all objects that were read from the file.

See Also:



160
161
 
# File 'docs/taglib/base.rb', line 160

def close
end

#null? ⇒ Boolean

Returns if the file is null (i.e. it could not be read).

Returns:

  • (Boolean) —

    if the file is null (i.e. it could not be read)



137
138
 
# File 'docs/taglib/base.rb', line 137

def null?
end

#save ⇒ Boolean

Saves the file

Returns:

  • (Boolean) —

    whether saving was successful



143
144
 
# File 'docs/taglib/base.rb', line 143

def save
end

#tag ⇒ TagLib::Tag

Gets the tag. Before accessing it, check if there were problems reading the file using #null?. If the tag is accessed anyway, a warning will be printed and it will return nil.

Returns:



151
152
 
# File 'docs/taglib/base.rb', line 151

def tag
end