How to use it

To use the engine in your applications all you need to do is include the API header file audioneex.h and link to the shared library according to the platform used to build the application.

The first thing to do is fingerprinting some audio (a process here referred to as “indexing”) by creating an instance of Indexer, setting some properties, starting an indexing session and call the Indexer::Index() method, as shown in the following code

#include <audioneex.h>

// Create an Indexer and connect it to a fingerprint
// database and audio provider
std::unique_ptr<Audioneex::Indexer>
indexer( Audioneex::Indexer::Create() );
indexer->SetDataStore( someDatastore );
indexer->SetAudioProvider( someAudioProvider );

// Start the indexing session
indexer->Start()

// For each audio recording, call the Index() method by
// passing a progressive (strictly increasing) fingerprint id.
// This will block and cause the engine to repeatedly call the
// OnAudioData() handler of the connected audio provider until
// all audio data for the current recording is exhausted.
while ( haveRecordingsToIndex )
{
    // ...

    indexer->Index( recID++ );
}

// End the indexing session
indexer->End()

The audio provider is any class implementing the AudioProvider interface (a “listener”). Then in the OnAudioData() handler just feed the requested amount of audio to the engine (indicated by the nsamples parameter) in the internal buffer until all audio is consumed

class SomeAudioProvider : public Audioneex::AudioProvider
{
    // ...

    int OnAudioData(uint32_t FID, float *buffer, size_t nsamples)
    {
        // Read nsamples from the source in 16 bit, 11025Hz, mono
        auto audio = someAudioSource->Read( nsamples, 16, 11025, 1 );

        if( audio )
            copy( audio->data(), buffer, nsamples )

        return audio->size();
    }

    // ...
}

Obviously this is a simplified code, but that’s the whole process. To perform identifications, create an instance of Recognizer, set the relevant properties and feed it with audio, as follows

// Create a Recognizer and connect it to a fingerprint database
std::unique_ptr<Audioneex::Recognizer>
recognizer( Audioneex::Recognizer::Create() );
recognizer->SetDataStore( someDataStore );

// Set other properties
// ...

// Feed audio in 1.5s-long chunks at 16 bit, 11025Hz, mono
// until there is a response or there is no more audio
do{
   audio = someAudioSource->Read( 1.5, 16, 11025, 1 );
   recognizer->Identify( audio->data(), audio->size() )
   results = recognizer->GetResults();
}
while(audio && !results);

if( results )
    DoSomething( results );

Please refer to the example programs for more details. There are also few important things to be aware of. The engine uses an error handling system based on C++ exceptions (enabled with /Ehsc in VC++ and -fexceptions in GCC) and most API methods throw exceptions, which cross the library boundaries. This means that the libraries should be used with a matching compiler version to avoid nasty surprises at runtime.

Edit on GitHub