Tagr

A self-hosted music metadata editor with a modern, intuitive web UI.

Live Demo — login with demo / demo
_{Hosted on Fly.io with auto-stop to save costs. First load may take ~30s while the machine wakes up.
Demo is read-only: you can browse, filter, scan, view song edit history, and play songs, but metadata editing is disabled.}

Tagr lets you browse, edit, and manage audio file tags from any browser — desktop or mobile. Just point it at your music folders, and get a clean three-panel interface for organizing your library — no desktop apps, no CLI wizardry.

Features

Metadata Editing

• Edit 40+ metadata fields inline — title, artist, album, year, genre, composer, BPM, lyrics, and more
• Custom metadata — add, edit, and remove your own custom tags beyond the standard fields
• Album art management — view, replace, and upload cover images directly
• Star ratings (1–5) with a visual widget
• Support for track/disc numbering, sort fields, catalog numbers, barcodes, and extended tags
• Read-only display of audio properties (codec, bitrate, sample rate, channels, bits per sample)

Change History

• Full audit trail of every metadata change with old and new values
• Revert individual changes or bulk-select and undo multiple edits at once
• Searchable history with shift+click and ctrl+click multi-selection
• Per-song and per-folder history views

Music Player

• Built-in audio player with interactive waveform visualization (WaveSurfer.js)
• Play/pause, previous/next track navigation
• Click-to-seek on the waveform
• Auto-advance to next song
• Collapsible sidebar player with album art, title, and artist display
• Listen history — every play is recorded once you have heard half the track (or four minutes), and the Recently played view in the sidebar lists it back. Play counts and last played dates are kept per song.
• ListenBrainz scrobbling — optionally forward those listens to your ListenBrainz profile, including "playing now" while a track is running. See Scrobbling.

Library Browsing

• Three-panel layout — folder tree, song list, and detail editor side by side
• Folder tree with hierarchical navigation and real-time search
• Sorting on any column — title, artist, album, year, duration, bitrate, date added, and dozens more
• Advanced filtering — text, numeric ranges, date ranges, and boolean filters across all fields
• Customizable columns — show/hide any of 40+ columns to match your workflow
• Virtual scrolling and infinite pagination for large libraries

Users and Roles

• Multiple users — the admin account comes from AUTH_USER / AUTH_PASSWORD; every other user is created from the app itself, in Settings → Users
• Roles — a Tagger can browse, play, edit metadata and rescan the library; a Listener can only browse and play. The UI hides what a role cannot do, and the API enforces it on every request
• Create, rename, change the role of, or delete users at any time. Passwords are stored bcrypt-hashed
• Per-user data — listen history, play counts and the ListenBrainz connection all belong to the user who made them

File Support

Lossless formats are automatically detected and displayed with a badge.

Mobile Support

Tagr is fully responsive and works on phones and tablets. The mobile UI adapts to smaller screens with:

• Full-screen panels with swipe gestures to navigate between folders, song list, and detail editor
• Expanded music player with album art, waveform, and playback controls
• Touch-friendly editing — all edit actions are always visible (no hover required)

Additional

• Multi-user authentication — password-protected access with roles (admin, tagger, listener)
• Resizable panels — drag to resize the three-panel layout to your liking
• Dark theme by default
• Toast notifications for operation feedback
• URL-based state — bookmarkable views with folder, song, sort, and filter state preserved in the URL

Quick Start with Docker

1. Clone the repository

wget https://raw.githubusercontent.com/suitux/Tagr/main/docker-compose.yml

2. Generate a secret key

openssl rand -hex 32

Copy the output — you'll use it as AUTH_SECRET in the next step.

3. Configure docker-compose.yml

services:
  tagr:
    image: ghcr.io/suitux/tagr:latest
    container_name: tagr
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - PUID=1000
      - PGID=1000
      - NODE_ENV=production
      - DATABASE_URL=file:/data/tagr.db
      - AUTH_SECRET=paste-your-generated-secret-here
      - AUTH_USER=admin
      - AUTH_PASSWORD=your-password-here
      - AUTH_URL=https://your-domain.com
    volumes:
      - sqlite_data:/data
      # Mount your music folder into the container:
      - /path/to/your/music:/music

volumes:
  sqlite_data:

Multiple folders: If your music is spread across different host paths, mount them as subdirectories under /music. Tagr scans /music recursively, so all subdirectories are included automatically:

volumes:
  - /home/user/Music:/music/library
  - /mnt/nas/Music:/music/nas

Set MUSIC_FOLDERS only if you want to restrict scanning to specific subdirectories (e.g., scan /music/library but skip /music/podcasts).

4. Build and run

docker compose up -d

Published images on GHCR are multi-arch and include linux/amd64 and linux/arm64.

5. Open your browser

Navigate to http://localhost:3000, log in with your credentials, and hit the scan button to index your library.

Manual Installation

Requirements: Node.js 22+.

git clone https://github.com/suitux/Tagr.git
cd tagr
pnpm install

Create a .env file in the project root:

DATABASE_URL=file:./data/tagr.db
AUTH_SECRET="c5398a60cfd61607192d74ae8db237aaeaa07a98cd8ecdb8776c86eb87376ba3"

AUTH_USER="admin"
AUTH_PASSWORD="admin"

# Music folders (comma-separated paths)
# Example: /Users/youruser/Music,/Volumes/External/Music
MUSIC_FOLDERS="/Users/youruser/Music,/Volumes/External/Music"

Then start:

pnpm build && pnpm start # Production
# or
pnpm dev                 # Development mode

Environment Variables

Scrobbling

Tagr can send what you play to ListenBrainz. No environment variable is involved — each user connects their own account:

1. Copy your user token from https://listenbrainz.org/settings/.
2. Open the menu next to the Tagr logo, choose Settings → Third party integrations, paste the token and hit Verify and save. Tagr checks the token against the service before storing it.
3. Leave API root empty unless you run your own ListenBrainz-compatible server.

What gets sent:

• A playing_now update when a track starts.
• A listen once you have actually played half the track or four minutes, whichever comes first — the rule ListenBrainz itself defines. Tracks shorter than 30 seconds and tracks you skip early are never submitted.
• Title, artist, album, track number, duration and any MusicBrainz IDs stored in the file's tags.

Tokens are encrypted with a key derived from AUTH_SECRET before they touch the database and are never sent back to the browser. Changing AUTH_SECRET invalidates stored tokens, so they have to be entered again.

If ListenBrainz is unreachable, listens are kept in a queue in the database and retried with an increasing delay the next time you play something. The Settings dialog shows how many are still waiting. Listen history and play counts inside Tagr are recorded regardless of whether scrobbling is configured.

Docker Volumes

Architecture

Browser (React Query) --> Next.js API Routes --> Prisma --> SQLite
                                                   |
                                              audiotagr --> audio files on disk

audiotagr

Every tag Tagr reads from or writes to your files goes through audiotagr (npm) — a standalone library extracted from this project and maintained in its own repo.

It is what actually talks to the audio files: scanning your folders, reading tags and audio properties, and writing your edits back to disk. It handles the per-format differences behind a single API — ID3v2 frames in MP3, Vorbis comments in FLAC and Ogg, iTunes atoms in M4A, ASF descriptors in WMA, APEv2 items — including the quirks that quietly corrupt tags otherwise, such as Style being folded into Genre or BPM landing in a field no reader looks at.

It is published under LGPL-3.0-only, so you can use it in your own projects whatever their license.

License

AGPL-3.0-only