17009263791

Committed 16 Aug 2025 02:06PM UTC coverage: 99.879% (-0.1%) from 100.0%

Build # 17009263791

Build Type

push

github

Committed by

web-flow

Commit Message

feat(pitch): ✨ allow using ASCII characters for `HelmholtzPitchNotation` (#626)

Signed-off-by: Albert Mañosa <26429103+albertms10@users.noreply.github.com>

Coverage Stats

11 of 13 new or added lines in 2 files covered. (84.62%)

1651 of 1653 relevant lines covered (99.88%)

2.03 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

98.67

/lib/src/note/note.dart

import 'package:meta/meta.dart' show immutable;
import 'package:music_notes/utils.dart';

import '../harmony/chord.dart';
import '../harmony/chord_pattern.dart';
import '../interval/interval.dart';
import '../key/key.dart';
import '../key/key_signature.dart';
import '../key/mode.dart';
import '../notation_system.dart';
import '../respellable.dart';
import '../scalable.dart';
import '../tuning/equal_temperament.dart';
import 'accidental.dart';
import 'base_note.dart';
import 'pitch.dart';

/// A musical note.
///
/// ---
/// See also:
/// * [BaseNote].
/// * [Accidental].
/// * [Pitch].
/// * [KeySignature].
/// * [Key].
@immutable
final class Note extends Scalable<Note>
    with RespellableScalable<Note>
    implements Comparable<Note> {
  /// The base note that defines this [Note].
  final BaseNote baseNote;

  /// The accidental that modifies the [baseNote].
  final Accidental accidental;

  /// Creates a new [Note] from [baseNote] and [accidental].
  const Note(this.baseNote, [this.accidental = Accidental.natural]);

  /// Note C.
  static const c = Note(BaseNote.c);

  /// Note D.
  static const d = Note(BaseNote.d);

  /// Note E.
  static const e = Note(BaseNote.e);

  /// Note F.
  static const f = Note(BaseNote.f);

  /// Note G.
  static const g = Note(BaseNote.g);

  /// Note A.
  static const a = Note(BaseNote.a);

  /// Note B.
  static const b = Note(BaseNote.b);

  /// Parse [source] as a [Note] and return its value.
  ///
  /// If the [source] string does not contain a valid [Note], a
  /// [FormatException] is thrown.
  ///
  /// Example:
  /// ```dart
  /// Note.parse('Bb') == Note.b.flat
  /// Note.parse('c') == Note.c
  /// Note.parse('z') // throws a FormatException
  /// ```
  factory Note.parse(
    String source, {
    List<Parser<Note>> chain = const [
      EnglishNoteNotation(),
      GermanNoteNotation(),
      RomanceNoteNotation(),
    ],
  }) => chain.parse(source);

  /// [Comparator] for [Note]s by fifths distance.
  static int compareByFifthsDistance(Note a, Note b) =>
      a.circleOfFifthsDistance.compareTo(b.circleOfFifthsDistance);

  /// [Comparator] for [Note]s by closest distance.
  static int compareByClosestDistance(Note a, Note b) => compareMultiple([
    () {
      final distance = (a.semitones - b.semitones).abs();

      return (distance <= chromaticDivisions - distance)
          ? a.semitones.compareTo(b.semitones)
          : b.semitones.compareTo(a.semitones);
    },
    ..._comparators(a, b),
  ]);

  static List<int Function()> _comparators(Note a, Note b) => [
    () => Scalable.compareEnharmonically(a, b),
    () => a.baseNote.semitones.compareTo(b.baseNote.semitones),
  ];

  /// The semitones distance of this [Note] relative to [Note.c].
  ///
  /// Example:
  /// ```dart
  /// Note.c.semitones == 0
  /// Note.d.semitones == 2
  /// Note.f.sharp.semitones == 6
  /// Note.b.sharp.semitones == 12
  /// Note.c.flat.semitones == -1
  /// ```
  @override
  int get semitones => baseNote.semitones + accidental.semitones;

  /// The difference in semitones between this [Note] and [other].
  ///
  /// Example:
  /// ```dart
  /// Note.c.difference(Note.d) == 2
  /// Note.a.difference(Note.g) == -2
  /// Note.e.flat.difference(Note.b.flat) == -5
  /// ```
  @override
  int difference(Note other) => super.difference(other);

  /// This [Note] sharpened by 1 semitone.
  ///
  /// Example:
  /// ```dart
  /// Note.c.sharp == const Note(BaseNote.c, Accidental.sharp)
  /// Note.a.sharp == const Note(BaseNote.a, Accidental.sharp)
  /// ```
  Note get sharp => Note(baseNote, accidental + 1);

  /// This [Note] flattened by 1 semitone.
  ///
  /// Example:
  /// ```dart
  /// Note.e.flat == const Note(BaseNote.e, Accidental.flat)
  /// Note.f.flat == const Note(BaseNote.f, Accidental.flat)
  /// ```
  Note get flat => Note(baseNote, accidental - 1);

  /// This [Note] without an accidental (natural).
  ///
  /// Example:
  /// ```dart
  /// Note.g.flat.natural == Note.g
  /// Note.c.sharp.sharp.natural == Note.c
  /// Note.a.natural == Note.a
  /// ```
  Note get natural => Note(baseNote);

  /// The [TonalMode.major] [Key] from this [Note].
  ///
  /// Example:
  /// ```dart
  /// Note.c.major == const Key(Note.c, TonalMode.major)
  /// Note.e.flat.major == Key(Note.e.flat, TonalMode.major)
  /// ```
  Key get major => Key(this, TonalMode.major);

  /// The [TonalMode.minor] [Key] from this [Note].
  ///
  /// Example:
  /// ```dart
  /// Note.d.minor == const Key(Note.d, TonalMode.minor)
  /// Note.g.sharp.minor == Key(Note.g.sharp, TonalMode.minor)
  /// ```
  Key get minor => Key(this, TonalMode.minor);

  /// The [ChordPattern.diminishedTriad] on this [Note].
  ///
  /// Example:
  /// ```dart
  /// Note.a.diminishedTriad == Chord([Note.a, Note.c, Note.e.flat])
  /// Note.b.diminishedTriad == Chord([Note.b, Note.d, Note.f])
  /// ```
  Chord<Note> get diminishedTriad => ChordPattern.diminishedTriad.on(this);

  /// The [ChordPattern.minorTriad] on this [Note].
  ///
  /// Example:
  /// ```dart
  /// Note.e.minorTriad == Chord([Note.e, Note.g, Note.b])
  /// Note.f.sharp.minorTriad == Chord([Note.f.sharp, Note.a, Note.c.sharp])
  /// ```
  Chord<Note> get minorTriad => ChordPattern.minorTriad.on(this);

  /// The [ChordPattern.majorTriad] on this [Note].
  ///
  /// Example:
  /// ```dart
  /// Note.d.majorTriad == Chord([Note.d, Note.f.sharp, Note.a])
  /// Note.a.flat.majorTriad == Chord([Note.a.flat, Note.c, Note.e.flat])
  /// ```
  Chord<Note> get majorTriad => ChordPattern.majorTriad.on(this);

  /// The [ChordPattern.augmentedTriad] on this [Note].
  ///
  /// Example:
  /// ```dart
  /// Note.d.flat.augmentedTriad == Chord([Note.d.flat, Note.f, Note.a])
  /// Note.g.augmentedTriad == Chord([Note.g, Note.b, Note.d.sharp])
  /// ```
  Chord<Note> get augmentedTriad => ChordPattern.augmentedTriad.on(this);

  /// This [Note] respelled by [baseNote] while keeping the same number of
  /// [semitones].
  ///
  /// Example:
  /// ```dart
  /// Note.c.sharp.respellByBaseNote(BaseNote.d) == Note.d.flat
  /// Note.f.respellByBaseNote(BaseNote.e) == Note.e.sharp
  /// Note.g.respellByBaseNote(BaseNote.a) == Note.a.flat.flat
  /// ```
  @override
  Note respellByBaseNote(BaseNote baseNote) {
    final rawSemitones = semitones - baseNote.semitones;
    final deltaSemitones =
        rawSemitones +
        (rawSemitones.abs() > (chromaticDivisions * 0.5)
            ? chromaticDivisions * -rawSemitones.sign
            : 0);

    return Note(baseNote, Accidental(deltaSemitones));
  }

  /// This [Note] respelled by [BaseNote.ordinal] distance while keeping the
  /// same number of [semitones].
  ///
  /// Example:
  /// ```dart
  /// Note.g.flat.respellByOrdinalDistance(-1) == Note.f.sharp
  /// Note.e.sharp.respellByOrdinalDistance(2) == Note.g.flat.flat
  /// ```
  @override
  Note respellByOrdinalDistance(int distance) =>
      respellByBaseNote(BaseNote.fromOrdinal(baseNote.ordinal + distance));

  /// This [Note] respelled upwards while keeping the same number of
  /// [semitones].
  ///
  /// Example:
  /// ```dart
  /// Note.g.sharp.respelledUpwards == Note.a.flat
  /// Note.e.sharp.respelledUpwards == Note.f
  /// ```
  @override
  Note get respelledUpwards => super.respelledUpwards;

  /// This [Note] respelled downwards while keeping the same number of
  /// [semitones].
  ///
  /// Example:
  /// ```dart
  /// Note.g.flat.respelledDownwards == Note.f.sharp
  /// Note.c.respelledDownwards == Note.b.sharp
  /// ```
  @override
  Note get respelledDownwards => super.respelledDownwards;

  /// This [Note] respelled by [accidental] while keeping the same number of
  /// [semitones].
  ///
  /// When no respelling is possible with [accidental], the next closest
  /// spelling is returned.
  ///
  /// Example:
  /// ```dart
  /// Note.e.flat.respellByAccidental(Accidental.sharp) == Note.d.sharp
  /// Note.b.respellByAccidental(Accidental.flat) == Note.c.flat
  /// Note.g.respellByAccidental(Accidental.sharp) == Note.f.sharp.sharp
  /// ```
  @override
  Note respellByAccidental(Accidental accidental) {
    final baseNote = BaseNote.fromSemitones(semitones - accidental.semitones);
    if (baseNote != null) return Note(baseNote, accidental);

    if (accidental.isNatural) {
      return respellByAccidental(Accidental(this.accidental.semitones.sign));
    }

    return respellByAccidental(accidental.incrementBy(1));
  }

  /// This [Note] with the simplest [Accidental] spelling while keeping the
  /// same number of [semitones].
  ///
  /// Example:
  /// ```dart
  /// Note.e.sharp.respelledSimple == Note.f
  /// Note.d.flat.flat.respelledSimple == Note.c
  /// Note.f.sharp.sharp.sharp.respelledSimple == Note.g.sharp
  /// ```
  @override
  Note get respelledSimple => super.respelledSimple;

  /// This [Note] positioned in the given [octave] as a [Pitch].
  ///
  /// Example:
  /// ```dart
  /// Note.c.inOctave(3) == const Pitch(Note.c, octave: 3)
  /// Note.a.flat.inOctave(2) == Pitch(Note.a.flat, octave: 2)
  /// ```
  Pitch inOctave(int octave) => Pitch(this, octave: octave);

  /// The circle of fifths starting from this [Note] split by sharps (`up`) and
  /// flats (`down`).
  ///
  /// Example:
  /// ```dart
  /// Note.c.splitCircleOfFifths.up.take(6).toList()
  ///   == [Note.g, Note.d, Note.a, Note.e, Note.b, Note.f.sharp]
  ///
  /// Note.c.splitCircleOfFifths.down.take(4).toList()
  ///   == [Note.f, Note.b.flat, Note.e.flat, Note.a.flat]
  ///
  /// Note.a.splitCircleOfFifths.up.take(4).toList()
  ///   == [Note.e, Note.b, Note.f.sharp, Note.c.sharp]
  /// ```
  /// ---
  /// See also:
  /// * [circleOfFifths] for a continuous list version of [splitCircleOfFifths].
  ({Iterable<Note> up, Iterable<Note> down}) get splitCircleOfFifths => (
    up: Interval.P5.circleFrom(this).skip(1),
    down: Interval.P4.circleFrom(this).skip(1),
  );

  /// The continuous circle of fifths up to [distance] including this [Note],
  /// from flats to sharps.
  ///
  /// Example:
  /// ```dart
  /// Note.c.circleOfFifths(distance: 3)
  ///   == [Note.e.flat, Note.b.flat, Note.f, Note.c, Note.g, Note.d, Note.a]
  ///
  /// Note.a.circleOfFifths(distance: 3)
  ///   == [Note.c, Note.g, Note.d, Note.a, Note.e, Note.b, Note.f.sharp]
  /// ```
  ///
  /// It is equivalent to sorting an array of the same [Note]s using the
  /// [compareByFifthsDistance] comparator:
  ///
  /// ```dart
  /// Note.c.circleOfFifths(distance: 3)
  ///   == ScalePattern.dorian.on(Note.c).degrees.skip(1)
  ///        .sorted(Note.compareByFifthsDistance)
  /// ```
  /// ---
  /// See also:
  /// * [splitCircleOfFifths] for a different representation of the same
  ///   circle of fifths.
  List<Note> circleOfFifths({int distance = chromaticDivisions ~/ 2}) {
    final (:down, :up) = splitCircleOfFifths;

    return [
      ...down.take(distance).toList(growable: false).reversed,
      this,
      ...up.take(distance),
    ];
  }

  /// The distance in relation to the circle of fifths.
  ///
  /// Example:
  /// ```dart
  /// Note.c.circleOfFifthsDistance == 0
  /// Note.d.circleOfFifthsDistance == 2
  /// Note.a.flat.circleOfFifthsDistance == -4
  /// ```
  int get circleOfFifthsDistance => Note.c.fifthsDistanceWith(this);

  /// The fifths distance between this [Note] and [other].
  ///
  /// Example:
  /// ```dart
  /// Note.c.fifthsDistanceWith(Note.e.flat) == -3
  /// Note.f.sharp.fifthsDistanceWith(Note.b) == -1
  /// Note.a.flat.fifthsDistanceWith(Note.c.sharp) == 11
  /// ```
  int fifthsDistanceWith(Note other) =>
      Interval.P5.circleDistance(from: this, to: other).$1;

  /// The [Interval] between this [Note] and [other].
  ///
  /// Example:
  /// ```dart
  /// Note.c.interval(Note.d) == Interval.m2
  /// Note.d.interval(Note.a.flat) == Interval.d5
  /// ```
  @override
  Interval interval(Note other) => Interval.fromSizeAndSemitones(
    baseNote.intervalSize(other.baseNote),
    difference(other) % chromaticDivisions,
  );

  /// Transposes this [Note] by [interval].
  ///
  /// Example:
  /// ```dart
  /// Note.c.transposeBy(Interval.tritone) == Note.f.sharp
  /// Note.a.transposeBy(-Interval.M2) == Note.g
  /// ```
  @override
  Note transposeBy(Interval interval) {
    final transposedBaseNote = baseNote.transposeBySize(interval.size);
    final positiveDifference = interval.isDescending
        ? transposedBaseNote.positiveDifference(baseNote)
        : baseNote.positiveDifference(transposedBaseNote);

    final accidentalSemitones =
        (accidental.semitones * interval.size.sign) +
        ((interval.semitones * interval.size.sign) - positiveDifference);
    final semitonesOctaveMod =
        accidentalSemitones -
        chromaticDivisions * ((interval.size.abs() - 1) ~/ 7);

    return Note(
      transposedBaseNote,
      Accidental(semitonesOctaveMod * interval.size.sign),
    );
  }

  /// The string representation of this [Note] based on [formatter].
  ///
  /// Example:
  /// ```dart
  /// Note.d.flat.toString() == 'D♭'
  /// Note.d.flat.toString(formatter: const RomanceNoteNotation()) == 'Re♭'
  /// Note.d.flat.toString(formatter: const GermanNoteNotation()) == 'Des'
  /// ```
  @override
  String toString({
    Formatter<Note> formatter = const EnglishNoteNotation(),
  }) => formatter.format(this);

  @override
  bool operator ==(Object other) =>
      other is Note &&
      baseNote == other.baseNote &&
      accidental == other.accidental;

  @override
  int get hashCode => Object.hash(baseNote, accidental);

  @override
  int compareTo(Note other) => compareMultiple(_comparators(this, other));
}

/// The [NotationSystem] interface for [Note].
abstract interface class NoteNotation extends NotationSystem<Note> {
  /// The [BaseNote] notation system used to format the [Note.baseNote].
  final NotationSystem<BaseNote> baseNoteNotation;

  /// The [Accidental] notation system used to format the [Note.accidental].
  final NotationSystem<Accidental> accidentalNotation;

  /// Creates a new [NoteNotation].
  const NoteNotation({
    this.baseNoteNotation = const EnglishBaseNoteNotation(),
    this.accidentalNotation = const SymbolAccidentalNotation(),
  });
}

/// The English notation system for [Note].
final class EnglishNoteNotation extends NoteNotation {
  /// Creates a new [EnglishNoteNotation].
  const EnglishNoteNotation({
    super.baseNoteNotation = const EnglishBaseNoteNotation(),
    super.accidentalNotation = const SymbolAccidentalNotation(
      showNatural: false,
    ),
  });

  /// The [EnglishNoteNotation] format variant that shows the
  /// [Accidental.natural] accidental.
  static const showNatural = EnglishNoteNotation(
    accidentalNotation: SymbolAccidentalNotation(),
  );

  /// Creates a new [EnglishNoteNotation] using ASCII characters.
  const EnglishNoteNotation.ascii({
    super.baseNoteNotation = const EnglishBaseNoteNotation(),
  }) : super(
         accidentalNotation: const SymbolAccidentalNotation.ascii(
           showNatural: false,
         ),
       );

  @override
  String format(Note note) =>
      note.baseNote.toString(formatter: baseNoteNotation) +
      note.accidental.toString(formatter: accidentalNotation);

  @override
  bool matches(String source) => source.isNotEmpty;

  @override
  Note parse(String source) {
    // First character is the base note
    if (!baseNoteNotation.matches(source[0])) {
      throw FormatException('Invalid BaseNote', source[0], 0);
    }
    final baseNote = baseNoteNotation.parse(source[0]);

    // Remaining characters are the accidental (if any)
    final accidentalSource = source.length > 1 ? source.substring(1) : '';
    final accidental = accidentalNotation.parse(accidentalSource);

    return Note(baseNote, accidental);
  }
}

/// The German alphabetic notation system for [Note].
///
/// See [Versetzungszeichen](https://de.wikipedia.org/wiki/Versetzungszeichen).
final class GermanNoteNotation extends NoteNotation {
  /// Creates a new [GermanNoteNotation].
  const GermanNoteNotation({
    super.baseNoteNotation = const GermanBaseNoteNotation(),
    super.accidentalNotation = const GermanAccidentalNotation(),
  });

  @override
  String format(Note note) => switch (note) {
    Note(baseNote: BaseNote.b, accidental: Accidental.flat) => 'B',

    Note(baseNote: BaseNote.a || BaseNote.e, :final accidental)
        when accidental.isFlat =>
      note.baseNote.toString(formatter: baseNoteNotation) +
          accidental.toString(formatter: accidentalNotation).substring(1),

    Note(:final baseNote, :final accidental) =>
      baseNote.toString(formatter: baseNoteNotation) +
          accidental.toString(formatter: accidentalNotation),
  };

  @override
  Note parse(String source) {
    if (source.isEmpty) throw FormatException('Invalid Note', source);
    if (source.toLowerCase() == 'b') {
      return const Note(BaseNote.b, Accidental.flat);
    }

    // For A and E with flats, the 'es' suffix is shortened to 's'
    if (source.length > 1) {
      final firstChar = source[0];
      if ((firstChar == 'A' ||
              firstChar == 'a' ||
              firstChar == 'E' ||
              firstChar == 'e') &&
          source.substring(1).startsWith('s') &&
          !source.substring(1).startsWith('es')) {
        final baseNote = baseNoteNotation.parse(firstChar);
        final accidental = accidentalNotation.parse('e${source.substring(1)}');
        return Note(baseNote, accidental);
      }
    }

    // Standard parsing: first character is base note, rest is accidental
    final baseNote = baseNoteNotation.parse(source[0]);
    final accidentalSource = source.length > 1 ? source.substring(1) : '';
    final accidental = accidentalNotation.parse(accidentalSource);

    return Note(baseNote, accidental);
  }
}

/// The Romance alphabetic notation system for [Note].
final class RomanceNoteNotation extends NoteNotation {
  /// Creates a new [RomanceNoteNotation].
  const RomanceNoteNotation({
    super.baseNoteNotation = const RomanceBaseNoteNotation(),
    super.accidentalNotation = const SymbolAccidentalNotation(
      showNatural: false,
    ),
  });

  /// The [RomanceNoteNotation] format variant that shows the
  /// [Accidental.natural] accidental.
  static const showNatural = RomanceNoteNotation(
    accidentalNotation: SymbolAccidentalNotation(),
  );

  /// Creates a new [RomanceNoteNotation] using ASCII characters.
  const RomanceNoteNotation.ascii({
    super.baseNoteNotation = const RomanceBaseNoteNotation(),
  }) : super(
         accidentalNotation: const SymbolAccidentalNotation.ascii(
           showNatural: false,
         ),
       );

  @override
  String format(Note note) =>
      note.baseNote.toString(formatter: baseNoteNotation) +
      note.accidental.toString(formatter: accidentalNotation);

  @override
  Note parse(String source) {
    if (source.isEmpty) throw FormatException('Invalid Note', source);

    // Find where the base note ends and accidental begins
    // Romance base notes can be 2-3 characters
    var baseNoteStr = '';
    var accidentalStr = '';

    const baseNotes = ['Do', 'Re', 'Mi', 'Fa', 'Sol', 'La', 'Si'];

    for (final baseNoteOption in baseNotes) {
      if (source.toLowerCase().startsWith(baseNoteOption.toLowerCase())) {
        baseNoteStr = source.substring(0, baseNoteOption.length);
        accidentalStr = source.substring(baseNoteOption.length);
        break;
      }
    }

    if (baseNoteStr.isEmpty) throw FormatException('Invalid Note', source);

    final baseNote = baseNoteNotation.parse(baseNoteStr);
    final accidental = accidentalNotation.parse(accidentalStr);

    return Note(baseNote, accidental);
  }
}

/// A list of notes extension.
extension Notes on List<Note> {
  /// Flattens all notes on this [List].
  List<Note> get flat => map((note) => note.flat).toList();

  /// Sharpens all notes on this [List].
  List<Note> get sharp => map((note) => note.sharp).toList();

  /// Makes all notes on this [List] natural.
  List<Note> get natural => map((note) => note.natural).toList();

  /// Creates a [Pitch] at [octave] for each [Note] in this list.
  ///
  /// Example:
  /// ```dart
  /// [Note.a, Note.c, Note.e].inOctave(4)
  ///   == [Note.a.inOctave(4), Note.c.inOctave(4), Note.e.inOctave(4)]
  /// ```
  List<Pitch> inOctave(int octave) =>
      map((note) => note.inOctave(octave)).toList();
}

albertms10 / music_notes / 17009263791

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous