zema_text 0.0.1

A Flutter widget package that parses raw Ge'ez text and renders it alongside traditional Yaredawi Zema musical notation (Yefidel Qirts and Melekket markers).

zema_text is a Flutter widget package designed to parse raw Ge'ez text and beautifully render it alongside its traditional, sacred musical notation.

Historically, the chants of Saint Yared (Zema) use physical vocal-shaping symbols (Yefidel Qirts) and mnemonic markers (Melekket) written directly above the Ge'ez alphasyllabary. This package handles the tokenizing and layout work needed to attach these Unicode markers to their base character and render them above it, without clipping or spacing issues.

Background

Ethiopian Orthodox Tewahedo liturgical chant (Yaredawi Zema) is notated by combining plain Ge'ez script with two families of markers placed above the base characters:

• Yefidel Qirts — vocal-shaping symbols indicating how a syllable should be sung (pitch, ornamentation, breath).
• Melekket — mnemonic markers that cue a singer to a known melodic pattern.

Getting started

flutter pub add zema_text

Usage

Source syntax

Raw Zema text is plain text with chord/notation markers written in [brackets]. A bracket pairs with the single character immediately before it:

import 'package:zema_text/zema_text.dart';

// ቅዱስ ("Qeddus" / "Holy") — the Trisagion refrain from the Ethiopian
// Orthodox Kidase (Divine Liturgy). 'ቅ' renders with the Kenat mark above
// it, 'ዱ' with the Difat mark above it, and 'ስ' plain.
const data = 'ቅ[${ZemaSymbols.kenat}]ዱ[${ZemaSymbols.difat}]ስ';

ZemaSymbols provides constants (with full Unicode metadata) for the ten traditional tonal marks, so you never have to copy-paste the raw glyphs:

Constant	Glyph	Name
ZemaSymbols.yizet	᎐	Yizet (ይዘት)
ZemaSymbols.deret	᎑	Deret (ደረት)
ZemaSymbols.rikrik	᎒	Rikrik (ርክርክ)
ZemaSymbols.shortRikrik	᎓	Short Rikrik (አጭር ርክርክ)
ZemaSymbols.difat	᎔	Difat (ድፋት)
ZemaSymbols.kenat	᎕	Kenat / Qenat (ቅናት)
ZemaSymbols.chiret	᎖	Chiret / Cheret (ጭረት)
ZemaSymbols.hidet	᎗	Hidet (ሂደት)
ZemaSymbols.deretHidet	᎘	Deret-Hidet (ደረት-ሂደት)
ZemaSymbols.kurt	᎙	Kurt / Qurt (ቁርጥ)

ZemaSymbols.all exposes the same ten marks as ZemaSymbol metadata objects (name, code point, Unicode name, HTML entity) for documentation, lookup, or building your own symbol picker UI.

Rendering

Drop ZemaText in wherever you'd use Text:

ZemaText(
  'ቅ[${ZemaSymbols.kenat}]ዱ[${ZemaSymbols.difat}]ስ',
  style: ZemaTextStyle(
    wordStyle: const TextStyle(fontSize: 28),
    chordStyle: const TextStyle(color: Colors.red),
    chordSpacing: 2,   // gap between mark and character
    chordScale: 0.65,  // mark font size, relative to wordStyle
  ),
  textAlign: TextAlign.center, // plus the rest of Text.rich's options
)

Every base character is dropped onto the same text baseline as the plain characters around it, with the notation marks floating in the space above the line — so a line mixing annotated and plain Ge'ez stays perfectly aligned instead of the annotated characters sinking below the others.

Malformed input (an unmatched [) throws a FormatException by default, matching how any other failing build() behaves. Supply errorBuilder to render a fallback instead:

ZemaText(
  rawInput,
  errorBuilder: (context, error) => Text('Invalid Zema text: ${error.message}'),
)

Working with tokens directly

The tokenizer and grouping logic are public too, if you want to inspect or transform Zema text without building a widget:

final tokens = lexer(rawText);      // List<Token>: WordToken / SpaceToken / ChordToken
final segments = parser(tokens);    // List<Segment>: WordSegment / ChordSegment

See example/ for a runnable playground app: a raw-text field feeding a live ZemaText preview, with every styling and layout option wired to a control so you can see changes in real time.

Package layout

• lib/src/lexer — scans raw text into a flat token stream.
• lib/src/parser — groups tokens into word/chord segments.
• lib/src/symbols — ZemaSymbols constants and ZemaSymbol metadata.
• lib/src/style — ZemaTextStyle styling options.
• lib/src/widget — the ZemaText widget.

Additional information

Contributions and issue reports are welcome.