home demo docs source

Timber is a library for doing realtime pitch detection in web apps. Here's a basic guide on using it in your own projects.


To get started, you'll need to download at least timber.js and Timber.swf (do not hotlink them - please host the files yourself).

Using it

Timber uses the swfobject library. You can either host that yourself, or use the Google-hosted copy:

<script src="http://ajax.googleapis.com/ajax/libs/swfobject/2.2/swfobject.js"></script>

You also need to import timber.js - you'll be hosting that yourself:

<script src="http://example.com/timber/timber.js"></script>
Next you need a placeholder DOM element that will hold the Flash part of Timber. Once the library has access to the user's microphone, this will be invisible. Until then (but only after you initialize Timber), this will display a request to access a microphone:
<div id="timber"></div>
Now you need to initialize Timber:
  load_timber("http://example.com/timber/", "timber", "my_init");
All three parameters are required. First you need to tell Timber where you've hosted it, so it can fetch the remaining files it needs to run. Next give it the DOM id of the placeholder you created above. Finally you specify the name of a javascript function which Timber should call after the library has finished initializing itself.
Once Timber has finished initializing, you can add an event handler that will get called any time a note is detected:
$("timber").setCallback("NOTE_DETECTED", "got_note");
Here's a full list of the callbacks you can add:
"DEBUG" (one string parameter, a debug message)
"MIC_INIT" (one string parameter, the name of the microphone that is being initialized)
"MIC_OK" (no parameters)
"MIC_FAILED" (no parameters)
"NOTE_DETECTED" (two numeric parameters: a note number between 0.0 and 12.0, with 0.0 representing a "C", and an amplitude between 0.0 and 1.0)
There are two more functions you can invoke on Timber: getMicrophoneNames returns a list of the available microphones, and useMicrophone tells Timber to try to use one of them. You don't necessarily need to use these functions - Timber will attempt to use the default microphone as soon as it's initialized.

Building it

Download and install haxe, and then run ./compile.sh in the src directory.