feat(streaming): Add bar-synchronized and per-frame chord detection

- Add bar-synchronized chord progression (requires stable BPM)
  - Track chord per bar using accumulated chroma average
  - Automatically start bar tracking when BPM confidence >= 0.3
  - Expose currentBar, barDuration, and barChordProgression
- Add per-frame chord detection in StreamFrame
  - Detect chord for each STFT frame using template correlation
  - Include chordRoot, chordQuality, chordConfidence per frame
- Update FrameBuffer to include chord arrays for bulk reads
- Export bar chord data through WASM bindings
- Add comprehensive tests for bar chord and per-frame detection

Author: libraz

js/index.ts

@@ -164,6 +164,14 @@ interface WasmChordChange {
   confidence: number;
 }
 
+interface WasmBarChord {
+  barIndex: number;
+  root: number;
+  quality: number;
+  startTime: number;
+  confidence: number;
+}
+
 interface WasmProgressiveEstimate {
   bpm: number;
   bpmConfidence: number;
@@ -175,6 +183,9 @@ interface WasmProgressiveEstimate {
   chordQuality: number;
   chordConfidence: number;
   chordProgression: WasmChordChange[];
+  barChordProgression: WasmBarChord[];
+  currentBar: number;
+  barDuration: number;
   accumulatedSeconds: number;
   usedFrames: number;
   updated: boolean;
@@ -196,6 +207,9 @@ interface WasmFrameBuffer {
   rmsEnergy: Float32Array;
   spectralCentroid: Float32Array;
   spectralFlatness: Float32Array;
+  chordRoot: Int32Array;
+  chordQuality: Int32Array;
+  chordConfidence: Float32Array;
 }
 
 interface WasmStreamAnalyzer {
@@ -1365,6 +1379,17 @@ export interface ChordChange {
   confidence: number;
 }
 
+/**
+ * A chord detected at bar boundary (beat-synchronized)
+ */
+export interface BarChord {
+  barIndex: number;
+  root: PitchClass;
+  quality: ChordQuality;
+  startTime: number;
+  confidence: number;
+}
+
 /**
  * Progressive estimation results for BPM, Key, and Chord
  */
@@ -1379,6 +1404,9 @@ export interface ProgressiveEstimate {
   chordQuality: ChordQuality;
   chordConfidence: number;
   chordProgression: ChordChange[];
+  barChordProgression: BarChord[];
+  currentBar: number;
+  barDuration: number;
   accumulatedSeconds: number;
   usedFrames: number;
   updated: boolean;
@@ -1406,6 +1434,9 @@ export interface FrameBuffer {
   rmsEnergy: Float32Array;
   spectralCentroid: Float32Array;
   spectralFlatness: Float32Array;
+  chordRoot: Int32Array;
+  chordQuality: Int32Array;
+  chordConfidence: Float32Array;
 }
 
 /**
@@ -1543,6 +1574,15 @@ export class StreamAnalyzer {
           startTime: c.startTime,
           confidence: c.confidence,
         })),
+        barChordProgression: s.estimate.barChordProgression.map((c) => ({
+          barIndex: c.barIndex,
+          root: c.root as PitchClass,
+          quality: c.quality as ChordQuality,
+          startTime: c.startTime,
+          confidence: c.confidence,
+        })),
+        currentBar: s.estimate.currentBar,
+        barDuration: s.estimate.barDuration,
         accumulatedSeconds: s.estimate.accumulatedSeconds,
         usedFrames: s.estimate.usedFrames,
         updated: s.estimate.updated,

js/sonare.js.d.ts

@@ -339,6 +339,14 @@ interface WasmChordChange {
   confidence: number;
 }
 
+interface WasmBarChord {
+  barIndex: number;
+  root: number;
+  quality: number;
+  startTime: number;
+  confidence: number;
+}
+
 interface WasmProgressiveEstimate {
   bpm: number;
   bpmConfidence: number;
@@ -350,6 +358,9 @@ interface WasmProgressiveEstimate {
   chordQuality: number;
   chordConfidence: number;
   chordProgression: WasmChordChange[];
+  barChordProgression: WasmBarChord[];
+  currentBar: number;
+  barDuration: number;
   accumulatedSeconds: number;
   usedFrames: number;
   updated: boolean;
@@ -371,6 +382,9 @@ interface WasmFrameBuffer {
   rmsEnergy: Float32Array;
   spectralCentroid: Float32Array;
   spectralFlatness: Float32Array;
+  chordRoot: Int32Array;
+  chordQuality: Int32Array;
+  chordConfidence: Float32Array;
 }
 
 interface WasmStreamAnalyzer {

src/streaming/stream_analyzer.cpp

@@ -325,6 +325,7 @@ StreamAnalyzer::StreamAnalyzer(const StreamConfig& config) : config_(config) {
   if (config_.compute_chroma) {
     chroma_buffer_.resize(12);
     chroma_sum_.fill(0.0f);
+    bar_chroma_sum_.fill(0.0f);
     /// Initialize chord templates for chord detection
     chord_templates_ = generate_triad_templates();
   }
@@ -423,6 +424,15 @@ StreamFrame StreamAnalyzer::process_single_frame(const float* frame_start, size_
       chroma_sum_[i] += chroma_buffer_[i];
     }
     ++chroma_frame_count_;
+
+    /// Detect chord for this frame
+    if (!chord_templates_.empty() && chroma_buffer_.size() == 12) {
+      auto [best_chord, chord_corr] =
+          find_best_chord(chroma_buffer_.data(), chord_templates_);
+      frame.chord_root = static_cast<int>(best_chord.root);
+      frame.chord_quality = static_cast<int>(best_chord.quality);
+      frame.chord_confidence = std::max(0.0f, chord_corr);
+    }
   }
 
   /// Compute onset strength
@@ -678,6 +688,84 @@ void StreamAnalyzer::update_progressive_estimate(float current_time) {
       }
     }
   }
+
+  /// Update bar-synchronized chord tracking
+  if (config_.compute_chroma) {
+    update_bar_chord_tracking(current_time);
+  }
+}
+
+void StreamAnalyzer::update_bar_chord_tracking(float current_time) {
+  /// Check if BPM is stable enough to start bar tracking
+  if (!bar_tracking_active_) {
+    if (current_estimate_.bpm_confidence >= kBpmConfidenceThreshold && current_estimate_.bpm > 0.0f) {
+      /// Start bar tracking
+      bar_tracking_active_ = true;
+      bar_duration_ = static_cast<float>(kBeatsPerBar) * 60.0f / current_estimate_.bpm;
+      current_bar_index_ = 0;
+      bar_start_time_ = current_time;
+      bar_chroma_sum_.fill(0.0f);
+      bar_chroma_count_ = 0;
+
+      /// Update estimate with bar info
+      current_estimate_.bar_duration = bar_duration_;
+      current_estimate_.current_bar = 0;
+    }
+    return;
+  }
+
+  /// Update bar duration if BPM changed significantly
+  float new_bar_duration = static_cast<float>(kBeatsPerBar) * 60.0f / current_estimate_.bpm;
+  if (std::abs(new_bar_duration - bar_duration_) > 0.1f) {
+    bar_duration_ = new_bar_duration;
+    current_estimate_.bar_duration = bar_duration_;
+  }
+
+  /// Accumulate chroma for current bar
+  for (int c = 0; c < 12; ++c) {
+    bar_chroma_sum_[c] += chroma_buffer_[c];
+  }
+  ++bar_chroma_count_;
+
+  /// Check if we've crossed a bar boundary
+  if (current_time >= bar_start_time_ + bar_duration_) {
+    /// Detect chord for completed bar using accumulated chroma
+    if (bar_chroma_count_ > 0 && !chord_templates_.empty()) {
+      /// Normalize accumulated chroma
+      std::array<float, 12> bar_chroma;
+      float sum = 0.0f;
+      for (int c = 0; c < 12; ++c) {
+        bar_chroma[c] = bar_chroma_sum_[c] / static_cast<float>(bar_chroma_count_);
+        sum += bar_chroma[c];
+      }
+      if (sum > kEpsilon) {
+        for (int c = 0; c < 12; ++c) {
+          bar_chroma[c] /= sum;
+        }
+      }
+
+      /// Find best chord for this bar
+      auto [best_chord, chord_corr] = find_best_chord(bar_chroma.data(), chord_templates_);
+
+      /// Add to bar chord progression
+      BarChord bar_chord;
+      bar_chord.bar_index = current_bar_index_;
+      bar_chord.root = static_cast<int>(best_chord.root);
+      bar_chord.quality = static_cast<int>(best_chord.quality);
+      bar_chord.start_time = bar_start_time_;
+      bar_chord.confidence = std::max(0.0f, chord_corr);
+      current_estimate_.bar_chord_progression.push_back(bar_chord);
+    }
+
+    /// Move to next bar
+    ++current_bar_index_;
+    bar_start_time_ = current_time;
+    bar_chroma_sum_.fill(0.0f);
+    bar_chroma_count_ = 0;
+
+    /// Update estimate
+    current_estimate_.current_bar = current_bar_index_;
+  }
 }
 
 size_t StreamAnalyzer::available_frames() const { return output_buffer_.size(); }
@@ -715,6 +803,9 @@ void StreamAnalyzer::read_frames_soa(size_t max_frames, FrameBuffer& buffer) {
     buffer.rms_energy.push_back(frame.rms_energy);
     buffer.spectral_centroid.push_back(frame.spectral_centroid);
     buffer.spectral_flatness.push_back(frame.spectral_flatness);
+    buffer.chord_root.push_back(frame.chord_root);
+    buffer.chord_quality.push_back(frame.chord_quality);
+    buffer.chord_confidence.push_back(frame.chord_confidence);
 
     // Append mel (row-major)
     buffer.mel.insert(buffer.mel.end(), frame.mel.begin(), frame.mel.end());
@@ -832,6 +923,14 @@ void StreamAnalyzer::reset(size_t base_sample_offset) {
   prev_chord_root_ = -1;
   prev_chord_quality_ = -1;
   chord_stable_time_ = 0.0f;
+
+  /// Reset bar tracking state
+  bar_tracking_active_ = false;
+  bar_duration_ = 0.0f;
+  current_bar_index_ = -1;
+  bar_start_time_ = 0.0f;
+  bar_chroma_sum_.fill(0.0f);
+  bar_chroma_count_ = 0;
 }
 
 AnalyzerStats StreamAnalyzer::stats() const {

src/streaming/stream_analyzer.h

@@ -170,6 +170,16 @@ class StreamAnalyzer {
   float chord_stable_time_ = 0.0f;        ///< Time chord has been stable
   static constexpr float kChordMinDuration = 0.2f;  ///< Min duration to register change
 
+  // Bar-synchronized chord tracking (requires stable BPM)
+  static constexpr float kBpmConfidenceThreshold = 0.3f;  ///< Min BPM confidence for bar sync
+  static constexpr int kBeatsPerBar = 4;  ///< Beats per bar (4/4 time signature)
+  bool bar_tracking_active_ = false;      ///< True when BPM is stable enough
+  float bar_duration_ = 0.0f;             ///< Duration of one bar in seconds
+  int current_bar_index_ = -1;            ///< Current bar index (0-based)
+  float bar_start_time_ = 0.0f;           ///< Start time of current bar
+  std::array<float, 12> bar_chroma_sum_;  ///< Accumulated chroma within current bar
+  int bar_chroma_count_ = 0;              ///< Number of frames accumulated in current bar
+
   // Internal methods
   void process_internal(const float* samples, size_t n_samples);
   StreamFrame process_single_frame(const float* frame_start, size_t sample_offset);
@@ -179,6 +189,7 @@ class StreamAnalyzer {
   float compute_onset();
   void compute_spectral_features(StreamFrame& frame);
   void update_progressive_estimate(float current_time);
+  void update_bar_chord_tracking(float current_time);
 };
 
 }  // namespace sonare

src/streaming/stream_frame.h

@@ -18,6 +18,15 @@ struct ChordChange {
   float confidence = 0.0f;    ///< Detection confidence (0-1)
 };
 
+/// @brief A chord detected at bar boundary (beat-synchronized).
+struct BarChord {
+  int bar_index = -1;         ///< Bar number (0-based, -1 = invalid)
+  int root = -1;              ///< Chord root (0-11 for C-B, -1 = unknown)
+  int quality = 0;            ///< Chord quality (0=Maj, 1=Min, 2=Dim, etc.)
+  float start_time = 0.0f;    ///< Start time in seconds
+  float confidence = 0.0f;    ///< Detection confidence (0-1)
+};
+
 /// @brief A single frame of analysis results.
 /// @details Contains all computed features for one STFT frame.
 /// The timestamp represents stream time (input sample position),
@@ -44,6 +53,11 @@ struct StreamFrame {
   // Onset detection (1-frame lag)
   float onset_strength = 0.0f;      ///< Onset strength value
   bool onset_valid = false;         ///< False for frame_index == 0 (no previous frame)
+
+  // Chord detection (per-frame)
+  int chord_root = -1;              ///< Detected chord root (0-11 for C-B, -1 = unknown)
+  int chord_quality = 0;            ///< Chord quality (0=Maj, 1=Min, 2=Dim, etc.)
+  float chord_confidence = 0.0f;    ///< Chord detection confidence (0-1)
 };
 
 /// @brief Progressive estimation results for BPM, Key, and Chord.
@@ -64,10 +78,16 @@ struct ProgressiveEstimate {
   int chord_root = -1;              ///< Current chord root (0-11 for C-B, -1 = unknown)
   int chord_quality = 0;            ///< Chord quality (0=Maj, 1=Min, 2=Dim, etc.)
   float chord_confidence = 0.0f;    ///< Chord detection confidence (0-1)
+  float chord_start_time = 0.0f;    ///< Start time of current chord
 
-  // Chord progression (accumulated over time)
+  // Chord progression (accumulated over time, includes current chord)
   std::vector<ChordChange> chord_progression;  ///< Detected chord changes
 
+  // Bar-synchronized chord progression (updated when BPM is stable)
+  std::vector<BarChord> bar_chord_progression;  ///< Chord per bar (beat-synced)
+  int current_bar = -1;         ///< Current bar index (-1 if BPM not stable)
+  float bar_duration = 0.0f;    ///< Duration of one bar in seconds (0 if BPM not stable)
+
   // Objective statistics (for UI display)
   float accumulated_seconds = 0.0f; ///< Total audio processed
   int used_frames = 0;              ///< Number of frames used for estimation
@@ -94,6 +114,9 @@ struct FrameBuffer {
   std::vector<float> rms_energy;    ///< [n_frames]
   std::vector<float> spectral_centroid; ///< [n_frames]
   std::vector<float> spectral_flatness; ///< [n_frames]
+  std::vector<int> chord_root;      ///< [n_frames] chord root per frame
+  std::vector<int> chord_quality;   ///< [n_frames] chord quality per frame
+  std::vector<float> chord_confidence; ///< [n_frames] chord confidence per frame
 
   /// @brief Clears all data.
   void clear() {
@@ -105,6 +128,9 @@ struct FrameBuffer {
     rms_energy.clear();
     spectral_centroid.clear();
     spectral_flatness.clear();
+    chord_root.clear();
+    chord_quality.clear();
+    chord_confidence.clear();
   }
 
   /// @brief Reserves capacity for n frames.
@@ -116,6 +142,9 @@ struct FrameBuffer {
     rms_energy.reserve(n);
     spectral_centroid.reserve(n);
     spectral_flatness.reserve(n);
+    chord_root.reserve(n);
+    chord_quality.reserve(n);
+    chord_confidence.reserve(n);
   }
 };