Skip to main content

Codetta

Your music library, looked after. On your own server.
Fix tags, match albums on MusicBrainz, organize your files and bring in new music,
from any browser, including your phone. FLAC, MP3, M4A, OGG, WAV, AIFF, WMA and more.

Status: alpha Version 0.8.1 License: AGPL-3.0 Python 3.14 Tests Docker image on ghcr.io Works great with Navidrome

A tour of Codetta: editing an album's tags, searching the library by tag, looking up an artist on MusicBrainz, a one-tap Library health fix, the player with synced lyrics, and the account panel

Quick start · Features · Compare · Docs · Roadmap


If you run your own music server, you know the drill: a SoundCloud download with no tags, an album where every track spells the artist differently, a folder of loose files that shows up as Unknown Album. I created this tool for home server users like myself who are looking for more granular control over their library. Honestly, it's my hobby project that I thought could be useful to others.

Codetta lives on your server, next to your music. Open it on your laptop or your phone, pick a track or a whole album, fix what's wrong and hit Save. Match albums on MusicBrainz for official tags and cover art, rename and organize files into tidy folders, and let new music from your downloads folder be matched and filed for you. Your files are updated safely, anything Codetta does can be undone, and Navidrome and other music apps pick up the changes on their next scan.

Codetta is alpha software. It's careful with your files, but it's young. Keep a backup of your library, as you would with any tool that edits files.

Codetta is AI-Assisted. I understand the controversy surrounding AI usage in software. I prioritize transparency, hence the disclaimer for those who do not favor AI. This project is assisted by Claude Opus 5.5.

Quick start

On a server with Docker:

mkdir codetta && cd codetta
curl -fsSLO https://raw.githubusercontent.com/gavndev/codetta/main/docker-compose.yml
cat > docker-compose.override.yml <<'EOF'
services:
  codetta:
    environment:
      PUID: "1000"   # the user that owns your music (ls -ln /path/to/music)
      PGID: "1000"
    volumes:
      - /path/to/your/music:/music
      # Optional: where new music lands (downloads, rips), for the inbox
      # - /path/to/downloads:/inbox
EOF
docker compose up -d

Open http://<your-server>:8111 and create your account. A few short setup steps follow (online features, folder naming, the inbox, optional integrations). Each can be skipped and changed later.

Runs on Intel/AMD and ARM, from a Raspberry Pi 4 up: about a 100 MB download and 70 MB of memory (about 130 MB at 100,000 tracks), and no disk activity when idle. The install guide walks through every step, including updates.

No server? Run it on your own computer instead: pipx install codetta, then codetta (details).

What Codetta does

Fix a whole album in one go

Select tracks and change only what you need, or fill in one track and Save to folder to apply exactly those changes to the whole album, cover art included. You see every change before anything is written.

Filling in album details and cover art on one track, then saving them to all five tracks in the folder

Search your entire library by tag

Type in the search box and press Enter. Results work like a folder, so you can edit them all at once.

Type Finds
genre: rap, hip-hop Rap or Hip-Hop (but not "Trap")
artist: drake year: 2024 both at once
night drive words in the title, artist, album or file name

Searching the library for genre synthwave or jazz, then for artist kosei, which finds Kōsei Mori

Match on MusicBrainz

Official titles, credits, dates, labels, catalog numbers, MusicBrainz IDs and cover art for any album folder. Compare editions, then review every change per file before anything is written. Untagged files are recognised by sound.

Organize your library

Organize renames and moves files from their tags with a pattern like {albumartist}/{album} ({year})/{disctrack} {title}. You see every move first, nothing is ever overwritten, and the whole thing can be undone.

Keep it healthy

A card on the Library page lists what's worth fixing across the whole library: albums your player shows split in two, missing tracks, missing or tiny covers, missing tags, duplicates, MP3s inside a FLAC album. Obvious fixes are one tap (with a preview and undo); switch off any check you don't care about.

Bring in new music

Point Codetta at your downloads folder. It groups what's there into albums, waits until downloads finish, finds each on MusicBrainz (by its tags, or by sound with AcoustID) and files it with your folder pattern. Confident matches can file themselves; the rest wait for a quick review. Albums you already have are never overwritten.

Listen and stay in the loop

  • Quick listen: a play button on every track and a now-playing pill, so you can check what a file is before you tag it.
  • Notifications tell you when the inbox has something for you, an album filed itself, or an update is out.

Safe by design

  • Verified writes. Every save goes to a temporary copy that's checked before it replaces the original, so a crash or full disk can't damage a file.
  • Nothing moves without your say-so. Organize and the inbox show every move first and never overwrite a file; an album you replace is kept aside.
  • Undo anything from the activity log (tags, covers, moves, a whole album), and it's kept across restarts.
  • Private by design. No tracking, analytics or telemetry of any kind, no ads, and the page never loads anything from another site. Codetta is offline unless you opt in: MusicBrainz, AcoustID, lyrics, the update check and integrations are connections, each off until you turn it on, each saying exactly what it sends. See PRIVACY.md.
  • Private by default. Built-in sign-in, a strict security setup, and it runs as your user. See SECURITY.md.

Made for your phone

Album view on a phone   Track editor on a phone

Optional: Soulseek through slskd

Already run slskd? Connect it, and Codetta can look for an album for you: type !slskd in the search bar, or press Find in slskd on an album to look for a better copy. The best copy is downloaded into your inbox, and you decide whether it joins your library. It's off unless you set it up. More about it →

Also: lyrics (plain or synced, with Find lyrics from LRCLIB), sort and classical fields, an Advanced mode with the raw tags, Tag Presets for turning loose downloads into proper releases, smart suggestions from the rest of the album, copy & paste tags, every field Navidrome shows (credits, mood, label, release type, multiple artists), multi-disc albums, any language and script, light and dark themes. See every feature →

How Codetta compares

Codetta MusicBrainz Picard beets Metadata Remote
What it is Web app on your server (or your own computer) Desktop app Command-line library manager Web app on your server
Use it from your phone ✅ Designed for it ❌ ❌ ➖ Responsive layout
Runs in Docker ✅ Official image ➖ Community images ➖ Community images ✅ Official image
Built-in sign-in ✅ – (local app) – (local app) ❌ Use a reverse proxy
Edit tags by hand, one track or many ✅ ✅ ➖ beet modify ✅
Album art ✅ + Cover Art Archive ✅ + Cover Art Archive ✅ via plugin ✅
Match releases on MusicBrainz ✅ Opt-in, incl. audio fingerprints, reviewed per file ✅ Incl. audio fingerprints ✅ Automatic on import ➖ Suggestions
Import new music (match and file a downloads folder) ✅ Inbox, reviewed or automatic ❌ ✅ beet import ❌
Rename / organize files ✅ Pattern, preview, undo ✅ ✅ ✅ Rename
Undo ✅ Kept across restarts ❌ ❌ ✅ Until restart
Search the whole library by tag ✅ ➖ ✅ Query language ➖ Filtering
Play tracks ✅ In the browser ➖ Basic player ➖ Via external player ✅ In the browser
Plugins ✅ Actions on tracks (plugin API, off until enabled), plus opt-in connections ✅ ✅ ❌
Formats 15 file types 20+ Most common formats 9
License AGPL-3.0 GPL-2.0 MIT AGPL-3.0

✅ yes · ➖ partly or with extra setup · ❌ no

Codetta takes your music from scattered files to a well-organized library in one place. It covers the whole trip (import, match, fix, and file) right from your browser, and you can see and approve each step along the way. No terminal or desktop install is needed, and nothing changes without you seeing it first.

Compared in November 2026 from each project's documentation. Spotted something out of date? Please open an issue.

Documentation

Roadmap

  • Batch matching: match many albums at once in the background, review the uncertain ones later.
  • Edition preferences: your preferred country, format (digital or CD) and release type when matching.
  • Refresh from MusicBrainz: pick up corrections made since an album was matched.
  • ReplayGain: volume levelling, opt-in.

What's new

0.6.x: a security sweep and a faster app (compressed pages, quicker folders), download progress in the inbox, a roomier top bar on phones, and an optional slskd integration. 0.5.0: the import inbox, Organize (rename and move from a pattern), quick listen with a now-playing pill, multi-disc albums, setup steps, What's new and notifications. 0.4.0: offline unless you opt in; Match on MusicBrainz and identify by sound with AcoustID. All changes are in the changelog.

License

Codetta is free software under the GNU AGPL v3.0 (or later): use it, study it, change it and share it. If you run a modified version for others, you must share your changes under the same license.

Built with mutagen, FastAPI and the Schibsted Grotesk typeface. Tag mappings follow MusicBrainz Picard. The optional Soulseek integration talks to slskd over its API. The artists and albums in the screenshots are made up.

Metadata

Release files for codetta 0.8.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codetta 0.8.1
File Size Uploaded Provenance Actions
codetta-0.8.1.tar.gz 491.3 kB With provenance Details for codetta-0.8.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codetta 0.8.1
File Interpreter ABI Platform Actions
codetta-0.8.1-py3-none-any.whl Python 3 none any Details for codetta-0.8.1-py3-none-any.whl

Total release size: 927.6 kB

Release files / codetta-0.8.1.tar.gz

Download URL codetta-0.8.1.tar.gz
Size 491.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7a14e483899091f22de36a178ecbaea4045fd481c36a61a84b12bf746425b0ba
BLAKE2b-256 checksum
How to use checksums
9f5fca84f1f73dff7f0c72f06b8234b095099dc0db72ac362f6e684743d6045d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / codetta-0.8.1-py3-none-any.whl

Download URL codetta-0.8.1-py3-none-any.whl
Size 436.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fed0df81dd28c93b66f2e2bdd755cb3a145e4475556369b0a2cafdc9b622f439
BLAKE2b-256 checksum
How to use checksums
523df9e0fcd26d1acf5ea17f69a4bc44e2973162ce7a5c6614c85733c1e2f111
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for codetta 0.8.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for codetta-0.8.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.8.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page