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



125
126
127
 
# File 'docs/taglib/base.rb', line 125

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



113
114
115
 
# File 'docs/taglib/base.rb', line 113

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:



135
136
 
# File 'docs/taglib/base.rb', line 135

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:



162
163
 
# File 'docs/taglib/base.rb', line 162

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)



139
140
 
# File 'docs/taglib/base.rb', line 139

def null?
end

#save ⇒ Boolean

Saves the file

Returns:

  • (Boolean) —

    whether saving was successful



145
146
 
# File 'docs/taglib/base.rb', line 145

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:



153
154
 
# File 'docs/taglib/base.rb', line 153

def tag
end