scanning your library
by
edwardsharp
edwardsharp freqhole scans directories to import music files into your library.
configuring scan directories
Section titled “configuring scan directories”scan directories are passed as arguments to the scan command — there’s no config file section for them. supported audio formats are configured in [media].supported_audio_formats.
in desktop app
Section titled “in desktop app”settings → library → add folder
running a scan
Section titled “running a scan”freqhole music scan --path ~/Musicrescan all previously tracked directories:
freqhole music scan rescandesktop app
Section titled “desktop app”library → scan now
web app
Section titled “web app”settings → library → scan (member/admin only)
what happens during scan
Section titled “what happens during scan”- discover files: find all audio files in configured directories
- extract metadata: read ID3/Vorbis tags from files
- extract artwork: pull embedded cover art
- deduplicate: skip files already in library (by path)
- create entities: songs → albums → artists (linked)
- index for search: update full-text search index
metadata extraction
Section titled “metadata extraction”supported tags
Section titled “supported tags”- title, artist, album artist
- album, track number, disc number
- year, genre
- duration, bitrate, sample rate
embedded artwork
Section titled “embedded artwork”cover art is extracted from:
- ID3 APIC frames (MP3)
- Vorbis METADATA_BLOCK_PICTURE (FLAC/OGG)
- MP4 covr atom (M4A)
stored as blobs, deduplicated by content hash.
file formats
Section titled “file formats”| format | extension | notes |
|---|---|---|
| MP3 | .mp3 | ID3v2 tags |
| FLAC | .flac | Vorbis comments |
| Ogg Vorbis | .ogg | Vorbis comments |
| AAC | .m4a | iTunes-style tags |
| WAV | .wav | limited metadata |
| Opus | .opus | Vorbis comments |
handling duplicates
Section titled “handling duplicates”freqhole tracks files by path. if the same file is moved:
- old path: shows as missing
- new path: imports as new song
to clean up missing files:
freqhole maintenance cleanup-orphansincremental vs full scan
Section titled “incremental vs full scan”incremental (default)
Section titled “incremental (default)”- only processes new files (not in database)
- fast for adding new music
- does not update changed tags
rescan
Section titled “rescan”freqhole music scan rescan- reprocesses all previously tracked directories
- slower but ensures everything is up to date
troubleshooting
Section titled “troubleshooting”files not appearing
Section titled “files not appearing”check:
- file extension in
[media].supported_audio_formats? - file readable by the freqhole process?
- valid audio file (not corrupted)?
wrong metadata
Section titled “wrong metadata”tags embedded in the file take priority. to fix:
- update tags in the file (with Mp3tag, Picard, etc.)
- run
freqhole music scan rescan
or edit in the web app (overrides file tags).
scan is slow
Section titled “scan is slow”normal for large libraries on first scan. subsequent scans are incremental.
tips:
- exclude non-music directories
- use SSD for database
- reduce extensions list