custom_flutter_chord 1.2.2

Lyrics Chord parser and renderer for Flutter. It also comes with transpose and auto-scroll features.

custom_flutter_chord

Chord parser and renderer for Flutter apps, with transposition, key-aware degrees, minor-key conversion and auto-scroll.

Proprietary software of GOVERNOR LTD. Use is permitted only under explicit prior authorization obtained through the official channels ([e-mail]). Copying and modification without authorization are not permitted. See LICENSE.

Features

• Chord/lyrics parsing into a ChordLyricsDocument
• Chord transposition by semitone increment
• Chord parsing with support for modifiers, extensions and inversions
• Multiple chord notations (american, italian, german, traditionalGerman, french, portuguese, roman, number)
• Functional degrees relative to the song key via keyRoot
• Minor-key conversion via MinorMode (relative / parallel)
• Auto scroll with adjustable speed
• Show/hide chords and lyrics independently
• Underline chord syllables
• Tap on chord callback
• ChordPro directives: chorus ({soc}/{eoc}), capo and comments
• Customizable text/chord styles, padding, line height and alignment
• Leading and trailing widgets

Usage

1) Render the lyrics and chords directly.

final textStyle = TextStyle(fontSize: 18, color: Colors.white);
final chordStyle = TextStyle(fontSize: 20, color: Colors.green);

final lyrics = '''
[C]Give me Freedom, [F]Give me fire
[Am] Give me reason, [G]Take me higher
''';

@override
Widget build(BuildContext context) {
  return LyricsRenderer(
    lyrics: lyrics,               // Lyrics and chords in ChordPro format
    textStyle: textStyle,         // TextStyle for the lyrics
    chordStyle: chordStyle,       // TextStyle for the chords
    widgetPadding: 50,            // Sum of the left & right padding (int)
    onTapChord: (String chord) {  // Called with the chord as rendered
      print('pressed chord: $chord');
    },
    transposeIncrement: 0,        // Semitones to transpose (int)
    scrollSpeed: 0,               // Auto-scroll speed (int)
    showChord: true,              // Show the chords
    showText: true,               // Show the lyrics
    chordNotation: ChordNotation.american,
    keyRoot: null,                // Pitch class of the song tonic (0-11, C = 0)
    minorMode: MinorMode.none,    // none / relative / parallel
    underlineChordSyllables: true,
  );
}

2) Get a parsed ChordLyricsDocument and style it as you like.

final textStyle = TextStyle(fontSize: 18, color: Colors.white);
final chordStyle = TextStyle(fontSize: 20, color: Colors.green);

final lyrics = '''
[C]Give me Freedom , [F]Give me fire
[Am] Give me reason , [G]Take me higher
''';

final chordProcessor = ChordProcessor(context);
final ChordLyricsDocument chordLyricsDocument = chordProcessor.processText(
  text: lyrics,
  lyricsStyle: textStyle,
  chordStyle: chordStyle,
  transposeIncrement: 0,
);

Implementation details

This section explains the main logic used for chord parsing, transposition and rendering.

Chord parsing

Each chord is split with ^([A-Ga-g][#b]?)(.*)$, separating the root (e.g. C, C#, Db) from the rest of the symbol (quality, extensions, inversions). Flats are normalized to sharps (Db -> C#, Bb -> A#, …) so that a consistent semitone index can be used, based on ['C','C#','D','D#','E','F','F#','G','G#','A','A#','B']. Slash chords are handled by processing the root and the bass note separately and re-joining them with /.

Order of operations

The chord text shown on screen — and the value passed to onTapChord — is produced by a single pipeline, so the rendered chord and the tapped chord always match:

1. transposeIncrement is applied to the parsed chord.
2. minorMode conversion is applied on top of the transposed chord.
3. chordNotation maps the result to the target notation (including the key-relative degrees described below).

Degrees relative to the key (keyRoot)

With ChordNotation.number or ChordNotation.roman, chords are rendered as degrees. By default the mapping is absolute (C = 1/I). When keyRoot is set to the pitch class of the song's original tonic (0-11, C = 0), the degrees become functional and relative to that key — in G: G → 1/I, C → 4/IV, Em → 6/vi. The applied transposeIncrement is accounted for internally, so the degrees stay invariant under transposition.

Roman degrees are quality-aware: uppercase for major, lowercase for minor, ° for diminished and + for augmented. Slash chords convert both the root and the bass.

Minor-key conversion (MinorMode)

MinorMode selects how the song is converted to a minor key, applied on top of the already transposed chords:

• MinorMode.none (default) — no conversion, the major key is kept.
• MinorMode.relative — relative minor. The chords themselves are left untouched (the chord set is the same); only the degree reference for the number/roman notations re-centres a minor third below the major tonic (e.g. C major → A minor).
• MinorMode.parallel — parallel minor. The tonic is kept and each diatonic chord of the major key is mapped to the natural-minor field: I→i, ii→ii°, iii→♭III, IV→iv, V→v, vi→♭VI, vii°→♭VII. In C: C→Cm, Dm→D°, Em→Eb, F→Fm, G→Gm, Am→Ab, B°→Bb.

Extensions (7, 9, sus, add, …) and slash chords are preserved; flat degrees are spelled with flats; chromatic chords (outside the major field) are kept unchanged.

The legacy minorScale boolean is still accepted for backwards compatibility; when minorMode is set it takes precedence.

Notes and limitations

• After conversion, chords are spelled with sharps except for the flat degrees of the parallel minor, which are spelled with flats.
• The enharmonic map is limited; unusual spellings may not be chosen contextually.
• Exotic modifiers may not be handled perfectly — the priority is to get the root and the chord quality right.

License

Copyright (c) 2026 GOVERNOR LTD. All rights reserved.

This package is proprietary software. Access, use, copying, modification and distribution are permitted only under explicit prior written authorization issued by GOVERNOR LTD through its official channels. Unauthorized copying or modification of the source code is prohibited.

For authorization requests and licensing inquiries: [e-mail] — governor.ltd. Full terms in LICENSE.