Practical overview
When it fits
Use it when you need to run or adapt music recognition against a defined catalog and can prepare the Python, frontend and audio-processing environment.
Who it is for
- Developers exploring or running a music-recognition project against a prepared track catalog.
- Users who can provide a local audio file or microphone recording and want to search that catalog.
- People adapting a music-search application using embeddings, vector similarity and audio fingerprints.
Documented uses
- Identify a track from an uploaded audio clip or microphone recording.
- Build a searchable catalog from a CSV using the documented ingestion, augmentation and enrichment pipeline.
- Inspect candidate tracks and identification scores through the command-line interface.
- Launch the documented local web interface for audio identification.
Requirements & limits
- The catalog must contain the target track for the documented matching workflow to find it.
- Catalog construction is a distinct step from querying: the README documents ingestion, augmentation and enrichment.
- Python 3.10 (64-bit), Node.js 18+ for the frontend, and ffmpeg are listed as requirements; Python 3.11+ is listed as unsupported.
- GPU is recommended for CLAP, MuQ and MERT; the README states CPU works for MFCC and CLAP.
- The repository is public, but no license is supplied in the repository metadata provided here.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Set up the local web interface
Install the documented Python and frontend dependencies, then start the development web interface.
Before you start
- 64-bit Python 3.10; Python 3.11+ is listed as unsupported.
- Node.js 18 or later for the React frontend.
- ffmpeg installed and available on PATH.
- Repository checkout and its root requirements.txt.
Steps
Create and activate a Python 3.10 virtual environment.
Install Python dependencies with pip install -r requirements.txt.
From webapp/frontend, install frontend dependencies with npm install.
Run python manage.py webapp; the README gives http://localhost:5173 as the development address.
Expected outcome
The project’s development web interface is launched locally at the address documented in the README.
Guide limitations
- This covers setup and launch, not catalog ingestion or a successful recognition run.
- The README says web use requires the root requirements.txt; webapp/backend/requirements.txt alone is insufficient for /api/identify.
- A GPU is recommended for CLAP, MuQ and MERT; CPU is stated to work for MFCC and CLAP.
Identify a local audio file from the command line
Use the documented command to request track identification for an audio file.
Before you start
- Repository dependencies installed in the Python 3.10 environment.
- An audio file available at a local path.
- A prepared track catalog and identification data; the README documents catalog construction as a separate pipeline.
Steps
Activate the project virtual environment.
Run python manage.py identify data/raw/my_audio.mp3, substituting the path to the local audio file.
For score details and ten candidates, use the documented --top 10 --detailed options.
Expected outcome
The command requests identification and can display detailed scores and a top-ten candidate list.
Guide limitations
- The README does not guarantee a match; results depend on the catalog and fingerprint/vector search.
- This guide documents the command, not a verified execution.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 18 October 2026
- Original website title
- thmsgo18/Shazam · Official homepage title · retained in its source language