Welcome to ChordMini

Advanced machine learning models for beat detection, chord recognition, and lyrics fetching. Get started with our comprehensive API documentation and examples.

Get StartedAPI Reference

Getting Started

The ChordMini API provides powerful audio analysis capabilities with no authentication required. Start making requests immediately to analyze audio files and extract musical information.

Beat Detection

Identify beat positions and downbeats using advanced ML models

Chord Recognition

Recognize chord progressions with multiple model options

Lyrics Fetching

Retrieve synchronized lyrics from LRClib database

Model Info

Get details about available models and capabilities

Quick Start

Base URL

https://chordmini-backend-full-191567167632.us-central1.run.app

Authentication

No API key required

Authentication

The ChordMini API is currently open and does not require authentication. All endpoints are publicly accessible, making it easy to get started with audio analysis immediately.

No API Key Required

Start making requests immediately without any setup or registration process.

⚠️

Future Changes: Authentication may be required in future versions. Implement proper error handling for potential 401/403 responses.

CORS Support

Cross-Origin Resource Sharing (CORS) is enabled for all origins, allowing browser-based requests.

Access-Control-Allow-Origin: *

Content Types

Supports multiple content types for different use cases.

multipart/form-data
for file uploads
application/json
for data requests

Rate Limits

The ChordMini API implements production-grade rate limiting to ensure fair usage and system stability. Rate limits vary by endpoint based on computational requirements and are enforced using Redis-based storage.

Production-Grade Rate Limiting

Redis-based rate limiting with sliding window ensures fair usage and maintains service quality. Heavy processing endpoints have stricter limits to prevent resource exhaustion.

Method: IP Address-based limiting with Redis storage • Window: Sliding window algorithm

Rate Limits by Endpoint

EndpointMethodRate LimitReason
/GET30/minuteHealth checks, status monitoring
/api/model-infoGET20/minuteInformation endpoint, moderate usage
/api/detect-beatsPOST2/minuteHeavy processing, resource intensive
/api/recognize-chords*POST2/minuteHeavy processing, ML inference
/api/lrclib-lyricsPOST10/minuteSynchronized lyrics with timestamps
/api/genius-lyricsPOST10/minuteGenius.com lyrics fetching
* Includes Firebase-based endpoints for cached processing

Available Models

ChordMini provides multiple machine learning models for different audio analysis tasks. Each model is optimized for specific use cases and performance characteristics.

Beat Detection Models

Beat-Transformer

Default

Deep learning model for beat tracking with downbeat detection. Provides high accuracy for modern music genres.

Best for: Pop, Rock, Electronic music

Madmom

Classical beat tracking algorithm with neural network components. Reliable for complex rhythmic patterns.

Best for: Jazz, Classical, Complex rhythms

Chord Recognition Models

Chord-CNN-LSTM

Default

Convolutional and LSTM neural network for chord recognition with 301 chord labels. Excellent balance of accuracy and performance.

Labels: 301 chord types • Best for: General purpose chord recognition

API Endpoints

All endpoints are available at the base URL:
https://chordmini-backend-full-191567167632.us-central1.run.app
POST
/api/detect-beats

Analyzes audio file and returns beat timestamps, BPM, and time signature.

Parameters: file (audio file), model (optional: beat-transformer, madmom, auto)

POST
/api/recognize-chords

Analyzes audio file and returns chord progression with timestamps.

Parameters: file (audio file), model (optional: chord-cnn-lstm)

POST
/api/lrclib-lyrics

Retrieves synchronized lyrics with timestamps from LRClib database.

Parameters: artist (string), title (string), duration (number, optional)

GET
/api/model-info

Returns information about available models and their capabilities.

Parameters: None required

Usage Examples

Here are some practical examples of how to use the ChordMini API using Javascript and cURL.

JavaScript Example

const formData = new FormData(); formData.append('file', audioFile); formData.append('model', 'chord-cnn-lstm'); const response = await fetch( 'https://chordmini-backend-full-191567167632.us-central1.run.app/api/recognize-chords', { method: 'POST', body: formData } ); const result = await response.json(); console.log(result);

Beat Detection

Request

curl -X POST "https://chordmini-backend-full-191567167632.us-central1.run.app/api/detect-beats" \ -F "file=@your-audio-file.mp3" \ -F "model=beat-transformer"

Response

{ "success": true, "beats": [0.5, 1.0, 1.5, 2.0, 2.5], "total_beats": 5, "model": "beat-transformer", "processing_time": 2.3 }

Chord Recognition

Request

curl -X POST "https://chordmini-backend-full-191567167632.us-central1.run.app/api/recognize-chords" \ -F "file=@your-audio-file.mp3" \ -F "model=chord-cnn-lstm"

Response

{ "success": true, "chords": [ {"start": 0.0, "end": 2.0, "chord": "C", "confidence": 0.95}, {"start": 2.0, "end": 4.0, "chord": "Am", "confidence": 0.87}, {"start": 4.0, "end": 6.0, "chord": "F", "confidence": 0.92} ], "total_chords": 3, "model": "chord-cnn-lstm", "processing_time": 3.1 }

Error Response Examples

Rate Limit Exceeded (429)

{ "error": "Rate limit exceeded", "message": "Too many requests. Please wait before trying again.", "retry_after": null }

Invalid File Format (400)

{ "error": "Invalid file format", "message": "Supported formats: MP3, WAV, FLAC, M4A, OGG", "supported_formats": ["mp3", "wav", "flac", "m4a", "ogg"] }

Troubleshooting

Common Issues

Rate Limit Exceeded (429)

You've exceeded the rate limit for the endpoint. Wait for the time specified in the Retry-After header.

Solution: Implement exponential backoff and respect rate limit headers

File Format Not Supported

The API supports common audio formats: MP3, WAV, FLAC, M4A, OGG.

Solution: Convert your audio file to a supported format

Processing Timeout

Large audio files may take longer to process. The API has a 10-minute timeout.

Solution: Use shorter audio clips or compress your audio file

API Status

Monitor the real-time status of ChordMini API services and endpoints. Check service availability and performance metrics.

Backend Services

Core API services including beat detection, chord recognition, and lyrics fetching.

Beat DetectionOperational
Chord RecognitionOperational
Lyrics ServicesOperational

Infrastructure

Server infrastructure and deployment status on Google Cloud Run.

Google Cloud RunOnline
Rate LimitingActive
CORS SupportEnabled

Detailed Status Page

For real-time monitoring and detailed service metrics, visit our dedicated status page.

View Status Page