# Install and use in other tools

| Setup | Interface | What it provides |
| --- | --- | --- |
| Terminal or build pipeline | Native `scorescript` CLI | Check, format, import, and export files |
| Personal website | SVG/PDF, or browser WASM | Static notation, or local interactive rendering |
| Node or Electron | Generated Node WASM package | A reusable compiled document |
| Code editor | `scorescript lsp` | Language-server integration |
| Agent client | `scorescript-mcp` | Native tools and reference resources |

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:

```sh
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.

```sh
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:

```sh
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:

```js
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.

| Method | Result |
| --- | --- |
| `update(source)` | Compile changed text; unchanged text keeps the same revision |
| `revision()` | Current revision as a decimal string |
| `diagnostics_json()` | Codes, severity, messages, and source ranges |
| `render_svg(optionsJson)` | Flowing SVG; options include `width_px` and `foreground` |
| `render_pages_json(optionsJson)` | Paginated SVG sheets and a layout report |
| `event_geometry_json(optionsJson)` | Event boxes and system positions for hit testing |
| `performance_json()` | Notes and timing data, not audio output |
| `performance_json_for(movement)` | Performance for an authored movement ID |
| `format()` | Canonical source text; it does not save the file |
| `free()` | Release the document when it is no longer used |

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](embedding.md) for both approaches.

## Agent clients

Build the native stdio server from the repository root:

```sh
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.