Java: Hello World

This was originally published on the Clarify blog on 09 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 Java, you can simply install the Clarify SDK via your Maven pom.xml

<dependency>
    <groupId>io.clarify.api</groupId>
    <artifactId>clarify-api-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

pom.xml

Loading Audio

Once you’ve installed the SDK, you instantiate the Clarify client by passing in your API Key. Next, you can create a bundle my passing in a name for your bundle and the audio/video URL itself:

import io.clarify.api.*;
import java.net.URI;

public class App {
  public static void main(String[] args) throws Exception {
    String appKey = "my api key";

    // Construct the API client
    ClarifyClient client = new ClarifyClient(appKey);

    // Create your first bundle using an example audio file
    String name = "Dorothy and the Wizard of Oz";
    URI mediaUrl =  URI.create("http://media.clarify.io/audio/books/dorothyandthewizardinoz_01_baum_64kb.mp3");
    Bundle bundle = client.createBundle(name, mediaUrl);

    System.out.println(bundle.id());
  }
}

app.java

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 searchBundles() method. If you uploaded the “Wizard of Oz” audio clip, you can search for “dorothy”:

import io.clarify.api.*;
import java.net.URI;

public class App {
  public static void main(String[] args) throws Exception {
    String appKey = "my api key";

    // Construct the API client
    ClarifyClient client = new ClarifyClient(appKey);

    // Search your media by query string
    String query = "dorothy";
    BundleSearchResults bundleSearchResults = client.searchBundles(query);
    JSONArray itemResults = bundleSearchResults.getItemResults();
    for(int i=0;i<itemResults.length();i++) {
        JSONObject item = (JSONObject)itemResults.get(i);
        System.out.println("score="+item.get("score"));
    }
  }
}

app.java

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.

import java.net.URI;
import java.io.IOException;

import us.monoid.json.*;
import io.clarify.api.*;

public class App
{
    public static void main( String[] args ) throws IOException, JSONException
    {
        String appKey = "abcde12345";
        //Construct the API client
        ClarifyClient client = new ClarifyClient(appKey);

        // Search your media by query string
        String query = "dorothy";
        BundleSearchResults bundleSearchResults = client.searchBundles(query);
        JSONArray itemResults = bundleSearchResults.getItemResults();
        for(int i=0;i<itemResults.length();i++) {
            JSONObject item = (JSONObject)itemResults.get(i);
            JSONArray results = (JSONArray)item.get("term_results");

            // Iterate over the term results to get the matches
            for(int j=0;j<=results.length();j++) {
                JSONObject term_results = (JSONObject)results.get(j);
                JSONArray matches = (JSONArray)term_results.get("matches");

                // Iterate over the matches to get the hits
                for(int k=0;k<=matches.length();k++) {
                    JSONObject match = (JSONObject)matches.get(k);
                    JSONArray hits = (JSONArray)match.get("hits");

                    // Iterate over the hits to get the details
                    for(int m=0;m<=hits.length();m++) {
                        JSONObject hit = (JSONObject)hits.get(m);
                        System.out.println(hit.get("start") + " -- " + hit.get("end"));
                    }
                }
            }
        }
    }
}

App.java

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.