Understanding Chroma Plugin Behavior - When Does It Actually Fingerprint?

[stevendennisha]

Hi everyone,
I'm trying to understand how the chroma plugin with auto: yes is supposed to work, and I've done some testing that has surprising results. I'd love to get clarity from the community on whether this is expected behavior.

System Information

Beets version: 2.5.1
Python version: 3.12.12
Plugins: chroma, embedart, emptylyrics, fetchart, inline, lyrics
OS: QNAP NAS (Linux)
Setup: Running beets in Docker container (linuxserver/beets)
fpcalc: Present and working (/usr/bin/fpcalc)
pyacoustid: Installed

Relevant config:
chroma:
auto: yes
write: yes
fingerprint: yes

import:
write: yes
move: yes
incremental: no
quiet: yes

My Understanding (Before Testing)
I thought chroma: auto: yes would:

Fingerprint all tracks during import
Use those fingerprints to improve matching accuracy
Write fingerprints to file metadata

What I Actually Discovered
I ran three tests with beet -v import and chroma: auto: yes enabled:
Test 1: Files WITH good metadata

Result: Chroma found 5 album candidates, excellent match (distance: 0.07)
Verbose output: Only showed chroma: acoustid album candidates: 5
No fingerprinting output: Never saw chroma: chroma: fingerprinted
Fingerprints written: NO (checked with metaflac)

Test 2: Files with NO metadata BUT helpful folder name (David Bowie/2018 - Let's Dance)

Result: Chroma found 5 candidates, poor match (distance: 0.71)
Verbose output: Only chroma: acoustid album candidates: 5
No fingerprinting output
Fingerprints written: NO

Test 3: Files with NO metadata AND unhelpful folder name (unknown-album)

Result: Chroma correctly identified as "David Bowie - Let's Dance", poor match (distance: 0.71)
Verbose output: Only chroma: acoustid album candidates: 5
No fingerprinting output
Fingerprints written: YES! (verified with metaflac - full ACOUSTID_FINGERPRINT present)

My Questions

Is this expected behavior? Does chroma only fingerprint as a "last resort" when there are no other hints?

Why doesn't chroma fingerprint when folder names exist? It seems like audio fingerprinting would be MORE accurate than folder structure parsing, yet it's used less?

Why is fingerprinting completely silent? Even with -v (verbose mode), I never saw chroma: chroma: fingerprinted output, even when it WAS fingerprinting (Test 3). This makes it very hard to know what's happening.

Is there a way to force fingerprinting for ALL imports regardless of metadata/folder hints? Or is the separate beet fingerprint command the only way?

My Use Case
I'm building an automated music pipeline where:

Files download from seedbox (sometimes with good tags, sometimes not)
Import with auto: yes

I'd prefer chroma to fingerprint everything during import for best accuracy, but it seems to only do it when desperate.
Thanks for any insights!

Steve