Skip to content

SDK CLI (pexsearch)

The SDK includes a command-line interface tool called pexsearch. It allows you to interact with the Search API directly from your terminal without writing code, making it ideal for testing, one-off searches, batch scripts, and managing your private catalog.

With pexsearch, you can:

  • Generate fingerprints from audio and video files and save them to disk
  • Perform searches against the Vobile Music Registry or your Custom Database
  • Execute synchronous searches (run) or asynchronous searches (start / check)
  • Manage your Custom Database catalog by ingesting media files and retrieving entry details

Installation

The pexsearch CLI tool is bundled with the Core Library (SDK) installer package. When you install the SDK package (Debian/Ubuntu .deb, Red Hat .rpm, or macOS .pkg), pexsearch is automatically installed into your system path (e.g., /usr/local/bin/pexsearch or /usr/bin/pexsearch).

To verify that pexsearch is installed and available in your environment, run:

pexsearch --help

Authentication

The pexsearch CLI authenticates using two environment variables:

  • PEXSEARCH_CLIENT_ID: Your client ID
  • PEXSEARCH_CLIENT_SECRET: Your client secret

Before executing any commands, export your credentials in your terminal session:

export PEXSEARCH_CLIENT_ID="YOUR_CLIENT_ID"
export PEXSEARCH_CLIENT_SECRET="YOUR_CLIENT_SECRET"

Info

Note: If you are both a Search: Vobile Music Registry and Search: Custom Database customer, each product requires a separate set of credentials. Make sure you set the environment variables to the credentials corresponding to the registry you want to query or manage.

Fingerprinting

Generate Fingerprint to Disk

The fingerprint command generates a fingerprint from a media file and writes the raw binary fingerprint to a file on disk.

pexsearch fingerprint <file> -o <output_path> [flags]
Flags
Flag Description
-o, --output (required) Path to the output file where the fingerprint will be stored
--audio Enable audio fingerprinting
--melody Enable melody fingerprinting
--phonetic Enable phonetic fingerprinting
--video Enable video fingerprinting
--classification Enable classification fingerprinting (music, speech, and silence detection)

Info

Note: If no fingerprint type flags (--audio, --melody, --phonetic, --video, --classification) are specified, pexsearch generates audio, melody, and phonetic fingerprints by default. If any flag is explicitly provided, only the specified fingerprint types are generated.

Examples
# GENERATE DEFAULT FINGERPRINT (AUDIO, MELODY, PHONETIC)
pexsearch fingerprint /path/to/audio.mp3 -o /path/to/fingerprint.ft

# GENERATE AUDIO-ONLY FINGERPRINT
pexsearch fingerprint /path/to/audio.mp3 -o /path/to/audio.ft --audio

# GENERATE MELODY AND PHONETIC FINGERPRINT
pexsearch fingerprint /path/to/audio.mp3 -o /path/to/melody.ft --melody --phonetic

# GENERATE CLASSIFICATION FINGERPRINT
pexsearch fingerprint /path/to/audio.mp3 -o /path/to/classification.ft --classification
Output

The command returns a JSON object confirming the output path:

{
  "output": "/path/to/fingerprint.ft"
}

Search: Vobile Music Registry

You can search the Vobile Music Registry to identify copyrighted music or find commercially distributed versions of your assets.

Synchronous Search (run)

The run command fingerprints the input file, initiates the search, waits for the search to complete, and returns the full search results in JSON format.

pexsearch run <file> [flags]
Flags
Flag Description
--type Search type: identify-music or find-matches
--audio Enable audio fingerprinting
--melody Enable melody fingerprinting
--phonetic Enable phonetic fingerprinting
--video Enable video fingerprinting
Examples
# IDENTIFY MUSIC WITH AUDIO FINGERPRINTING
pexsearch run /path/to/audio.mp3 --type identify-music --audio

# IDENTIFY MUSIC WITH MELODY AND PHONETIC FINGERPRINTING (COVER SONG DETECTION)
pexsearch run /path/to/audio.mp3 --type identify-music --melody --phonetic

# FIND MATCHES TO COMMERCIALLY DISTRIBUTED RECORDINGS
pexsearch run /path/to/audio.mp3 --type find-matches --audio
Output

The command outputs the complete JSON search results. See Search Response for details on interpreting the response structure:

{
  "lookup_ids": [
    "522174538802801153"
  ],
  "query_file_duration_seconds": 158.0,
  "matches": [
    {
      "asset": {
        "title": "Example Track Title",
        "artist": "Example Artist",
        "isrc": "USRC12103120",
        "id": "487041776134662145",
        "duration_seconds": 207.0,
        "album_name": "Example Album",
        "label": "Example Records"
      },
      "match_details": {
        "audio": {
          "query_match_duration_seconds": 158.0,
          "query_match_percentage": 100.0,
          "asset_match_duration_seconds": 207.0,
          "asset_match_percentage": 100.0,
          "segments": [
            {
              "query_start": 0,
              "query_end": 158,
              "asset_start": 0,
              "asset_end": 207,
              "audio_pitch": 0,
              "audio_speed": 100
            }
          ]
        }
      }
    }
  ]
}

Asynchronous Search (start and check)

For long-running queries or automated pipelines, you can decouple starting the search from checking the results.

1. Start the Search (start)
pexsearch start <file> [flags]

# START AN ASYNCHRONOUS SEARCH
pexsearch start /path/to/audio.mp3 --type identify-music --audio

The command returns a JSON object containing the lookup ID(s):

{
  "lookup_ids": "522174538802801153"
}
2. Check Search Results (check)

Use the lookup ID returned from start to retrieve the search results:

pexsearch check <lookup_ids> [flags]

# CHECK RESULTS FOR A SINGLE LOOKUP ID
pexsearch check 522174538802801153

# CHECK RESULTS FOR MULTIPLE LOOKUP IDS (COMMA-SEPARATED)
pexsearch check 522174538802801153,522174538802801154

Search: Custom Database

To search against your private catalog instead of the Vobile Music Registry, add the --private flag to the search commands.

Important

Ensure your PEXSEARCH_CLIENT_ID and PEXSEARCH_CLIENT_SECRET environment variables are set to your Custom Database credentials.

# RUN SEARCH AGAINST CUSTOM DATABASE
pexsearch run /path/to/query.mp3 --private --audio

# START SEARCH AGAINST CUSTOM DATABASE
pexsearch start /path/to/query.mp3 --private --audio

# CHECK RESULTS AGAINST CUSTOM DATABASE
pexsearch check <lookup_ids> --private

Custom Database Catalog Management

For Custom Database clients, pexsearch provides commands to ingest assets into your private catalog and retrieve entry metadata.

Ingest Asset (ingest)

The ingest command fingerprints a media file and uploads it into your private catalog under a custom provided identifier.

pexsearch ingest <provided_id> <file> [flags]
Flags
Flag Description
--audio Enable audio fingerprinting
--melody Enable melody fingerprinting
--phonetic Enable phonetic fingerprinting
--video Enable video fingerprinting
Example
# INGEST AN ASSET WITH AUDIO FINGERPRINTING
pexsearch ingest "my-unique-asset-001" /path/to/master.wav --audio

# INGEST AN ASSET WITH AUDIO AND MELODY FINGERPRINTING
pexsearch ingest "my-unique-asset-002" /path/to/master.wav --audio --melody
Output

Upon successful ingestion, the command returns the provided identifier:

{
  "provided_id": "my-unique-asset-001"
}

Get Entry Details (get)

The get command retrieves the status and fingerprint details of an existing catalog entry using its provided ID.

pexsearch get <provided_id>
Example
pexsearch get "my-unique-asset-001"
Output
{
  "provided_id": "my-unique-asset-001",
  "status": 1,
  "fingerprint_types": [
    1
  ]
}

Shell Autocompletion

The pexsearch completion command generates shell autocompletion scripts for various shells:

# BASH
pexsearch completion bash > /etc/bash_completion.d/pexsearch

# ZSH
pexsearch completion zsh > "${fpath[1]}/_pexsearch"

# FISH
pexsearch completion fish > ~/.config/fish/completions/pexsearch.fish

# POWERSHELL
pexsearch completion powershell | Out-String | Invoke-Expression

Command Reference Summary

Command Usage Description
fingerprint pexsearch fingerprint <file> -o <output> [flags] Generate a fingerprint and save it to disk
run pexsearch run <file> [flags] Fingerprint, submit search, wait, and return results
start pexsearch start <file> [flags] Fingerprint and start an asynchronous search
check pexsearch check <lookup_ids> [flags] Retrieve results of previously started searches
ingest pexsearch ingest <provided_id> <file> [flags] Ingest a media file into your Custom Database catalog
get pexsearch get <provided_id> Retrieve metadata for a Custom Database catalog entry
completion pexsearch completion <shell> Generate shell autocompletion script