Flaced

Flaced is a CLI for managing music libraries. Currently it includes tools for showing tags, setting tags, auditing a music library for issues with tagging and analysing tracks to detect upsampled, transcoded or padded audio.

Flaced is built to handle all common file formats for music and has the same interface for interacting with them.

Install

cargo install --path .

Showing tags

flaced show '17 Secunda.flac'
# Every field, picture and tag block
flaced show -d '17 Secunda.flac'

Tagging music

Set or remove tags:

# Set tags
flaced tag '--album=The Elder Scrolls V: Skyrim: Original Game Soundtrack' --title=Secunda '17 Secunda.flac'
# Remove tags
flaced tag --remove disc '17 Secunda.flac' '48 Sky Above, Voice Within.flac'
# Dry run
flaced tag --dry-run '--album=The Elder Scrolls V: Skyrim: Original Game Soundtrack' --title=Secunda '17 Secunda.flac'
# The following flags exist: --album, --albumartist, --artist, --title, --date, --track, --disc, --genre
# Other tags
flaced tag --set 'composer=Jeremy Soule' --remove comment '17 Secunda.flac'

# Recursively
flaced tag -r '--albumartist=Jeremy Soule' .

Audit library

Right now this assumes the layout album artist/album/{optional CD folder}/track

flaced report ~/Music
flaced report --errors-only ~/Music

Check	Severity
Track cannot be read	error
Track missing albumartist, album or title	error
Track missing artist, date or tracknumber	warning
album not identical across all tracks in an album folder	error
albumartist not identical across all tracks in an artist folder	error
Album folder has no cover.png / cover.jpg / … (a cover in every disc folder also counts)	error
Audio file directly in the root or in an artist folder	warning
Artist folder without albums, album folder without tracks	warning

Checking quality of a file

This is meant to detect when a file is upconverted in any way. An MP3 128 is not faulty as long as it's not upconverted from MP3 96. Flaced uses its built-in decoder for most formats. Opus, WavPack, Monkey's Audio and HE-AAC need ffmpeg and are listed as not analysed without it. The PDF report (--pdf) requires typst to be installed.

flaced quality album/*.flac
flaced quality -r ~/Music
flaced quality -v --json '53 Skyrim Atmospheres.flac'
flaced quality --pdf report.pdf -r 'The Elder Scrolls V Skyrim Original Game Soundtrack'

Checks

✗ means the measurement proves the file holds less than it claims, ! is a clue with innocent explanations, · is an informational measurement and ? a test that could not decide (shown with -v).

Check	How	Result
Band limit	A sharp step in the long-term spectrum (P99 of each frequency over time) that no frame ever crosses: steep, deep compared with the spectrum's trend, and no frame with energy just below it has energy just above (frames with clipped samples are left out, since clipping splatters energy everywhere)	✗ below ~19 kHz in a 44.1/48 kHz lossless file, ! at 19–21 kHz (matches LAME 256/320, but also some resamplers)
Band gating	A step just as steep (50 dB/kHz or more, which no natural or analog process makes) that real content crosses in only a few frames: an encoder switching its top band off when bits run short, as LAME does above 16 kHz on quiet material	!
Upsampling	The same step, or a step between two noise floors, at 44.1/48/88.2/96 kHz's Nyquist frequency in a higher-rate file; the mirror images a cheap resampler leaves above that frequency (fine structure correlating bin by bin with the content below); samples repeated or linearly interpolated in a fixed phase	✗
Transcoded lossy	A lossy file's content stops far below the lowpass its own encoder used (from the LAME tag) or normally uses at that bitrate	✗ with a LAME tag, ! without
Padded or scaled bit depth	Low bits zero in every sample; sample values on a coarser grid than the container's (padding plus a gain); low bits zeroed block by block (lossyWAV); float files holding integer data	✗
16-bit floor in a 24-bit file	The quiet-passage noise floor, as a density, compared with the theoretical floor of 16-bit quantisation (−139.8 dB/Hz for TPDF dither at 44.1 kHz), or the rising floor of noise-shaped dither	!, ✗ when another test confirms it
Channels	Bit-identical (dual mono, ·), inverted polarity or a silent channel (✗), a side signal band-limited far below the mid (joint stereo of a lossy encoder, !)
Integrity and mastering	FLAC MD5 mismatch and decode errors (✗), clipping at the file's own peak (so clipped-then-attenuated audio counts), dropouts of exact digital silence, held samples (!); peak, true peak, RMS and DC (·)

Development

cargo test
cargo clippy --all-targets

The fixtures in tests/fixtures are 0.1 s of silence generated with ffmpeg -f lavfi -i anullsrc=r=8000:cl=mono -t 0.1 -map_metadata -1 -fflags +bitexact <file>. The quality fixtures in tests/fixtures/quality are rebuilt by make.sh there (needs ffmpeg, sox and lame). scripts/quality-calibrate.sh builds a full set of degraded copies of known-good files and prints how each was judged, for tuning the detectors.