Ruby: Hello World

This was originally published on the Clarify blog on 02 December 2014.

This quickstart demonstrates a simple way to get started using the Clarify API. Following these steps, it should take you no more than 5-10 minutes to have a fully functional search for your audio.

Configuring Your Environment

While you can use any programming language you choose, we provide helper libraries in a few to get you started. In Ruby, you simply install the Clarify gem and set your API key as an environment variable:

gem install clarify

export CLARIFY_API_KEY=abcde12345

setup.sh

Loading Audio

Once you’ve initialized the environment with your API key, you instantiate a Bundle object and store the bundle by specifying a name and url to your audio or video file.

require 'clarify'
require 'pp'

# This assumes that you set up your key in the environment using: export CLARIFY_API_KEY=myapikey
clarify = Clarify::Client.new(api_key: ENV['CLARIFY_API_KEY'])

created_bundle = clarify.bundles.create!(
  name: 'Dorothy and the Wizard of Oz',
  media_url: 'http://media.clarify.io/audio/books/dorothyandthewizardinoz_01_baum_64kb.mp3'
)

pp created_bundle

create.rb

Naming the bundle is optional. We have a number of audio and video files available for processing on our Media Page [Clarify sample media library].

Hint: You don’t have to download these files. Instead you can pass us these urls via the .create() method shown above.

Searching Audio

To search, we’ll use the search() function. If you uploaded the “Wizard of Oz” audio clip, you can search for “dorothy”:

require 'clarify'

clarify = Clarify::Client.new(api_key: 'docs-api-key')

results = clarify.bundles.search('dorothy')

results.each do |bundle_results, bundle_url|
  # Fetch the bundle:
  bundle = clarify.get(bundle_url)

  puts "#{bundle.name} - #{bundle_url}"
  bundle_results['term_results'].each do |term_result|
    term_result['matches'].each do |match|
      type = match['type']
      match['hits'].each do |hit|
        puts "\tmatched #{type} content at #{hit['start']} to #{hit['end']}"
      end
    end
  end
end

search.rb

Then you can process and interact the results however you wish. The code below simply shows the resulting bundle id, bundle name, and the start/end offsets for each occurrence of the search terms. This assumes that the audio clip has been indexed by the time you search. If it hasn’t, wait and try again in a few minutes.

# bundles_search.rb
require 'clarify'

clarify = Clarify::Client.new(api_key: 'docs-api-key')

results = clarify.bundles.search('dorothy')

results.each do |bundle_results, bundle_url|
  # Fetch the bundle:
  bundle = clarify.get(bundle_url)

  puts "#{bundle.name}"
  bundle_results['term_results'].each do |term_result|
    term_result['matches'].each do |match|
      type = match['type']
      match['hits'].each do |hit|
        puts "#{hit['start']} -- #{hit['end']}"
      end
    end
  end
end

search.rb

And here are the results using the Wizard of Oz clip we loaded:

Dorothy and the Wizard of Oz

2.05 -- 2.22

172.49 -- 172.7

224.75 -- 225.01

271.42 -- 271.6

480.64 -- 480.8

Putting it all Together

From here, we can visualize our search results with the included audio player. The player should work with minimal additional configuration, but the bulk of the logic is already above in the results.

Related Posts