where media lives

freqhole reads your music + video collection. it never moves, renames, or deletes files you ask it to scan. here’s where data lives depending on how you’re running freqhole.

---

the server (desktop app or CLI)

the server holds two things:

• your media files — wherever you already have them. freqhole scans directories you point it at. it reads files to extract metadata, artwork, and posters, then leaves them alone.
• a metadata database — a single SQLite file (by default data/grimoire.db) that stores music, video, artwork, posters, playlists, user accounts, and playback history. this is everything freqhole knows about your library.

freqhole does not copy, move, or rename scanned media files. if you delete a file from disk, freqhole will show it as missing — it won’t clean it up on your behalf unless you explicitly run a maintenance command.

where the database lives

how you’re running	default location
desktop app (macOS)	~/Library/Application Support/net.freqhole.charnel/data/grimoire.db
desktop app (Linux)	~/.local/share/freqhole/data/grimoire.db
desktop app (Windows)	%APPDATA%\net.freqhole.charnel\data\grimoire.db
CLI	./data/grimoire.db (relative to config file, configurable)

the data_dir setting in freqhole-config.toml controls this:

data_dir = "/home/user/freqhole-data"

artwork + posters

cover art extracted from music, art fetched from metadata providers, and video posters are stored as blobs managed by freqhole. thumbnails at multiple sizes are generated and stored alongside them.

---

uploaded files

files uploaded via the web UI are saved to a date-based directory under server.fetch_music.output_dir (or data/fetch/ if that config key isn’t set):

{output_dir}/{YYYY}/{MM}/{blob_id}.{ext}
# e.g. /path/to/fetch/2026/03/a1b2c3d4.mp3

the filename is the internal blob ID — the original filename is stored in the database.

yt-dlp fetched files

when fetching music by URL, each job gets its own subdirectory so partial downloads don’t collide. the filenames come from the yt-dlp --output template in your config (default: uploader-title-[id].mp3):

{output_dir}/{job_id}/Artist-Title-[youtube-id].mp3

output_dir must be an absolute path in freqhole-config.toml:

[server.fetch_music]
output_dir = "/absolute/path/to/fetch"

music synced from remotes

when you save music from a remote server (P2P or HTTP), it’s organized into artist/album folders under server.fetch_music.output_dir (or data/synced/ if not set):

{output_dir}/{artist}/{album}/{track}-{title}.{ext}
# e.g. data/synced/Mindless Self Indulgence/Frankenstein Girls Will Seem Strangely Sexy/01-Backmask.mp3

# multi-disc albums include the disc number:
# data/synced/Pink Floyd/The Wall/01-01-In the Flesh.mp3

special characters in artist, album, and title are stripped from directory and filenames. if a file already exists at that path, a numeric suffix is appended (-1, -2, etc.) — existing files are never overwritten.

---

the web app

the web app stores everything locally in your browser. nothing is written to your file system.

library metadata

when you connect to a server, the web app syncs music + video library indexes to IndexedDB — a structured database built into every modern browser. this is what lets you browse your library offline.

media files

saved music + video is cached using the Origin Private File System (OPFS) — a private, sandboxed storage area that browsers provide to web apps. OPFS is not accessible to other sites or visible in your regular file manager.

cached media lets you keep playing when you’re offline or have a slow connection. you can control how much is cached and clear it at any time from the app’s settings.

artwork + posters

album art, artist images, and video posters are stored in IndexedDB alongside library metadata.

saving music from remotes

when you play or queue music from a remote server, the audio is saved to OPFS by default — so it’s available offline the next time. a few specifics:

• queue auto-save: anything added to the queue from a remote is saved locally as it plays, ready for offline use.
• P2P remotes: music fetched over P2P is also saved locally by default.

both behaviors can be turned off in settings if you’d prefer not to keep local copies.

purge

to clear everything, use the app’s settings or clear site data for spume.freqhole.net (or your self-hosted origin) in your browser’s settings.

---

the desktop app (charnel)

charnel uses a local freqhole server embedded in the application. all storage follows the same rules as the CLI server above — the database and blob storage live on disk in the app’s data directory, and your scanned media stays wherever you put it.

the app also has a local web view (similar to the web app), but because it talks to the local embedded server over a private channel, media and artwork are served directly — no OPFS caching needed.

---

backing up

to back up your freqhole setup you need:

1. data/grimoire.db — main database: metadata, playlists, accounts
2. data/grimoire-blobdata.db — blob binary data (artwork, thumbnails)
3. data/blobs/ — blob files on disk
4. data/fetch/ — any media downloaded via the fetch features (if you use them)

your original media files are managed entirely by you.