furumi-ng/PLAYER-API.md

# Furumi Web Player API

Base URL: `http://<host>:<port>/api`

All endpoints require authentication when `--token` is set (via cookie `furumi_token=<token>` or query param `?token=<token>`).

All entity references use **slugs** — 12-character hex identifiers (not sequential IDs).

## Artists

### `GET /api/artists`

List all artists that have at least one track.

**Response:**
```json
[
  {
    "slug": "a1b2c3d4e5f6",
    "name": "Pink Floyd",
    "album_count": 5,
    "track_count": 42
  }
]
```

Sorted alphabetically by name.

### `GET /api/artists/:slug`

Get artist details.

**Response:**
```json
{
  "slug": "a1b2c3d4e5f6",
  "name": "Pink Floyd"
}
```

**Errors:** `404` if not found.

### `GET /api/artists/:slug/albums`

List all albums by an artist.

**Response:**
```json
[
  {
    "slug": "b2c3d4e5f6a7",
    "name": "Wish You Were Here",
    "year": 1975,
    "track_count": 5,
    "has_cover": true
  }
]
```

Sorted by year (nulls last), then name.

### `GET /api/artists/:slug/tracks`

List all tracks by an artist across all albums.

**Response:** same as album tracks (see below).

Sorted by album year, album name, track number, title.

## Albums

### `GET /api/albums/:slug`

List all tracks in an album.

**Response:**
```json
[
  {
    "slug": "c3d4e5f6a7b8",
    "title": "Have a Cigar",
    "track_number": 3,
    "duration_secs": 312.5,
    "artist_name": "Pink Floyd",
    "album_name": "Wish You Were Here",
    "album_slug": "b2c3d4e5f6a7",
    "genre": "Progressive Rock"
  }
]
```

Sorted by track number (nulls last), then title. Fields `album_name`, `album_slug` may be `null` for tracks without an album.

### `GET /api/albums/:slug/cover`

Serve the album cover image from the `album_images` table.

**Response:** Binary image data with appropriate `Content-Type` (`image/jpeg`, `image/png`, etc.) and `Cache-Control: public, max-age=86400`.

**Errors:** `404` if no cover exists.

## Tracks

### `GET /api/tracks/:slug`

Get full track details.

**Response:**
```json
{
  "slug": "c3d4e5f6a7b8",
  "title": "Have a Cigar",
  "track_number": 3,
  "duration_secs": 312.5,
  "genre": "Progressive Rock",
  "storage_path": "/music/storage/Pink Floyd/Wish You Were Here/03 - Have a Cigar.flac",
  "artist_name": "Pink Floyd",
  "artist_slug": "a1b2c3d4e5f6",
  "album_name": "Wish You Were Here",
  "album_slug": "b2c3d4e5f6a7",
  "album_year": 1975
}
```

**Errors:** `404` if not found.

### `GET /api/tracks/:slug/cover`

Serve cover art for a specific track. Resolution order:

1. Album cover from `album_images` table (if the track belongs to an album with a cover)
2. Embedded cover art extracted from the audio file metadata (ID3/Vorbis/etc. via Symphonia)
3. `404` if no cover art is available

**Response:** Binary image data with `Content-Type` and `Cache-Control: public, max-age=86400`.

**Errors:** `404` if no cover art found.

## Streaming

### `GET /api/stream/:slug`

Stream the audio file for a track.

Supports HTTP **Range requests** for seeking:
- Full response: `200 OK` with `Content-Length` and `Accept-Ranges: bytes`
- Partial response: `206 Partial Content` with `Content-Range`
- Invalid range: `416 Range Not Satisfiable`

`Content-Type` is determined by the file extension (e.g. `audio/flac`, `audio/mpeg`).

**Errors:** `404` if track or file not found.

## Search

### `GET /api/search?q=<query>&limit=<n>`

Search across artists, albums, and tracks by name (case-insensitive substring match).

| Parameter | Required | Default | Description |
|-----------|----------|---------|-------------|
| `q`       | yes      | —       | Search query |
| `limit`   | no       | 20      | Max results  |

**Response:**
```json
[
  {
    "result_type": "artist",
    "slug": "a1b2c3d4e5f6",
    "name": "Pink Floyd",
    "detail": null
  },
  {
    "result_type": "album",
    "slug": "b2c3d4e5f6a7",
    "name": "Wish You Were Here",
    "detail": "Pink Floyd"
  },
  {
    "result_type": "track",
    "slug": "c3d4e5f6a7b8",
    "name": "Have a Cigar",
    "detail": "Pink Floyd"
  }
]
```

`detail` contains the artist name for albums and tracks, `null` for artists.

Sorted by result type (artist → album → track), then by name.

## Authentication

When `--token` / `FURUMI_PLAYER_TOKEN` is set:

- **Cookie:** `furumi_token=<token>` — set after login
- **Query parameter:** `?token=<token>` — redirects to player and sets cookie

When token is empty, authentication is disabled and all endpoints are public.

Unauthenticated requests receive `401 Unauthorized` with a login form.

## Error format

All errors return JSON:

```json
{
  "error": "description of the error"
}
```

With appropriate HTTP status code (`400`, `404`, `500`, etc.).