### Start LRCLIB Quadlet Service

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Starts the LRCLIB systemd user service defined by the Quadlet configuration.

```bash
systemctl --user start lrclib.service
```

--------------------------------

### Configure LRCLIB as a systemd Service using Quadlet

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Example of a systemd Quadlet file to configure LRCLIB to run as a persistent service. It defines container settings, service behavior, and installation targets.

```systemd
# Create systemd Quadlet service file at ~/.config/containers/systemd/lrclib.container
# [Container]
# Image=lrclib-rs:latest
# PublishPort=3300:3300
# Volume=lrclib-data:/data
# ContainerName=lrclib-rs
# Environment=LRCLIB_LOG=info
# 
# [Service]
# Restart=always
# 
# [Install]
# WantedBy=multi-user.target default.target

# Reload and start systemd service
systemctl --user daemon-reload
systemctl --user start lrclib.service
systemctl --user status lrclib.service
```

--------------------------------

### Configure LRCLIB Quadlet Service

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Example Quadlet unit file content for running the LRCLIB container as a systemd service. This configuration handles auto-start and logging.

```ini
[Container]
Image=lrclib-rs:latest
PublishPort=3300:3300
Volume=lrclib-data:/data
ContainerName=lrclib-rs
Environment=LRCLIB_LOG=info

[Service]
Restart=always

[Install]
WantedBy=multi-user.target default.target
```

--------------------------------

### Get Lyrics by Metadata via REST API

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Retrieves lyrics by matching track, artist, album, and duration. It uses fuzzy matching and a ±2 second duration tolerance.

```bash
curl "http://localhost:3300/api/get?track_name=Bohemian%20Rhapsody&artist_name=Queen&album_name=A%20Night%20at%20the%20Opera&duration=354"
```

--------------------------------

### GET /api/get

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Retrieves lyrics for a track by matching track name, artist name, album name, and duration. Performs fuzzy matching with normalized text and supports duration tolerance of ±2 seconds.

```APIDOC
## GET /api/get

### Description
Retrieves lyrics for a track by matching track name, artist name, album name, and duration. The endpoint performs fuzzy matching with normalized text and supports duration tolerance of ±2 seconds for flexible matching.

### Method
GET

### Endpoint
`/api/get`

### Parameters
#### Query Parameters
- **track_name** (string) - Required - The name of the track.
- **artist_name** (string) - Required - The name of the artist.
- **album_name** (string) - Required - The name of the album.
- **duration** (integer) - Required - The duration of the track in seconds.

### Request Example
```bash
curl "http://localhost:3300/api/get?track_name=Bohemian%20Rhapsody&artist_name=Queen&album_name=A%20Night%20at%20the%20Opera&duration=354"
```

### Response
#### Success Response (200 OK)
- **id** (integer) - The unique identifier of the track.
- **name** (string) - The name of the track.
- **trackName** (string) - The name of the track.
- **artistName** (string) - The name of the artist.
- **albumName** (string) - The name of the album.
- **duration** (float) - The duration of the track in seconds.
- **instrumental** (boolean) - Indicates if the track is instrumental.
- **plainLyrics** (string) - The plain text lyrics of the song.
- **syncedLyrics** (string) - The time-synchronized LRC format lyrics.

#### Response Example (200 OK)
```json
{
  "id": 12345,
  "name": "Bohemian Rhapsody",
  "trackName": "Bohemian Rhapsody",
  "artistName": "Queen",
  "albumName": "A Night at the Opera",
  "duration": 354.0,
  "instrumental": false,
  "plainLyrics": "Is this the real life?\nIs this just fantasy?",
  "syncedLyrics": "[00:00.00] Is this the real life?\n[00:04.50] Is this just fantasy?"
}
```

#### Error Response (404 Not Found)
- **message** (string) - Description of the error.
- **name** (string) - The name of the error.
- **statusCode** (integer) - The HTTP status code.

#### Response Example (404 Not Found)
```json
{
  "message": "Failed to find specified track",
  "name": "TrackNotFound",
  "statusCode": 404
}
```
```

--------------------------------

### Get Lyrics by Track ID via REST API

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Fetches lyrics directly using a unique database identifier. This is the most efficient method for retrieving specific track data.

```bash
curl "http://localhost:3300/api/get/12345"
```

--------------------------------

### GET /api/get/{id}

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Retrieves lyrics for a specific track using its unique database ID. This is the most direct way to fetch lyrics when you already know the track identifier.

```APIDOC
## GET /api/get/{id}

### Description
Retrieves lyrics for a specific track using its unique database ID. This is the most direct way to fetch lyrics when you already know the track identifier.

### Method
GET

### Endpoint
`/api/get/{id}`

### Parameters
#### Path Parameters
- **id** (integer) - Required - The unique database ID of the track.

### Request Example
```bash
curl "http://localhost:3300/api/get/12345"
```

### Response
#### Success Response (200 OK)
- **id** (integer) - The unique identifier of the track.
- **name** (string) - The name of the track.
- **trackName** (string) - The name of the track.
- **artistName** (string) - The name of the artist.
- **albumName** (string) - The name of the album.
- **duration** (float) - The duration of the track in seconds.
- **instrumental** (boolean) - Indicates if the track is instrumental.
- **plainLyrics** (string) - The plain text lyrics of the song.
- **syncedLyrics** (string) - The time-synchronized LRC format lyrics.

#### Response Example (200 OK)
```json
{
  "id": 12345,
  "name": "Stairway to Heaven",
  "trackName": "Stairway to Heaven",
  "artistName": "Led Zeppelin",
  "albumName": "Led Zeppelin IV",
  "duration": 482.0,
  "instrumental": false,
  "plainLyrics": "There's a lady who's sure all that glitters is gold...",
  "syncedLyrics": "[00:00.00] There's a lady who's sure all that glitters is gold..."
}
```

#### Error Response (404 Not Found)
- **message** (string) - Description of the error.
- **name** (string) - The name of the error.
- **statusCode** (integer) - The HTTP status code.

#### Response Example (404 Not Found)
```json
{
  "message": "Failed to find specified track",
  "name": "TrackNotFound",
  "statusCode": 404
}
```
```

--------------------------------

### GET /api/search

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Searches for tracks matching a keyword query or specific metadata fields. Returns an array of matching tracks with their lyrics. Results are cached for performance with automatic refresh after 20 hours.

```APIDOC
## GET /api/search

### Description
Searches for tracks matching a keyword query or specific metadata fields. Returns an array of matching tracks with their lyrics. Results are cached for performance with automatic refresh after 20 hours.

### Method
GET

### Endpoint
`/api/search`

### Parameters
#### Query Parameters
- **q** (string) - Optional - A general keyword to search for.
- **track_name** (string) - Optional - The name of the track to search for.
- **artist_name** (string) - Optional - The name of the artist to search for.
- **album_name** (string) - Optional - The name of the album to search for.

### Request Example
```bash
# Search by general keyword
curl "http://localhost:3300/api/search?q=bohemian%20rhapsody"

# Search by specific fields
curl "http://localhost:3300/api/search?track_name=Hotel%20California&artist_name=Eagles"

# Search by album
curl "http://localhost:3300/api/search?album_name=Abbey%20Road"

# Combined search parameters
curl "http://localhost:3300/api/search?track_name=Yesterday&artist_name=Beatles&album_name=Help"
```

### Response
#### Success Response (200 OK)
- Returns an array of track objects matching the search criteria. Each object contains:
  - **id** (integer) - The unique identifier of the track.
  - **name** (string) - The name of the track.
  - **trackName** (string) - The name of the track.
  - **artistName** (string) - The name of the artist.
  - **albumName** (string) - The name of the album.
  - **duration** (float) - The duration of the track in seconds.
  - **instrumental** (boolean) - Indicates if the track is instrumental.
  - **plainLyrics** (string) - The plain text lyrics of the song.
  - **syncedLyrics** (string) - The time-synchronized LRC format lyrics.

#### Response Example (200 OK)
```json
[
  {
    "id": 67890,
    "name": "Bohemian Rhapsody",
    "trackName": "Bohemian Rhapsody",
    "artistName": "Queen",
    "albumName": "A Night at the Opera",
    "duration": 354.0,
    "instrumental": false,
    "plainLyrics": "Is this the real life?",
    "syncedLyrics": "[00:00.00] Is this the real life?"
  },
  {
    "id": 67891,
    "name": "Bohemian Rhapsody",
    "trackName": "Bohemian Rhapsody",
    "artistName": "Queen",
    "albumName": "Greatest Hits",
    "duration": 355.0,
    "instrumental": false,
    "plainLyrics": "Is this the real life?",
    "syncedLyrics": "[00:00.00] Is this the real life?"
  }
]
```
```

--------------------------------

### Build and Run LRCLIB Server with Cargo

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Instructions for building the LRCLIB server from source using Cargo and running it in development mode with specified logging and database.

```bash
# Build from source
car go build --release

# Run directly with Cargo
LRCLIB_LOG=info cargo run --release -- serve --database db.sqlite3
```

--------------------------------

### Build and Run LRCLIB Server with Docker

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Instructions for building a Docker image for the LRCLIB server and running it. This includes volume mounting, port mapping, environment variables, and naming the container.

```bash
# Build Docker image
docker build -t lrclib-rs:latest -f Dockerfile .

# Run with Docker
docker run --rm -d \
  -v lrclib-data:/data \
  -p 3300:3300 \
  -e LRCLIB_LOG=info \
  -e LRCLIB_MANAGE_TOKEN=your_secret_token \
  --name lrclib-rs \
  lrclib-rs:latest
```

--------------------------------

### Run LRCLIB Server with Podman

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Instructions for running the LRCLIB server using Podman. Similar to Docker, it covers volume mounting, port mapping, and environment variables.

```bash
# Run with Podman
podman run --rm -d \
  -v lrclib-data:/data \
  -p 3300:3300 \
  -e LRCLIB_LOG=info \
  --name lrclib-rs \
  lrclib-rs:latest
```

--------------------------------

### Run LRCLIB Server Locally (Rust)

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Runs the LRCLIB server in release mode with specified logging level and database file. The server will be accessible at http://0.0.0.0:3300.

```bash
LRCLIB_LOG=info cargo run --release -- serve --database db.sqlite3
```

--------------------------------

### Build LRCLIB Server (Rust)

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Builds the LRCLIB server project in release mode using Cargo. This command compiles the Rust code and optimizes it for production.

```bash
cargo build --release
```

--------------------------------

### Request Proof-of-Work Challenge

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Requests a challenge required for publishing or flagging lyrics. The difficulty scales dynamically to prevent spam.

```bash
curl -X POST "http://localhost:3300/api/request-challenge"
```

--------------------------------

### Build LRCLIB Docker Image

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Builds a Docker image for the LRCLIB application, tagging it as 'lrclib-rs:latest'. This command uses the Dockerfile in the project root.

```bash
podman build -t lrclib-rs:latest -f Dockerfile .
```

--------------------------------

### POST /api/manage/set-config

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Administrative endpoint to dynamically update server worker counts.

```APIDOC
## POST /api/manage/set-config

### Description
Updates the background worker count. Requires Bearer authentication with a manage token.

### Method
POST

### Endpoint
/api/manage/set-config

### Parameters
#### Request Body
- **workersCount** (number) - Required - Number of workers to set

### Request Example
{
  "workersCount": 4
}

### Response
#### Success Response (202)
- **None** (null) - Accepted

#### Response Example
{}
```

--------------------------------

### Publish Instrumental Track using curl

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Publishes an instrumental track to the LRCLIB API. Requires a valid publish token. The request body includes track details and a placeholder for synced lyrics indicating it's instrumental.

```bash
curl -X POST "http://localhost:3300/api/publish" \
  -H "Content-Type: application/json" \
  -H "X-Publish-Token: AbCdEfGhIjKlMnOpQrStUvWxYz123456:solved_nonce_value" \
  -d '{
    "trackName": "Instrumental Track",
    "artistName": "Artist Name",
    "albumName": "Album Name",
    "duration": 180.0,
    "syncedLyrics": "[au: instrumental]"
  }'
```

--------------------------------

### Access LRCLIB SQLite Database via Docker

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Runs a temporary container to interact with the LRCLIB SQLite database file located at /data/db.sqlite3 within the persistent volume.

```bash
podman run --rm -it -v lrclib-data:/data lrclib-rs:latest sqlite3 /data/db.sqlite3
```

--------------------------------

### Reload Systemd Daemon (User)

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Reloads the user's systemd daemon configuration to recognize new or updated unit files.

```bash
systemctl --user daemon-reload
```

--------------------------------

### POST /api/publish

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Publishes new lyrics to the database. Supports plain text, synchronized LRC format, or instrumental tracks.

```APIDOC
## POST /api/publish

### Description
Publishes lyrics for a specific track. Requires a valid publish token obtained via proof-of-work.

### Method
POST

### Endpoint
/api/publish

### Parameters
#### Request Body
- **trackName** (string) - Required - Name of the track
- **artistName** (string) - Required - Name of the artist
- **albumName** (string) - Required - Name of the album
- **duration** (number) - Required - Duration in seconds
- **plainLyrics** (string) - Optional - Plain text lyrics
- **syncedLyrics** (string) - Optional - LRC formatted lyrics

### Request Example
{
  "trackName": "My Song",
  "artistName": "My Artist",
  "albumName": "My Album",
  "duration": 240.5,
  "plainLyrics": "Verse one lyrics here"
}

### Response
#### Success Response (201)
- **None** (null) - Successfully created

#### Response Example
{}
```

--------------------------------

### POST /api/request-challenge

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Requests a proof-of-work challenge that must be solved before publishing or flagging lyrics. The challenge difficulty scales dynamically based on recent submission volume to prevent spam during high-traffic periods.

```APIDOC
## POST /api/request-challenge

### Description
Requests a proof-of-work challenge that must be solved before publishing or flagging lyrics. The challenge difficulty scales dynamically based on recent submission volume to prevent spam during high-traffic periods.

### Method
POST

### Endpoint
`/api/request-challenge`

### Parameters
No parameters required.

### Request Example
```bash
curl -X POST "http://localhost:3300/api/request-challenge"
```

### Response
#### Success Response (200 OK)
- **prefix** (string) - The prefix string for the proof-of-work challenge.
- **target** (string) - The target hash value for the proof-of-work challenge.

#### Response Example (200 OK)
```json
{
  "prefix": "AbCdEfGhIjKlMnOpQrStUvWxYz123456",
  "target": "000000FF00000000000000000000000000000000000000000000000000000000"
}
```

**Note:** To solve the challenge, find a nonce such that the SHA256 hash of `prefix + nonce` is less than the `target`. The resulting publish token is `prefix:nonce`.
```

--------------------------------

### Check LRCLIB Quadlet Service Status

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Checks the status of the LRCLIB systemd user service to verify if it is running correctly.

```bash
systemctl --user status lrclib.service
```

--------------------------------

### POST /api/publish

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Publishes new lyrics or updates existing lyrics for a track. Requires a valid publish token obtained by solving the proof-of-work challenge. Supports both plain lyrics and synchronized LRC format. Instrumental tracks are detected automatically via the `[au: instrumental]` tag.

```APIDOC
## POST /api/publish

### Description
Publishes new lyrics or updates existing lyrics for a track. Requires a valid publish token obtained by solving the proof-of-work challenge. Supports both plain lyrics and synchronized LRC format. Instrumental tracks are detected automatically via the `[au: instrumental]` tag.

### Method
POST

### Endpoint
`/api/publish`

### Parameters
#### Request Body
- **publishToken** (string) - Required - The token obtained by solving the proof-of-work challenge (format: `prefix:nonce`).
- **trackName** (string) - Required - The name of the track.
- **artistName** (string) - Required - The name of the artist.
- **albumName** (string) - Required - The name of the album.
- **duration** (float) - Required - The duration of the track in seconds.
- **plainLyrics** (string) - Optional - The plain text lyrics of the song.
- **syncedLyrics** (string) - Optional - The time-synchronized LRC format lyrics.
- **instrumental** (boolean) - Optional - Set to true if the track is instrumental. Can also be indicated by `[au: instrumental]` tag in lyrics.

### Request Example
```bash
# First, request a challenge and solve it
curl -X POST "http://localhost:3300/api/request-challenge"
# Solve the challenge to get nonce, then create token: "prefix:nonce"

# Then, publish lyrics
curl -X POST "http://localhost:3300/api/publish" \
  -H "Content-Type: application/json" \
  -d '{
    "publishToken": "AbCdEfGhIjKlMnOpQrStUvWxYz123456:nonce123",
    "trackName": "Bohemian Rhapsody",
    "artistName": "Queen",
    "albumName": "A Night at the Opera",
    "duration": 354.0,
    "plainLyrics": "Is this the real life?\nIs this just fantasy?",
    "syncedLyrics": "[00:00.00] Is this the real life?\n[00:04.50] Is this just fantasy?"
  }'
```

### Response
#### Success Response (200 OK)
- **message** (string) - Confirmation message indicating successful publication or update.
- **id** (integer) - The ID of the published or updated track.

#### Response Example (200 OK)
```json
{
  "message": "Lyrics published successfully",
  "id": 12345
}
```

#### Error Response (e.g., 400 Bad Request, 401 Unauthorized)
- **message** (string) - Description of the error.
- **name** (string) - The name of the error.
- **statusCode** (integer) - The HTTP status code.
```

--------------------------------

### Access SQLite Database within Docker

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Command to execute `sqlite3` within a running LRCLIB Docker container to directly access the SQLite database file.

```bash
# Access SQLite database directly
docker exec -it lrclib-rs sqlite3 /data/db.sqlite3
```

--------------------------------

### Restart LRCLIB Quadlet Service

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Restarts the LRCLIB systemd user service, typically used after updating the container image.

```bash
systemctl --user restart lrclib.service
```

--------------------------------

### POST /api/flag

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Reports incorrect or problematic lyrics for a track to the server administrators.

```APIDOC
## POST /api/flag

### Description
Flags a track for incorrect lyrics. Requires a valid publish token.

### Method
POST

### Endpoint
/api/flag

### Parameters
#### Request Body
- **trackId** (number) - Required - The ID of the track to flag
- **content** (string) - Optional - Description of the issue

### Request Example
{
  "trackId": 12345,
  "content": "Lyrics are for wrong song"
}

### Response
#### Success Response (201)
- **None** (null) - Successfully flagged

#### Response Example
{}
```

--------------------------------

### Publish Plain Lyrics using curl

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Publishes plain text lyrics for a track to the LRCLIB API. Requires a valid publish token. The request body includes track details and the plain lyrics.

```bash
curl -X POST "http://localhost:3300/api/publish" \
  -H "Content-Type: application/json" \
  -H "X-Publish-Token: AbCdEfGhIjKlMnOpQrStUvWxYz123456:solved_nonce_value" \
  -d '{
    "trackName": "My Song",
    "artistName": "My Artist",
    "albumName": "My Album",
    "duration": 240.5,
    "plainLyrics": "Verse one lyrics here\nChorus lyrics here\nVerse two lyrics here"
  }'
```

--------------------------------

### Run LRCLIB Docker Container

Source: https://github.com/tranxuanthang/lrclib/blob/main/README.md

Runs the LRCLIB Docker container in detached mode, mapping port 3300 and mounting a volume for data persistence. The container is named 'lrclib-rs'.

```bash
podman run --rm -it -d -v lrclib-data:/data -p 3300:3300 -e LRCLIB_LOG=info --name lrclib-rs lrclib-rs:latest
```

--------------------------------

### Publish Synchronized Lyrics (LRC) using curl

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Publishes synchronized lyrics in LRC format for a track to the LRCLIB API. Requires a valid publish token. The request body includes track details and the LRC formatted lyrics.

```bash
curl -X POST "http://localhost:3300/api/publish" \
  -H "Content-Type: application/json" \
  -H "X-Publish-Token: AbCdEfGhIjKlMnOpQrStUvWxYz123456:solved_nonce_value" \
  -d '{
    "trackName": "My Song",
    "artistName": "My Artist",
    "albumName": "My Album",
    "duration": 240.5,
    "syncedLyrics": "[00:00.00] Verse one lyrics here\n[00:15.50] Chorus lyrics here\n[00:45.00] Verse two lyrics here"
  }'
```

--------------------------------

### Set Management API Config using curl

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Administratively adjusts the worker count for background processing. Requires authentication via the LRCLIB_MANAGE_TOKEN environment variable.

```bash
curl -X POST "http://localhost:3300/api/manage/set-config" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_manage_token_here" \
  -d '{
    "workersCount": 4
  }'
```

--------------------------------

### Flag Lyrics using curl

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Reports incorrect or problematic lyrics for a specific track. Requires a valid publish token. Optionally, a content field can describe the issue.

```bash
# Flag lyrics with a reason
curl -X POST "http://localhost:3300/api/flag" \
  -H "Content-Type: application/json" \
  -H "X-Publish-Token: AbCdEfGhIjKlMnOpQrStUvWxYz123456:solved_nonce_value" \
  -d '{
    "trackId": 12345,
    "content": "Lyrics are for wrong song"
  }'

# Flag lyrics without reason
curl -X POST "http://localhost:3300/api/flag" \
  -H "Content-Type: application/json" \
  -H "X-Publish-Token: AbCdEfGhIjKlMnOpQrStUvWxYz123456:solved_nonce_value" \
  -d '{
    "trackId": 12345
  }'
```

--------------------------------

### Search Lyrics via REST API

Source: https://context7.com/tranxuanthang/lrclib/llms.txt

Searches for tracks using keywords or specific metadata fields. Returns an array of matching tracks with cached results.

```bash
curl "http://localhost:3300/api/search?q=bohemian%20rhapsody"
curl "http://localhost:3300/api/search?track_name=Hotel%20California&artist_name=Eagles"
curl "http://localhost:3300/api/search?album_name=Abbey%20Road"
curl "http://localhost:3300/api/search?track_name=Yesterday&artist_name=Beatles&album_name=Help"
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.