Install and use in other tools

The source-build instructions below require authorized access to the ScoreScript repository. They do not require a public npm or crates.io package. This documentation does not provide a verified public package-install route; do not assume an identically named registry package is this engine.

Install the command-line tool

Prerequisites: an authorized checkout, Rust/Cargo compatible with that checkout, and the platform's Rust build tools. From the repository root:

cargo install --locked --path crates/scorescript_cli --no-default-features
scorescript --help
scorescript docs --list

Cargo installs the binary into its configured bin directory; that directory must be on PATH. Omit --no-default-features if the terminal-score picture feature is wanted. The smaller build still checks, formats, renders SVG, and exports PDF and MIDI. Installing the CLI does not install the Studio desktop app.

scorescript check piece.scorescript
scorescript render piece.scorescript -o piece.svg
scorescript pdf piece.scorescript -o piece.pdf
scorescript midi piece.scorescript -o piece.mid

For an automated build, stop when check exits nonzero. Preserve diagnostics; a renderer can draw partial output even when source has errors. Pin the engine revision used by a build so upgrading it is a deliberate change.

Node and Electron

Prerequisites: the checkout, Rust/Cargo, wasm-pack, and Node. From the repository root, build the Node-target package:

bash crates/scorescript_wasm/build.sh node

This creates crates/scorescript_wasm/pkg-node/ and runs its packaged-runtime smoke check. Copy the whole generated package into your application's vendor/scorescript/ directory. Keep its JavaScript and WASM from the same build. Save this example as render.cjs in your application root:

const { readFileSync, writeFileSync } = require("node:fs");
const { CompiledDocument } = require("./vendor/scorescript/scorescript.js");

const score = new CompiledDocument(readFileSync("piece.scorescript", "utf8"));
try {
  const diagnostics = JSON.parse(score.diagnostics_json());
  if (diagnostics.length) console.error(diagnostics);
  if (diagnostics.some(d => d.severity === "error")) {
    throw new Error("ScoreScript source contains errors");
  }
  writeFileSync("piece.svg", score.render_svg(JSON.stringify({ width_px: 800 })));
} finally {
  score.free();
}

Run node render.cjs. The Node build uses CommonJS and needs no asynchronous initialization. The browser build uses ES modules and does require initialization; the two generated packages are not interchangeable.

For an editor, retain one CompiledDocument per open file and call update(source) when its text changes. Then read diagnostics, notation, and performance from that same document. Call free() when closing it. In Electron, keep filesystem access behind the application's existing trusted host boundary; do not enable Node access in an untrusted page to run this example.

Document API

The generated type declarations (scorescript.d.ts) describe the exact API of your build. JSON-returning methods return strings; decode them with JSON.parse. Option arguments are JSON strings, not JavaScript objects.

Use the option shape belonging to the output method; flowing and paginated layout options are not interchangeable. parse_json() exposes the parsed structure, not a substitute for checking semantic diagnostics.

Code editors and Markdown pipelines

Configure an editor's language-server client to launch scorescript lsp over stdio for .scorescript files. Syntax highlighting and preview UI are separate editor integrations; launching the server does not add those automatically.

A Markdown fence tagged scorescript is source text, not a universal embed standard. A Markdown site needs a build plugin or browser component that sends that fence to the native CLI or WASM engine. The simplest pipeline renders an SVG during the site build and replaces the fence with an image and source link. See website embedding for both approaches.

Agent clients

Build the native stdio server from the repository root:

cargo install --locked --path hosts/chatgpt-mcp

Set the client's MCP server command to the installed scorescript-mcp binary, with no arguments, using that client's configuration format. Client setup and support for previews or attachments vary; a stdio process is not a public HTTP endpoint.

The server exposes compile_score, update_score, format_score, read_score, render_score, export_score_file, and import_musicxml. Read scorescript://docs/index first, then the specific chapter resource, such as scorescript://docs/structure. These are the same authored chapters available through scorescript docs and this website.

For an existing document, use update_score with an increasing revision. The server returns artifacts for the client to save; it does not accept an arbitrary path and write into the client's filesystem. Ordinary terminal file work can use the CLI directly without an MCP round trip.