chord_descriptor.h

// SPDX-FileCopyrightText: © 2018-2022, 2024-2026 Alexandros Theodotou <alex@zrythm.org>
// SPDX-License-Identifier: LicenseRef-ZrythmLicense
 
#pragma once
 
#include <algorithm>
#include <array>
#include <cstdint>
#include <optional>
 
#include <QObject>
#include <QtQmlIntegration/qqmlintegration.h>
 
#include <boost/container/static_vector.hpp>
#include <nlohmann/json_fwd.hpp>
 
namespace zrythm::utils
{
class Utf8String;
}
 
namespace zrythm::dsp::chords
{
Q_NAMESPACE
QML_ELEMENT
 
enum class MusicalNote : std::uint8_t
{
  C = 0,
  CSharp,
  D,
  DSharp,
  E,
  F,
  FSharp,
  G,
  GSharp,
  A,
  ASharp,
  B
};
Q_ENUM_NS (MusicalNote)
 

enum class ChordType : std::uint8_t
{
  None,
  Major,
  Minor,
  Diminished,
  SuspendedFourth,
  SuspendedSecond,
  Augmented,
  Custom,
};
Q_ENUM_NS (ChordType)
 

enum class ChordAccent : std::uint8_t
{
  None,
  Seventh,
  MajorSeventh,
  /* NOTE: all accents below assume Seventh */
  FlatNinth,
  Ninth,
  SharpNinth,
  Eleventh,
  FlatFifthSharpEleventh,
  SharpFifthFlatThirteenth,
  SixthThirteenth,
};
Q_ENUM_NS (ChordAccent)
 

constexpr MusicalNote
transpose_note (MusicalNote note, bool up) noexcept
{
  return static_cast<MusicalNote> (
    (static_cast<int> (note) + (up ? 1 : 11)) % 12);
}
 
} // namespace zrythm::dsp::chords
 
namespace zrythm::dsp
{
 
using MusicalNote = chords::MusicalNote;
using ChordType = chords::ChordType;
using ChordAccent = chords::ChordAccent;

class ChordDescriptor : public QObject
{
  Q_OBJECT
  QML_ELEMENT
 
public:
  static constexpr std::uint8_t kDefaultBasePitch = 36; // C2
 
  ChordDescriptor () = default;
 
  ChordDescriptor (
    MusicalNote                root,
    ChordType                  type,
    ChordAccent                accent = ChordAccent::None,
    int                        inversion = 0,
    std::optional<MusicalNote> bass = std::nullopt,
    QObject *                  parent = nullptr)
      : QObject (parent), root_note_ (root), type_ (type), accent_ (accent),
        inversion_ (std::clamp (inversion, minInversion (), maxInversion ())),
        bass_note_ (bass)
  {
  }
 
  // ========================================================================
  // QML Interface
  // ========================================================================
 
  Q_PROPERTY (
    zrythm::dsp::chords::MusicalNote rootNote READ rootNote WRITE setRootNote
      NOTIFY rootNoteChanged)
  Q_PROPERTY (bool hasBass READ hasBass WRITE setHasBass NOTIFY hasBassChanged)
  Q_PROPERTY (
    zrythm::dsp::chords::MusicalNote bassNote READ bassNote WRITE setBassNote
      NOTIFY bassNoteChanged)
  Q_PROPERTY (
    zrythm::dsp::chords::ChordType chordType READ chordType WRITE setChordType
      NOTIFY chordTypeChanged)
  Q_PROPERTY (
    zrythm::dsp::chords::ChordAccent chordAccent READ chordAccent WRITE
      setChordAccent NOTIFY chordAccentChanged)
  Q_PROPERTY (
    int inversion READ inversion WRITE setInversion NOTIFY inversionChanged)
  Q_PROPERTY (QString displayName READ displayName NOTIFY displayNameChanged)
 
  MusicalNote rootNote () const { return root_note_; }
  void        setRootNote (MusicalNote v)
  {
    if (root_note_ != v)
      {
        root_note_ = v;
        Q_EMIT rootNoteChanged (v);
        Q_EMIT displayNameChanged ();
        Q_EMIT changed ();
      }
  }
 
  bool hasBass () const { return bass_note_.has_value (); }
  void setHasBass (bool v)
  {
    if (hasBass () != v)
      {
        bass_note_ = v ? std::optional<MusicalNote> (root_note_) : std::nullopt;
        Q_EMIT hasBassChanged (v);
        Q_EMIT displayNameChanged ();
        Q_EMIT changed ();
      }
  }
 
  MusicalNote bassNote () const { return bass_note_.value_or (MusicalNote::C); }
  void        setBassNote (MusicalNote v)
  {
    bool had = hasBass ();
    if (!bass_note_.has_value () || *bass_note_ != v)
      {
        bass_note_ = v;
        if (!had)
          Q_EMIT hasBassChanged (true);
        Q_EMIT bassNoteChanged (v);
        Q_EMIT displayNameChanged ();
        Q_EMIT changed ();
      }
  }
 
  ChordType chordType () const { return type_; }
  void      setChordType (ChordType v)
  {
    if (type_ != v)
      {
        type_ = v;
        Q_EMIT chordTypeChanged (v);
        Q_EMIT displayNameChanged ();
        Q_EMIT changed ();
      }
  }
 
  ChordAccent chordAccent () const { return accent_; }
  void        setChordAccent (ChordAccent v)
  {
    if (accent_ != v)
      {
        accent_ = v;
        Q_EMIT chordAccentChanged (v);
        Q_EMIT displayNameChanged ();
        Q_EMIT changed ();
      }
  }
 
  int  inversion () const { return inversion_; }
  void setInversion (int v)
  {
    v = std::clamp (v, minInversion (), maxInversion ());
    if (inversion_ != v)
      {
        inversion_ = v;
        Q_EMIT inversionChanged (v);
        Q_EMIT displayNameChanged ();
        Q_EMIT changed ();
      }
  }
 
  QString displayName () const;
 
  Q_SIGNAL void rootNoteChanged (zrythm::dsp::chords::MusicalNote note);
  Q_SIGNAL void hasBassChanged (bool has);
  Q_SIGNAL void bassNoteChanged (zrythm::dsp::chords::MusicalNote note);
  Q_SIGNAL void chordTypeChanged (zrythm::dsp::chords::ChordType type);
  Q_SIGNAL void chordAccentChanged (zrythm::dsp::chords::ChordAccent accent);
  Q_SIGNAL void inversionChanged (int inversion);
  Q_SIGNAL void displayNameChanged ();
  Q_SIGNAL void changed ();
 
  // ========================================================================
  // Queries
  // ========================================================================
 
  Q_INVOKABLE bool isKeyInChord (MusicalNote key) const;
  Q_INVOKABLE bool isKeyBass (MusicalNote key) const;
 
  static constexpr size_t kMaxIntervals = 12;

  static boost::container::static_vector<int, kMaxIntervals>
  get_intervals_for_type_and_accent (ChordType type, ChordAccent accent);

   * Returns the semitone intervals from root for the current type and accent.
   * e.g., Major = {0, 4, 7}, Minor7 = {0, 3, 7, 10}
   */
  boost::container::static_vector<int, kMaxIntervals> getIntervals () const;

  struct ChordPitches
  {
    static constexpr size_t               kMaxPitches = 8;
    std::array<std::uint8_t, kMaxPitches> data{};
    size_t                                count = 0;
 
    auto         begin () const { return data.begin (); }
    auto         end () const { return data.begin () + count; }
    bool         empty () const { return count == 0; }
    size_t       size () const { return count; }
    std::uint8_t operator[] (size_t i) const { return data[i]; }
 
    friend bool operator== (const ChordPitches &, const ChordPitches &);
  };

  ChordPitches
  getMidiPitches (std::uint8_t base_pitch = kDefaultBasePitch) const;
 
  int maxInversion () const;
  int minInversion () const { return -maxInversion (); }
 
  // ========================================================================
  // String utilities
  // ========================================================================
 
  static utils::Utf8String chord_type_to_string (ChordType type);
  static utils::Utf8String chord_accent_to_string (ChordAccent accent);
  static utils::Utf8String note_to_string (MusicalNote note);
  utils::Utf8String        to_string () const;
 
  bool isEquivalent (const ChordDescriptor &other) const;
 
private:
  friend void to_json (nlohmann::json &j, const ChordDescriptor &c);
  friend void from_json (const nlohmann::json &j, ChordDescriptor &c);

  MusicalNote root_note_ = MusicalNote::C;

  ChordType type_ = ChordType::None;

  ChordAccent accent_ = ChordAccent::None;

  int inversion_ = 0;

  std::optional<MusicalNote> bass_note_;

  std::optional<boost::container::static_vector<int, kMaxIntervals>>
    custom_intervals_;
};
 
} // namespace zrythm::dsp