# @dsebastien/music-notation 中文文档

规范地址：https://npmcn.com/package/%40dsebastien/music-notation/

版本：0\.19\.2
npm 元数据更新时间：2026-11-10T09:25:16.501Z
中文译文更新时间：2026-11-12T21:28:24.086Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dsebastien/music-notation
原文对照：https://npmcn.com/package/%40dsebastien/music-notation/?lang=original
项目主页：https://github.com/dsebastien/music-notation
源码仓库：https://github.com/dsebastien/music-notation

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：6.1 MB，95 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.0\.0
- 运行依赖：1 个
- peer 依赖：@coderline/alphatab ^1\.9\.0
- 首次发布：2026-10-28T19:40:41.372Z
- 最新版本发布：2026-11-10T09:25:16.098Z
- 近 30 天下载量：5543（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：30（近 12 个月 30 个）

## 中文简介

弦图,钢琴键盘,活板和弦道图作为SVG和HTML提供,没有框架. 在Obsidian、Obsidian出版社和任何网页上工作.

## 安装

```sh
npm install @dsebastien/music-notation
```

也可以使用：`pnpm add @dsebastien/music-notation`、`yarn add @dsebastien/music-notation`、`bun add @dsebastien/music-notation`

## README

# 音乐符号

弦图,钢琴键盘,活板,弦乐图,弦乐图和指取图案,进取图和五分之一的圆相,从小的文字块被渲染为SVG和HTML. 没有框架, 没有装入浏览器捆绑的页面的构建步骤 。 做为 [欧比多语Name](https://obsidian.md/) (单位:千美元) [音乐练习](https://github.com/dsebastien/obsidian-music-practice) 插件和 Obsidian Publish,可在任何网页上使用.

![Chord diagrams, a piano chord, a keyboard, a fretboard and a chord chart](https://npmcn.com/package/%40dsebastien/music-notation/docs/images/overview.png)

## 块

每个区块是一个有栅栏的代码区块,其语言表达的是它所画的东西:

````markdown
```chord
A x02220 x01230
```

```chord
C/G
instrument: piano
hands: left+right
fingering: 5 1 3 5
```

```keyboard
D dorian
labels: degrees
```

```fretboard
scale: A minor pentatonic
frets: 5-8
labels: intervals
```

```chords
{title: Example}
{key: G}
[G]Hello [D/F#]little [Em]world
```
````

用文字来配和弦,或从相片中识别出,用各种方式来演奏和弦,三相,和弦过渡,分级位置和模式:

````markdown
```chord
F Sharp Minor 7
---
frets: x02220
```

```chord
A Major
voicings: 6
```

```chord
G
triads: 1-3
```

```chord
from: C x32010
to: Am
```

```fretboard
A minor pentatonic
positions: all
```

```keyboard
modes: C major
```
````

罗马数字或纳什维尔数字中的进步,五分之一的圆形,以及符合一首歌曲和弦的尺度:

````markdown
```progression
I V vi IV
key: G
```

```circle
key: E minor
```

```fretboard
scales-for: G D Em C
```
````

在网络上找到它们的方式、卡波克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克克

````markdown
```strum
[G]D - D U [C]- U D U
```

```chord
A x02220 x01230
capo: 2
sounds: yes
```

```fretboard
arpeggio: Am7
positions: all
```

```chord
Dm7
instrument: piano
voicing: rootless A
```

```chords
{capo: 2}
{diagrams: on}
[G]Hello [Cadd9]little [Em]world
```
````

![A Major's easiest voicings, and G triads on the three highest strings](https://npmcn.com/package/%40dsebastien/music-notation/docs/images/voicings.png)

![G triads on the top strings, and the easiest ways from C to Am](https://npmcn.com/package/%40dsebastien/music-notation/docs/images/triads-transitions.png)

![A tab with its player](https://npmcn.com/package/%40dsebastien/music-notation/docs/images/tab.png)

几个相邻的图表, 由 `---`,首先使用共享设置;垂直或水平并用左手:

````markdown
```chord
orientation: horizontal
hand: left
---
G 320003 210003
---
C x32010 x32010
```
````

完整的语法在 [指南](https://dsebastien.github.io/music-notation/),与 [现场实例](https://dsebastien.github.io/music-notation/examples.html) (单位:千美元) [游乐场](https://dsebastien.github.io/music-notation/playground.html)。错误显示内在信息,而使源不受影响.

## 安装

```bash
npm install @dsebastien/music-notation
```

```ts
import { renderBlock, injectStyles } from '@dsebastien/music-notation'
import { lookupGuitarVoicing } from '@dsebastien/music-notation/voicings'

injectStyles(document)
const result = renderBlock('chord', 'Am', container, { voicings: lookupGuitarVoicing })
if (!result.ok) console.warn(result.error)
```

-   `renderBlock(language, source, host, options)` 附加渲染到 `host` 永远不要扔。 它回来了 `{ ok, el, error, destroy() }`。 。 。 .
-   `@dsebastien/music-notation/voicings` 添加了由和弦符号所发现的约1,800个吉他发音(`chord` 图标,仅包含符号。 这是一个单独的切入点,因为数据重约230KB.
-   **听听图**: 与 `play` 选项,单击一个图表来播放它,并点击一个点或一个键来播放该音符;每个块下的一个栏来播放选定的图表或所有图表,然后循环、速度和声音(音量是应用程序的设置)。 吉他和弦会起弦,钢琴和弦会打作一块块,鳞片会从他们的通琴上起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起 当它演奏时,每张音符都会点亮你的画作.
-   **弦图案**数字 : `strum` 块绘制图案( e)`D DU UDU`, (中文(简体) ), `D - D U - U D U`)在有计数,口音,哑音和鬼弦和和弦变化的节奏网格上;有回放后,会玩出取出其和弦,有回旋,节奏和倒数. `playStrum(pattern, { bpm, chord, tuning })` 从代码播放一个.
-   **及时实践**数字 : `progression` blocks and CordPro charts得到一个在时间上弹出其和弦的栏,一个和弦一个栏(或作为图表的栏线说),用一个节拍键来点击,一个倒计时和一个回路. 每根和弦被接在节奏上,一回是一巴,做作"arpeggio"或"接弦"图案,和弦会打出灯来. `playProgression(chords, { bpm, strum, pattern, click, countIn, loop })` 使用自己的玩家,从代码进行.
-   **统一比额表**(单位:千美元) `progression` 块为 `harmonize: triads`, (中文(简体) ), `sevenths`, (中文(简体) ), `sus` 或者说 `power` 和任何7个注的比额表 `key:` (单位:千美元)`A harmonic minor`, (中文(简体) ), `D dorian`)以数字和图表来绘制每度的和弦,准备及时播放. `harmonize(scale, { kind })` 从代码中给出相同的和弦.
-   **Capo (卡波语)**: 任何吉他和弦或活板上都有一个卡波条,并有在标题中发音的和弦`sounds: yes`)或标题(`sounds: title`: Em 形状 `capo: 3` 是"Gm (EM形状)".
-   **指着言语**数字 : `caption: fingering` 写下如何在图下演奏和弦, in `chord` 财务报告和审定财务报表 `progression` 块(吉他和钢琴).
-   **公式**数字 : `caption: formula` 写出和弦的音符,公式(1 b3 5 b7),文字和其他符号的质量,或比例尺的音符,公式和步骤(W W H),在和弦图,键盘和活板下(`chordFormula`, (中文(简体) ), `scaleFormula`) (中文(简体) ).
-   **可访问图表**:每个图都有屏幕读取器的描述(指向文字,键,每个字符串上的注释),以及 `root-mark: shape` (或 `rootMark` 选项)绘制根作为形状,而不仅仅是颜色.
-   **取指图案**数字 : `picking` 块用 PIMA 字母( p, p' for the second bass, i, m, a) 或字符串数字画出一个图案,作为小分页,在和弦或进取上画出,并及时播放. 特拉维斯,另类低音和1-2-3-4来取名. `playPicking(pattern, { chord, chords, bpm })` 从代码播放一个.
-   **标签和分数**数字 : `@dsebastien/music-notation/tab` 绘图 `tab` 财务报告和审定财务报表 `score` 块( αTex, 或 Guitar Pro and MusicXML 文件) [字母标签](https://alphatab.net/),并添加一个玩家。 它还会转换分数文件,文本标签和和和弦表,并会输出吉他Pro 7和MIDI.
-   `generateVoicings(symbol, options)` 在任何调音上都能找到任何可调音的和弦,最容易先用手指和形状名称; `fingerVoicing(frets)` 任何发音. `fingeringInWords(chord)` 写吉他或钢琴和弦的指向 在平淡的句子,因为 `caption: fingering` 以图表显示.
-   铸造者`renderGuitarDiagram`, (中文(简体) ), `renderKeyboard`, (中文(简体) ), `renderFretboard`, (中文(简体) ), `renderChart`, (中文(简体) ), `renderStrum`, (中文(简体) ), `renderPicking`, (中文(简体) ), `renderCircle`),解析器和理论辅助器 (`parseChord`, (中文(简体) ), `transposeChord`, (中文(简体) ), `chordNoteSet`, (中文(简体) ), `scaleNoteSet`(......)也出口.
-   以 Solfège (Do Ré Mi) 或 德文 (H for B) 表示: `naming: solfege` 或者说 `naming: german` 在一个区块中,或作为一个选项; 注释可以在三种系统中的任何一种中写出.
-   钻取层:与 `pick`,每个字串 × 烦恼 和键盘的每个键是点击或键盘所选择的目标;应用标记选择对或错(`attachPick`) (中文(简体) ).
-   **导出为图像**数字 : `toSvgString(el)` 财务报告和审定财务报表 `toPng(el)` 在页面的颜色或淡出或暗出的主题中,给一个独立的SVG或一个图或整块的PNG(包括标题和标题,每个样式内含);每个栏上的照片按钮将所选图复制到剪贴板(Shift:整块),并同时回放(`copy: false` 别管了).
-   样式 : `injectStyles(document)`,或船舶 `@dsebastien/music-notation/music-notation.css`。颜色遵循 Obsidian 的主题变量,任意一页都有倒数.

## 检查您的笔记

这个 `check` 命令绘制您 Markdown 文件的每个块并列出错误, 每行一个 (`file:line: language: message`) (中文(简体) ). 当一个区块出现错误时,它以代码1退出:

```bash
npx @dsebastien/music-notation check notes/*.md
```

`--describe` 打印每个块所绘制的内容(标题、和弦名称、每个点或键的音符、所显示的皱纹或键),以及 `--json` 和JSON一样 这个 [指南](https://dsebastien.github.io/music-notation/check.html) 有细节.

## 犹太出版社

将此添加到您的网站 `publish.js`。它仅在有标记块的页面上加载捆绑,而标签捆绑(带有alphaTab)仅在有标签或分数的页面上加载:

```js
;(() => {
    const VERSION = '0.19.1'
    const CDN = `https://cdn.jsdelivr.net/npm/@dsebastien/music-notation@${VERSION}/dist`
    const selector = (languages) => languages.map((l) => `pre > code.language-${l}`).join(', ')
    const BLOCKS = selector([
        'chord',
        'chords',
        'keyboard',
        'fretboard',
        'strum',
        'picking',
        'progression',
        'circle'
    ])
    const TABS = selector(['tab', 'score'])
    const requested = new Set()
    const load = (file) => {
        if (requested.has(file)) return
        requested.add(file)
        const script = document.createElement('script')
        script.src = `${CDN}/${file}`
        document.head.appendChild(script)
    }
    const check = () => {
        if (document.querySelector(BLOCKS)) load('music-notation.publish.min.js')
        if (document.querySelector(TABS)) load('music-notation.tab.min.js')
    }
    check()
    new MutationObserver(check).observe(document.body, { childList: true, subtree: true })
})()
```

捆绑使每一个街区,现在和当你导航, 隐藏一个街区的源头 只有当它提供.

## 信贷和许可证

麻省理工学院. 建造在 [托内](https://github.com/tonaljs/tonal) 音乐理论和 [和弦-db](https://github.com/tombatossals/chords-db) (MIT)吉他发音。 这个 `check` 命令捆绑 [链接](https://github.com/WebReflection/linkedom) (ISC)用于节点DOM. 标签和分数使用 [字母标签](https://alphatab.net/) (MPL-2.0),应用通过. 标签包从jsDelivr装入.

## 新闻支持( S)

为了了解图书馆的最新情况,一般说来,个人知识管理和记录:

-   订阅 [我的通讯](https://dsebastien.net/newsletter)
-   订阅 [我的YouTube频道](https://youtube.com/@dsebastien)
-   请加入 [知识社区](https://www.store.dsebastien.net/product/knowii-community/)

如果这对您有用:

-   [成为 GitHub 赞助商](https://github.com/sponsors/dsebastien)
-   [给我买杯咖啡](https://www.buymeacoffee.com/dsebastien)
-   [看看我的产品](https://store.dsebastien.net/)

## 常见问题

### @dsebastien/music-notation 是什么？

弦图,钢琴键盘,活板和弦道图作为SVG和HTML提供,没有框架\. 在Obsidian、Obsidian出版社和任何网页上工作\.

### 如何安装 @dsebastien/music-notation？

在项目目录运行 npm install @dsebastien/music-notation，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 music-notation，可以用 npx music-notation 直接运行。

### @dsebastien/music-notation 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dsebastien/music-notation 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @dsebastien/music-notation 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dsebastien/music-notation 可以商用吗？

@dsebastien/music-notation 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dsebastien/music-notation 的下载量有多少？

根据 npm 官方下载统计，@dsebastien/music-notation 在 2026/10/13 – 2026/11/11 这 30 天内被下载 5,543 次，日均约 185 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dsebastien/music-notation 还在维护吗？

最新版本 0\.19\.2 发布于 2026/11/10（3 天前）；至今共发布 30 个版本，其中过去 12 个月发布了 30 个；首次发布于 2026/10/29。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。