guitar_chord_library 0.1.0

A perfect simple chord library for guitar and ukulele. Both flat and sharp note usage are supported.

Guitar Chord Library

A comprehensive, lightweight chord library for Guitar and Ukulele in Dart and Flutter. Supports sharp (#) and flat (b) notations, chord name parsing, transposing, capo calculations, reverse chord lookup, and ASCII diagram visualizers.

Pull requests are always welcome!

---

Features

• Instruments Supported: 6-string Guitar and 4-string Ukulele.
• Direct Chord Search by Name: Search chords directly using real-world names like "Am", "C#m7", "Bbmaj7", "Dsus4".
• Chord Transposition: Shift chords and root keys up or down by semitones.
• Capo Helper: Calculate playable chord shapes when using a capo.
• Reverse Chord Finder: Identify chord names and positions from fret fingerings (e.g. [-1, 3, 2, 0, 1, 0] -> Cmajor).
• Visual ASCII Diagram & Tab: Generate text-based chord boxes and tablature without any UI framework dependencies.
• JSON Serialization: Full toJson() and fromJson() support for saving to databases or APIs.
• Convenient Parsers: Pre-parsed fretList and fingerList (List<int>).
• Fast & Lightweight: Cached singletons and const data models.

---

Getting Started

Add guitar_chord_library to your pubspec.yaml:

dependencies:
  guitar_chord_library: ^0.1.0

Or run:

dart pub add guitar_chord_library
# or for Flutter:
flutter pub add guitar_chord_library

---

Usage Examples

1. Select Instrument & Look Up Chords

import 'package:guitar_chord_library/guitar_chord_library.dart';

void main() {
  final guitar = GuitarChordLibrary.instrument(InstrumentType.guitar);
  final ukulele = GuitarChordLibrary.instrument(InstrumentType.ukulele);

  // Search by full name (C, Am, C#m7, Dsus4, etc.)
  final chord = guitar.getChordByName('Am');
  print('Full Name: ${chord?.name}'); // Aminor
  print('Short Name: ${chord?.shortName}'); // Am (Amajor -> A, Aminor -> Am)

  // Get chord positions directly by chord name
  final positions = guitar.getPositionsByName('C')!;
  final pos = positions.first;
  print('Frets list: ${pos.fretList}'); // [-1, 3, 2, 0, 1, 0]
  print('Fingers list: ${pos.fingerList}'); // [0, 3, 2, 0, 1, 0]
}

2. Chord Transposition

Easily transpose songs into different keys:

// Transpose root notes
ChordHelper.transpose('C', semitones: 2); // 'D'
ChordHelper.transpose('C', semitones: -1); // 'B'

// Transpose full chord names
ChordHelper.transposeChord('Am', semitones: 2); // 'Bm'
ChordHelper.transposeChord('F#7', semitones: -1, useFlat: true); // 'F7'

3. Capo Helper

Calculate what chord shape to play when using a capo:

// If the original song has G#m and capo is on 4th fret:
ChordHelper.getPlayableChord(originalChord: 'G#m', capoFret: 4); // 'Em'

// What sounding chord is produced when playing C with capo on 2nd fret:
ChordHelper.getSoundingChord(playedChord: 'C', capoFret: 2); // 'D'

4. Reverse Chord Lookup (Identify from Frets)

Find what chord corresponds to a finger placement:

final matchingChords = guitar.identifyChord([-1, 3, 2, 0, 1, 0]);
print(matchingChords.map((c) => c.name)); // ['Cmajor']

5. ASCII Chord Box Diagram & Tab

Render text-based diagrams for console, logs, or text displays:

final pos = guitar.getChordPositions('C')!.first;

// ASCII Chord Box Diagram
print(pos.toAsciiDiagram(title: 'C Major'));
/*
  C Major (fr 1)
  x  3  2  0  1  0 
  +--+--+--+--+--+--+
  |  |  |  |  | 1|  |
  +--+--+--+--+--+--+
  |  |  | 2|  |  |  |
  +--+--+--+--+--+--+
  |  | 3|  |  |  |  |
  +--+--+--+--+--+--+
  |  |  |  |  |  |  |
  +--+--+--+--+--+--+
*/

// ASCII Tablature
print(pos.toAsciiTab());
/*
e |--0--|
B |--1--|
G |--0--|
D |--2--|
A |--3--|
E |--x--|
*/

6. JSON Serialization

// Serialize
final Map<String, dynamic> json = chord.toJson();

// Deserialize
final Chord restored = Chord.fromJson(json);

---

License

This project is licensed under the MIT License - see the LICENSE file for details.