chord_suggestion.h

// SPDX-FileCopyrightText: © 2026 Alexandros Theodotou <alex@zrythm.org>
// SPDX-License-Identifier: LicenseRef-ZrythmLicense
 
#pragma once
 
#include <optional>
#include <vector>
 
#include "dsp/chord_descriptor.h"
#include "dsp/musical_scale.h"
 
namespace zrythm::dsp::chords
{
 
// ============================================================================
// Enums
// ============================================================================

enum class ChordCandidateCategory : uint32_t
{
  DiatonicTriads = 1 << 0,
  DiatonicSevenths = 1 << 1,
  SecondaryDominants = 1 << 2,
  BorrowedChords = 1 << 3,
  LeadingTone = 1 << 4,
};
 
inline ChordCandidateCategory
operator| (ChordCandidateCategory a, ChordCandidateCategory b) noexcept
{
  return static_cast<ChordCandidateCategory> (
    static_cast<uint32_t> (a) | static_cast<uint32_t> (b));
}
 
inline ChordCandidateCategory
operator& (ChordCandidateCategory a, ChordCandidateCategory b) noexcept
{
  return static_cast<ChordCandidateCategory> (
    static_cast<uint32_t> (a) & static_cast<uint32_t> (b));
}
 
inline ChordCandidateCategory &
operator|= (ChordCandidateCategory &a, ChordCandidateCategory b) noexcept
{
  a = a | b;
  return a;
}

enum class HarmonicFunction
{
  Tonic,
  Predominant,
  Dominant,
  Other,
};

enum class CandidateType
{
  DiatonicTriad,
  DiatonicSeventh,
  SecondaryDominant,
  BorrowedChord,
  LeadingTone,
};
 
// ============================================================================
// Structs
// ============================================================================

struct ChordKey
{
  MusicalNote root_note = MusicalNote::C;
  ChordType   type = ChordType::Major;
  ChordAccent accent = ChordAccent::None;
 
  bool operator== (const ChordKey &other) const
  {
    return root_note == other.root_note && type == other.type
           && accent == other.accent;
  }

  ChordDescriptor make_descriptor () const
  {
    return ChordDescriptor (root_note, type, accent);
  }
};

struct CandidateChord
{
  ChordKey           chord_key{};
  CandidateType      type = CandidateType::DiatonicTriad;
  int                scale_degree = -1;
  std::optional<int> secondary_dominant_target_degree{};
};

struct ChordSuggestion
{
  ChordKey         chord_key{};
  CandidateType    candidate_type = CandidateType::DiatonicTriad;
  float            overall_score = 0.0f;
  float            functional_score = 0.0f;
  float            root_motion_score = 0.0f;
  float            voice_leading_score = 0.0f;
  int              scale_degree = -1;
  HarmonicFunction function = HarmonicFunction::Other;
  int              rank = 0;
};
 
// ============================================================================
// Public API
// ============================================================================

bool
is_minor_type (const MusicalScale &scale);

int
get_scale_degree (MusicalNote root, const MusicalScale &scale);

float
score_root_motion (MusicalNote prev_root, MusicalNote next_root);

float
score_voice_leading (const ChordKey &prev, const ChordKey &next);

float
score_diatonic_membership (const ChordKey &chord, const MusicalScale &scale);

float
score_functional_compatibility (
  const ChordKey     &prev,
  const ChordKey     &candidate,
  const MusicalScale &scale);

float
score_seventh_resolution (
  const ChordKey     &prev,
  const ChordKey     &next,
  const MusicalScale &scale);

float
score_secondary_dominant (
  const CandidateChord &prev,
  const CandidateChord &candidate,
  const MusicalScale   &scale);

float
score_leading_tone_resolution (
  const ChordKey     &prev,
  const ChordKey     &candidate,
  const MusicalScale &scale);

float
score_borrowed_chord (const CandidateChord &candidate, const MusicalScale &scale);

std::vector<CandidateChord>
generate_candidates (
  const MusicalScale    &scale,
  ChordCandidateCategory categories);

std::vector<ChordSuggestion>
suggest_next_chords (
  const ChordKey        &current_chord,
  const MusicalScale    &scale,
  ChordCandidateCategory categories,
  int                    max_results = 3);
 
} // namespace zrythm::dsp::chords