How mersenne-sister/mmlxr works
Main System Components
• Frontend/UI Layer
• This includes everything rendered in the browser using HTML (compiled from Pug templates in src/views), CSS (Stylus files in src/style), and JavaScript.
• Key interactive components are the code editor (integrated via Ace Editor files under src/js/ace), the piano roll, track tab, file management UI, and other modal dialogs.
• A front-end framework is visually enhanced by Semantic UI (both the provided Semantic-UI directory and related assets in docs).
• MML Compiler/Processing Engine (Worker Thread)
• Core music processing modules reside in src/mmlxr. This is where the MML is compiled, macros, comments, repeats, and groups are processed, and events are created.
• A dedicated PEG.js parser (in src/peg) extracts grammar for the MML language.
• This engine is responsible for “compiling” the user’s input MML, preparing events for playback, and carrying out the audio synthesis logic.
• Communication Infrastructure
• A two-thread architecture is in place. The main thread handles UI and audio node management with Web Audio while a background worker thread handles heavy processing tasks.
• The README play sequence illustrates clearly the message passing between the worker thread and the main thread (using messages such as COM_PLAY, COM_PLAYSOUND, COM_BUFFER, and COM_STOPSOUND).
• Audio Engine
• Utilizes the Web Audio API. The main thread sets up audio nodes (ScriptProcessor or audio callbacks) to receive buffers produced by the worker thread.
• Modules within src/mmlxr (e.g., wave_generator.ts) work in tandem with the audio engine to convert compiled events into sound.
• Build and Configuration Environment
• Tools like gulp (gulpfile.js), webpack (webpack.config.js), and package.json indicate a modern build process.
• Configuration files (config.yml, tsconfig.json, etc.) set up the environment for both development and production.
Determining the Relationships and Interactions
• Data Flow and Control Path:
• The user interacts with the UI in the browser (e.g., entering MML code, using the editor’s autocompletion) which is then sent to the worker thread.
• The worker thread processes the MML code by calling various submodules (like the parser, macro processor, note tab processor, etc.) and compiles it into a sequence of events.
• Once compiled, the worker sends data back (as buffer chunks) to the main thread where the Web Audio API picks up these buffers to play sound.
• There is bidirectional communication: control commands (e.g., stopping sound) flow from the UI to the worker, and playback data flows from the worker back to the UI.
• Inter-module interactions:
• The MML compilation workflow touches various logical modules (flmml_analyzer, file_manager, mixer, etc. in src/mmlxr) and interacts with the audio engine.
• The Peg parser (for MML syntax) is integrated as part of this pipeline.
Architectural Patterns & Design Principles
• Separation of Concerns:
• Clear division between UI (handling rendering and user interaction) and background processing (compiling MML, generating audio data).
• Asynchronous Communication:
• Use of Web Worker for heavy compute ensures that the UI remains responsive.
• The detailed play sequence in the README illustrates how command messages traverse between main and worker threads.
• Modular Design:
• The numerous TypeScript modules under src/mmlxr indicate well-organized components for each feature (editor, keyboard, piano roll, etc.).
• The presence of distinct folders (src/js for editor support, src/style for styling, src/views for templating, etc.) reinforces this modularity.
• Intermediary steps in the Web Worker where the MML code flows through parsing (PEG.js), macro/comment and note processing, and then compilation into events.