musescore-plugin-lib

musescore-plugin-lib は、MuseScore Studio プラグイン向けの 共有 JS ユーティリティです。
スコア走査・選択・バージョンゲート・設定永続化・ログ（コンソール代替）など、繰り返し出る処理を共通化します。

対象バージョン: MuseScore Studio 4.4 以降のみ（Qt 6）。
4.3.x 以前は非対応です。4.3 と 4.4+ を同一 QML で共存させる設計は採用していません（Settings の import 要件などが衝突するため）。

ソースと詳細 API: GitHub — yu1row/musescore-plugin-lib（MIT）

1. 何ができるか

モジュール	役割
`score.js`	`startCmd` / `endCmd`、小節・セグメント走査
`cursor.js`	Cursor 生成・選択範囲走査
`selection.js`	選択要素の取得・型フィルタ
`elements.js`	Note / Chord / Rest 判定
`notes.js`	音名変換・ユニーク pitch
`version.js`	MuseScore バージョン判定・起動ゲート
`settings.js`	設定スキーマ（初期値＝キー）／読込・保存・UI 同期
`log.js`	ダイアログ／FileIO 向けログ（`console.log` 代替）

例プラグイン（examples/）と Node 単体テスト（npm test）、実機チェックリスト（docs/SMOKE.md）も同梱しています。

2. インストール

リポジトリを Plugins フォルダへ配置する（フォルダごと）
- Windows 例: %USERPROFILE%\Documents\MuseScore4\Plugins\musescore-plugin-lib\
MuseScore Studio 4.4+ を起動し、Plugin Manager で例を有効化する

自作プラグインから使う場合も、同じ Plugins 配下に置き、相対パスで import します。

Plugins/
├── musescore-plugin-lib/
│   └── lib/…
└── my-plugin/
    └── MyPlugin.qml

3. 基本的な使い方

qml

import MuseScore
import QtQuick

import "../musescore-plugin-lib/lib/score.js" as Score
import "../musescore-plugin-lib/lib/selection.js" as Selection
import "../musescore-plugin-lib/lib/elements.js" as Elements
import "../musescore-plugin-lib/lib/notes.js" as Notes
import "../musescore-plugin-lib/lib/version.js" as Version
import "../musescore-plugin-lib/lib/log.js" as Log

MuseScore {
    id: plugin
    title: "My Plugin"
    pluginType: "dialog"
    requiresScore: true
    width: 400
    height: 180

    property var logger: Log.create({ prefix: "MyPlugin: " })
    property string feedback: ""

    function showFeedback(message) {
        Log.clear(logger)
        Log.info(logger, message)
        feedback = Log.dump(logger)
    }

    onRun: {
        var gate = Version.requirePluginAtLeast(plugin, "4.4.0")
        if (!gate.ok) {
            showFeedback(gate.message)
            return
        }

        Score.withCmd(curScore, "My edit", function () {
            Selection.forEach(curScore, function (el) {
                if (Elements.isNote(el))
                    showFeedback(Notes.label(el))
            })
        })
    }

    // Label { text: feedback } と OK → quit() など
}

各 .js は QML 側の import MuseScore を継承するため、Element.NOTE などをモジュール内で利用できます。.pragma library は使っていません。

4. 設定の永続化（settings.js）

4.4+ では Settings が MuseScore モジュールに統合されています。
import Qt.labs.settings は書かないでください。 Studio 同梱の Qt には当該モジュールが入っておらず、import するとプラグインが認識されない／起動に失敗します（開発ノウハウ §7.6）。

初期値とキーは defaults オブジェクトに集約
UI との同期は binder マップ（コントロール ID を Settings に書かない）

qml

import "../musescore-plugin-lib/lib/settings.js" as SettingsUtil

Settings {
    id: backend
    category: "MyPlugin"
    property string payload: "{}"
}

property var store: SettingsUtil.create({
    modeIndex: 0,
    verbose: true
})

onRun: {
    store = SettingsUtil.loadTo(backend, store, {
        modeIndex: function (v) { modeBox.currentIndex = v },
        verbose: function (v) { verboseBox.checked = v }
    })
}

// OK:
// store = SettingsUtil.saveFrom(backend, store, collectors); quit()

5. ログ（console 代替）

MuseScore 4 には Plugin Creator／デバッグコンソール UI がありません。console.log は GUI では通常見えません。

用途	手段
ユーザー向けメッセージ	`log.js` の `dump` をダイアログの `Label` に表示
開発時の詳細ログ	`FileIO` + `Log.writeFile` / `appendFile`

デバッグ全般の整理は開発ノウハウ §1.3 も参照してください。

6. 終了時の注意

プラグイン終了は quit()
Qt.quit() は使わない（MuseScore 本体まで閉じる／クラッシュの原因）
dialog でスコアをすべて閉じたあとに閉じるとアプリ終了することがある → requiresScore: false を検討し、処理時に curScore を検査する（開発ノウハウ §7.4–7.5）

7. テスト

層	内容
Node 単体	`npm test`（GitHub Actions でも実行）
実機スモーク	リポジトリの `docs/SMOKE.md`

方針の詳細はリポジトリの docs/TESTING.md を参照してください。

8. 関連リンク

リソース	URL
ソース / API 詳細	github.com/yu1row/musescore-plugin-lib
API 詳細（リポジトリ内）	docs/API.md
分割＋lib＋日本語の雛形	プラグインテンプレート（GitHub）
4.4 更新メモ（公式）	Updating plugins for 4.4
本サイト: 開発ノウハウ	開発ノウハウ
本サイト: API リファレンス	API リファレンス

musescore-plugin-lib ​

1. 何ができるか ​

2. インストール ​

3. 基本的な使い方 ​

4. 設定の永続化（settings.js） ​

5. ログ（console 代替） ​

6. 終了時の注意 ​

7. テスト ​

8. 関連リンク ​