Metadata-Version: 2.5
Name: gagaku-player
Version: 0.2.1
Summary: 雅楽の譜字をテキストで書くと、笙・篳篥・竜笛・琵琶・筝・鞨鼓・鉦鼓・太鼓の合奏として再生するデスクトップアプリ
Project-URL: Homepage, https://zitengxiang.github.io/gagaku-player/
Project-URL: Source, https://github.com/ZiTengXiang/gagaku-player
Project-URL: Issues, https://github.com/ZiTengXiang/gagaku-player/issues
Author: ZiTengXiang
License-Expression: MIT
License-File: LICENSE
Keywords: gagaku,japanese traditional music,music,notation,synthesizer,雅楽
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Win32 (MS Windows)
Classifier: Environment :: X11 Applications
Classifier: Intended Audience :: End Users/Desktop
Classifier: Natural Language :: Japanese
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Sound/Audio :: Players
Classifier: Topic :: Multimedia :: Sound/Audio :: Sound Synthesis
Requires-Python: >=3.10
Requires-Dist: numpy>=1.24
Requires-Dist: sounddevice>=0.4; platform_system != 'Windows'
Description-Content-Type: text/markdown

# 雅楽譜プレイヤー

[![CI](https://github.com/ZiTengXiang/gagaku-player/actions/workflows/ci.yml/badge.svg)](https://github.com/ZiTengXiang/gagaku-player/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/gagaku-player)](https://pypi.org/project/gagaku-player/)

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

紹介サイト: https://zitengxiang.github.io/gagaku-player/

## インストールと起動

pip で入れる場合:

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

ソースから動かす場合:

```bash
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線譜(鞨鼓・鉦鼓は×の符頭、来はトレモロ)。再生ハイライトとクリックでのジャンプは楽譜表示と同じ。
- 右上: 譜字パレット(楽器タブごと)。クリックするとカーソル位置に挿入。
- 右下: ミキサー(パートごとのミュート・音量)。
- ツールバー「1小節 _ 拍」: 1小節の拍数。変えるとヘッダに `beats:` を書き、譜面テキスト・楽譜表示・五線譜を、その拍数ごとの小節に区切り直す(音は変わらない)。
- ツールバー「小節の間(ま) _ 拍」: 小節の間に間(ま)を取るかどうかの切り替えと、その長さ。
  - **間あり**: 各小節の終わり(最後の小節を除く)に指定した拍数の間を挟み、その間は小節の終わりで鳴っている音(延ばしている音・小節線をまたぐ音)をすべて延ばす。小節の終わりで休んでいるパートは休みのまま。
  - **間なし**(チェックを外す): これまでどおりインテンポで続ける。
  - 設定はヘッダの `ma:` に保存される。楽譜の表示は変わらず、再生・WAV書き出しの時間だけが変わる。
- ツールバー: 再生(F5) / カーソル位置から再生(F6) / 停止(Esc) / 速さ% / 残響 / WAV書き出し。

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

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

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

| トークン | 意味 |
|---|---|
| `譜字` | 1拍 |
| `譜字:2` / `譜字:1/2` | 長さ指定(拍) |
| `-` `ー` | 直前の音を1拍延ばす |
| `-:2` / `-:1/2` | 直前の音を指定した拍数だけ延ばす |
| `.` `・` `〇` `休` (`.:2` も可) | 休み |
| `\|` | 小節線(見た目だけ) |
| `tempo=72` | その位置からテンポ変更(全パート共通) |
| `譜字'` / `譜字,` | 1オクターブ上 / 下 |
| `# …` | コメント |

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

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

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

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

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

### 楽器ごとの譜字

| 楽器 | 譜字 |
|---|---|
| 笙 | 合竹: 乞 一 工 凢 乙 下 十 美 行 比、特殊合竹 乙美 乙言 凢美 凢言。`単千` のように「単」を付けると一本だけ。双調では「十」が5音の十になる。 |
| 篳篥 | 舌 五 工 凢 六 四 一 丄 丁(低い順, G4〜A5、Wikipedia「篳篥」の正律)。ムは現行曲では使わない。音頭に塩梅を付ける。平調では、舌を正律の G4 から F#4(下無)に、丄を G5 から F#5 に半音下げて吹く(メリ)。ほかの調子のメリは未設定で、`tunings.json` の `hichiriki` で譜字ごとに上書きできる。 |
| 竜笛 | 五 丄 夕 中 丅 六 干(〒)(和)。`責六` または `六'` で責。干は六の上(E6)で鳴る。低い干(E5)は `干,`。 |
| 琵琶 | 1弦 一 工 凢 フ 斗 / 2弦 乚 下 十 乙 コ / 3弦 ク 七 ヒ 〻 之 / 4弦 丄 八 丨 ム 也(開放, 第1〜4柱)。通常は掻撥、`単ク` で単音。`一+ク` のように `+` でつなぐと、別々の弦を同時に鳴らす(割撥。同じ弦どうしはエラー)。掻撥は「着地型」で、最後の弦(目的の音)を譜面の位置の拍頭ちょうどに鳴らし、それより前の弦は直前の1拍を弦の数で等分して先に弾く(4本なら 0.75・0.5・0.25 拍前と拍頭。`instruments.py` の `BIWA_PICKUP_BEATS` で長さを変更可)。 |
| 筝 | 一〜十 斗 為 巾(単音)、`閑三` = 閑掻、`早三` = 早掻。 |
| 鞨鼓 | 正(右の単打)、片来(左桴のみのロール)、諸来(両桴のロール)。ロールは `諸来:3` のように長さを指定。来は打ち始めが間遠く次第に速まり、速さはテンポに連動する(`instruments.py` の `KAKKO_ROLL_SPEED` で調整可)。 |
| 鉦鼓 | 金・生(一打)、ク(左)、レイ(右)、クレイ(左右2打)。 |
| 太鼓 | 図(軽い前打)、百(強打)。 |

## 音高・調弦について

- 基準ピッチは 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/assets/          アイコン
examples/               サンプル譜(pip 版ではパッケージ内に同梱)
tools/make_previews.py  楽器ごとの試聴用WAVを書き出す
tools/make_icon.py      アイコンを作り直す
tests/                  pytest のテスト
docs/                   紹介サイト(GitHub Pages)
.github/workflows/      CI(テスト・ビルド)と PyPI への公開
```

## 開発

```bash
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.1.1`)で GitHub のリリースを作ると自動で行われる(`.github/workflows/publish.yml`、Trusted Publishing)。

## ライセンス

[MIT License](LICENSE)
