Description

Fourio is a command-line implementation of a music recognition system inspired by Shazam.The name Fourio is a portmanteau of "Fourier" and "Audio" named after the Fourier Transform.It analyzes song fingerprints, detects matches from local or downloaded tracks, and integrates with Spotify and YouTube for metadata and previews. It has addtional features like a REST APIs, Multiple DB support like MongoDB and SQLite.

This version of Fourio is fully written in Python, powered by:

• ⚡ FastAPI — backend API framework for high-performance web services
• 🧠 Typer — command-line interface (CLI) for intuitive developer experience
• 🧩 uv — ultra-fast dependency manager and environment tool
• 🎵 ffmpeg — audio conversion and processing utility
• ☁️ Spotify API — metadata integration for tracks, albums, and playlists
• 🎞️ YouTube API — for fetching song previews and additional metadata

Project Struture

fourio/
├── app/
│   ├── api/             # Web API endpoints
│   ├── utils/           # Logging, file handling, general utilities
│   ├── db/              # Database connection and operations
│   ├── models/          # Data models
│   ├── services/        # Different services like Spotify, YouTube and WAV conversion
│   ├── core/            # Core fingerprinting, Spectrogram and matching logic
│   └── main.py          # FastAPI entry point
|── .env                 # Environment variables
├── pyproject.toml       # uv dependencies
├── requirements.txt     # Python dependencies  (Optional)
├── cli_logic.py         # CLI logic        
├── cli.py               # Typer CLI entry point
├── .gitignore
├── README.md
└── LICENSE

---

Installation

✔ Prerequisites

🔹 Python 3.10+

• Download Python

🔹 FFmpeg (required for audio decoding)

Install FFmpeg:

• Windows (Chocolatey — Recommended)

  choco install ffmpeg

  Chocolatey install guide

• macOS (Homebrew)

    brew install ffmpeg

• Linux (Ubuntu/Debian)

    sudo apt update
    sudo apt install ffmpeg

• Official FFmpeg download page

Verify installation:

  ffmpeg -version

🔹 uv — ultra-fast Python environment & dependency manager

Install guide: https://github.com/astral-sh/uv

---

🚀 Steps

1. Clone the repository and create a virtual environment using uv

# Clone the repo
git clone https://github.com/RudraNarayan94/Fourio.git
cd fourio

# Create virtual environment (using uv)
uv venv

# Install dependencies
uv sync

2. (Optional) Setup using Python venv + requirements.txt

  # Clone the repo
git clone https://github.com/RudraNarayan94/Fourio.git
cd fourio

# Create virtual environment (using venv)
python -m venv venv

# Activate it
source venv/bin/activate     # macOS/Linux
# On Windows:
# venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

---

🎵 Environment Setup

Create a .env file inside folder.

Use the structure defined in the sample file:
👉 See .env.example (link)

The .env file should include keys for:

• Spotify API access
• Database configuration
• Backend settings
• YouTube API key (optional)

You can generate Spotify credentials by creating an app at the
👉 Spotify Developer Dashboard:
https://developer.spotify.com/dashboard/

Once created, copy your:

SPOTIFY_CLIENT_ID=your-client-id
SPOTIFY_CLIENT_SECRET=your-client-secret

These credentials allow Fourio to access track metadata, album details, and playlist information.

---

🧠 Usage

Run CLI

uv run python cli.py --help

🎧 Commands

Command	Description
find <path_to_audio_file>	Analyze audio file in any format and find matching fingerprints
download <spotify_url>	Download and process a song/album/playlist from Spotify
save <path_or_dir> [--force/-f]	Fingerprint and save local songs
erase	Clear all stored songs and fingerprints from the database

🔌REST api Endpoints

Endpoint	Method	Description
/fourio/match	POST	Match audio fingerprint against database and return top 10 matches
/recordings/save	POST	Save base64-encoded audio recording as WAV file
/songs/total	GET	Get total number of indexed songs in database
/songs/download	POST	Download and process Spotify track/album/playlist

💡 Examples

📌Run Server

uv run python -m uvicorn app.main:app --reload

▶ Download a Spotify track

uv run python cli.py download https://open.spotify.com/track/4pqwGuGu34g8KtfN8LDGZm

🔎 Find a song match

uv run python cli.py find songs/Voila.mp3

💾 Save local songs

uv run python cli.py save ./local_songs/ --force

🧹 Erase all data

uv run python cli.py erase

📚 Resources

• SeekTune - Go implementation of Shazam(main resource)
• How does Shazam work - Coding Geek (main resource)
• Song recognition using audio fingerprinting
• How does Shazam work - Toptal
• Creating Shazam in Java

---

🧑‍💻 Author

Rudra Narayan Sahoo

• Connect with me on LinkedIn.
• Check out my other GitHub projects.

🚀 Future Roadmap

Fourio have the potential to gradually evolve into a full-stack, Shazam-style system with a modern UI and scalable backend. Feel free to contribute or suggest features!

🎧 Frontend (React)

• Modern UI for song matching & downloads
• Microphone recording & PCM extraction
• Client-side fingerprint generation
• WebSocket for real-time matching

⚙️ Backend (FastAPI)

• WEBSOCKETS Endpoints for song processing & matching
• Redis for backend service

🧠 Fingerprinting Engine

• Better DB Schema for fingerprints
• Tunable fingerprint density & thresholds

☁️ Deployment

• Docker setup
• Optional FFmpeg/GPU acceleration

---

📜 License

This project is licensed under the MIT License.