Verovioxide

https://docs.rs/verovioxide/0.0.1
Admin
Verovioxide provides safe Rust bindings to the Verovio music notation engraving library for loading,...
Tokens:4,451
Snippets:57
Trust Score:9.1
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quick Start Rendering

Source: https://docs.rs/verovioxide

Initialize the toolkit, load a file, and render to an SVG file.

```rust
use verovioxide::{Toolkit, Options, Result, Svg};
use std::path::Path;

fn main() -> Result<()> {
    // Create a Verovio toolkit with bundled resources
    let mut voxide = Toolkit::new()?;

    // Load notation (format auto-detected)
    voxide.load(Path::new("score.musicxml"))?;

    // Configure rendering
    let options = Options::builder()
        .scale(100)
        .adjust_page_height(true)
        .build();
    voxide.set_options(&options)?;
    voxide.render_to("score.svg")?;
    Ok(())
}
```

--------------------------------

### Install Verovioxide

Source: https://docs.rs/verovioxide

Add the library to your project dependencies.

```shell
cargo add verovioxide
```

--------------------------------

### Install with Prebuilt Binaries

Source: https://docs.rs/verovioxide

Use prebuilt binaries to avoid long compilation times during the initial build.

```shell
cargo add verovioxide-sys --features prebuilt
cargo add verovioxide
```

```toml
[dependencies]
verovioxide = "0.3"
verovioxide-sys = { version = "0.3", features = ["prebuilt"] }
```

--------------------------------

### Render ABC Notation

Source: https://docs.rs/verovioxide

Executes the render_abc example to process ABC notation files.

```bash
cargo run --example render_abc
```

--------------------------------

### Render MusicXML to SVG

Source: https://docs.rs/verovioxide

Executes the render_musicxml example to convert a MusicXML file into an SVG output.

```bash
cargo run --example render_musicxml -- \
  test-fixtures/musicxml/simple.musicxml \
  simple.svg
```

--------------------------------

### Retrieve Page Information

Source: https://docs.rs/verovioxide

Get the total number of pages in the loaded document.

```rust
let count = voxide.page_count();
println!("Document has {} pages", count);
```

--------------------------------

### Query elements using type-safe API

Source: https://docs.rs/verovioxide

Use the get() method with specific query types to retrieve element information like page, attributes, and timing.

```rust
use verovioxide::{Toolkit, Page, Attrs, Time, Times};

let mut voxide = Toolkit::new()?;
voxide.load("score.mei")?;

// Get page containing an element
let page: u32 = voxide.get(Page::of("note-001"))?;

// Get element attributes as JSON
let attrs: String = voxide.get(Attrs::of("note-001"))?;

// Get timing information
let time: f64 = voxide.get(Time::of("note-001"))?;
let times: String = voxide.get(Times::of("note-001"))?;
```

--------------------------------

### Build and Test Project

Source: https://docs.rs/verovioxide

Standard commands to compile and verify the project.

```bash
cargo build
cargo test
```

--------------------------------

### Clone Repository with Submodules

Source: https://docs.rs/verovioxide

Initialize the repository and its submodules.

```bash
git clone --recursive https://github.com/oxur/verovioxide.git
cd verovioxide
```

--------------------------------

### Configure toolkit options

Source: https://docs.rs/verovioxide

Use the Options builder to define page layout, font, SVG, and MIDI settings.

```rust
use verovioxide::{Options, BreakMode, HeaderMode, FooterMode};

let options = Options::builder()
    // Page dimensions (MEI units, 10 units = 1mm)
    .page_width(2100)      // A4 width
    .page_height(2970)     // A4 height
    .adjust_page_height(true)

    // Margins
    .page_margin(50)
    .page_margin_top(100)

    // Scale and spacing
    .scale(100)            // Percentage
    .spacing_staff(12)
    .spacing_system(6)

    // Font
    .font("Leipzig")       // or "Bravura", "Gootville", "Leland", "Petaluma"
    .lyric_size(0.8)

    // Layout
    .breaks(BreakMode::Auto)
    .header(HeaderMode::None)
    .footer(FooterMode::None)

    // SVG output
    .svg_view_box(true)
    .svg_remove_xlink(true)
    .svg_css("svg { background: white; }")

    // MIDI generation
    .midi_tempo(120.0)
    .midi_velocity(80)

    // Transposition
    .transpose("M2")       // Up a major second

    .build();

voxide.set_options(&options)?;
```

--------------------------------

### Options::builder

Source: https://docs.rs/verovioxide

Configures rendering, layout, and output settings for the toolkit.

```APIDOC
## Options::builder()

### Description
Creates an Options object to configure page dimensions, margins, scaling, fonts, layout modes, SVG output, MIDI generation, and transposition.

### Method
Rust Builder Pattern

### Parameters
- **page_width/height** (u32) - Optional - Dimensions in MEI units
- **scale** (u32) - Optional - Percentage scale
- **font** (String) - Optional - Font name (e.g., "Leipzig", "Bravura")
- **breaks** (BreakMode) - Optional - Break configuration mode

### Response
- **Options** (Object) - A configured options object to be passed to voxide.set_options().
```

--------------------------------

### Use Local Verovio Source

Source: https://docs.rs/verovioxide

Override the download source by providing a local directory path.

```bash
VEROVIO_SOURCE_DIR=/path/to/verovio cargo build
```

--------------------------------

### render_to_as(path, format)

Source: https://docs.rs/verovioxide

Renders the loaded music data to a file using an explicit format configuration.

```APIDOC
## render_to_as(path, format)

### Description
Writes the rendered output to the specified file path using the provided format configuration.

### Parameters
- **path** (String) - Required - The destination file path.
- **format** (Object) - Required - The output format configuration.
```

--------------------------------

### Render PNGs to files

Source: https://docs.rs/verovioxide

Shows how to save rendered PNG output directly to the filesystem.

```rust
// Format inferred from extension
voxide.render_to("output.png")?;

// Explicit control
voxide.render_to_as("output.png", Png::page(3))?;
voxide.render_to_as("output.png", Png::all_pages())?;  // Creates output/ directory
```

--------------------------------

### Render PNGs in-memory

Source: https://docs.rs/verovioxide

Demonstrates various ways to render music notation to PNG bytes, including scaling, background customization, and multi-page support.

```rust
use verovioxide::Png;

// Basic rendering (returns Vec<u8>)
let png_bytes: Vec<u8> = voxide.render(Png::page(1))?;

// With options
let png_bytes = voxide.render(
    Png::page(1)
        .width(800)           // Scale to 800px width
        .height(600)          // Or scale to fit height
        .scale(2.0)           // Or use zoom factor
        .white_background()   // White instead of transparent
)?;

// Custom background color
let png_bytes = voxide.render(
    Png::page(1).background(240, 240, 240, 255)  // Light gray
)?;

// Render all pages
let all_pngs: Vec<Vec<u8>> = voxide.render(Png::all_pages())?;

// Render page range
let pngs: Vec<Vec<u8>> = voxide.render(Png::pages(2, 5))?;
```

--------------------------------

### Render All Pages

Source: https://docs.rs/verovioxide

Processes a multi-page MusicXML file and outputs individual SVG files to a specified directory.

```bash
mkdir output-dir
cargo run --example render_all_pages -- \
  "examples/Goldberg-Variationen-1-and-2.musicxml" \
  output-dir/
```

--------------------------------

### render_to(path)

Source: https://docs.rs/verovioxide

Renders the loaded music data directly to a file, inferring the format from the file extension.

```APIDOC
## render_to(path)

### Description
Writes the rendered output to the specified file path. The output format is automatically inferred from the file extension.

### Parameters
- **path** (String) - Required - The destination file path.
```

--------------------------------

### Legacy Rendering Methods

Source: https://docs.rs/verovioxide

Use older API methods for backwards compatibility.

```rust
let svg = voxide.render_to_svg(1)?;
let pages = voxide.render_all_pages()?;
let mei = voxide.get_mei()?;
let humdrum = voxide.get_humdrum()?;
let midi = voxide.render_to_midi()?;
let timemap = voxide.render_to_timemap()?;
```

--------------------------------

### Use legacy query methods

Source: https://docs.rs/verovioxide

Access older query methods maintained for backwards compatibility.

```rust
let page = voxide.get_page_with_element("note-001")?;
let attrs = voxide.get_element_attr("note-001")?;
let time = voxide.get_time_for_element("note-001")?;
let elements = voxide.get_elements_at_time(5000)?;
```

--------------------------------

### render(format)

Source: https://docs.rs/verovioxide

Renders the loaded music data into a specified format. Returns the data as a byte vector or collection of byte vectors.

```APIDOC
## render(format)

### Description
Generates output from the loaded music data based on the provided format configuration.

### Parameters
- **format** (Object) - Required - The output format configuration (e.g., Png::page(1), Mei, Humdrum, Pae, Midi, Timemap, ExpansionMap).

### Returns
- **Vec<u8> | Vec<Vec<u8>>** - The rendered output data.
```

--------------------------------

### Configure Custom Resource Path

Source: https://docs.rs/verovioxide

Disable default bundled data and specify a custom path for Verovio resources.

```toml
[dependencies]
verovioxide = { version = "0.3", default-features = false }
```

```rust
let voxide = Toolkit::with_resource_path(Path::new("/path/to/verovio/data"))?;
```

--------------------------------

### Define option modes

Source: https://docs.rs/verovioxide

Reference for available modes for breaks, condensation, and headers/footers.

```rust
// Break modes
BreakMode::Auto     // Automatic page/system breaks
BreakMode::None     // No automatic breaks
BreakMode::Encoded  // Use breaks from input file
BreakMode::Line     // Break at each line
BreakMode::Smart    // Smart break placement

// Condense modes
CondenseMode::None
CondenseMode::Auto
CondenseMode::Encoded

// Header/Footer modes
HeaderMode::None | HeaderMode::Auto | HeaderMode::Encoded
FooterMode::None | FooterMode::Auto | FooterMode::Encoded | FooterMode::Always
```

--------------------------------

### Force Rebuild

Source: https://docs.rs/verovioxide

Bypass the build cache to trigger a fresh compilation.

```bash
cargo build --features force-rebuild
```

--------------------------------

### Serialize and deserialize options

Source: https://docs.rs/verovioxide

Convert options to and from JSON format.

```rust
let json = options.to_json()?;
let options = Options::from_json(&json)?;
```

--------------------------------

### Toolkit::get

Source: https://docs.rs/verovioxide

Retrieves information about elements, timing, or features using type-safe query types.

```APIDOC
## Toolkit::get(query)

### Description
Retrieves specific data from the loaded score based on the provided query type. Supported types include Page, Attrs, Time, Times, Elements, and Features.

### Method
Rust Method

### Parameters
- **query** (QueryType) - Required - The query object (e.g., Page::of("id"), Elements::at(ms), Features)

### Response
- **result** (T) - The requested data, type-safe based on the query provided.
```

--------------------------------

### File Rendering

Source: https://docs.rs/verovioxide

Save rendered output directly to files using inferred or explicit formats.

```rust
voxide.render_to("output.svg")?;    // SVG page 1
voxide.render_to("output.mid")?;    // MIDI
voxide.render_to("output.mei")?;    // MEI
```

```rust
voxide.render_to_as("output.svg", Svg::page(3))?;        // Specific page
voxide.render_to_as("output.svg", Svg::all_pages())?;    // Creates output/ directory
voxide.render_to_as("output.json", Timemap)?;            // Disambiguate .json
```

--------------------------------

### Format-Specific Rendering Options

Source: https://docs.rs/verovioxide

Apply typed options when rendering Timemap or MEI formats.

```rust
// Timemap with options
let timemap = voxide.render(
    Timemap::with_options()
        .include_measures(true)
        .include_rests(false)
)?;

// MEI with options
let mei = voxide.render(
    Mei::with_options()
        .remove_ids(true)
        .page_based(false)
)?;
```

--------------------------------

### Display PNG in terminal

Source: https://docs.rs/verovioxide

Integrates with the image and viuer crates to display rendered PNG bytes in the terminal.

```rust
use verovioxide::Png;
use image::load_from_memory;
use viuer::Config;

let png_bytes = voxide.render(Png::page(1).width(800))?;
let img = load_from_memory(&png_bytes)?;
viuer::print(&img, &Config::default())?;
```

--------------------------------

### In-Memory Rendering

Source: https://docs.rs/verovioxide

Render notation data directly into memory using various format builders.

```rust
use verovioxide::{Svg, Midi, Mei, Timemap, Humdrum, Pae, ExpansionMap};

// SVG rendering
let svg: String = voxide.render(Svg::page(1))?;           // Single page
let svg: String = voxide.render(Svg::page(1).with_declaration())?;
let pages: Vec<String> = voxide.render(Svg::all_pages())?; // All pages
let pages: Vec<String> = voxide.render(Svg::pages(2, 5))?; // Page range

// Other formats
let midi: String = voxide.render(Midi)?;          // Base64-encoded MIDI
let mei: String = voxide.render(Mei)?;            // MEI XML
let humdrum: String = voxide.render(Humdrum)?;    // Humdrum/Kern
let pae: String = voxide.render(Pae)?;            // Plaine & Easie
let timemap: String = voxide.render(Timemap)?;    // JSON timing data
let expansion: String = voxide.render(ExpansionMap)?;
```

--------------------------------

### Enable Additional Fonts

Source: https://docs.rs/verovioxide

Add specific SMuFL fonts to the project dependencies.

```toml
[dependencies]
verovioxide = { version = "0.3", features = ["font-bravura", "font-leland"] }
```

--------------------------------

### Logging Configuration

Source: https://docs.rs/verovioxide

Configures logging output to either stderr or an internal buffer for debugging purposes.

```rust
// Enable logging to stderr
Toolkit::enable_log(true);

// Or capture to buffer
Toolkit::enable_log_to_buffer(true);
// ... operations ...
let log = voxide.get_log();
```

--------------------------------

### Query elements by time

Source: https://docs.rs/verovioxide

Retrieve elements sounding at a specific timestamp in milliseconds.

```rust
use verovioxide::{Toolkit, Elements};

// Get elements sounding at 5000ms
let elements: String = voxide.get(Elements::at(5000))?;
```

--------------------------------

### Query descriptive features

Source: https://docs.rs/verovioxide

Retrieve descriptive features of the loaded score.

```rust
use verovioxide::{Toolkit, Features};

let features: String = voxide.get(Features)?;
```

--------------------------------

### Disable PNG support in Cargo.toml

Source: https://docs.rs/verovioxide

Configures project dependencies to exclude PNG support for reduced binary size.

```toml
[dependencies]
verovioxide = { version = "0.3", default-features = false, features = ["bundled-data"] }
```
Tokens:
Raw