How sitandr/conchord works
Project’s Nature
• Conchord is a Typst package aimed at string-instrument chord generation and rendering.
• It leverages a WebAssembly (WASM) module to generate chord tab strings and uses multiple modules to render chords and tabs.
Major Components
• Core Library Module: File “lib.typ” acts as the central entry point that aggregates and exposes functionality.
• Chord Generation Module:
– Files in the “gen” directory (e.g., “gen/gen.typ” and “gen/conchord_gen.wasm”) implement the WASM-based music theory engine that generates chord tab strings.
– Functions like get-chords, n-best, and get-chord are part of this module.
• Chord Rendering Module:
– This includes the “smart-chord” function and related chordgen functions.
• Tabs Rendering Module:
– Located in the “tabs” directory (with files such as “tabs/drawing.typ”, “tabs/gen.typ”, “tabs/tabs.typ”), this module implements the DSL for rendering tablature.
– It supports various features like duration, bars, ties, slides, bends, vibratos, and even custom content.
• Reference & Documentation:
– The “reference” directory holds documentation (e.g., “reference/reference.typ” and “reference/reference.pdf”) that details the API and chord naming rules.
• Examples:
– The “examples” folder contains numerous Typst example scripts, which illustrate how to use chord generation, chord drawing, tab features, and even integration of chord libraries within complete song documents.
Relationships/Interactions
• User Code (written in Typst using Conchord) invokes high-level functions (e.g., smart-chord, new-chordgen, overchord) from the Core Library.
• When a chord needs to be generated, the call flows from a rendering function (such as smart-chord) to the chord generation functions (get-chords) in the Gen module.
• The Gen module sends data to the WASM engine (“conchord_gen.wasm”), which returns all possible chord variants.
• A parallel flow exists for handling tablature where user-written tab strings are parsed by the Tabs module and rendered accordingly.
• Reference documentation supports developers by explaining naming conventions and low-level design choices.
Architectural Patterns & Technologies
• Modular Structure – Each major functional area is separated into its own directory, promoting separation of concerns.
• WASM Integration – Use of the WASM engine for runtime chord generation adds an additional layer external to the typical Typst rendering process.
• Extensibility – The package is designed so that users can either use built-in functions (e.g., smart-chord) or create custom chord rendering (using new-chordgen).