SongXML Engine

中文文档 | English Documentation

SongXML 是一套基于 TypeScript 的乐谱生态系统，SongXML Engine 是其中的核心引擎层，负责乐理对象建模、乐谱序列化与分析计算。上层应用（记谱编辑器、乐谱渲染、WebDAV 等）基于本引擎构建。SongXML Engine 提供完整的乐理对象模型（Note / Chord / Pitch / Stream / Key 等），支持 MusicXML 和 MIDI 双向序列化，以及调性分析、和弦变换、旋律分析等分析能力。整个库纯内存运算，文件操作由调用方处理。

致谢

本项目基于 music21，将其核心对象模型与分析算法移植到 TypeScript 并做了针对浏览器环境的定制。衷心感谢 music21 的作者及社区贡献者：

• Michael Scott Asato Cuthbert — music21 的创建者与核心维护者
• Christopher Ariza — 分析模块、流处理等核心贡献者
• Maura Church / Mark Gotham — Neo-Riemannian 理论模块
• Jared Sadoian — 窗口化分析框架

music21 采用 BSD 许可证发布。

• music21 原项目：https://github.com/cuthbertLab/music21
• music21 文档：https://web.mit.edu/music21/

与 music21 的差异

因目标环境是浏览器，本库在以下方面与 music21 不同：

| 方面 | music21（Python） | SongXML Engine（TypeScript） | |---|---|---| | 文件 I/O | 读写本地文件、下载、launch 外部程序 | 纯内存运算，write() 返回 string / Uint8Array | | 乐谱格式 | MusicXML / MIDI / ABC / LilyPond / Humdrum 等 | 仅 MusicXML 和 MIDI（双向） | | 循环依赖 | Python 模块级互相 import | 合并文件 + setter 延迟注入 | | 乐谱语料 | 内置 corpus（巴赫/莫扎特等） | 不含任何乐谱语料 |

安装

npm install songxml-engine
# 或
pnpm add songxml-engine

导入方式

import { Score, Note, converter } from 'songxml-engine'

就这么简单。开箱即用——无需注册、无需额外配置。十二音技法（serial）、Xenakis 筛（sieve）、轻量记号（tinyNotation）、声部进行分析（voiceLeading）等独立大模块按需导入：

import { Sieve } from 'songxml-engine/sieve'
import { parseTinyNotation } from 'songxml-engine/tinyNotation'

API 文档

完整 API 文档位于 documents/ 目录：

• 01 核心对象模型（上） — Stream / 音符 / 和弦 / 音高 / 时值 / 谱号 / 调号 / 拍号 / 速度 / 力度
• 02 核心对象模型（下） — 小节线 / 装饰法 / 表情记号 / 连接线 / 音程 / 罗马数字 / 音阶
• 03 序列化 — MusicXML 导入导出 / MIDI 导入导出 / Converter 调度层
• 04 分析 — 调性分析 / 旋律分析 / Neo-Riemannian 变换 / 等音优化 / 浮动调性 / 和弦缩减 / TimespanTree
• 05 扩展模块 — 十二音技法 / Xenakis 筛 / 轻量记号 / 声部进行分析 / 装饰音实现
• 06 架构与差异 — 与 music21 差异 / 循环依赖处理 / Tree-shaking / 浏览器限制

English

SongXML is a TypeScript-based music score ecosystem. SongXML Engine is its core engine layer, responsible for music theory object modeling, score serialization, and analysis. Upper-layer applications (score editors, rendering, WebDAV, etc.) are built on top of this engine. SongXML Engine provides a complete music theory object model (Note / Chord / Pitch / Stream / Key, etc.), supports bidirectional MusicXML and MIDI serialization, and offers analysis capabilities such as key analysis, chord transformation, and melodic analysis. The library operates purely in memory — file operations are handled by the caller.

Acknowledgements

This project is based on music21, porting its core object model and analysis algorithms to TypeScript with browser-specific adaptations. Sincere thanks to the music21 authors and community contributors:

• Michael Scott Asato Cuthbert — Creator and lead maintainer of music21
• Christopher Ariza — Analysis module, stream processing
• Maura Church / Mark Gotham — Neo-Riemannian theory modules
• Jared Sadoian — Windowed analysis framework

music21 is released under the BSD License.

• music21 project: https://github.com/cuthbertLab/music21
• music21 docs: https://web.mit.edu/music21/

Differences from music21

Due to the browser target environment, this library differs from music21 in the following ways:

| Aspect | music21 (Python) | SongXML Engine (TypeScript) | |---|---|---| | File I/O | Read/write files, download, launch programs | Pure in-memory, write() returns string / Uint8Array | | Score formats | MusicXML / MIDI / ABC / LilyPond / Humdrum, etc. | MusicXML and MIDI only (bidirectional) | | Circular deps | Python module-level mutual imports | Merged files + setter lazy injection | | Score corpus | Built-in corpus (Bach, Mozart, etc.) | No score corpus included |

Installation

npm install songxml-engine
# or
pnpm add songxml-engine

Usage

import { Score, Note, converter } from 'songxml-engine'

That's it. Out of the box — no registration, no configuration needed. Independent modules like serial (twelve-tone), sieve (Xenakis), tinyNotation, and voiceLeading are imported on demand:

import { Sieve } from 'songxml-engine/sieve'
import { parseTinyNotation } from 'songxml-engine/tinyNotation'

API Documentation

Full API documentation is in the documents/ directory:

• 01 Core Objects (Part 1) — Stream / Note / Chord / Pitch / Duration / Clef / Key / TimeSignature / Tempo / Dynamic
• 02 Core Objects (Part 2) — Barline / Articulation / Expression / Spanner / Interval / RomanNumeral / Scale
• 03 Serialization — MusicXML import/export / MIDI import/export / Converter dispatcher
• 04 Analysis — Key analysis / melodic analysis / Neo-Riemannian transforms / enharmonic optimization / floating key / chord reduction / TimespanTree
• 05 Extensions — Twelve-tone serial / Xenakis sieve / tinyNotation / voice-leading analysis / ornament realization
• 06 Architecture — Differences from music21 / circular dependency handling / tree-shaking / browser limitations