# Music library: automatic discovery and organization

SolMusic automatically reads existing band profiles and generated tracks. No manual registration is required. The interface refreshes every 10 seconds while the tab is visible.

## Bands and artists

Band profiles are read from:

```text
/home/frog/music/catalogo-bandas/<band-id>/banda.json
```

New bands appear under Artists even before they have audio. The profile supplies the artist name and genre. Tracks in `musicas/<band-id>/` inherit that identity. A matching JSON file next to the audio supplies the track title.

## Audio folders

The library service on port 7861 recursively scans these locations:

| Displayed source | Folder | Initial review status |
| --- | --- | --- |
| Approved | `/home/frog/music/aprovados` | Approved |
| ACE-Step | `/home/frog/music/ACE-Step-1.5/gradio_outputs` | Unrated |
| Tests | `/home/frog/music/musicas` | Unrated |

Supported formats: `.wav`, `.mp3`, `.flac`, `.ogg`, `.opus`, `.m4a`, `.aac`, including uppercase extensions. Empty files, hidden files/folders, and symbolic links outside the library roots are excluded. Rejected tracks are hidden in SolMusic.

The band generator already saves completed tracks in:

```text
/home/frog/music/musicas/<band-id>/
  Artist Name - Track Title.mp3
  Artist Name - Track Title.json
```

New tracks appear automatically after the generator finishes saving them. There is no need to copy files or register tracks. For other generation workflows, save outputs inside one of the three scanned folders.

## Metadata and optional corrections

For standalone audio, a JSON file with the same base name can supply artist, genre, title, description, lyrics, and language:

```json
{
  "title": "Evening Light",
  "artist": "Example Band",
  "genre": "Jazz",
  "caption": "Instrumental jazz with piano and double bass",
  "lyrics": "",
  "vocal_language": "en"
}
```

ID3 tags are not currently read. Outside the band ID convention, folder names alone do not define artist, album, or genre. Without a title in the JSON file, the audio filename is used.

Use the track's `⋯` button for optional artist/genre corrections. Overrides are stored in PostgreSQL and shared across browsers. Existing `SolMusic/data/metadata.json` is imported once and preserved as a backup. Back up the PostgreSQL database with your library. Track IDs depend on absolute audio paths, so moving or renaming audio requires entering overrides again.

Duration is detected using `ffprobe` when available. The library caches description/lyrics metadata; changing only a sidecar JSON may require restarting the library service. SolMusic reads artist, genre, and title again on each refresh.

## Local network

Open `http://192.168.100.35:7870` on a device connected to the same network. This address may change if your router assigns a different IP. The server listens on all network interfaces.

## Hosting online

The browser uses API paths on the same domain as the app. It never needs to access the listener's own localhost. The hosted SolMusic server must reach the library and ACE-Step over a private network or tunnel.

| Environment variable | Default | Purpose |
| --- | --- | --- |
| `LIBRARY_HOST` | `127.0.0.1` | Library server hostname/IP |
| `LIBRARY_PORT` | `7861` | Library server port |
| `ACE_HOST` | `127.0.0.1` | ACE-Step server hostname/IP |
| `ACE_PORT` | `7860` | ACE-Step server port |
| `PORT` | `7870` | SolMusic listening port |
| `MUSIC_ROOT` | `/home/frog/music` | Local or mounted catalog and audio root |

Example:

```bash
LIBRARY_HOST=10.0.0.20 ACE_HOST=10.0.0.21 PORT=7870 ./start.sh
```

For automatic organization on another machine, mount or synchronize the band catalog and audio sidecars under `MUSIC_ROOT`. The library API remains responsible for listing and streaming audio. Its configured roots must point to the same audio files, since track IDs depend on their absolute paths.

For public access, configure HTTPS and access control at the reverse proxy. Generation and metadata editing do not have built-in authentication. This project has not been published to the internet.

See docs/backend.md for PostgreSQL setup, anonymous profiles, public like totals, personal favorites, backups, and capacity limits. Advanced generation and reference audio are explained in docs/studio.md.