beatmatchr/README.md

beatmatchr backend

A lightweight FastAPI service that powers beatmatchr. This guide walks through the steps required to run the backend locally.

Prerequisites

• Python 3.10 or newer installed and available on your PATH.
• ffmpeg installed (macOS: brew install ffmpeg, Ubuntu/Debian: sudo apt install ffmpeg).
• Docker and Docker Compose (v2) for running Postgres and Redis.

1. Create and activate a virtual environment

python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

2. Install Python dependencies

With the virtual environment active, install the requirements:

pip install --upgrade pip
pip install -r requirements.txt

3. Start Postgres and Redis via Docker Compose

A docker-compose.yml file is provided at the repository root. Launch the services in the background:

docker compose up -d

This spins up:

• Postgres on port 5432 with database/user/password beatmatchr.
• Redis on port 6379 for task queue usage.

If you need to tear everything down (including volumes), run:

docker compose down -v

4. Configure environment variables

Export environment variables that the backend expects. The defaults line up with docker-compose.yml, so you can simply create a .env file (or export them in your shell):

export POSTGRES_USER=beatmatchr
export POSTGRES_PASSWORD=beatmatchr
export POSTGRES_DB=beatmatchr
export POSTGRES_HOST=localhost
export POSTGRES_PORT=5432
export REDIS_HOST=localhost
export REDIS_PORT=6379
export REDIS_DB=0
export CELERY_BROKER_URL=redis://localhost:6379/0
export CELERY_RESULT_BACKEND=redis://localhost:6379/0

Feel free to adjust these if you change the Docker Compose configuration.

5. Run database migrations / initialize tables

If you have Alembic migrations configured, apply them with:

alembic upgrade head

If migrations are not available yet, you can run your project-specific database bootstrap script (for example python -m backend.db init_db) to create tables manually. Ensure the DATABASE_URL environment variable is pointing at the Postgres instance from the Docker Compose stack.

6. Start the FastAPI application

Launch the app with uvicorn (hot reload optional):

uvicorn backend.main:app --reload

The API will be available at http://localhost:8000/.

7. Start the Celery/RQ worker

For Celery, point to the Celery app defined in your project (replace the module path if needed):

celery -A backend.worker.celery_app worker --loglevel=info

If you are using RQ instead of Celery, start a worker referencing the same Redis instance:

rq worker beatmatchr --url redis://localhost:6379/0

8. Example API usage

Replace PROJECT_ID with the UUID returned from the create project call.

Create a project

curl -X POST "http://localhost:8000/projects" \
  -H "Content-Type: application/json" \
  -d '{"name": "Demo Project", "description": "My first beatmatch"}'

Upload audio to a project

curl -X POST "http://localhost:8000/projects/PROJECT_ID/audio" \
  -F "file=@/path/to/local/file.wav"

Add a source clip by URL

curl -X POST "http://localhost:8000/projects/PROJECT_ID/sources" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/audio.mp3", "start": 0, "end": 30}'

Fetch lyrics for a track

curl "http://localhost:8000/projects/PROJECT_ID/lyrics"

With the services running and environment variables configured, you should be able to follow the steps above to interact with the beatmatchr backend locally.