Persian-to-Braille began as a project focused on Persian text translation. In its current v2 architecture, that original idea has expanded into something much broader: a modular Braille platform with formal specifications, reusable translation engines, a public SDK, Microsoft 365 integrations, reverse-translation foundations, and now a dedicated Braille Music subsystem.
The newest major capability is MIDI to Braille Music.
Instead of treating music accessibility as an afterthought inside the user interface, Persian-to-Braille now contains a dedicated, platform-agnostic Music Braille engine. The goal is to take structured musical information from Standard MIDI Files and transform a selected musical source into a deterministic Braille representation that can be consumed in different environments.
From a MIDI file to Braille
The current production-integrated workflow begins with a standard .mid or .midi file.
The file is parsed, its musical sources are inspected, and available lines are exposed to the user using a concrete identity: Track + Channel. The user selects exactly one source line and the engine then performs the notation and rhythm processing required for Music Braille generation.
The resulting flow is:
MIDI file
↓
SMF parsing
↓
Track + Channel source-line discovery
↓
Explicit source-line selection
↓
Notation and rhythm processing
↓
Music Braille encoding
↓
Unicode Music Braille / BRF
↓
Application integration
This architecture deliberately avoids guessing which channel is the melody, accompaniment, percussion, pad, sequence, or another musical role. MIDI files are often created for playback rather than notation, and automatically deciding what should be preserved or discarded can easily change the musical meaning.
Persian-to-Braille therefore follows a stricter rule: the software exposes the available source lines and lets the user decide what should be translated.
Track + Channel as the source identity
A MIDI track alone is not always enough to identify the musical material that should be translated. A track can contain multiple channels, while different tracks can also use the same channel number.
For this reason, the current Music Braille architecture treats Track + Channel as the source-line identity.
This makes the translation boundary explicit and reproducible. The same selected source line can be reprocessed without relying on heuristics or hidden classification decisions.
No silent filtering
One of the core design principles of the project is to avoid silently changing semantic content.
When a source line contains material that cannot be represented correctly by the currently supported Music Braille profile, the system is designed to fail closed rather than quietly deleting notes, simplifying the line, or inventing an approximation.
This is particularly important for accessibility software. A visually plausible result is not enough if the underlying musical information has been altered without the user knowing.
A dedicated Music Braille engine
The Braille Music implementation is not embedded inside Microsoft Word.
It lives in a dedicated package:
@persian-braille/music
The package contains the platform-agnostic Music Braille runtime, including MIDI parsing, source-line classification, notation construction, rhythm quantization, atomic and stateful encoding, piano-roll reduction, measure handling, meter-change serialization, in-accord representation, and related conformance logic.
Applications do not need to depend on these internals directly. The recommended consumer boundary remains the public SDK:
Application
↓
@persian-braille/sdk
↓
@persian-braille/music
This separation means that Microsoft Word is only one host. The Music engine can later be reused by command-line tools, web applications, desktop software, other Office hosts, or third-party integrations.
Microsoft Word integration
The first production-integrated Music Braille host is Microsoft Word Desktop on Windows.
Inside the Persian-to-Braille task pane, the application now exposes two distinct feature surfaces:
Persian / English
Music / MIDI
The Music / MIDI workflow allows the user to:
- choose a MIDI file;
- inspect the available Track + Channel source lines;
- select exactly one source line;
- generate a Unicode Music Braille preview;
- generate a BRF-compatible representation;
- invalidate and regenerate the preview when the selected source changes;
- insert the exact generated Braille into the current Word caret position.
The Word integration does not recompute the result during insertion. The exact preview that the user reviewed is the value written into the document.
Real-world MIDI hardening
Synthetic fixtures are useful for unit tests, but real MIDI files expose a very different class of problems.
Phase 14 therefore included real-world hardening against multi-track orchestral and electronic MIDI structures. This work covered parser metadata, non-pitched source classification, pitch-bend scope, composite rhythm quantization, tied-duration decomposition, in-accord behavior, meter changes, source isolation, rhythm coherence, and bounded piano-roll reduction.
The objective was not to make every possible MIDI file magically translatable. Instead, the goal was to establish a deterministic boundary between supported musical material and unsupported material.
When the system can translate a source line reliably, it produces Braille. When it cannot, it reports the failure instead of hiding the limitation.
Unicode and BRF output
The pipeline supports both Unicode Braille output and BRF/Braille ASCII projection.
Unicode is useful for modern applications, documents, previews, testing, and direct insertion into environments such as Microsoft Word.
BRF remains important for established Braille workflows, embossing pipelines, file interchange, and compatibility with systems that expect Braille ASCII representations.
Providing both representations allows the Music engine to bridge modern application interfaces and traditional Braille production workflows.
Architecture over feature-specific shortcuts
A significant part of this work was not visible in the user interface.
Phase 14 added formal contracts, conformance seeds, architecture audits, validators, regression suites, package-boundary checks, Windows live-acceptance evidence, public SDK packaging validation, and distribution checks.
The public SDK packaging validation is especially important. The Music engine is now a real publishable runtime dependency of the SDK, and the repository validates an isolated packed consumer installation rather than relying only on workspace behavior.
That means the project tests the same architectural question a third-party consumer will eventually face: can the packaged SDK and its runtime dependencies actually be installed and used outside the repository?
A broader direction for Persian-to-Braille
The addition of Braille Music changes the identity of the project.
Persian-to-Braille is no longer best described as a single-purpose Persian text converter. It is becoming a broader Braille platform built around reusable engines and explicit public boundaries.
The current architecture includes:
- a formal Persian Braille specification;
- deterministic Unicode and Persian normalization;
- a Persian Braille Core engine;
- a public TypeScript SDK;
- Microsoft Word, Excel, and PowerPoint integrations;
- reverse-translation foundations;
- a dedicated Music Braille engine;
- MIDI source inspection and translation;
- Unicode and BRF output;
- automated architecture, conformance, regression, and package validation.
The long-term direction is to keep these capabilities independent enough that other applications can use them without depending on Microsoft Office.
Current scope
The current Music Braille capability is intentionally bounded.
It supports MIDI-based workflows and explicit single-source-line translation. It does not claim automatic translation of every track in arbitrary MIDI files, automatic melody detection, automatic instrument-role inference, or silent simplification of unsupported material.
Microsoft Word Desktop on Windows is the first live-validated host for Music Braille.
MusicXML is planned separately for a later project phase.
Open-source foundation
Persian-to-Braille v2 is released under the MIT License.
The project is designed so that the translation engines, SDK, specifications, tests, and validation tooling can form a reusable foundation for future accessibility software.
The objective is straightforward but ambitious: make Braille translation infrastructure more explicit, more testable, more reusable, and easier to integrate into real software.
With MIDI to Braille Music, Persian-to-Braille takes another substantial step toward that goal.
