verovio_sys/
lib.rs

1//! Low-level [`cxx`] bridge to the [Verovio](https://www.verovio.org/) C++
2//! music engraving library.
3//!
4//! This crate compiles the vendored Verovio source tree into a static
5//! archive and exposes the `Toolkit` class through a thin C++ shim. You
6//! almost certainly want the safe wrapper in the [`verovio`](https://docs.rs/verovio)
7//! crate instead — this crate is a build dependency, not a user-facing API.
8
9#[cxx::bridge(namespace = "vrv_rs")]
10pub mod ffi {
11    unsafe extern "C++" {
12        include!("vrv_bridge.h");
13
14        #[namespace = "vrv"]
15        type Toolkit;
16
17        fn new_toolkit(init_fonts: bool) -> UniquePtr<Toolkit>;
18
19        fn get_version(tk: &Toolkit) -> String;
20
21        /// Point Verovio at a directory containing SMuFL font data
22        /// (Bravura.xml, Bravura/, etc.). Returns true on success. Must
23        /// succeed before any LoadData / RenderTo* call.
24        fn set_resource_path(tk: Pin<&mut Toolkit>, path: &str) -> bool;
25        fn get_resource_path(tk: &Toolkit) -> String;
26
27        /// Upstream `Doc::GetID` — opaque per-document identifier; useful
28        /// for diagnostics / log correlation. Non-`const` upstream.
29        fn get_id(tk: Pin<&mut Toolkit>) -> String;
30
31        // LoadData and SetOptions return bool: true on success, false on
32        // failure (Verovio logs the reason internally; the log surface is
33        // gated by a crate-level mutex in the safe wrapper).
34        fn load_data(tk: Pin<&mut Toolkit>, data: &str) -> bool;
35        /// Delegate to `Toolkit::LoadFile` — handles UTF-16 MusicXML and
36        /// compressed `.mxl` transparently. Use when you want the full
37        /// upstream loader rather than reading into a `String` first.
38        fn load_file(tk: Pin<&mut Toolkit>, filename: &str) -> bool;
39        /// Load a compressed MusicXML file (`.mxl`) from raw bytes.
40        fn load_zip_data_buffer(tk: Pin<&mut Toolkit>, data: &[u8]) -> bool;
41
42        fn set_options(tk: Pin<&mut Toolkit>, options: &str) -> bool;
43        fn reset_options(tk: Pin<&mut Toolkit>);
44        /// Apply a scoped selection (measure/staff range). See
45        /// `Toolkit::Select` upstream for the JSON schema. An empty
46        /// string / empty object clears the selection.
47        fn select(tk: Pin<&mut Toolkit>, selection: &str) -> bool;
48
49        // Toolkit::GetPageCount is non-const upstream — Verovio computes
50        // layout lazily on this call. Surface it as `Pin<&mut>` accordingly.
51        fn page_count(tk: Pin<&mut Toolkit>) -> i32;
52
53        // Const-correct getters.
54        fn get_options(tk: &Toolkit) -> String;
55        fn get_default_options(tk: &Toolkit) -> String;
56        /// Full option schema (type, default, min, max, grouped by
57        /// category). Const upstream.
58        fn get_available_options(tk: &Toolkit) -> String;
59
60        /// Typed scale setter — avoids round-tripping `{"scale": N}` JSON.
61        fn set_scale(tk: Pin<&mut Toolkit>, scale: i32) -> bool;
62        fn get_scale(tk: Pin<&mut Toolkit>) -> i32;
63
64        /// Force the input format instead of auto-detect. Accepts the same
65        /// strings Verovio's `--from` CLI flag does (`"mei"`, `"musicxml"`,
66        /// `"abc"`, `"pae"`, `"humdrum"`, …).
67        fn set_input_from(tk: Pin<&mut Toolkit>, format: &str) -> bool;
68        fn set_output_to(tk: Pin<&mut Toolkit>, format: &str) -> bool;
69
70        /// Re-seed the `@xml:id` generator. Pass `0` for a time-based
71        /// random seed. No-op when `--xml-id-checksum` is set.
72        fn reset_xml_id_seed(tk: Pin<&mut Toolkit>, seed: i32);
73
74        // Rendering surface. All are non-const upstream — Verovio computes
75        // layout lazily and stores it on the Toolkit instance.
76        fn render_to_svg(tk: Pin<&mut Toolkit>, page_no: i32, xml_declaration: bool) -> String;
77        fn render_to_midi(tk: Pin<&mut Toolkit>) -> String;
78        fn render_to_timemap(tk: Pin<&mut Toolkit>, json_options: &str) -> String;
79        fn render_to_expansion_map(tk: Pin<&mut Toolkit>) -> String;
80        /// Render the document as Plaine & Easie code. Only the top staff
81        /// / layer is exported (upstream limitation).
82        fn render_to_pae(tk: Pin<&mut Toolkit>) -> String;
83
84        /// Validate Plaine & Easie input — returns a JSON object with
85        /// warnings / errors. **Discards any previously loaded data.**
86        fn validate_pae(tk: Pin<&mut Toolkit>, data: &str) -> String;
87
88        /// Serialize the loaded document as MEI. `json_options` is upstream's
89        /// `{pageNo, scoreBased, basic, removeIds}` JSON document; pass an
90        /// empty string for defaults.
91        fn get_mei(tk: Pin<&mut Toolkit>, json_options: &str) -> String;
92
93        /// Extract descriptive features tailored for incipit search.
94        /// `json_options` is upstream's feature-extraction option schema.
95        fn get_descriptive_features(tk: Pin<&mut Toolkit>, json_options: &str) -> String;
96
97        fn redo_layout(tk: Pin<&mut Toolkit>, json_options: &str);
98        /// Cheaper than `redo_layout` — recalculates only note vertical
99        /// positions on the current page. Use after option changes that
100        /// don't affect horizontal spacing.
101        fn redo_page_pitch_pos_layout(tk: Pin<&mut Toolkit>);
102
103        fn get_elements_at_time(tk: Pin<&mut Toolkit>, millisec: i32) -> String;
104
105        // Element introspection — inverse of get_elements_at_time, plus
106        // attribute readback for the hit-testing/click-to-seek pathway.
107        /// Page (1-based) on which `xml_id` is rendered, or `0` if missing.
108        fn get_page_with_element(tk: Pin<&mut Toolkit>, xml_id: &str) -> i32;
109        /// Wall-clock millisecond onset of `xml_id`. `RenderToMIDI` (or
110        /// `render_to_timemap`) must have run first to populate the time
111        /// table; the safe wrapper handles this transparently.
112        fn get_time_for_element(tk: Pin<&mut Toolkit>, xml_id: &str) -> i32;
113        /// JSON object with MIDI pitch, duration, channel, etc. for the
114        /// element. Empty / `"{}"` if `xml_id` is unknown or not a note.
115        fn get_midi_values_for_element(tk: Pin<&mut Toolkit>, xml_id: &str) -> String;
116        /// JSON object with score-time + real-time onset/offset/tied
117        /// duration. Same prerequisite as `get_time_for_element`.
118        fn get_times_for_element(tk: Pin<&mut Toolkit>, xml_id: &str) -> String;
119        /// JSON object of every MEI attribute on `xml_id` (including
120        /// attributes Verovio itself doesn't honor).
121        fn get_element_attr(tk: Pin<&mut Toolkit>, xml_id: &str) -> String;
122        /// MEI ID of the **notated** element when the input id refers to
123        /// an expansion clone. Returns `xml_id` itself if no expansion.
124        fn get_notated_id_for_element(tk: Pin<&mut Toolkit>, xml_id: &str) -> String;
125        /// JSON array of every expansion clone id sharing a notated id.
126        fn get_expansion_ids_for_element(tk: Pin<&mut Toolkit>, xml_id: &str) -> String;
127
128        // Process-global log threshold. Gated behind a Mutex in the safe
129        // wrapper so concurrent toolkit users don't race on Verovio's
130        // namespace-level `vrv::logLevel`.
131        fn enable_log(level: i32);
132    }
133}
verovio_sys/lib.rs

verovio_sys/
lib.rs
