serato-doctor/docs/design/audio-comparison.md

Audio comparison for duplicate review

Problem

Filenames alone are weak evidence. DJs need to hear each candidate and locate it on disk before deciding which copy is authoritative.

Design

Exact-duplicate and cloud-conflict groups expose a shared audio player with a preview action for each file. Switching files reuses the same player, making back-to-back comparison quick. A separate action reveals the selected file in macOS Finder.

The browser never receives unrestricted filesystem access. Each analyzed audio path gets a short, process-local HMAC token. Preview and Finder endpoints reject altered, expired, missing, non-audio, or otherwise unsigned paths. Audio serving supports HTTP byte ranges so playback can seek without loading an entire track.

Edge cases

• A file moved after analysis is rejected.
• Forged or stale tokens cannot select another local file.
• Preview controls remain useful if autoplay is blocked because native audio controls stay visible.
• Finder failures are reported beside the button without affecting analysis.

Tests

• Valid signed audio resolves to the analyzed file.
• A modified token is rejected.
• Duplicate detail payloads include preview and Finder controls for every file.