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: Custom Database and Search: Pex Registry customer, each product will require a separate set of credentials.

Python

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

Go

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

PHP

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

Node.js

// AUTHENTICATE CLIENT
let client = new pex.PrivateSearchClient(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

First, generate a fingerprint from the media file you. You can either generate a fingerprint to ingest into your custom database or you can generate a fingerprint to initiate a search with.

Python

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

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

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

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

Go

// CREATE AUDIO FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(inputFile, pex.FingerprintTypeAudio)
if err != nil {
	panic(err)
}
	
// CREATE MELODY FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(inputFile, pex.FingerprintTypeMelody)
if err != nil {
	panic(err)
}

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

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

PHP

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

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

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

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

Node.js

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

// CREATE MELODY FINGERPRINT
let ft = await client.fingerprintFile("video.mp4", [pex.MELODY])

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

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

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.

For information on the difference between audio and melody fingerprints and the use cases they address, please see our FAQ page

Searching Functionality

Generate Fingerprint

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

Python

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

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

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

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

Go

// CREATE AUDIO FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(inputFile, pex.FingerprintTypeAudio)
if err != nil {
	panic(err)
}
	
// CREATE MELODY FINGERPRINT FROM MEDIA FILE
ft, err := client.FingerprintFile(inputFile, pex.FingerprintTypeMelody)
if err != nil {
	panic(err)
}

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

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

PHP

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

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

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

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

Node.js

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

// CREATE MELODY FINGERPRINT
let ft = await client.fingerprintFile("video.mp4", [pex.MELODY])

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

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

Note: Our SDK's computations are single-threaded. If you need to process larger volumes of files, running computations in parallel is recommended. This can significantly improve processing capacity.

For information on the difference between audio and melody fingerprints and the use cases they address, please see our FAQ page

Initiate Search

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

Python

# BUILD CUSTOM DATABASE SEARCH REQUEST
req = pex.PrivateSearchRequest(fingerprint=ft)

# START SEARCH
future = client.start_search(req)

Go

// BUILD CUSTOM DATABASE SEARCH REQUEST
req := &pex.PrivateSearchRequest{
	Fingerprint: ft,
}

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

PHP

// BUILD CUSTOM DATABASE SEARCH REQUEST
$req = new \Pex\PrivateSearchRequest($ft);

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

Node.js

// START CUSTOM DATABASE SEARCH REQUEST
let result = await client.startSearch({
  "fingerprint": ft
})

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

Catalog Management

Add Fingerprint to Custom Database

Now that the fingerprint has been generated, you can add that fingerprint file to your custom database. You can associate a "custom_id" string of your choosing for each fingerprint (to help you uniquely identify each fingerprint that is in your database):

Python

# ADD FINGERPRINT CUSTOM DATABASE
client.ingest("custom_id", ft)

Go

# ADD FINGERPRINT CUSTOM DATABASE
if err := client.Ingest("custom_id", ft); err != nil {
	panic(err)
}

PHP

// ADD FINGERPRINT CUSTOM DATABASE
$client->ingest("custom_id", $ft);

Node.js

// ADD FINGERPRINT CUSTOM DATABASE
await client.ingest("my-provided-id", ft)

Note: After ingesting an asset, it will take a short time (generally a few minutes) before it is available in your custom database to be searched against

Archive Fingerprint from your Custom Database

If you would like to remove an asset from your Custom Database so that it can no longer be matched against, you can do so with this command:

Python

# ARCHIVE FINGERPRINT
client.archive("custom_id")

Go

# ARCHIVE FINGERPRINT
if err := client.Archive("custom_id"); err != nil {
	panic(err)
}

PHP

// ARCHIVE FINGERPRINT
$client->archive("custom_id");

Node.js

// ARCHIVE FINGERPRINT
await client.ingest("my-provided-id")

Lists Assets in your Custom Database

If you would like to view what assets are currently in your Custom Database, you can do so with the Lister functionality:

Python

lister = client.list_entries(pex.ListEntriesRequest())
// To limit the number of entries:
//   lister = client.list_entries(pex.ListEntriesRequest(limit=5))

while lister.has_next_page:
  entries = lister.list()

  for entry in entries:
    print(entry)

Go

lister := client.ListEntries(&pex.ListEntriesRequest{})
// To limit the number of entries:
//   lister := client.ListEntries(&pex.ListEntriesRequest{
//     Limit: 5,
//   })

for lister.HasNextPage {
  entries := lister.List()

  for _, entry := range entries {
    fmt.Println(entry)
  }
}

PHP

$lister = $client->listEntries(new Pex\ListEntriesRequest());
// To limit the number of entries:
//   $lister = $client->listEntries(new Pex\ListEntriesRequest(limit: 5));

while ($lister->hasNextPage()) {
  $entries = $lister->list();

  foreach ($entries as $entry) {
    echo json_encode($entry, JSON_PRETTY_PRINT) . PHP_EOL;
  }
}

Node.js

let lister = client.listEntries({});
// To limit the number of entries:
//   let lister = client.listEntries({limit: 5});

while (lister.hasNextPage()) {
  let entries = await lister.list();

  for (const entry of entries) {
    console.log(entry);
  }
}