feat(temporal): swing vs straight groove detection

[seonghobae]

What

Adds a new detect_groove(audio, sr, beat_times) function in
services/analysis-engine/src/bandscope_analysis/temporal/groove.py that
classifies a performance as straight or swing feel directly from the
audio and the beat grid produced by the temporal analyzer.

Why

BandScope's temporal analysis already extracts BPM and beats but says nothing
about feel. Straight vs swing (triplet) is a first-class musical attribute
players want surfaced. This is a real, self-contained DSP feature with no new
dependencies.

How

• Computes the onset-strength envelope (librosa.onset.onset_strength) and its
  frame times.
• For each consecutive beat pair, trims the interval ends (to exclude the beats'
  own onsets) and locates the dominant off-beat onset, measuring its relative
  position p in [0, 1].
• Aggregates the median off-beat position across the track:
  • swing_ratio = p / (1 - p) (~1.0 straight, ~2.0 triplet swing).
  • feel = "swing" when median position >= 0.58 (ratio >= ~1.4), the
    midpoint between straight (0.5) and triplet (0.667) placement. Documented in
    the module.
  • confidence from the consistency (inverted, normalized IQR) of the off-beat
    positions, bounded to [0, 1].
• Safe failure: fewer than 3 beats, empty audio, or no detectable off-beat
  onsets return {"feel": "straight", "swing_ratio": 1.0, "confidence": 0.0}.
  No exception escapes.
• Bounded and side-effect free: operates only on the passed in-memory arrays;
  no file/network/shell access. A # Security Notes: block documents this.

Tests

tests/test_groove.py synthesizes deterministic click tracks with known feel:

• Straight eighths (onsets exactly halfway) → feel == "straight",
  swing_ratio ~= 1.11 (asserted approx(1.0, abs=0.35)).
• Swung eighths (onsets at 2/3) → feel == "swing",
  swing_ratio ~= 2.21 (asserted approx(2.0, abs=0.5)).
• Fewer than 3 beats, empty audio, zero-length intervals, silence,
  beats beyond audio, and an internally raised error all return the safe
  default with confidence == 0.0.

New module is at 100% line coverage; full analysis-engine suite passes.

🤖 Generated with Claude Code