Metadata-Version: 2.3
Name: conslyric
Version: 0.2.0
Summary: Pythonで記述されたConslyric Schemaの実行環境
Author: AmaseCocoa
Author-email: AmaseCocoa <cocoa@amase.cc>
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: typer>=0.20.0
Requires-Python: >=3.12
Project-URL: Issues, https://github.com/AmaseCocoa/conslyric/issues
Project-URL: Repository, https://github.com/AmaseCocoa/conslyric
Description-Content-Type: text/markdown

# ConsLyric
コンソールでいろいろするためのツール/DSL。ConsLyricっていう名前だけど多分そういう用途以外でも使えるはず。

## Conslyric Engine
Pythonで記述された実行環境。古いスキーマを渡された場合はそのバージョン特有のバグ含む問題を可能な限りエミュレーションしようとします。

```
$ conslyric (プログラムのファイル)
```

デバッグログを有効にする場合:

```
$ conslyric (プログラムのファイル) -V
```

## Conslyric Schema v1
Conslyric Schemaは、CLI（コマンドラインインターフェース）環境において、歌詞やテキストを楽曲のタイミングと演出ルールに基づいて再生するために設計されたドメイン固有言語（DSL）です。YAML形式で記述され、表示時間、待機時間、色、画面クリアなどの演出制御を宣言的に行います。

---

## 1. 基本構造

YAMLデータは、以下の主要なトップレベル要素で構成されます。

| 要素名 | 型 | 必須 | 説明 |
| :--- | :--- | :--- | :--- |
| **`consLyric`** | string | 必須 | スキーマバージョンを指定します（例: `4`）。古いバージョンが指定された場合、そのバージョンの動作（バグを含む）をエミュレートしようとします。 |
| **`metadata`** | map | 必須 | 再生全体に関する設定情報とデフォルト値を定義します。 |
| **`define`** | map | 任意 | 再利用可能な関数（コマンド群）を定義します。 |
| **`run`** | array | 必須 | 歌詞の本体と、実行されるすべての演出コマンドを順番に記述します。 |

---

## 2. `metadata`

再生時の全体設定とデフォルト値を定義します。

| キー | 型 | 必須 | 説明 |
| :--- | :--- | :--- | :--- |
| `time` | string | 必須 | 楽曲の**総再生時間の上限**（リミット）を定義します（例: `4m1s`）。`run`配列から計算された全体の表示時間がこの値を超過した場合、実行時に**例外**が発生します。 |
| `showDefault` | string | 必須 | 歌詞行が表示される**デフォルトの持続時間**（例: `2s`）。`setRule`で上書きされない場合に適用されます。 |
| `sleepDefault` | string | 必須 | 歌詞行間の**デフォルトの待機時間**（例: `3s`）。`setRule`で上書きされない場合に適用されます。 |

---

## 3. `define` (関数定義)

再利用可能なコマンドのシーケンス（関数）を定義します。

| キー | 型 | 説明 |
| :--- | :--- | :--- |
| `[関数名]` | map | 任意の関数名をキーとします（例: `fastLyric`）。 |
| `type` | string | **必須。** 関数であることを示すため、`func`と指定します。 |
| `args` | array | 関数が受け取る引数を定義します。形式は `[引数名]:[型]`（例: `showTime:num`）。 |
| `run` | array | 関数が呼び出されたときに実行されるコマンドのリストです。引数は `${引数名}` の形式で参照できます。 |

---

## 4. `run` (再生シーケンス)

歌詞と制御コマンドを混在させた配列です。

### 4.1. 歌詞行

引用符なしで記述された文字列は、表示対象のテキストとして扱われます。その行の持続時間は、直前の`setShowRule`または`showDefault`、次の行までの待機時間は直前の`setSleepRule`または`sleepDefault`に基づきます。

### 4.2. 制御コマンド

以下のコマンド（ディレクティブ）を使用して、表示ルールや画面の状態を操作します。

| コマンド | パラメータ | 動作 | リセットのタイミング |
| :--- | :--- | :--- | :--- |
| `setShowRule:[時間]` | 時間（例: `0.5s`, `2s`） | **現在の歌詞行の表示時間**を上書き設定します。 | `endSection` |
| `setSleepRule:[時間]` | 時間（例: `0s`, `1s`） | **現在の歌詞行の後の待機時間**を上書き設定します。 | `endSection` |
| `cons:clear` | なし | コンソール画面をクリアします。 | 常に実行されます。 |
| `cons:setcolor:[色]` | 色（例: `red`, `orange`） | 以降のテキストの色を設定します。 | `cons:color:reset` |
| `cons:color:reset` | なし | テキストの色をデフォルトに戻します。 | 常に実行されます。 |
| `endSection` | なし | **`setShowRule`および`setSleepRule`で設定された全てのルールを、`metadata`で定義されたデフォルト値にリセット**します。画面クリアは行いません。 | 常に実行されます。 |
| `[関数名]:[引数]` | map | `define`セクションで定義された関数を呼び出します（例: `fastLyric: {showTime: 0.2, sleepTime: 0.1}`）。 | 常に実行されます。 |