Add duplicate audio comparison controls

docs/design/audio-comparison.md

@@ -0,0 +1,32 @@
+# 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.