MuseScore Plugin API リファレンス

本リファレンスは、主に src/engraving/api/v1/ の実装と、MuseScore PluginAPI Docs（3.5）のクラス構成に基づきます。
QML では import MuseScore 3.0、Extensions macros では api.engraving（EngravingApiV1）経由で同等の操作が可能です。

表記: プロパティは読み取り専用の場合「RO」、読み書き可能な場合「RW」と記します。

使用例: 主要クラスのメソッド表の下に、折りたたみ（▼）の短い QML スニペットがあります。複数 API をまたぐ典型フローは 付録 A を参照してください。

---

目次

1. PluginAPI（QML: MuseScore）
2. Score
3. Cursor
4. Selection
5. ScoreElement / EngravingItem
6. Note / Chord / ChordRest / DurationElement / Tuplet / Beam
7. Segment / Measure / System / Page
8. Part / Staff / Instrument / Excerpt / Spanner など
9. FileIO / QProcess
10. Fraction / Interval とその他ユーティリティ
11. 列挙（Enum）
12. クラス一覧（3.5 Docs との対応）

---

1. PluginAPI（QML: MuseScore）

実装: qmlpluginapi.h
役割: プラグインのルート。メタ情報、現在のスコア、要素生成、列挙へのアクセスを提供します。

1.1 メタ・実行環境プロパティ

プロパティ	型		説明
menuPath	string	RW	メニュー配置パス
title	string	RW	タイトル
version	string	RW	プラグイン版
description	string	RW	説明
pluginType	string	RW	"dialog" など
dockArea	string	RW	left / top / bottom / right
requiresScore	bool	RW	スコア必須（既定 true）
thumbnailName	string	RW	サムネイル名
categoryCode	string	RW	カテゴリコード
division	int	RO	4分音符あたりの tick 数
mscoreVersion	int	RO	バージョン（MMmmuu 形式）
mscoreMajorVersion	int	RO	メジャー
mscoreMinorVersion	int	RO	マイナー
mscoreUpdateVersion	int	RO	アップデート
mscoreDPI	real	RO	DPI
curScore	Score	RO	現在のスコア
scores	Score[]	RO	開いているスコア一覧（3.2+）

1.2 シグナル

シグナル	QML ハンドラ	説明
run()	onRun	プラグイン起動時
scoreStateChanged(state)	onScoreStateChanged	スコア状態変化（3.3+、実験的）
closeRequested	—	quit() 時など

state の主なフィールド: selectionChanged, excerptsChanged, instrumentsChanged, startLayoutTick, endLayoutTick, undoRedo（3.5+）。

1.3 メソッド

メソッド	説明
newScore(name, part, measures)	新規スコア作成
newElement(type)	要素生成（Element.NOTE 等）
removeElement(element)	要素削除
cmd(name)	内部コマンド実行（例: "select-all", "escape", "cut"）
writeScore(score, name, ext)	スコア書き出し
readScore(name, noninteractive=false)	スコア読み込み
closeScore(score) / closeScore()	スコアを閉じる
fraction(num, den)	Fraction 生成
fractionFromTicks(ticks)	tick から Fraction
ornamentInterval(step, type)	装飾音程
interval(chromatic, diatonic)	音程
intervalFromOrnamentInterval(o)	装飾音程から音程
newQProcess()	外部プロセス（QML 型名 QProcess）
log / logn / log2 / openLog / closeLog	ログ
quit()	プラグイン終了

使用例: 要素生成・内部コマンド・スコア I/O

// 要素の生成（配置は Cursor.add などと組み合わせる → 付録 A）
var text = newElement(Element.STAFF_TEXT)
text.text = "Hello"

// 内部コマンド（選択・カット等）
cmd("select-all")

// スコアの読み書き・終了
var score = readScore("/path/to/score.mscz")
writeScore(curScore, "/path/to/out", "mscz")
quit()

1.4 列挙へのアクセス

ルート上のプロパティとして列挙オブジェクトが公開されます。例:

Element.NOTE
Element.CHORD
Placement.ABOVE
Direction.UP
Segment.ChordRest   // セグメント種別（名前は実装の SegmentType に対応）
Cursor.SCORE_START

完全な一覧は §11 を参照。

---

2. Score

実装: score.h
取得: curScore、または readScore / newScore の戻り値。

2.1 主なプロパティ

プロパティ	型		説明
scoreName	string	RW	ファイル名（パス・拡張子なし）
title	string	RO	作品タイトル（meta workTitle）
composer	string	RO	作曲者
lyricist	string	RO	作詞者
duration	int	RO	再生時間（秒）
mscoreVersion / mscoreRevision	string	RO	最終保存時の版情報
style	MStyle	RO	スタイル設定
keysig	int	RO	開始調号（シャープ正・フラット負）
npages / pages	int / Page[]	RO	ページ（pages は 4.6+）
pageNumberOffset	int	RW	ページ番号オフセット
parts	Part[]	RO	パート一覧
nstaves / staves	int / Staff[]	RO	五線
ntracks	int	RO	トラック数
systems	System[]	RO	システム（4.6+）
spanners	Spanner[]	RO	スパナー（4.7+）
hasHarmonies / harmonyCount	bool / int	RO	コード記号
hasLyrics / lyricCount / lyrics	…	RO	歌詞（lyrics は 4.7+）
nmeasures	int	RO	小節数
firstMeasure / lastMeasure	Measure	RO	先頭・末尾小節
firstMeasureMM / lastMeasureMM	Measure	RO	複数小節休符考慮
lastSegment	Segment	RO	末尾セグメント
layoutMode	int	RW	レイアウトモード（4.6+）
showInvisible 等	bool	RW	表示オプション（4.6+）
selection	Selection	RO	選択
excerpts	Excerpt[]	RO	抜粋（リンクパート）

2.2 主なメソッド

メソッド	説明
newCursor()	Cursor を生成（初期位置なし → rewind が必要）
startCmd(actionName?) / endCmd(rollback?)	編集コマンドの開始／終了
metaTag(tag) / setMetaTag(tag, value)	メタタグ
appendPart(instrumentId)	楽器 ID でパート追加
appendPartByMusicXmlId(id)	MusicXML Sound ID で追加
insertPart(instrumentId, index)	指定位置に挿入（4.7+）
appendMeasures(n)	小節追加
firstSegment(segmentType?)	先頭セグメント
findSegmentAtTick(types, tick)	指定位置のセグメント検索（4.6+）
tick2measure(tick)	tick（Fraction）→ 小節（4.6+）
addText(type, text)	テキスト追加
doLayout(startTick, endTick)	強制レイアウト（4.6+）
createPlayEvents()	再生イベント生成
showElementInScore(element, staffIdx?)	要素をスコア上で表示
extractLyrics()	歌詞を文字列で抽出
removeParts / removeStaves	パート／五線削除（4.7+）
moveParts / moveStaves	並び替え（4.7+）
appendStaff / appendLinkedStaff	五線追加（4.7+）
setVoiceVisible(staff, voiceIndex, visible)	声部表示（抜粋スコア向け、4.7+）
replaceInstrument / replaceDrumset など	楽器・ドラムセット操作（4.7+）

使用例: Cursor 生成・編集コマンド・メタタグ・小節追加

var cursor = curScore.newCursor()
cursor.rewind(Cursor.SCORE_START)

curScore.startCmd("my-plugin")
curScore.setMetaTag("workTitle", "Untitled")
console.log(curScore.metaTag("workTitle"))
curScore.appendMeasures(4)
curScore.endCmd()

---

3. Cursor

実装: cursor.h
取得: score.newCursor()

作成直後は位置が未定義です。rewind / rewindToTick / rewindToFraction で初期化するか、inputStateMode を INPUT_STATE_SYNC_WITH_SCORE にしてスコアの入力状態と同期します。

3.1 プロパティ

プロパティ	型		説明
track	int	RW	トラック
staffIdx	int	RW	五線インデックス（track / 4）
staff	Staff	RW	現在の Staff（4.6+）
voice	int	RW	声部（track % 4）
filter	int	RW	移動対象セグメント種別のビットマスク（既定: ChordRest）
tick	int	RO	MIDI tick（4.6 以降非推奨。位置取得は fraction を推奨）
utick	int	RO	リピートを考慮した tick（4.6+）
fraction	Fraction	RO	全音符基準の位置（4.6+）
tempo	real	RO	現在テンポ
keySignature	int	RO	現在の調号
score	Score	RW	関連スコア
element	EngravingItem	RO	現在トラックの要素
segment	Segment	RO	現在セグメント
measure	Measure	RO	現在小節
stringNumber	int	RW	弦番号（タブ等、3.5+）
inputStateMode	enum	RW	入力状態の同期モード（3.5+）

3.2 列挙

RewindMode

値	意味
Cursor.SCORE_START (0)	スコア先頭
Cursor.SELECTION_START (1)	選択開始
Cursor.SELECTION_END (2)	選択終了

InputStateMode

値	意味
Cursor.INPUT_STATE_INDEPENDENT	スコア入力状態と独立（既定）
Cursor.INPUT_STATE_SYNC_WITH_SCORE	スコア入力状態と同期

3.3 メソッド

メソッド	説明
rewind(mode)	位置を巻き戻し
rewindToTick(tick)	tick へ移動
rewindToFraction(f)	Fraction へ移動
time(includeRepeats?)	時間（秒）
next() / prev()	次／前のセグメントへ（filter 適用）
nextMeasure()	次の小節へ
add(element)	要素を追加
addNote(pitch, addToChord=false)	音符追加
addRest()	休符追加
addTuplet(ratio, duration)	連符追加
setDuration(z, n)	音価設定（n==0 なら 4分）

使用例: 巻き戻し・走査・音符追加

var cursor = curScore.newCursor()
cursor.rewind(Cursor.SCORE_START)
// 選択範囲から始める場合: cursor.rewind(Cursor.SELECTION_START)

curScore.startCmd("add-notes")
cursor.setDuration(1, 4)          // 4分音符
cursor.addNote(60)                // MIDI C4
cursor.next()
cursor.addRest()

// 先頭から ChordRest を走査
cursor.rewind(Cursor.SCORE_START)
while (cursor.segment) {
    var el = cursor.element
    if (el && el.type === Element.CHORD)
        console.log(el.notes[0].pitch)
    if (!cursor.next())
        break
}
curScore.endCmd()

使用例: Fraction 位置への移動と要素の追加

var cursor = curScore.newCursor()
cursor.rewindToFraction(fraction(1, 1))  // 全音符 1 つ分の位置へ

var text = newElement(Element.STAFF_TEXT)
text.text = "mark"
curScore.startCmd()
cursor.add(text)
curScore.endCmd()

---

4. Selection

実装: selection.h（3.3+）
取得: score.selection

プロパティ	型		説明
elements	EngravingItem[]	RO	選択中の要素
isRange	bool	RO	範囲選択か（3.5+）
startSegment / endSegment	Segment	RO	範囲の開始（含む）／終了（含まない）
startStaff / endStaff	int	RO	範囲の五線（終了は含む）

メソッド	説明
select(e, add=false)	要素を選択
selectRange(startTick, endTick, startStaff, endStaff)	範囲選択
deselect(e)	選択解除
clear()	全解除

使用例: 要素選択・範囲選択・解除

var sel = curScore.selection
var cursor = curScore.newCursor()
cursor.rewind(Cursor.SCORE_START)

if (cursor.element)
    sel.select(cursor.element)           // 単一選択
// sel.select(cursor.element, true)      // 追加選択

// 範囲選択（tick は整数。Fraction の ticks を使う例）
var start = fraction(0, 1).ticks
var end = fraction(4, 1).ticks
sel.selectRange(start, end, 0, 0)

console.log(sel.elements.length, sel.isRange)
sel.clear()

---

5. ScoreElement / EngravingItem

5.1 ScoreElement

実装: scoreelement.h — ほとんどの楽譜オブジェクトの基底。

プロパティ	型		説明
type	ElementType	RO	要素型（Element.* と比較）
name	string	RO	型名（非ローカライズ）
spatium	real	RO	スペーシウム（4.6+）
eid	string	RO	要素 ID（4.6+）

メソッド	説明
userName()	ローカライズされた型名
is(other)	同一オブジェクトか

5.2 EngravingItem

実装: elements.h — 記譜上の要素。

主なプロパティ（抜粋）:

プロパティ	型		説明
parent	EngravingItem	RO	親要素
staff	Staff	RO	所属五線
staffIdx	int	RO	五線インデックス（4.6+）
offsetX / offsetY	real	RW	ユーザーオフセット（spatium）
pos / posX / posY	PointF / real	RO	基準位置（親相対、spatium）
pagePos / canvasPos	PointF	RO	ページ／キャンバス座標
bbox	RectF	RO	バウンディングボックス
color	color	RW	色（API_PROPERTY / Pid）
visible	bool	RW	表示／非表示
selected	bool	RO	選択状態
text / htmlText	variant	RW	テキスト系要素向け（htmlText は 4.6+）

メソッド	説明
clone()	複製（プラグイン所有）

多くの見た目・配置プロパティは内部 Pid 経由の API_PROPERTY マクロで公開されています（配置、フォント、線種など）。詳細は elements.h を参照してください。

---

6. Note / Chord / ChordRest / DurationElement

6.1 DurationElement

音価を持つ要素の基底。

プロパティ	型		説明
duration	Fraction	RW	表記上の音価（和音・休符は 4.6+ で書き込み可）
globalDuration	Fraction	RO	グローバル音価（親連符比を反映、3.5+）
actualDuration	Fraction	RO	実際の音価（連符・局所拍子等を反映、3.5+）
tuplet / topTuplet	Tuplet	RO	所属連符／最外連符（topTuplet は 4.6+）
measure	Measure	RO	所属小節（4.6+）

6.2 ChordRest

和音・休符の共通基底。

プロパティ	型		説明
lyrics	Lyrics[]	RO	歌詞一覧
beam	Beam	RO	ビーム（3.6+）
elements	EngravingItem[]	RO	フェルマータ等の付属要素（4.6+）
isFullMeasureRest	bool	RO	全休符か（4.6+）

6.3 Chord

プロパティ	型		説明
notes	Note[]	RO	構成音
graceNotes / graceNotesBefore / graceNotesAfter	Chord[]	RO	装飾音符（前後分割は 4.6+）
articulations	EngravingItem[]	RO	アーティキュレーション（4.6+）
stem / stemSlash / hook	EngravingItem	RO	符幹・スラッシュ・フック（3.6+）
upNote / downNote	Note	RO	最高／最低音（4.6+）
arpeggio / tremoloSingleChord / tremoloTwoChord	EngravingItem	RO	アルペジオ・トレモロ（4.6+）
playEventType	PlayEventType	RW	再生イベント種別（3.3+）
noteType	NoteType	RO	音符種別（3.2.1+）

メソッド	説明
add(element) / remove(element)	子の追加／削除

使用例: 和音内の音符を走査・pitch / tpc を読む

var el = cursor.element
if (el && el.type === Element.CHORD) {
    for (var i = 0; i < el.notes.length; i++) {
        var n = el.notes[i]
        console.log(n.pitch, n.tpc)
    }
}

6.4 Note

プロパティ	型		説明
pitch	int	RW	MIDI 音高
tpc	int	RW	現在の Concert Pitch 設定に応じた TPC
tpc1	int	RW	コンサートピッチの TPC
tpc2	int	RW	移調楽器側の TPC
tuning	real	RW	チューニング（cents）
userVelocity	int	RW	ベロシティ
line / fixed / fixedLine	int / bool / int	RW	五線上の線位置
fret / string	int	RW	タブ用フレット／弦
dead	bool	RW	デッドノート（4.6+）
accidental	EngravingItem	RO	臨時記号オブジェクト
accidentalType	AccidentalType	RW	臨時記号種別
dots	EngravingItem[]	RO	付点
elements	EngravingItem[]	RO	子要素（運指・記号など）
playEvents	PlayEvent[]	RO	再生イベント（3.3+）
tieBack / tieForward	Tie	RO	タイ（3.3+）
firstTiedNote / lastTiedNote	Note	RO	タイ連結の端（3.3+）
spannerForward / spannerBack	Spanner[]	RO	スパナー（4.6+）
noteType	NoteType	RO	音符種別（3.2.1+）
isTrillCueNote	bool	RO	トリル用キューか（4.6+）

メソッド	説明
createPlayEvent()	PlayEvent 生成（3.3+）
add / remove	子要素の追加／削除（3.3.3+）

使用例: pitch の書き換え

curScore.startCmd("transpose-up")
var el = cursor.element
if (el && el.type === Element.CHORD) {
    for (var i = 0; i < el.notes.length; i++)
        el.notes[i].pitch += 12   // 1 オクターブ上げ
}
curScore.endCmd()

6.5 Tuplet

連符。DurationElement を継承（elements.h）。

プロパティ	型		説明
numberType	int	RW	数字表示種別（TupletNumberType）
bracketType	int	RW	囲み種別（TupletBracketType）
hasBracket	bool	RO	囲みの有無（4.6+）
actualNotes	int	RO	基準音価に対する実際の音符数
normalNotes	int	RO	対応する「通常」音符数
p1 / p2	QPointF	RW	左端／右端のユーザーオフセット（spatium 単位）
defaultP1 / defaultP2	QPointF	RO	左端／右端の実位置（spatium 単位、4.6+）
elements	要素[]	RO	連符に属する要素（3.5+）

6.6 Beam

ビーム。EngravingItem を継承（elements.h）。

プロパティ	型		説明
growLeft / growRight	real	RW	左右のフェザリング（羽状ビーム）
isCrossStaff	bool	RO	クロススタッフビームか
isFullCrossStaff	bool	RO	全体が別の五線上にあるか
defaultCrossStaffIdx	int	RO	既定のクロススタッフ位置
minCRMove / maxCRMove	int	RO	クロススタッフ位置の最小／最大
elements	ChordRest[]	RO	ビームに属する和音・休符

---

7. Segment / Measure

7.1 Segment

時間位置ごとのコンテナ。

プロパティ	型		説明
annotations	EngravingItem[]	RO	アノテーション（テキスト・アーティキュレーション等）
next / prev	Segment	RO	スコア内の次／前（小節境界を越える）
nextInMeasure / prevInMeasure	Segment	RO	小節内の次／前
segmentType	int	RO	種別（Segment.*）
tick	int	RO	tick（整数）
fraction	Fraction	RO	位置（4.6+）

メソッド	説明
elementAt(track)	指定トラックの要素

使用例: セグメントの辿りとトラック要素の取得

var seg = curScore.firstSegment()
while (seg) {
    var el = seg.elementAt(0)   // トラック 0
    if (el)
        console.log(seg.fraction.str, el.type)
    seg = seg.next
}

7.2 Measure / MeasureBase

プロパティ	型		説明
tick / ticks	Fraction	RO	開始位置・長さ
elements	EngravingItem[]	RO	子要素（レイアウト区切り・ジャンプ等、3.3+）
nextMeasure / prevMeasure	Measure	RO	隣接小節
nextMeasureMM / prevMeasureMM	Measure	RO	複数小節休符を考慮した隣接（3.6+）

使用例: 小節の列挙

var m = curScore.firstMeasure
while (m) {
    console.log(m.tick.str, m.ticks.str)
    m = m.nextMeasure
}

7.3 System

システム（1 段の譜表）。EngravingItem を継承（elements.h、4.6+）。

プロパティ	型		説明
measures	MeasureBase[]	RO	このシステム内の小節・フレーム
firstMeasure / lastMeasure	Measure	RO	最初／最後の小節
first / last	MeasureBase	RO	最初／最後の小節またはフレーム
isLocked	bool	RW	システムがロックされているか
pageBreak	bool	RO	改ページを持つか
systemDividerLeft / systemDividerRight	EngravingItem	RO	左右のシステム区切り（存在すれば）

メソッド	説明
bbox(staffIdx)	指定五線のバウンディングボックス
yOffset(staffIdx)	最上段譜線からの Y 位置
show(staffIdx)	指定五線が表示されているか（Staff.show と異なる場合あり）
setHideStaffIfEmpty(staffIdx, hide)	空時の非表示挙動を上書き（AutoOnOff、4.7+）

7.4 Page

ページ。EngravingItem を継承（elements.h）。

プロパティ	型		説明
pageNumber	int	RO	0 始まりのページ番号（表示番号は pageNumber + 1 + score.pageNumberOffset、4.7+）
pagenumber	int	RO	pageNumber の別名（後方互換、3.5+）
systems	System[]	RO	このページ上のシステム一覧（4.6+）

---

8. Part / Staff / Excerpt など

8.1 Part

パート。ScoreElement を継承（part.h）。

プロパティ	型		説明
startTrack / endTrack	int	RO	先頭トラック／次パート先頭
instrumentId	string	RO	先頭楽器の MuseScore 楽器 ID（4.6+）
musicXmlId	string	RO	MusicXML Sound ID（3.2+）
partName	string	RO	パート名（Mixer 表示、3.2.1+）
longName / shortName	string	RO	現在楽器の長名／短名（3.2.1+）
midiChannel / midiProgram	int	RO	MIDI チャンネル／プログラム（3.2.1+）
harmonyCount	int	RO	コード記号数（3.2.1+）
hasChordSymbol	bool	RO	コード記号を持つか（4.6+）
hasDrumStaff / hasPitchedStaff / hasTabStaff	bool	RO	打楽器／音高／タブ譜を持つか（3.2.1+）
lyricCount	int	RO	歌詞音節数（3.2.1+）
show	bool	RW	パートの表示／非表示（3.6+ で書き込み可）
instruments	Instrument[]	RO	楽器一覧（3.5+）
staves	Staff[]	RO	所属五線一覧（4.6+）
masterPart	Part	RO	メインスコア側の対応パート（4.6+）

メソッド	説明
instrumentAtTick(tick)	指定位置の楽器（int は 3.5+、Fraction は 4.6+）
longNameAtTick(f) / shortNameAtTick(f)	指定位置の長名／短名（4.6+）
instrumentNameAtTick(f) / instrumentIdAtTick(f)	指定位置の楽器名／ID（4.6+）
currentHarpDiagramAtTick(f)	指定位置で有効なハープペダル図（4.6+）
nextHarpDiagramFromTick(f) / prevHarpDiagramFromTick(f)	次／前のハープペダル図（4.6+）
tickOfCurrentHarpDiagram(f)	有効なハープペダル図の tick（4.6+）

8.2 Staff

五線。ScoreElement を継承（elements.h、3.5+）。

プロパティ	型		説明
part	Part	RO	所属パート
idx	int	RO	五線インデックス（4.6+）
small	bool	RW	小さい五線
mag	real	RW	拡大率
color	color	RW	五線の色
playbackVoice1〜playbackVoice4	bool	RW	各声部を再生に含めるか
visible	bool	RW	五線自体の表示（4.6+）
show	bool	RO	実効的な表示（パート＋五線、4.6+）
cutaway	bool	RW	カットアウェイ五線（空小節を隠す、4.6+）
staffInvisible	bool	RW	譜線を非表示（4.6+）
hideSystemBarLine	bool	RW	システム小節線を隠す（4.6+）
showMeasureNumbers	enum	RW	小節番号表示（AutoOnOff、4.6+）
mergeMatchingRests	enum	RW	声部間で休符を統合（AutoOnOff、4.6+）
showIfEntireSystemEmpty	bool	RW	システム全体が空でも表示（4.6+）
reflectTranspositionInLinkedTab	bool	RW	連動タブ譜に移調を反映（4.6+）
staffBarlineSpan / staffBarlineSpanFrom / staffBarlineSpanTo	int	RW	小節線の連結範囲
staffUserdist	real	RW	五線前の追加スペース
primaryStaff	Staff	RO	元（非リンク）の五線（4.6+）

メソッド（いずれも Fraction tick 指定、4.6+）	説明
clefType(f) / key(f) / timeSig(f)	音部記号種別／調号／拍子
transpose(f) / timeStretch(f)	移調（Interval）／タイムストレッチ比
swing(f) / capo(f)	スウィング設定／カポ設定（オブジェクトを返す）
stemless(f) / staffHeight(f)	符幹なしか／五線高さ
isPitchedStaff(f) / isTabStaff(f) / isDrumStaff(f)	五線種別の判定
lines(f) / lineDistance(f) / isLinesInvisible(f)	譜線数／間隔／不可視か
middleLine(f) / bottomLine(f)	中央線／最下線
staffMag(f) / spatium(f) / pitchOffset(f)	五線倍率／スペーシウム／オッターバによる音高オフセット
isVoiceVisible(voice)	パートスコアで指定声部が表示されるか

特定小節から譜線数・記号生成などを変えたい場合は、Staff プロパティではなく Element.STAFFTYPE_CHANGE（譜表タイプ変更）を使います。

8.3 Instrument

楽器定義。QObject 派生（instrument.h、3.5+）。

プロパティ	型		説明
instrumentId	string	RO	MuseScore 楽器 ID
musicXmlId	string	RO	MusicXML Sound ID
longName / shortName	string	RO	長名／短名
stringData	StringData	RO	弦情報（フレット楽器向け）
drumset	Drumset	RO	打楽器セット（無音高打楽器向け、4.6+）
channels	Channel[]	RO	チャンネル一覧

メソッド	説明
cloneDrumset()	書き換え可能な Drumset の複製を返す（4.7+）
is(other)	同一オブジェクトか

8.4 Channel

音色・MIDI チャンネル設定（instrument.h、3.5+）。instrument.channels から取得。

プロパティ	型		説明
name	string	RO	チャンネル名
isHarmonyChannel	bool	RO	コード記号の再生を担うか（4.6+）
volume / pan / chorus / reverb	int	RW	音量／パン／コーラス／リバーブ（0–127）
mute	bool	RW	ミュート（4.0 以降は非推奨）
midiProgram	int	RW	MIDI プログラム番号（0–127、undo 可）
midiBank	int	RW	MIDI バンク番号（undo 可）

注: volume / pan / chorus / reverb / mute の変更は標準の「元に戻す」で復元されません。midiProgram / midiBank は undo スタックに記録されます。

8.5 StringData

弦データ（instrument.h、3.5+）。

プロパティ	型		説明
strings	list	RO	弦の一覧。各要素は pitch（0 フレット時の音高）と open（常時開放弦か）を持つ
frets	int	RO	フレット数

8.6 Drumset

打楽器セット（instrument.h、4.6+）。instrument.drumset は読み取り専用。書き換えには Instrument.cloneDrumset() の複製を使い、Score.replaceDrumset() で適用します。

メソッド	説明
isValid(pitch)	指定 MIDI 音高がセットに含まれるか
noteHead(pitch)	符頭グループ（NoteHeadGroup）
noteHeads(pitch, type)	符頭記号（SymId、type は NoteHeadType）
line(pitch) / voice(pitch) / stemDirection(pitch)	譜線位置／声部／符幹方向
name(pitch) / translatedName(pitch) / shortcut(pitch)	名称／訳名／ショートカット
variants(pitch)	バリアント一覧（pitch / tremolo / articulationName）
panelRow(pitch) / panelColumn(pitch)	打楽器パネルの行／列
defaultPitchForLine(line)	指定線の既定音高
nextPitch(pitch) / prevPitch(pitch)	次／前の使用音高
setName / setNoteHead / setLine / setVoice / setStemDirection / setShortcut	各設定（複製に対して、4.7+）
is(other)	同一オブジェクトか

8.7 Excerpt

抜粋（リンクパート）。QObject 派生（excerpt.h）。score.excerpts から取得。

プロパティ	型		説明
partScore	Score	RO	このパートのスコアオブジェクト
title	string	RO	パートのタイトル

メソッド	説明
is(other)	同一オブジェクトか（3.3+）

8.8 MStyle

スコアスタイル設定（style.h、3.5+）。score.style から取得。キーは Sid 値の名前。

メソッド	説明
value(key)	スタイル値を取得（戻り値の型は設定に依存）
setValue(key, value)	スタイル値を設定
resetValue(key)	スタイル値を既定へリセット（4.7+）

var style = curScore.style
var genClef = style.value("genClef") // 既定 true
style.setValue("genClef", false)

8.9 PlayEvent

再生イベント。mu::engraving::NoteEvent のラッパ（playevent.h、3.3+）。note.playEvents から取得。

プロパティ	型		説明
pitch	int	RW	親音符の実音高に加える相対音高
ontime	int	RW	発音開始（公称音長の 1/1000 単位）
len	int	RW	イベント長（同 1/1000 単位）
offtime	int	RO	消音時刻（ontime と len から導出）

8.10 Spanner / SpannerSegment

スパナー（線的要素）とその表示セグメント。ともに EngravingItem を継承（elements.h、4.6+）。

Spanner

プロパティ	型		説明
spannerTick	Fraction	RW	開始 tick
spannerTicks	Fraction	RW	継続長
spannerTrack2	int	RW	終了トラック
startElement / endElement	EngravingItem	RO	開始／終了要素
spannerSegments	SpannerSegment[]	RO	属するセグメント一覧
ornament	Ornament	RO	装飾オブジェクト

SpannerSegment

プロパティ	型		説明
spanner	Spanner	RO	親スパナー
spannerSegmentType	int	RO	セグメント種別（SpannerSegmentType）
pos2	QPointF	RO	終端位置（userOff2 を含む）
userOff2	QPointF	RW	線分の終端オフセット
slurUoff1〜slurUoff4	QPointF	RW	スラー・タイの各制御点オフセット

8.11 Tie

タイ。Spanner を継承（elements.h、3.3+）。

プロパティ	型		説明
startNote / endNote	Note	RO	開始／終了音符
isInside	bool	RO	内側配置か（4.6+）

8.12 Ornament

装飾記号。EngravingItem を継承（elements.h、4.6+）。

プロパティ	型		説明
hasIntervalAbove / hasIntervalBelow	bool	RO	上／下の音程を持つか
showCueNote	bool	RO	キュー音符を表示するか
accidentalAbove / accidentalBelow	EngravingItem	RO	上／下音程の臨時記号

8.13 Lyrics

歌詞。EngravingItem を継承（elements.h）。

プロパティ	型		説明
plainText	string	RO	書式を除いた歌詞テキスト
isMelisma	bool	RO	メリスマか
separator	EngravingItem	RO	歌詞ライン（存在すれば）
syllabic	int	RW	音節種別（Syllabic）
lyricTicks	Fraction	RW	歌詞の tick 長

8.14 Harmony

コード記号。EngravingItem を継承（elements.h）。

プロパティ	型		説明
plainText	string	RO	書式を除いた表記
displayText	string	RO	表示テキスト（書式付き）
harmonyName	string	RO	図データベース照合用の内部名

8.15 FretDiagram

フレットボード図。EngravingItem を継承（elements.h、4.7+）。

プロパティ	型		説明
harmony	Harmony	RO	図に紐づくコード記号（無ければ null）
harmonyPlainText / harmonyDisplayText	string	RO	コード記号のテキスト
strings / frets	int	RO	弦数／表示フレット数
fretOffset	int	RO	開始フレット（0 でナット表示）

メソッド	説明
dots()	ドット一覧（string / fret / dotType）
markers()	弦マーカー一覧（string / markerType）
barres()	バレー一覧（fret / startString / endString）
setDot(string, fret, add?, dotType?)	ドットの追加／削除（undo 可）
setMarker(string, marker)	弦マーカー設定（FretMarkerType）
setBarre(string, fret, add?)	バレー追加
clear()	ドット・マーカー・バレーを全消去

---

9. FileIO / QProcess

9.1 FileIO

実装: util.h
インポート: import FileIO 3.0

メンバー	説明
source	操作対象パス
read()	内容を文字列で読む
write(data)	書き込み（ユーザーデータ配下のみ）
writeBinary(data)	バイナリ書き込み（同上）
exists() / remove()	存在確認／削除
homePath() / tempPath()	ホーム／一時パス
userDataPath()	MuseScore ユーザーデータ
pluginsUserPath()	Plugins フォルダ
userProjectsPath() / userTemplatesPath() / userStylesPath()	各ユーザーフォルダ
userSoundFontDirectories()	SoundFont ディレクトリ一覧
pluginDirectoryPath()	このプラグインのフォルダ
projectPath() / projectDirectoryPath() / isProjectDirectory()	現在プロジェクト
isPathWriteable(path)	書き込み可否
modifiedTime()	更新時刻
error(msg) シグナル	エラー通知

使用例: 読み書き

import FileIO 3.0

FileIO {
    id: io
    source: ""
}

// 読み込み
io.source = io.pluginDirectoryPath() + "/config.txt"
if (io.exists())
    console.log(io.read())

// 書き込み（ユーザーデータ配下のみ可）
io.source = io.userDataPath() + "/plugins/my-plugin-out.txt"
io.write("hello\n")

9.2 MsProcess（QML: QProcess）

メソッド	説明
start(command)	起動（非推奨）
startWithArgs(program, args)	引数付き起動（4.3+）
waitForFinished(msecs=30000)	終了待ち
readAllStandardOutput()	標準出力

---

10. Fraction とその他ユーティリティ

10.1 Fraction

全音符を 1 とする有理数（apistructs.h、QML 型名は FractionWrapper）。ルートの fraction(n, d) / fractionFromTicks(t) で生成します。

プロパティ	型		説明
numerator / denominator	int	RO	分子／分母
ticks	int	RO	tick 換算（全音符数に相当）
str	string	RO	文字列表現
real	real	RO	実数値（例: 1/4 → 0.25、4.6+）
reduced	Fraction	RO	約分した分数（4.6+）
inverse	Fraction	RO	逆数（4.6+）
absValue	Fraction	RO	絶対値（4.6+）

メソッド	説明
plus(o) / minus(o)	加算／減算（4.6+）
times(o) / times(v)	乗算（分数／整数、4.6+）
dividedBy(o) / dividedBy(v)	除算（分数／整数、4.6+）
greaterThan(o) / lessThan(o)	大小比較（4.6+）
equals(o)	値が等しいか（2/4 と 1/2 は true、4.6+）
identical(o)	分子・分母が一致するか（2/4 と 1/2 は false、4.6+）

10.2 Interval / OrnamentInterval

音程ラッパ（apistructs.h、4.6+）。ルートの interval(chromatic, diatonic) / ornamentInterval(step, type) で生成します。

Interval（IntervalWrapper）

メンバー	型		説明
diatonic	int	RO	全音階ステップ数
chromatic	int	RO	半音ステップ数
isZero	bool	RO	音程が 0 か
flip()	メソッド		音程を反転

OrnamentInterval（OrnamentIntervalWrapper）

メンバー	型		説明
step	enum	RO	音程ステップ（IntervalStep）
type	enum	RO	音程種別（IntervalType）
isPerfect	bool	RO	完全音程か

---

11. 列挙（Enum）

QML では Element.NOTE のようにアクセスします。定義の一次ソースは apitypes.h です。

11.1 頻出: Element（ElementType）

値（例）	意味
NOTE	音符
CHORD	和音
REST	休符
MEASURE	小節
SEGMENT	セグメント
STAFF / PART / SCORE	五線／パート／スコア
CLEF / KEYSIG / TIMESIG	音部記号／調号／拍子
BAR_LINE	小節線
TIE / SLUR / BEAM	タイ／スラー／ビーム
LYRICS / HARMONY	歌詞／コード記号
DYNAMIC / TEMPO_TEXT	強弱／テンポ
STAFF_TEXT / SYSTEM_TEXT	五線／システムテキスト
FINGERING	運指テキスト（Note.add の子として配置）
LAYOUT_BREAK	改行・改ページ（layoutBreakType で種別指定）
STAFFTYPE_CHANGE	譜表タイプ変更（下記）
ARTICULATION / ORNAMENT / FERMATA	アーティキュレーション等
HAIRPIN / OTTAVA / VOLTA / PEDAL / TRILL / GLISSANDO	各種スパナー
TUPLET	連符
PAGE / SYSTEM	ページ／システム
FRET_DIAGRAM	フレット図
…	その他多数（150+）

11.1.1 StaffTypeChange

配置した位置以降の五線見た目を上書きする要素です。専用の QML クラスはなく、newElement(Element.STAFFTYPE_CHANGE) で得た EngravingItem に対し、API_PROPERTY（内部 Pid）経由で設定します。

使う意図

• Staff/Part の既定設定はそのままに、特定小節から線数・記号生成・符幹などを切り替えたいとき
• 数字譜・実験記譜など、「五線譜としての見た目」を局所的に変えたいとき（譜表・記譜操作ガイド）

UI の「譜表の種類の変更」と同じ仕組みです。要素を置くと編集用の四角マーカーが出ます（印刷されないことが多い）。

プロパティ	型		説明
staffLines	int	RW	譜線数（0 で線なし。数字譜向き）
staffInvisible	bool	RW	譜線を不可視に（「不可視を表示」オンだと灰色で残る）
staffGenClef	bool	RW	音部記号を生成するか
staffGenTimesig	bool	RW	拍子記号を生成するか（4/4 の C 表示も含む）
staffGenKeysig	bool	RW	調号を生成するか
staffStemless	bool	RW	符幹・旗・連桁を出さない
staffShowLedgerlines	bool	RW	加線を表示するか
staffShowBarlines	bool	RW	小節線を表示するか

curScore.startCmd()
var stc = newElement(Element.STAFFTYPE_CHANGE)
cursor.add(stc)
stc.staffLines = 0
stc.staffGenClef = false
stc.staffGenTimesig = false
stc.staffGenKeysig = false
stc.staffStemless = true
stc.staffShowLedgerlines = false
curScore.endCmd()

実装の一次ソース: elements.h の API_PROPERTY_T(... STAFF_*)、内部は StaffTypeChange の setProperty。

注意: Staff.staffInvisible は API 上 RW でも、プラグインからの直接書き込みでは見た目が変わらないことがあります。譜線まわりは StaffTypeChange 側を優先してください。

11.2 PluginAPI 上のその他の列挙プロパティ（抜粋）

QML 名	内容
Accidental	臨時記号種別
Placement / PlacementH	上下／水平配置
Direction / DirectionH	方向
Beam	ビームモード
Segment	セグメント種別
NoteHeadType / NoteHeadGroup / NoteHeadScheme	符頭
NoteType	音符種別
PlayEventType	再生イベント
Tid	テキストスタイル
Lyrics	歌詞音節（Syllabic）
Spanner	スパナーアンカー
LayoutBreak	改行・改ページ
SymId	記号 ID（3.5+）
ClefType / DynamicType / Key	音部／強弱／調（4.6+）
LayoutMode	レイアウトモード（4.6+）
OrnamentStyle	装飾スタイル
Glissando / GlissandoStyle	グリッサンド
HarmonyType	ハーモニー種別（3.5+）

4.6 以降、多数の列挙が追加されています。完全リストは qmlpluginapi.h の DECLARE_API_ENUM を参照してください。

---

12. クラス一覧（3.5 Docs との対応）

PluginAPI Docs: annotated.html に記載の Ms::PluginAPI クラスと、現行実装の対応です。

「クラス」列は本書内の該当節へ、「ソース」列は現行実装のヘッダ（main ブランチ）へのリンクです。

クラス（本書内リンク）	現行実装	ソース	主な用途
PluginAPI	PluginAPI（QML: MuseScore）	qmlpluginapi.h	ルート API
Cursor	Cursor	cursor.h	走査・入力
Score	Score	score.h	楽譜
Selection	Selection	selection.h	選択
ScoreElement	ScoreElement	scoreelement.h	基底
Element	EngravingItem	elements.h	記譜要素
DurationElement	DurationElement	elements.h	音価付き
ChordRest	ChordRest	elements.h	和音／休符共通
Chord	Chord	elements.h	和音
Note	Note	elements.h	音符
Tuplet	Tuplet	elements.h	連符
Beam	Beam	elements.h	ビーム
Segment	Segment	elements.h	セグメント
Measure / MeasureBase	Measure	elements.h	小節
System	System	elements.h	システム
Page	Page	elements.h	ページ
Part	Part	part.h	パート
Staff	Staff	elements.h	五線
Instrument	Instrument	instrument.h	楽器
Channel	Channel	instrument.h	チャンネル
StringData	StringData	instrument.h	弦データ
Drumset	Drumset	instrument.h	打楽器セット
Excerpt	Excerpt	excerpt.h	抜粋
MStyle	MStyle	style.h	スタイル
PlayEvent	PlayEvent	playevent.h	再生イベント
Spanner / SpannerSegment	Spanner	elements.h	スパナー
Tie	Tie	elements.h	タイ
Ornament	Ornament	elements.h	装飾記号
Lyrics	Lyrics	elements.h	歌詞
Harmony	Harmony	elements.h	コード記号
FretDiagram	FretDiagram	elements.h	フレット図
FractionWrapper	Fraction	apistructs.h	分数
Interval / OrnamentInterval	IntervalWrapper ほか	apistructs.h	音程
FileIO	FileIO	util.h	ファイル I/O
MsProcess	MsProcess（QML: QProcess）	util.h	外部プロセス
Enum	Enum	enums.h	列挙ラッパ
ScoreView	MuseScore 3 のみ（4 では未登録）	（3.x: mscore/plugin/api/util.h）	ダイアログ内のスコアプレビュー
Qml*ListAccess	内部（直接は使わない）	scoreelement.h ほか	notes 等のリストプロパティ実装

名前空間は Docs では Ms::PluginAPI、現行ソースでは mu::engraving::apiv1 です。QML からの見え方（MuseScore, Element.NOTE 等）は互換を意識して維持されています。

ScoreView（利用シーン）

プラグインのダイアログ UI に、スコアの簡易ビューを埋め込むための QML コンポーネントです（3.2+）。pluginType: "dialog" でプレビューを出したいときに使います。

メソッド / プロパティ	説明
setScore(score)	表示する Score を設定
setCurrentPage(n) / nextPage() / prevPage()	ページ切替
color / scale	背景色・拡大率

MuseScore 3 付属の view.qml が典型例です。

ScoreView {
    id: scoreview
    anchors.fill: parent
    color: "white"
    Component.onCompleted: scoreview.setScore(curScore)
}

現行 MuseScore 4 の qmlpluginapi.cpp では ScoreView の qmlRegisterType がコメントアウトされており、4.x のプラグインからは使えません（3.5 Docs との対応表用の行です）。

Qml*ListAccess（利用シーン）

C++ 側のコンテナを QML のリスト（length / 添字アクセス）として公開するための 内部ラッパです。プラグイン作者が QmlListAccess などをインスタンス化することはありません。

代わりに、次のようなプロパティ経由で結果だけを使います。

見えるプロパティ	内部クラス	ソース
chord.notes、selection.elements、scores など	QmlListAccess（読み取り専用）	scoreelement.h
score.excerpts	QmlExcerptsListAccess	excerpt.h
note.playEvents	QmlPlayEventsListAccess（append / clear あり）	playevent.h

// 例: Chord.notes（QmlListAccess 経由）
for (var i = 0; i < chord.notes.length; i++)
    console.log(chord.notes[i].pitch)

// 例: Note.playEvents（装飾音の再生タイミング編集など）
note.playEvents.clear()

Docs のクラス一覧に載っているのは実装詳細の対応用で、日常のプラグイン記述では上記の各プロパティ節を参照すれば十分です。

---

付録 A: 典型的なコードパターン

各クラス直下の折りたたみ例はメソッド単位の断片です。ここでは複数 API をまたぐ典型フローを示します。

選択範囲の音符を走査

import MuseScore 3.0

MuseScore {
    version: "1.0"
    description: "選択音符の pitch をログ"
    onRun: {
        var cursor = curScore.newCursor()
        cursor.rewind(Cursor.SELECTION_START)
        var endSeg = curScore.selection.endSegment
        curScore.startCmd()
        while (cursor.segment && cursor.segment !== endSeg) {
            var el = cursor.element
            if (el && el.type === Element.CHORD) {
                for (var i = 0; i < el.notes.length; i++)
                    console.log(el.notes[i].pitch, el.notes[i].tpc)
            }
            if (!cursor.next())
                break
        }
        curScore.endCmd()
        quit()
    }
}

要素の新規作成と配置

curScore.startCmd()
var text = newElement(Element.STAFF_TEXT)
text.text = "Hello"
cursor.add(text)
curScore.endCmd()

---

付録 B: 詳細を調べるとき

目的	参照先
プロパティの正確な定義	src/engraving/api/v1/*.h
3.5 時代の HTML リファレンス	PluginAPI Docs クラス一覧
pitch / tick / tpc の表	pitch.html、ticklength.html、tpc.html
Extensions の UI / macros	docs/apidocs_static/tutorials/
公開ドキュメント生成物	musescore.github.io

前章: プラグイン開発の概要