SimpMusic Lyrics

A robust and scalable RESTful API service for managing song lyrics, translations records. Built with Kotlin, Spring Boot, MongoDB database and Meilisearch for searching, featuring advanced duplicate detection and clean architecture patterns.

SimpMusic Lyrics is focusing on YouTube Music, providing data from videoId of the track. The database is populated by the community, SimpMusic app users, and through automated crawling of other web services.

The app is in alpha phase, the APIs will be changed

Main endpoint: HTTPS only

https://api-lyrics.simpmusic.org/v1

Web client:

• https://lyrics.simpmusic.org/

Features

Core Functionality

• Lyrics Management: Create, read, search, and manage song lyrics
• Super Fast Search: Powered by Meilisearch for quick full-text search
• Multi-language Support: Handle translated lyrics in multiple languages
• Advanced Search: Search by song title, artist name, or full-text content
• Duplicate Detection: SHA256-based content deduplication
• Real-time Processing: Asynchronous operations with Kotlin Coroutines
• Standardized API Responses: Consistent response format with type-safe handling of success, error, and processing states

Installation

1. Clone the Repository

git clone https://github.com/your-username/lyrics-api.git
cd lyrics-api

2. Set up Sentry (Optional)

• If you want to use Sentry for error tracking, create a Sentry account and get your DSN.

3. Host your own Meilisearch or use Cloud

• Note your Meilisearch URL and Master Key
• Using Meilisearch for super fast search capabilities

4. Set up MongoDB connection

• Note your MongoDB connection string and database name

5. Configure Environment

Create .env following the .env.example

6. Build the Application

# Clean and build
./gradlew clean build

# Run tests
./gradlew test

# Generate JAR
./gradlew bootJar

7. Run the Application

# Development mode
./gradlew bootRun

# Production mode
java -jar build/libs/lyrics-<version>.jar

Database Setup

The application automatically creates required collections:

• lyrics - Main lyrics collection
• translated_lyrics - Translated lyrics collection

API Documentation

Base URL

http://localhost:8080/v1

SwaggerUI

http://localhost:8080/swagger-ui/index.html

Endpoints Overview

Lyrics Management

# All endpoints now return ApiResult<T> wrapper with standardized response format

GET    /v1/{videoId}           # Get lyrics by video ID
GET    /v1/{videoId}?limit=10&offset=0 # Get paginated lyrics by video ID
GET    /v1/search/title?title= # Search by song title
GET    /v1/search/title?title=&limit=10&offset=0 # Paginated search by song title
GET    /v1/search?q=           # Full-text search
GET    /v1/search?q=&limit=10&offset=0 # Paginated full-text search
POST   /v1                     # Create new lyrics

Translated Lyrics

GET    /v1/translated/{videoId}    # Get translations
GET    /v1/translated/{videoId}?limit=10&offset=0 # Get paginated translations
GET    /v1/translated/{videoId}/{language} # Get specific translation
POST   /v1/translated              # Create translation

Voting

POST   /v1/vote                    # Vote for lyrics -> ApiResult<LyricResponseDTO>
POST   /v1/translated/vote         # Vote for translated lyrics -> ApiResult<TranslatedLyricResponseDTO>

API Response Format

All API endpoints now return responses with a standardized structure using ApiResult<T> wrapper:

Success Response

{
  "data": [
    ...
  ],
  "success": true
}

Error Response

{
  "error": {
    "error": true,
    "code": 404,
    "reason": "Lyrics not found for videoId: abc123"
  },
  "success": false
}

Processing Response

{
  "processing": {
    "code": 102,
    "message": "Processing request to get lyrics for videoId: abc123"
  },
  "success": false
}

This standardized format makes it easier to handle API responses consistently across clients. The success field provides a quick way to determine the response type.

Security Features

Rate Limiting

The API is protected with rate limiting to prevent abuse:

• 15 requests per minute per IP address
• Applies to all API endpoints
• When limit is exceeded, returns HTTP 429 (Too Many Requests)

HMAC Authentication

All non-GET requests (POST, PUT, DELETE, PATCH) require HMAC authentication:

1. Generate a timestamp (current time in milliseconds)
2. Create data string: timestamp + request_uri
3. Generate HMAC using the shared secret key, checkout generateHmac function in HmacService.kt for full algorithm.
4. Add headers to your request:
   • X-Timestamp: Your timestamp
   • X-HMAC: Your generated HMAC token
5. Your HMAC token is available in 5 minutes

Example using curl:

# Headers required
X-Timestamp: 1630000000000
X-HMAC: base64EncodedHmacToken

# Example command
curl -X POST "http://localhost:8080/v1" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: 1630000000000" \
  -H "X-HMAC: base64EncodedHmacToken" \
  -d '{"videoId":"dQw4w9WgXcQ", ...}'

Roadmap

• Basic CRUD operations for lyrics
• Security for non-GET requests
• Rate limiting
• Paginated search
• Standardized API response format
• Input data
• Public server
• Frontend integration
• Automated remove negative votes lyrics

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support & Donations

Special thanks to all supporter ❤️

   
 

MOMO or Vietnamese banking

SimpMusic is sponsored by:

Check out the Vercel open-source program:

• https://vercel.com/open-source-program

Get free $200 credit over 60 days on DigitalOcean: GET NOW

Crowdin and Sentry both have a free enterprise plan for Open-source projects. Follow the URLs:

• Open Source License Request Form | Crowdin
• Sentry for Open Source | Sentry

This project is a part of SimpMusic.org Open-source project by me maxrave-dev