Basic Usage

Core Functionality

Authenticate

The first step is to initialize the SDK client with the credentials that have been provided to you:

Note: If you are both a Search: Pex Registry and Search: Custom Database customer, each product will require a separate set of credentials.

Python

# AUTHENTICATE CLIENT
client = pex.PexSearchClient("CLIENT_ID", "CLIENT_SECRET")

Go

// AUTHENTICATE CLIENT
client, err := pex.NewPexSearchClient("clientID", "clientSecret")
if err != nil {
	panic(err)
}
defer client.Close()

PHP

// AUTHENTICATE CLIENT
$client = new Pex\PexSearchClient(CLIENT_ID, CLIENT_SECRET);

Node.js

// AUTHENTICATE CLIENT
let client = new pex.PexSearchClient(CLIENT_ID, CLIENT_SECRET)
await client.connect()

Note: There might be a slight delay the first time you authenticate as the SDK downloads and installs necessary updates

Generate Fingerprint

Before performing any searches you need to generate a fingerprint from a media file:

Python

# CREATE AN AUDIO FINGERPRINT FROM MEDIA FILE
ft = client.fingerprint_file(
    "/path/to/file.mp3",
    pex.FingerprintType.AUDIO
)

# CREATE A MELODY + PHONETIC FINGERPRINT FROM MEDIA FILE
ft = client.fingerprint_file(
    "/path/to/file.mp3",
    pex.FingerprintType.MELODY | pex.FingerprintType.PHONETIC
)

# CREATE A CLASSIFICATION FINGERPRINT FROM MEDIA FILE
ft = client.fingerprint_file(
    "/path/to/file.mp3",
    pex.FingerprintType.CLASSIFICATION
)

Go

// CREATE AN AUDIO FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(
    inputFile,
    pex.FingerprintTypeAudio,
)

// CREATE A MELODY + PHONETIC FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(
    inputFile,
    pex.FingerprintTypeMelody|pex.FingerprintTypePhonetic,
)

// CREATE A CLASSIFICATION FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(
    inputFile,
    pex.FingerprintTypeClassification,
)

PHP

// CREATE AN AUDIO FINGERPRINT FROM MEDIA FILE
$ft = $client->fingerprintFile(
    INPUT_FILE,
    [Pex\FingerprintType::Audio]
);

// CREATE A MELODY + PHONETIC FINGERPRINT FROM MEDIA FILE
$ft = $client->fingerprintFile(
    INPUT_FILE,
    [Pex\FingerprintType::Melody, Pex\FingerprintType::Phonetic]
);

// CREATE A CLASSIFICATION FINGERPRINT FROM MEDIA FILE
$ft = $client->fingerprintFile(
    INPUT_FILE,
    [Pex\FingerprintType::Classification]
);

Node.js

// CREATE AN AUDIO FINGERPRINT FROM MEDIA FILE
let ft = await client.fingerprintFile(
  "video.mp4",
  [pex.AUDIO]
);

// CREATE A MELODY + PHONETIC FINGERPRINT FROM MEDIA FILE
let ft = await client.fingerprintFile(
  "video.mp4",
  [pex.MELODY, pex.PHONETIC]
);

// CREATE A CLASSIFICATION FINGERPRINT FROM MEDIA FILE
let ft = await client.fingerprintFile(
  "video.mp4",
  [pex.CLASSIFICATION]
);

Alternatively, a fingeprint can be created from a byte buffer holding a media file

Python

# CREATE AN AUDIO FINGERPRINT FROM BYTE BUFFER HOLDING A MEDIA FILE
ft = client.fingerprint_buffer([]byte, pex.FingerprintType.AUDIO)

Go

// CREATE AUDIO FINGERPRINT FROM BYTE BUFFER HOLDING A MEDIA FILE
ft, err := client.FingerprintBuffer([]byte, pex.FingerprintTypeAudio)
if err != nil {
	panic(err)
}

PHP

// CREATE AUDIO FINGERPRINT FROM BYTE BUFFER HOLDING A MEDIA FILE
$ft = $client->fingerprintBuffer([]byte, [Pex\FingerprintType::Audio]);

Node.js

// CREATE AUDIO FINGERPRINT FROM BYTE BUFFER HOLDING A MEDIA FILE
let ft = await client.fingerprintBuffer([]byte, [pex.AUDIO])

Note: When creating audio fingerprints, the SDK uses a single CPU. For melody fingerprints, the SDK uses two CPUs, if available.

If you need to process larger volumes of files, running computations in parallel is recommended. This can significantly improve processing capacity.

Search Functionality

Initiate Search

Once the fingerprint has been generated, you are ready to initiate a search:

Python

# BUILD REQUEST FOR "IDENTIFY MUSIC" SEARCH TYPE
req = pex.PexSearchRequest(fingerprint=ft, type=pex.PexSearchType.IDENTIFY_MUSIC)

# BUILD REQUEST FOR "FIND MATCHES" SEARCH TYPE
req = pex.PexSearchRequest(fingerprint=ft, type=pex.PexSearchType.FIND_MATCHES)

# START SEARCH
future = client.start_search(req)

Go

// BUILD REQUEST FOR "IDENTIFY MUSIC" SEARCH TYPE
req := &pex.PexSearchRequest{
	Fingerprint: ft,
	Type:        pex.IdentifyMusic,
}

// BUILD REQUEST FOR "FIND MATCHES" SEARCH TYPE
req := &pex.PexSearchRequest{
	Fingerprint: ft,
	Type:        pex.FindMatches,
}

// START SEARCH
fut, err := client.StartSearch(req)
if err != nil {
	panic(err)
}

PHP

// BUILD REQUEST FOR "IDENTIFY MUSIC" SEARCH TYPE
$req = new Pex\PexSearchRequest($ft, $type=Pex\PexSearchType::IdentifyMusic)

// BUILD REQUEST FOR "FIND MATCHES" SEARCH TYPE
$req = new Pex\PexSearchRequest($ft, $type=Pex\PexSearchType::FindMatches)

// START SEARCH
$fut = $client->startSearch($req);

Node.js

// START SEARCH FOR "IDENTIFY MUSIC" SEARCH TYPE
let result = await client.startSearch({
  "fingerprint": ft,
  "type": pex.IDENTIFY_MUSIC,
})

// START SEARCH FOR "FIND MATCHES" SEARCH TYPE
let result = await client.startSearch({
  "fingerprint": ft,
  "type": pex.FIND_MATCHES,
})

A search combines a fingerprint type (how your file is analyzed) with a search type (what kind of lookup is performed). The combination you choose determines the results you’ll see. Refer to Search Types & Use Cases for examples of common use cases and suggested combinations.

Retrieve Search Results

Once a search is complete, you can retrieve the results of the search:

Python

# RETRIEVE SEARCH RESULTS
result = future.get()

Go

// RETRIEVE SEARCH RESULTS
res, err := fut.Get()
if err != nil {
	panic(err)
}

PHP

// RETRIEVE SEARCH RESULTS
$res = $fut->get();

Node.js

// THE STARTSEARCH FUNCTION DESCRIBED IN THE PREVIOUS SECTION WILL AUTOMATICALLY RETRIEVE THE RESULTS WHEN THE SEARCH IS COMPLETED

Interpret Search Results

To view details on what's contained in a search response, please see the following section: Search Response