glaemscribe 0.2.0

Python implementation of Glaemscribe transcription engine

Glaemscribe-py

A Python implementation of Glaemscribe for transcribing Tolkien's Elvish languages (Quenya and Sindarin) to Tengwar script using Unicode.

Glaemscribe-py is a Python port of the original Glaemscribe. It focuses on Elvish → Tengwar transcription and outputs Unicode Private Use Area (PUA) characters instead of font-specific codes, so you can use modern Unicode Tengwar fonts.

Key features

• Quenya transcription – Classical Quenya → Tengwar
• Sindarin transcription – General Sindarin → Tengwar
• Font flexibility – Works with any Unicode Tengwar TTF or OTF font
• PNG rendering helpers – Example scripts for image output

Installation

Python 3.8+ is required.

pip install glaemscribe

Quenya and Sindarin transcription work out of the box. English phonetic transcription additionally requires the phonetic extra and the espeak-ng system binary:

pip install glaemscribe[phonetic]

# Ubuntu / Debian
sudo apt install espeak-ng

# macOS
brew install espeak-ng

Without these, calling transcribe(..., mode="english") or text_to_ipa() will raise a clear ImportError with install instructions.

Fonts

This library outputs Unicode Tengwar (PUA) and can be used with any Unicode Tengwar font. The repository includes a small, curated set of Unicode Tengwar fonts, all under the SIL Open Font License (OFL):

• FreeMonoTengwar – baseline font used during development
• AlcarinTengwar-Regular – Unicode Tengwar font by Toshi Omagari
• AlcarinTengwar-Bold – Bold companion font by Toshi Omagari

These fonts live under src/glaemscribe/fonts/ and are suitable for most uses. See the respective licence files alongside the fonts for details. There are many Tengwar fonts available online, an example of how to use a custom font is shown in the Quick start section.

Quick start

Simple API (recommended)

The easiest way to use Glaemscribe is with the high-level transcribe() function:

from glaemscribe import transcribe, list_modes
from glaemscribe.render import TengwarRenderer

# Simple Quenya transcription
quenya_text = transcribe("Elen síla lúmenn' omentielvo", mode="quenya")
renderer = TengwarRenderer()
renderer.render_to_file(quenya_text, "quenya_text.png")
print(quenya_text)

# Sindarin transcription
sindarin_text = transcribe("Ai na vedui Dúnadan !", mode="sindarin")
# For other tengwar fonts simply pass in the path to the ttf or otf file
renderer_alcarin = TengwarRenderer(font_name='alcarin-bold', font_size=36)
renderer_alcarin.render_to_file(sindarin_text, "sindarin_text.png")

# List available modes
modes = list_modes()
print(modes)  # ['quenya', 'sindarin', 'english', ...]

Rendered outputs using the default fonts look like this:

Quenya example text rendered to Tengwar using FreeMonoTengwar font

Sindarin example text rendered to Tengwar using AlcarinTengwar-Bold font

Mode aliases for convenience:

• "quenya" → Quenya Classical Tengwar
• "sindarin" → Sindarin General Use
• "sindarin-beleriand" → Sindarin Beleriand mode
• "english" → English Tengwar (experimental)

See scripts/simple_usage.py for more examples.

Advanced usage (custom modes/options)

For advanced use cases, you can use the lower-level API:

from glaemscribe.parsers.mode_parser import ModeParser
from glaemscribe.resources import get_mode_path

parser = ModeParser()
mode = parser.parse(str(get_mode_path('quenya-tengwar-classical')))
mode.processor.finalize({})

success, result, debug = mode.transcribe("Elen síla lúmenn' omentielvo")
if success:
    print(result)

Example Scripts

The scripts/ directory contains several useful examples:

• simple_usage.py - Simple API examples for common use cases
• render_text.py - Render Tengwar text to PNG images, also accepts custom fonts
• validate_unicode.py - Validate Unicode transcriptions
• render_poem.py - Render the Namárië poem with multiple fonts

Example:

python scripts/simple_usage.py
python scripts/render_text.py "Elen síla" --mode quenya --output output.png

Marimo notebooks (interactive examples)

The notebooks/ directory contains interactive marimo apps that show end-to-end usage patterns:

• notebooks/marimo_getting_started.py - Intro walkthrough for modes, transcription, and rendering
• notebooks/marimo_namarie_poem.py - Interactive rendering of Namárië with font controls
• notebooks/marimo_tengwar_espeak.py - IPA + Tengwar workflow using espeak-ng (phonetic pipeline)

Install marimo:

pip install marimo

Launch any notebook app with:

marimo edit notebooks/marimo_getting_started.py
marimo edit notebooks/marimo_namarie_poem.py
marimo edit notebooks/marimo_tengwar_espeak.py

You can also run them directly as Python scripts:

python notebooks/marimo_getting_started.py

Contributing

Contributions are welcome! When contributing:

1. Maintain compatibility with original Glaemscribe behavior
2. Add tests for new features
3. Follow existing code style and patterns
4. Update documentation as needed

License

This port follows the same license as the original Glaemscribe project (GNU Affero General Public License v3.0).

Acknowledgments

• Benjamin Babut (Talagan) - Original creator of Glaemscribe
• The Tengwar and Quenya community - For supporting the creation of the original Glaemscribe

---