Gagaku Score Player (雅楽譜プレイヤー)

日本語の説明は下に記載しています

English | 日本語

English

A free desktop app for programming (DTM) gagaku, Japanese imperial court music. Type gagaku notation characters (譜字) as plain text and the app plays them as an ensemble of shō, hichiriki, ryūteki, gakubiwa, gakusō, kakko, shōko and taiko (Windows, macOS and Linux; written in Python). No DAW or sample library is needed. It also shows a Western staff view and exports WAV files.

Website (English): https://zitengxiang.github.io/gagaku-player/en/ Website (Japanese): https://zitengxiang.github.io/gagaku-player/

Install and run

With pip:

pip install gagaku-player
gagaku-player --demo          # open the sample piece "Wakatake"
gagaku-player piece.gaku      # open a score

From source:

git clone https://github.com/ZiTengXiang/gagaku-player.git
cd gagaku-player
pip install -r requirements.txt
python main.py examples/demo_hyojo.gaku

• Requirements: Python 3.10+ and numpy (tkinter ships with Python). You can also start it with python -m gagaku.
• On Windows nothing else is needed (playback uses the built-in winsound). On macOS/Linux, installing with pip also installs sounddevice for playback (from source, run pip install sounddevice).
• To launch from an icon on Windows, make a shortcut that runs pythonw.exe main.py and set its icon to gagaku/assets/gagaku.ico (pythonw opens no console window). Rebuild the icon with python tools/make_icon.py (needs Pillow and the Yu Mincho font).
• If the app crashes when started without a console, it writes the details to error.log and shows a dialog.

Screen

• Left, "譜面テキスト" (score text) tab: the score editor. While playing, the sounding notes are highlighted in yellow. Lines with errors turn red.
• Left, "楽譜表示" (score view) tab: a read-only full score with the beats of all instruments aligned vertically, five bars per system, all instruments stacked. Bar lines come from | in the score; sustained notes are drawn as thin lines. Sounding notes are highlighted during playback; clicking a note selects it in the text (press F6 to play from there).
• Left, "五線譜" (staff) tab: a read-only full score in Western staff notation, five bars per system, with the gagaku character under each note. One beat = a quarter note; notes crossing beats or bar lines are tied. Clefs are chosen automatically from each instrument's range (treble, bass, and treble 8va/8vb). There is no key signature; sharps are written on each note. Shō chords (合竹) are written as chords; biwa sweeps (掻撥) and koto patterns (閑掻・早掻) as arpeggiated chords. Percussion uses a one-line staff (× noteheads for kakko and shōko; tremolo for rolls 来). Highlighting and click-to-jump work as in the score view.
• Menu bar: File (new, open, save, export WAV, quit) and Plugins (find and manage plugins).
• Top right: a palette of notation characters per instrument. Click to insert at the cursor.
• Bottom right: the mixer (mute and volume per part).
• Toolbar "1小節 _ 拍" (beats per bar): changing it writes beats: to the header and re-bars the score text, score view and staff at that many beats (the sound does not change).
• Toolbar "小節の間(ま) _ 拍" (ma between bars): turns the pause between bars on or off and sets its length.
  • On: a pause of the given number of beats is inserted at the end of each bar (except the last). During it, every note sounding at the end of the bar (held notes and notes crossing the bar line) is sustained. Parts resting at the end of the bar stay silent.
  • Off (unchecked): plays straight through in tempo, as before.
  • The setting is saved as ma: in the header. The notation does not change; only the timing of playback and WAV export does.
• Toolbar: play (F5) / play from cursor (F6) / stop (Esc) / speed % / reverb / export WAV.

Plugins

Open Plugins → Find and manage plugins… (プラグイン → プラグインを探す・管理…) from the menu bar.

• Type in the search box to filter plugins by name, description or tag (for example english or 英語). The list combines the plugins bundled with the app and the online catalog on the website (https://zitengxiang.github.io/gagaku-player/plugins/index.json), so new plugins can appear without updating the app.
• Install adds the selected plugin and enables it. Files downloaded from the online catalog are checked against the SHA-256 hashes in the catalog before they are saved.
• Enable / Disable turns an installed plugin on or off at any time (double-clicking a row does the same). The change applies immediately and is remembered for the next start.
• Uninstall removes it.
• Plugins run as Python code. Install only plugins you trust.
• Plugins and settings are stored in ~/.gagaku_player/ (plugins/<id>/ and settings.json; change the location with the GAGAKU_PLAYER_HOME environment variable).

English UI plugin

Switches the menus, buttons, tabs, help texts, status messages and instrument names to English. Notation buttons are shown as Ichi（一）, and hovering a button shows a small pop-up with its reading, Japanese spelling and pitches for the current mode, for example:

Reading: jō
Japanese: 丄(じょう)
Notes: E2, B2, E3, A3 (arpeggio, landing on A3 on the beat)
Mode: Hyōjō

The notation characters written in the score text stay in Japanese, because they are the score data.

Writing a plugin

A plugin is a folder with two files:

plugin.json   {"id": "myplugin", "name": "My plugin", "version": "1.0.0", "api": 1,
               "description": {"ja": "…", "en": "…"}, "tags": ["…"]}
plugin.py     class Plugin:
                  def activate(self, api): ...
                  def deactivate(self, api): ...   # optional

activate receives an API object with:

• api.set_texts({key: text}) — replace UI texts (keys as used by App.t() in gagaku/gui.py; see TEXTS in gagaku/bundled_plugins/english/plugin.py for the full list)
• api.add_palette_label(func) — func(instrument_key, character) -> label or None
• api.add_palette_tooltip(func) — func(instrument_key, character, mode) -> pop-up text or None
• api.add_instrument_label(func) — func(instrument_key) -> name or None
• api.instruments (the gagaku.instruments module) and api.current_mode()

Everything a plugin registers is removed automatically when it is disabled. To publish a plugin in the in-app catalog, put it in gagaku/bundled_plugins/<id>/ and run python tools/build_plugin_index.py, which copies it to docs/plugins/ and writes index.json with the hashes.

Score format (.gaku, UTF-8 text)

title: Piece title
mode: 平調          # 壱越調 平調 双調 黄鐘調 盤渉調 太食調
tempo: 60           # BPM per beat
beats: 4            # beats per bar (if omitted, bars follow | in the score)
ma: 1               # length of the pause between bars, in beats; omit or 0 for none

[笙]
乙 - - - | 一 - 工 - |
[竜笛]
干 - 五 丄 | 責干:2 中 夕 |

A part may be split over several [instrument] blocks (they continue one after another). Notes can also follow the instrument name on the same line, as in [笙] 乙 - 下 |. If the parts have different lengths, a warning appears in the status bar.

Aligning vertically (auto-format)

When you open, save, play or export, or press the "縦にそろえる" (align) button (Ctrl+Shift+F), the score text is formatted like this:

# ---- 1〜5小節
[笙]    十    -   凢   -   |  乞  -  一  -  |  ...
[篳篥]  丄    四  六   工  |  五  -  工  六 |  ...
[竜笛]  責丄  干  六   中  |  夕  -  中  六 |  ...

• Five bars per system. In each system the lines of all instruments are stacked and the beats line up vertically (in a monospaced font). Bars are separated by |.
• Two spaces between beats, one space between notes within a beat (half beats and so on). 乙:2 is rewritten as 乙 -.
• Formatting never changes the music (start beat, length and tempo changes stay the same). Comments written inside the score body are moved together after the header.
• It does not run while you type; if the columns drift after editing, press Ctrl+Shift+F.

Notation per instrument

Pitch and tuning

• Reference pitch A4 = 430 Hz (a4_hz in gagaku/tunings.json), in equal temperament.
• The pitches of the shō pipes and the makeup of its chords, and the pitches of the ryūteki characters, follow the tables in Japanese Wikipedia ("笙", "龍笛").
• No source was found for the gakubiwa and gakusō tunings in each mode. They are therefore provisional, built from the tonic and scale of each mode. Edit gagaku/tunings.json to use accurate tunings (biwa: [open, frets 1–4] per string; koto: the 13 strings 一–巾).
• The 閑掻, 早掻, 掻撥 and 来 techniques are simplified approximations.
• All sounds are synthesized with numpy; no samples are used.
  • Shō: pipes shared between consecutive chords keep sounding, and only the changing pipes enter and leave slightly staggered (手移り). Each chord swells with the breath.
  • Hichiriki and ryūteki: notes up to a rest are synthesized as one phrase and joined with 塩梅 (the hichiriki dips before rising to a higher note). Repeated notes are re-articulated with a short break.
  • Biwa and koto: strings with partials that decay at different rates, plus the sound of the plectrum or picks and the body resonance.
  • Kakko, taiko and shōko: inharmonic membrane and metal modes.
• Write preview WAVs per instrument to previews/ with python tools/make_previews.py.

Layout

main.py                 entry point
gagaku/score.py         score parser
gagaku/instruments.py   notation → pitch/technique, instrument sounds
gagaku/tunings.json     biwa and koto tunings (editable)
gagaku/synth.py         synthesis and reverb
gagaku/render.py        mixing and WAV export
gagaku/audio.py         playback
gagaku/gui.py           Tkinter GUI
gagaku/scoreview.py     score view (five bars per system)
gagaku/formatter.py     score text formatter (aligns beats)
gagaku/staffview.py     staff view (with notation characters)
gagaku/plugins.py       plugin system (load, enable, catalog, install)
gagaku/bundled_plugins/ plugins bundled with the app (English UI)
gagaku/assets/          icon
examples/               sample scores (bundled in the pip package)
tools/make_previews.py  writes preview WAVs per instrument
tools/make_icon.py      rebuilds the icon
tools/make_site_audio.py writes the website's preview MP3s
tools/build_plugin_index.py builds the online plugin catalog (docs/plugins/)
tests/                  pytest tests
docs/                   website (GitHub Pages)
.github/workflows/      CI (test and build) and PyPI publishing

Development

pip install -e . pytest
python -m pytest

• On every push and pull request, GitHub Actions runs the tests on Windows and Ubuntu with Python 3.10–3.13 and builds the package (.github/workflows/ci.yml).
• To publish to PyPI, bump __version__ in gagaku/__init__.py, then create a GitHub release with the matching tag (for example v0.2.2); publishing runs automatically (.github/workflows/publish.yml, Trusted Publishing).

License

MIT License

日本語

雅楽の打ち込み・DTM ができる無料のデスクトップアプリ。雅楽の譜字をテキストで入力すると、笙・篳篥・竜笛・琵琶・筝・鞨鼓・鉦鼓・太鼓の合奏として再生する(Windows・macOS・Linux、Python 製)。DAW や音源ソフトは不要で、五線譜表示や WAV 書き出しにも対応する。

紹介サイト(日本語): https://zitengxiang.github.io/gagaku-player/ 紹介サイト(英語): https://zitengxiang.github.io/gagaku-player/en/

インストールと起動

pip で入れる場合:

pip install gagaku-player
gagaku-player --demo          # サンプル曲「若竹」を開く
gagaku-player 曲.gaku         # 譜面を開く

ソースから動かす場合:

git clone https://github.com/ZiTengXiang/gagaku-player.git
cd gagaku-player
pip install -r requirements.txt
python main.py examples/demo_hyojo.gaku

• 必要なもの: Python 3.10+、numpy(tkinter は Python に標準添付)。python -m gagaku でも起動できる。
• Windows では追加のインストールは不要(再生に標準の winsound を使う)。macOS/Linux では pip で入れると再生用の sounddevice も入る(ソースから動かす場合は pip install sounddevice)。
• Windows でアイコンから起動したい場合は、pythonw.exe main.py を実行するショートカットを作り、アイコンに gagaku/assets/gagaku.ico を指定する(pythonw ならコンソール画面が出ない)。アイコンは python tools/make_icon.py で作り直せる(Pillow と游明朝フォントが必要)。
• コンソールなしで起動して落ちた場合は、error.log に詳細を書き出してダイアログを出す。

画面

• 左「譜面テキスト」タブ: 譜面エディタ。再生中は鳴っている譜字が黄色くハイライトされる。エラーの行は赤くなる。
• 左「楽譜表示」タブ: 全楽器の拍の頭を縦にそろえ、1段5小節で全楽器を上下に並べた総譜(読み取り専用)。小節の区切りは譜面の |、延ばしは細い線で示す。再生中は鳴っている音がハイライトされ、音をクリックするとテキストの該当箇所が選択される(そのまま F6 でそこから再生)。
• 左「五線譜」タブ: 全楽器を1段5小節の総譜として五線譜で書き、各音の下に譜字を付ける(読み取り専用)。1拍 = 4分音符で、小節や拍をまたぐ音はタイでつなぐ。音部記号は楽器の音域から自動で選ぶ(ト音記号・ヘ音記号・オクターブ上下のト音記号)。調号は使わず ♯ を音ごとに付ける。笙は合竹を和音で、琵琶の掻撥と筝の閑掻・早掻は鳴る音をアルペジオ付きの和音で書く。打楽器は1線譜(鞨鼓・鉦鼓は×の符頭、来はトレモロ)。再生ハイライトとクリックでのジャンプは楽譜表示と同じ。
• メニューバー: ファイル(新規・開く・保存・WAV書き出し・終了)と、プラグイン(プラグインを探す・管理)。
• 右上: 譜字パレット(楽器タブごと)。クリックするとカーソル位置に挿入。
• 右下: ミキサー(パートごとのミュート・音量)。
• ツールバー「1小節 _ 拍」: 1小節の拍数。変えるとヘッダに beats: を書き、譜面テキスト・楽譜表示・五線譜を、その拍数ごとの小節に区切り直す(音は変わらない)。
• ツールバー「小節の間(ま) _ 拍」: 小節の間に間(ま)を取るかどうかの切り替えと、その長さ。
  • 間あり: 各小節の終わり(最後の小節を除く)に指定した拍数の間を挟み、その間は小節の終わりで鳴っている音(延ばしている音・小節線をまたぐ音)をすべて延ばす。小節の終わりで休んでいるパートは休みのまま。
  • 間なし(チェックを外す): これまでどおりインテンポで続ける。
  • 設定はヘッダの ma: に保存される。楽譜の表示は変わらず、再生・WAV書き出しの時間だけが変わる。
• ツールバー: 再生(F5) / カーソル位置から再生(F6) / 停止(Esc) / 速さ% / 残響 / WAV書き出し。

プラグイン

メニューバーの プラグイン → プラグインを探す・管理… を開く。

• 検索欄に入力すると、名前・説明・タグでプラグインを絞り込める(例 英語、english)。一覧は、アプリに同梱のものと、紹介サイトのオンライン一覧(https://zitengxiang.github.io/gagaku-player/plugins/index.json)を合わせたもの。アプリを更新しなくても新しいプラグインが出てくる。
• インストール で、選んだプラグインを入れて有効にする。オンライン一覧から入れるときは、一覧に載っている SHA-256 とファイルを照合してから保存する。
• 有効にする / 無効にする で、入れたプラグインをいつでも切り替えられる(行のダブルクリックでも同じ)。すぐに反映され、次に起動したときも保たれる。
• アンインストール で取り除く。
• プラグインは Python のコードとして動く。信頼できるものだけを入れること。
• プラグインと設定は ~/.gagaku_player/ に保存される(plugins/<id>/ と settings.json。環境変数 GAGAKU_PLAYER_HOME で場所を変えられる)。

English UI プラグイン

メニュー・ボタン・タブ・説明文・ステータス表示・楽器名を英語にする。譜字ボタンは Ichi（一） の形式で表示し、ボタンにカーソルを置くと、読み・日本語表記・今の調子での構成音を小さなポップアップで表示する。

Reading: jō
Japanese: 丄(じょう)
Notes: E2, B2, E3, A3 (arpeggio, landing on A3 on the beat)
Mode: Hyōjō

譜面テキストに書く譜字そのものは、譜面のデータなので日本語のまま。

プラグインの作り方

プラグインは2つのファイルを入れたフォルダ。

plugin.json   {"id": "myplugin", "name": "My plugin", "version": "1.0.0", "api": 1,
               "description": {"ja": "…", "en": "…"}, "tags": ["…"]}
plugin.py     class Plugin:
                  def activate(self, api): ...
                  def deactivate(self, api): ...   # 任意

activate には次の機能を持つ API が渡される。

• api.set_texts({キー: 文言}) — 画面の文言を差し替える(キーは gagaku/gui.py の App.t() に渡しているもの。一覧は gagaku/bundled_plugins/english/plugin.py の TEXTS)
• api.add_palette_label(func) — func(楽器キー, 譜字) -> 表示名 または None
• api.add_palette_tooltip(func) — func(楽器キー, 譜字, 調子) -> ポップアップの文 または None
• api.add_instrument_label(func) — func(楽器キー) -> 楽器名 または None
• api.instruments(gagaku.instruments モジュール)と api.current_mode()

プラグインが登録したものは、無効にすると自動で取り除かれる。アプリ内の一覧に載せるには、gagaku/bundled_plugins/<id>/ に置いて python tools/build_plugin_index.py を実行する(docs/plugins/ に写してハッシュ入りの index.json を作る)。

譜面の書式(.gaku, UTF-8テキスト)

title: 曲名
mode: 平調          # 壱越調 平調 双調 黄鐘調 盤渉調 太食調
tempo: 60           # 1拍あたりのBPM
beats: 4            # 1小節の拍数(省略時は譜面の | で区切る)
ma: 1               # 小節の間(ま)の長さ(拍)。省略または 0 なら間なし

[笙]
乙 - - - | 一 - 工 - |
[竜笛]
干 - 五 丄 | 責干:2 中 夕 |

1つのパートを複数の [楽器] 段に分けて書いてもよい(後ろへ続く)。[笙] 乙 - 下 | のように楽器名と同じ行に音を続けて書くこともできる。パートの長さが揃わないとステータスバーに警告が出る。

縦にそろえる(自動整形)

ファイルを開いたとき・保存したとき・再生/WAV書き出しのとき、または「縦にそろえる」ボタン(Ctrl+Shift+F)で、譜面テキストを次の形に整形する。

# ---- 1〜5小節
[笙]    十    -   凢   -   |  乞  -  一  -  |  ...
[篳篥]  丄    四  六   工  |  五  -  工  六 |  ...
[竜笛]  責丄  干  六   中  |  夕  -  中  六 |  ...

• 1段に5小節。各段で全楽器の行が上下に並び、拍の頭が縦にそろう(等幅フォント表示で)。小節は | で区切る。
• 拍と拍の間は空白2つ、同じ拍の中の音(半拍など)は空白1つ。乙:2 は 乙 - のように書き直す。
• 整形しても音は変わらない(各音の開始拍・長さ・テンポ変化は同じ)。本文の途中に書いたコメントはヘッダの後ろへまとめて移る。
• 入力中は自動では動かないので、書き足した後に縦がずれたら Ctrl+Shift+F で直せる。

楽器ごとの譜字

音高・調弦について

• 基準ピッチは A4 = 430 Hz(gagaku/tunings.json の a4_hz)。平均律で計算している。
• 笙の各竹の音高と合竹の構成、竜笛の譜字の音高は、Wikipedia「笙」「龍笛」の表による。
• 楽琵琶・楽箏の調子ごとの調弦は、調べた範囲では出典が見つからなかった。 そのため各調子の主音と音階から組んだ暫定値になっている。正確な調弦は gagaku/tunings.json を書き換えれば反映される(琵琶は各弦の[開放, 第1〜4柱]、筝は一〜巾の13弦)。
• 閑掻・早掻・掻撥・来の奏法は、手順を簡略化した近似。
• 音色は numpy による合成で、サンプル音源ではない。
  • 笙: 合竹が替わっても共通の竹は鳴り続け、入れ替わる竹だけが手移りで少しずつずれて出入りする。合竹ごとに息で膨らむ。
  • 篳篥・竜笛: 休みまでの音をひと続きのフレーズとして合成し、音と音の間を塩梅でつなぐ(篳篥は上行時にいったん下げてから押し上げる)。同じ音が続くときは指打ちで切る。
  • 琵琶・筝: 倍音ごとに減衰の違う弦の音に、撥・爪の打撃音と胴の共鳴を加える。
  • 鞨鼓・太鼓・鉦鼓: 膜・金属の非整数倍モードによる合成。
• 楽器ごとの試聴用WAVは python tools/make_previews.py で previews/ に書き出せる。

構成

main.py                 起動
gagaku/score.py         譜面パーサ
gagaku/instruments.py   譜字→音高/奏法、楽器ごとの音色
gagaku/tunings.json     琵琶・筝の調弦(編集可)
gagaku/synth.py         合成・残響
gagaku/render.py        ミックス・WAV書き出し
gagaku/audio.py         再生
gagaku/gui.py           Tkinter GUI
gagaku/scoreview.py     楽譜表示(1段5小節の総譜)
gagaku/formatter.py     譜面テキストの整形(拍頭を縦にそろえる)
gagaku/staffview.py     五線譜表示(字譜つき)
gagaku/plugins.py       プラグインの仕組み(読み込み・有効化・一覧・インストール)
gagaku/bundled_plugins/ 同梱プラグイン(English UI)
gagaku/assets/          アイコン
examples/               サンプル譜(pip 版ではパッケージ内に同梱)
tools/make_previews.py  楽器ごとの試聴用WAVを書き出す
tools/make_icon.py      アイコンを作り直す
tools/make_site_audio.py 紹介サイトの試聴用MP3を書き出す
tools/build_plugin_index.py オンラインのプラグイン一覧(docs/plugins/)を作る
tests/                  pytest のテスト
docs/                   紹介サイト(GitHub Pages)
.github/workflows/      CI(テスト・ビルド)と PyPI への公開

開発

pip install -e . pytest
python -m pytest

• push や pull request のたびに、GitHub Actions が Windows / Ubuntu × Python 3.10〜3.13 でテストし、パッケージをビルドする(.github/workflows/ci.yml)。
• PyPI への公開は、gagaku/__init__.py の __version__ を上げてから、同じ番号のタグ(例 v0.2.2)で GitHub のリリースを作ると自動で行われる(.github/workflows/publish.yml、Trusted Publishing)。

ライセンス

MIT License