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

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

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



104
105
106
# File 'docs/taglib/base.rb', line 104

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

Class Method Details

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

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



92
93
94
# File 'docs/taglib/base.rb', line 92

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

Instance Method Details

- (TagLib::AudioProperties) audio_properties

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:



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

def audio_properties
end

- (void) close

This method returns an undefined value.

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

See Also:



141
142
# File 'docs/taglib/base.rb', line 141

def close
end

- (Boolean) null?

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)



118
119
# File 'docs/taglib/base.rb', line 118

def null?
end

- (Boolean) save

Saves the file

Returns:

  • (Boolean)

    whether saving was successful



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

def save
end

- (TagLib::Tag) 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:



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

def tag
end