Class: MusicBrainz::TRM

Class | MusicBrainz::TRM
In: | musicbrainz.c (CVS)
Parent: | Object

Client API to generate MusicBrainz TRM signatures. The easiest way to explain the code is probably with a simple example.

      # load the musicbrainz library
      require 'musicbrainz'

      # create a musicbrainz trm handle
      trm = MusicBrainz::TRM.new

      # prepare for CD-quality audio
      samples, channels, bits = 44100, 2, 16
      trm.pcm_data samples, channels, bits

      # read data from file and pass it to the TRM handle
      # until MusicBrainz has enough information to generate
      # a signature
      while buf = fh.read(4096)
        break if trm.generate_signature(buf)
      end

      # check for signature
      if sig = trm.finalize_signature
        # print human-readable version of signature
        puts trm.convert_sig(sig)
      else
        $stderr.puts "Couldn't generate signature"
      end

### Methods

convert_sig convert_sig_to_ascii finalize_signature generate_signature length= new pcm_data pcm_data_info proxy= set_length set_pcm_data set_pcm_data_info set_proxy set_song_length sig_to_ascii song_length=

### Public Class methods

new()

Allocate and initialize a new MusicBrainz::TRM object.

Example:

      trm = MusicBrainz::TRM.new

### Public Instance methods

convert_sig(p1)

Convert 16-byte raw signature into a human-readable 36-byte ASCII string.

Used after MusicBrainz::TRM#generate_signature has returned true and MusicBrainz::TRM#finalize_signature has returned a signature.

Aliases:

      MusicBrainz::TRM#sig_to_ascii
      MusicBrainz::TRM#convert_sig_to_ascii

Examples:

      puts 'signature: ' << trm.convert_sig raw_sig

convert_sig_to_ascii(p1)

Alias for convert_sig

finalize_signature(...)

Finalize generated signature.

Call this after MusicBrainz::TRM#generate_signature has returned true.

Accepts an optional 16-byte string, used to associate the signature with a particular collection in the RElatable Engine. Returns nil on error, or a 16 byte signature on success.

Example:

      sig = trm.finalize_signature

generate_signature(p1)

Pass raw PCM data to generate a signature.

Note: MusicBrainz::TRM#pcm_data must be called before this function.

Returns true if enough data has been sent to generate a signature, and false if more data is needed.

Example:

      trm.generate_signature buf

length=(p1)

Set the length of an audio stream (in seconds).

Note: This method is optional, but if it is called, it must be called after MusicBrainz::TRM#pcm_data and before any calls to MusicBrainz::TRM#generate_signature.

Aliases:

      MusicBrainz::TRM#set_length
      MusicBrainz::TRM#song_length=
      MusicBrainz::TRM#set_song_length

Examples:

      trm.length = 4000

pcm_data(p1, p2, p3)

Set the information of an audio stream to be signatured.

Note: this MUST be called before attempting to generate a signature.

samples: samples per second (Hz) of audio data (eg 44100) channels: number of audio channels (eg 1 for mono, or two for stereo) bits: bits per sample (eg 8 or 16)

Aliases:

      MusicBrainz::TRM#set_pcm_data
      MusicBrainz::TRM#pcm_data_info
      MusicBrainz::TRM#set_pcm_data_info

Examples:

      # prepare for CD-quality audio
      samples, channels, bits = 44100, 2, 16
      trm.pcm_data samples, channels, bits

pcm_data_info(p1, p2, p3)

Alias for pcm_data

proxy=(...)

Set the proxy name and port for the MusicBrainz::TRM object.

Note: If unspecified, the port defaults to 8080.

Returns false if MusicBrainz could not connect to the proxy.

Aliases:

      MusicBrainz::TRM#set_proxy

Examples:

      # connect to 'proxy.localdomain', port 8080
      trm.proxy = 'proxy.localdomain'

      # connect to proxy.example.com, port 31337
      trm.proxy = 'proxy.example.com:31337'

      # connect to www.musicbrainz.org, port 8080
      trm.set_proxy 'www.musicbrainz.org'

      # connect to proxy.example.com, port 31337
      trm.set_proxy 'proxy.example.com', 31337

set_length(p1)

Alias for length=

set_pcm_data(p1, p2, p3)

Alias for pcm_data

set_pcm_data_info(p1, p2, p3)

Alias for pcm_data

set_proxy(...)

Alias for proxy=

set_song_length(p1)

Alias for length=

sig_to_ascii(p1)

Alias for convert_sig

song_length=(p1)

Alias for length=

[Validate]