MuseScore プラグイン開発の概要

1. はじめに

MuseScore（現行製品名: MuseScore Studio）は、プラグイン／拡張機能によって機能を追加できます。
本ワークスペースのソースは MuseScore Studio 5.0.0（prerelease）です。

拡張には大きく次の 2 系統があります。

系統	形式	状態
Extensions（推奨）	`manifest.json` + JavaScript / QML	`apiversion: 2`。新規開発向け
レガシー QML プラグイン	単一（または複数）の `.qml`、ルートは `MuseScore { }`	`import MuseScore 3.0`。互換のため残存。`apiversion: 1` 相当

楽譜の読み書き・走査・音符操作などの Engraving API は両系統で共通です（実装: src/engraving/api/v1/）。

2. Extensions（現行・推奨）

2.1 種類

type	説明
`macros`	UI なし。スクリプト（通常 `main.js` の `main()`）だけを実行
`form`	UI あり。QML（ルートは `ExtensionBlank`）
`composite`	複数アクション（form と macros の組み合わせ可）

2.2 インストール場所

ユーザー拡張フォルダにサブフォルダを作成します。

OS	パス
Windows	`C:\Users\<ユーザー名>\AppData\Local\MuseScore\MuseScore5\extensions`
Linux	`$HOME/.local/share/MuseScore/MuseScore5/extensions`
macOS	（ドキュメント未記載。Preferences → Folders で確認）

手順:

フォルダを作成（例: myquickstart）
manifest.json とスクリプト／QML を配置
MuseScore を起動し、Home → Plugins で有効化
スコアを開き、Menu → Plugins から実行

2.3 manifest.json

必須・主なフィールド:

フィールド	必須	説明
`uri`	○	一意 ID。形式: `musescore://extensions/<名前>`
`type`	○	`macros` / `form` / `composite`
`title`	○	表示名
`description`	○	短い説明
`actions`	○	実行するスクリプト／フォームの一覧
`thumbnail`		PNG サムネイル
`version`		拡張のバージョン
`vendor`		作者
`apiversion`		`1`=旧 PluginAPI（非推奨）、`2`=現行（省略時デフォルト）
`ui_context`		`ProjectOpened`（既定）または `Any`

macros の例:

json

{
    "uri": "musescore://extensions/myquickstart",
    "type": "macros",
    "title": "My quick start",
    "description": "API 学習用のサンプル拡張",
    "apiversion": 2,
    "actions": [
        { "path": "main.js" }
    ]
}

main.js の例:

javascript

const Log = require("MuseApi.Log");
const Interactive = require("MuseApi.Interactive");

function main() {
    Log.info("called main from quickstart");
    Interactive.info("Quick start", "called MAIN from quickstart");
}

form の例（Main.qml）:

qml

import QtQuick
import MuseApi.Controls
import MuseApi.Interactive

ExtensionBlank {
    id: root
    implicitHeight: 400
    implicitWidth: 400

    StyledTextLabel {
        id: label1
        anchors.centerIn: parent
        text: "Quick start"
    }

    FlatButton {
        anchors.top: label1.bottom
        anchors.topMargin: 8
        anchors.horizontalCenter: parent.horizontalCenter
        text: "Click me"
        onClicked: Interactive.info("Quick start", "Clicked on button")
    }
}

2.4 composite のアクション例

json

"actions": [
    { "code": "configure", "type": "form",  "title": "Configure", "path": "configure.qml" },
    { "code": "add",       "type": "macros", "title": "Add",       "path": "add.js" },
    { "code": "remove",    "type": "macros", "title": "Remove",    "path": "remove.js" }
]

func を指定すると、同一 JS 内の別関数を呼べます（省略時は main）。
show_on_appmenu（既定 true）/ show_on_toolbar（既定 false）で表示先を制御できます。

同梱サンプル: share/extensions/（quickstart, example1〜3, colornotes など）。

3. レガシー QML プラグイン

3.1 基本構造

プラグインは QML で記述し、ルートオブジェクトは必ず MuseScore { } です
（C++ の PluginAPI が QML 名 MuseScore として公開されています）。

qml

import MuseScore 3.0

MuseScore {
    menuPath: "Plugins.pluginName"
    description: "Description goes here"
    version: "1.0"
    onRun: {
        console.log("Hello World!");
        quit();   // プラグイン終了。Qt.quit() は本体まで閉じることがあるので使わない
    }
}

要素	意味
`import MuseScore 3.0`	MuseScore API の利用に必要（URI 名は歴史的に 3.0）
`MuseScore { }`	ルート。メタ情報とロジックをここに書く
`onRun`	実行時に呼ばれるエントリポイント（`run` シグナル）
`quit()`	プラグイン終了（`Qt.quit()` は使わない）

3.2 主なメタプロパティ

プロパティ	説明
`title`	タイトル（現行 UI 向け）
`menuPath`	メニュー配置パス（互換用。例: `"Plugins.Foo"`）
`version`	プラグイン版
`description`	説明
`pluginType`	`"dialog"` など。未定義なら即実行型
`dockArea`	`left` / `top` / `bottom` / `right`
`requiresScore`	スコア必須か（既定 `true`）。dialog で全スコア閉鎖後に閉じてもアプリ終了しにくくするには `false` を検討（ノウハウ §7.5）
`thumbnailName`	サムネイルファイル名
`categoryCode`	カテゴリコード

UI 付き（pluginType: "dialog"）のコントロール・メッセージ／ファイルダイアログの例は開発ノウハウ §2 を参照してください。
UI と楽譜処理（動作）をファイル分割する方針は開発ノウハウ §3 です。
終了・設定・子 QML の誤検出などの落とし穴は開発ノウハウ §7 です。

3.3 配置

同梱例: share/plugins/
ユーザー Plugins フォルダ（Preferences → Folders → Plugins）にも配置可能

独自フォントを楽譜の記号表示に使う場合は、OS へのインストールを前提とします。手順は独自フォント開発ガイドを参照してください。

同梱例の概要:

プラグイン	内容
`note_names`	選択範囲の音符名を Staff Text で表示
`tuning`	調律・テンペラメントを cents で適用（dialog）
`new_retrograde`	選択音符の逆行
`intervals`	音程の鏡映（dialog）
`lilyrics`	LilyPond 形式歌詞の適用（dialog）

3.4 デバッグ

注: MuseScore 4.x には、3.x の Plugin Creator 相当の組み込みデバッグコンソールは搭載されていません。console.log(...) は書けるが、一般配布ビルドでは端末やアプリログに出ないことが多いです。

3.x: Plugins → Plugin Creator（Ctrl+Shift+P）で編集・実行・コンソール確認が可能でした。
4.x の代替（実務）:
- 楽譜上の見た目・undo で成否を確認する
- アプリログで読込／QML エラーを確認する（Windows: %LOCALAPPDATA%\MuseScore\MuseScore4\logs\）
- FileIO でログファイルへ書く、または dialog 内にテキスト表示する
- （任意）端末から -d / --debug で起動（Linux では有効な報告が多い）
- （任意）コミュニティ製の Plugin Development Console / DebugTools
手順・コード例の詳細は開発ノウハウ §1.3 を参照。
5.x では Extensions 中心の UI に移行しています。レガシー QML も引き続きスキャンされます。

4. ライフサイクルとスコア編集の基本

4.1 起動〜終了

ユーザーがメニュー等から拡張を起動
macros: main() / レガシー QML: onRun
処理後、レガシーでは quit() で終了。dialog / form は UI を閉じるまで生存

4.2 スコア変更の定石

スコアを変更するときは、undo スタックのため コマンドで囲みます。

qml

onRun: {
    curScore.startCmd()
    // … 変更処理 …
    curScore.endCmd()
    quit()
}

4.3 Cursor による走査・入力

qml

var cursor = curScore.newCursor()
cursor.rewind(Cursor.SELECTION_START)  // または SCORE_START / SELECTION_END
while (cursor.segment) {
    var e = cursor.element
    if (e && e.type == Element.CHORD) {
        // e.notes を処理
    }
    cursor.next()
}

音符追加の例:

qml

cursor.setDuration(1, 4)   // 4分音符
cursor.addNote(60)         // 中央ハ (MIDI pitch 60)

4.4 スコア状態の監視（実験的）

onScoreStateChanged（MuseScore 3.3+）で選択変更などを受け取れます。
ハンドラ内でスコアを変更する場合は startCmd/endCmd で囲み、無限再帰に注意してください。

5. 重要な単位・概念

5.1 pitch（MIDI 音高）

Note.pitch は MIDI 番号です。異名同音は区別しません。

音	オクターブ 4 の例
C（中央ハ）	60
C♯	61
D	62
…	…
B	71

5.2 tpc（Tonal Pitch Class）

異名同音を区別する整数です。Note.tpc / tpc1 / tpc2 で参照します。

tpc	音名の例
14	C
21	C♯
9	D♭
13	F
20	F♯

（詳細表は docs/old_docs/tpc.md および PluginAPI Docs: tpc.html）

5.3 tick / division / Fraction

division … 4分音符あたりの tick 数（読み取り専用）
音価の例: 4分 = division、8分 = division/2、全音符 = 4 * division
MuseScore 4.6 以降 は位置表現に Fraction（全音符を 1 とする分数）を推奨
- cursor.fraction、fraction(num, den)、fractionFromTicks(ticks)
- cursor.tick は非推奨（比較用途ではまだ有用な場合あり）

5.4 track / staff / voice

staffIdx … 五線のインデックス（0 始まり）
voice … 声部 0〜3
track … staffIdx * 4 + voice

6. オブジェクトモデル（概要）

ScoreElement          … type / name / userName() / is()
  └ EngravingItem     … 位置・色・親子・staff など
       ├ Note
       ├ DurationElement
       │    ├ Tuplet
       │    └ ChordRest → Chord
       ├ Segment / Measure / Page / System
       ├ Staff / Part
       └ …
Score                 … 楽譜全体（ScoreElement 継承）
Cursor                … 走査・入力用（Score から独立したヘルパー）
Selection             … 選択状態

型判定の例:

qml

if (el.type == Element.NOTE) { ... }
if (el.type == Element.CHORD) { ... }

7. 国際化（i18n）

文字列は qsTr() / qsTranslate() で囲み、必要に応じて translations/locale_XX.qm を用意します。
ツール導入から組み込みまでの詳細は国際化（i18n）開発ガイドを参照してください。qsTranslate 用のコンテキスト名は本体翻訳コンテキスト一覧、.qm の自動生成は翻訳コンパイル自動化です。要約は開発ノウハウ §5 です。

一次資料: PluginAPI Docs: i18n.html、docs/old_docs/i18n.md。

8. MuseScore 2 → 3 移植の要点（参考）

PluginAPI Docs: plugin2to3.html より:

import MuseScore 1.0 → import MuseScore 3.0
一部列挙の名前空間変更（例: MScore.UP → Direction.UP）
位置プロパティ: pos 系から offset 系への移行など

新規開発では Extensions（apiversion: 2）を使うことを推奨します。

9. 参考パス一覧

内容	参照
現行 API 実装	`src/engraving/api/v1/`
Extensions チュートリアル	`docs/apidocs_static/`
旧 QML 入門	`docs/old_docs/plugins.md`
3.5 Doxygen	PluginAPI Docs
同梱レガシー例	`share/plugins/`
同梱 Extensions 例	`share/extensions/`
公開 API サイト	musescore.github.io

次章: API リファレンス／開発ノウハウ（VSCode 環境）

MuseScore プラグイン開発の概要 ​

1. はじめに ​

2. Extensions（現行・推奨） ​

2.1 種類 ​

2.2 インストール場所 ​

2.3 manifest.json ​

2.4 composite のアクション例 ​

3. レガシー QML プラグイン ​

3.1 基本構造 ​

3.2 主なメタプロパティ ​

3.3 配置 ​

3.4 デバッグ ​

4. ライフサイクルとスコア編集の基本 ​

4.1 起動〜終了 ​

4.2 スコア変更の定石 ​

4.3 Cursor による走査・入力 ​

4.4 スコア状態の監視（実験的） ​

5. 重要な単位・概念 ​

5.1 pitch（MIDI 音高） ​

5.2 tpc（Tonal Pitch Class） ​

5.3 tick / division / Fraction ​

5.4 track / staff / voice ​

6. オブジェクトモデル（概要） ​

7. 国際化（i18n） ​

8. MuseScore 2 → 3 移植の要点（参考） ​

9. 参考パス一覧 ​