chenpi 0.1.0__py3-none-any.whl

chenpi/USAGE.md

@@ -0,0 +1,135 @@
+# chenpi の使い方 (このライブラリを使うコードを書く人・エージェント向け)
+
+chenpi は DS / 3DS 用キャプチャ基板の映像・音声を numpy / OpenCV の画像として読む **Windows 専用** のライブラリ。
+`cv2.VideoCapture` と同じ形 (`read()` → `(ok, frame)`, `isOpened()`, `release()`) で使える。
+このファイルはインストール先 (`site-packages/chenpi/USAGE.md`) にも入っている。
+
+## 対応機種
+
+| kind | 機種 | クラス | 画面 |
+|---|---|---|---|
+| `"ds"` | 新型 Loopy DS キャプチャ (USB Type-C 版, FTDI) | `LoopyDSCapture` | 上下とも 256x192 |
+| `"3ds"` | Optimize 3DS キャプチャ Old 3DS 用 (Cypress) | `Optimize3DSCapture` | 上 400x240、下 320x240 |
+
+どちらも約 60fps、音声はステレオ int16 / `SAMPLE_RATE` (≒ 32728.5 Hz)。
+未対応: Optimize の New 3DS 用 / 2DS 用、RGB888、3D 表示、Loopy 製 3DS キャプチャ。
+
+## 最小の例
+
+```python
+import cv2
+from chenpi import open_capture
+
+cv2.setNumThreads(1)                      # 毎フレーム OpenCV で処理するなら推奨 (下の「注意」参照)
+with open_capture("auto") as cap:         # "ds" / "3ds" も可。見つからなければ RuntimeError など
+    while True:
+        ok, frame = cap.read()            # BGR uint8 の numpy 配列
+        if not ok:
+            if not cap.isOpened():        # 切断・受信エラー
+                break
+            continue                      # 1 秒以内に新しいフレームが来なかった (本体の電源が切れている等)
+        cv2.imshow("chenpi", frame)
+        if cv2.waitKey(1) & 0xFF == ord("q"):
+            break
+```
+
+## 公開 API
+
+`from chenpi import ...` で使えるもの。これ以外 (先頭が `_` のもの、各モジュール内の関数) は内部用。
+
+### 開く
+
+- `open_capture(device="auto", key=None, **kwargs) -> LoopyDSCapture | Optimize3DSCapture`
+  - `device`: `"auto"` (DS → 3DS の順に、空いている機器を探す) / `"ds"` / `"3ds"`。`DEVICES` にこの 3 つが入っている。
+  - `key`: Optimize 3DS のプロダクトキー (後述)。DS では使わない。
+  - `kwargs`: `layout`, `swap_rb`, `firmware_dir` (両クラス共通の引数)。
+- `list_devices() -> list[DeviceInfo]`: 接続中の機器の一覧。**機器の状態を変えない** (ファーム書き込み等をしない) ので何度呼んでもよい。
+- `open_device(info, key=None, **kwargs)`: `list_devices()` で選んだ 1 台を開く。GUI のコンボボックス向け。
+- `DeviceInfo` (frozen dataclass): `kind` ("ds"/"3ds"), `name`, `id`, `path`, `status`, `needs_key`, `available` (property)。
+  - `status`: `"ready"` / `"in_use"` (他のプログラムが開いている) / `"replug"` (Optimize を公式ソフトで使った後。USB の抜き差しが必要)。
+  - `id`: DS は FTDI のシリアル。**Optimize は開くまで分からないので None** (開いた後の `cap.serial` がデバイス ID)。
+  - `str(info)` が表示用の文字列 (例 `"Optimize Old 3DS [使用中]"`)。
+
+### クラスを直接使う
+
+- `LoopyDSCapture(serial=None, layout="vertical", firmware_dir=None, swap_rb=False, dll_path="ftd2xx.dll")`
+  - `serial` を指定するとその機器だけを開く (見つからなければ FTError。別の機器にはフォールバックしない)。
+- `Optimize3DSCapture(key=None, path=None, layout="vertical", firmware_dir=None, swap_rb=False)`
+  - `key` 省略時は環境変数 `OPTIMIZE_3DS_KEY`。**キーが無いと開けない** (キーなしだと約 4 分で転送が止まる機器のため)。
+  - `key` は文字列 (カンマ・セミコロン・空白区切りで複数可) か文字列のリスト。デバイス ID が合うものが使われる。
+  - `path` 省略時は、空いていてキーの合う 1 台を探して開く。
+
+### 開いた後 (両クラス共通)
+
+| メンバー | 内容 |
+|---|---|
+| `read(timeout=1.0) -> (bool, ndarray \| None)` | **次の新しいフレーム** を待って返す。同じフレームを二度は返さない。timeout 秒来なければ `(False, None)` |
+| `read_audio() -> ndarray` | 前回の呼び出し以降の音声。int16, shape `(N, 2)` [L, R]。待たない (無ければ N=0)。約 2 秒分を超えて読まれない分は古い順に捨てる |
+| `isOpened() -> bool` | 受信中か。切断・エラーで False |
+| `release()` | 閉じる。`with` 文でも閉じる |
+| `volume` (float, 既定 1.0) | `read_audio()` にかかる倍率。0 で無音、1 超で増幅 (int16 の範囲で頭打ち)。いつ変えてもよい |
+| `layout` | `"vertical"` / `"horizontal"` / `"top"` / `"bottom"` |
+| `serial` | DS: FTDI シリアル。3DS: デバイス ID (16 桁の 16 進) |
+| `description` | 機種名 (`"NDS.2"` / `"Optimize Old 3DS"` など) |
+
+`read()` が返す frame の shape (高さ, 幅, 3):
+
+| layout | DS | 3DS |
+|---|---|---|
+| vertical (上に上画面) | (384, 256, 3) | (480, 400, 3) 下画面は左右に 40px の黒帯 |
+| horizontal (左に上画面) | (192, 512, 3) | (240, 720, 3) |
+| top | (192, 256, 3) | (240, 400, 3) |
+| bottom | (192, 256, 3) | (240, 320, 3) |
+
+### ファームウェア
+
+基板に書き込むファームウェアは **著作権の都合で同梱していない**。初回は cc3dsfs から取得する必要がある。
+
+- 無い状態で開くと `FirmwareMissing` (`FileNotFoundError` のサブクラス)。`e.names` に足りないファイル名。
+- `download_firmware(names=None, dest=None, progress=print) -> Path`: cc3dsfs の固定コミットから取得し、SHA-256 を照合して保存。
+  既定の保存先は `user_firmware_dir()` (`%LOCALAPPDATA%\chenpi\firmware`)。
+- `missing_firmware(kind=None) -> list[str]`: 足りないファイル名 (`kind` は "ds" / "3ds" / None)。
+- **利用者に確認せずにダウンロードしないこと** (第三者のファイルをネットから取得するため)。例:
+
+  ```python
+  from chenpi import FirmwareMissing, download_firmware, open_capture
+
+  try:
+      cap = open_capture("auto", key=keys)
+  except FirmwareMissing as e:
+      if ask_user(f"{e.names} を cc3dsfs から取得しますか?"):
+          download_firmware()
+          cap = open_capture("auto", key=keys)
+  ```
+
+### 例外
+
+| 例外 | 主な原因 | 対処 |
+|---|---|---|
+| `FirmwareMissing` | ファームウェアが無い | 利用者に確認して `download_firmware()` |
+| `OptimizeError` | 3DS: キーが無い・合わない、機器が無い、使用中、要抜き差し、切断 | メッセージを利用者に見せる |
+| `FTError` | DS: 機器が無い、使用中、FPGA 設定の失敗 | 同上 |
+| `RuntimeError` | `open_capture("auto")` でどの機器も開けなかった (各機種の理由をまとめたメッセージ) | 同上 |
+| `OSError` | DS 用の `ftd2xx.dll` (FTDI ドライバ) が無い | ドライバの導入を案内 |
+
+受信中の切断は例外にならない。`read()` が `(False, None)` を返し、`isOpened()` が False になる。
+
+### 低レベル
+
+- `SAMPLE_RATE`: 音声のサンプルレート (DS / 3DS 共通)。
+- `parse_frame(raw, swap_rb=False)` / `parse_audio(raw)`: Loopy DS の生データ 1 フレームの解析 (テスト・解析用)。
+
+## 注意 (よくある間違い)
+
+- **`cv2.setNumThreads(1)`**: 毎フレーム `cv2.resize` / `imshow` などをするアプリでは、最初に呼ぶと CPU 使用率が大きく下がる
+  (OpenCV のスレッドが空回りするため。1 コア約 9 割 → 約 3 割)。プロセス全体の設定なのでライブラリは変えていない。
+- **スレッド**: `read()` は新しいフレームまで待つ (最大 `timeout` 秒)。GUI のメインスレッドで呼ばず、別スレッドで回す。
+  `volume` の変更や `read_audio()` は他のスレッドからでよい。
+- **同時に 1 プログラムだけ**: 同じ機器を 2 つのプロセスで開くことはできない (公式ソフト・cc3dsfs とも)。機器を切り替えるときは先に `release()`。
+- **Optimize 3DS**:
+  - 公式ソフトを使った後は USB の抜き差しが必要 (`status == "replug"`)。
+  - 3DS 本体のサウンド設定は「ステレオ」に。サラウンドだと PC で聞くとこもる。本体の音量スライダーはキャプチャの音に効かない (`volume` で調整)。
+- **フレームの時刻**: `read()` の戻り値は `(ok, frame)` から変えない方針 (cv2 互換)。受信時刻が必要なら将来 `get(cv2.CAP_PROP_POS_MSEC)` で提供する予定 (未実装)。
+- **音声の再生**: 音声は約 16.7ms (1 フレーム) ごとにまとめて届く。sounddevice などで鳴らすなら、25ms 程度溜めてから再生を始めないとプツプツ途切れる
+  (実装例: このパッケージの `__main__.py` の `_play_audio`)。
+- ビューア `chenpi-view` (`python -m chenpi`) と仮想カメラ `chenpi-virtualcam` はコマンドとして入る。`--help` で使い方。

chenpi/__init__.py

@@ -0,0 +1,21 @@
+"""chenpi: DS / 3DS 用キャプチャ基板を cv2.VideoCapture と同じ形で読む Windows 専用ライブラリ。
+
+詳しい使い方 (API の一覧・frame の大きさ・例外・注意点) は、このファイルと同じフォルダの USAGE.md を読むこと。
+
+    from chenpi import open_capture
+    with open_capture("auto") as cap:      # "ds" (Loopy DS) / "3ds" (Optimize Old 3DS, キー必須)
+        ok, frame = cap.read()             # 次の新しいフレームを待つ。BGR uint8
+        audio = cap.read_audio()           # int16 (N, 2) [L, R], SAMPLE_RATE Hz
+
+- 機器の一覧から選ぶなら list_devices() → open_device(info)。
+- ファームウェアは同梱していない。無ければ FirmwareMissing になるので、利用者に確認してから download_firmware()。
+"""
+
+from .capture import SAMPLE_RATE, FTError, LoopyDSCapture, parse_audio, parse_frame
+from .devices import DEVICES, DeviceInfo, list_devices, open_capture, open_device
+from .firmware import FirmwareMissing, download_firmware, missing_firmware, user_firmware_dir
+from .optimize3ds import Optimize3DSCapture, OptimizeError
+
+__all__ = ["LoopyDSCapture", "Optimize3DSCapture", "DeviceInfo", "list_devices", "open_device", "open_capture",
+           "DEVICES", "FTError", "OptimizeError", "FirmwareMissing", "download_firmware", "missing_firmware",
+           "user_firmware_dir", "SAMPLE_RATE", "parse_audio", "parse_frame"]

chenpi/__main__.py

@@ -0,0 +1,148 @@
+"""`uv run chenpi-view` / `python -m chenpi` で起動する確認用ビューア。"""
+
+import argparse
+import threading
+import time
+
+
+def _play_audio(cap, stop, latency=0.05, prefill=0.025, stats=None):
+    """受信した音声を既定の出力デバイスに流す。映像とずれないよう、未再生分は少しだけ持つ。
+
+    音声は 1 フレーム (約 16.7ms) ごとにまとめて届くので、到着のゆらぎで手元が空になると無音が挟まって
+    プツッと鳴る。prefill 秒ぶん溜めてから鳴らし始め、空になったらまた溜め直す。
+    stats に dict を渡すと、無音で埋めた回数 (starved) と古い分を捨てた回数 (dropped) を数える (診断用)。
+    """
+    import numpy as np
+    import sounddevice as sd
+
+    from .capture import SAMPLE_RATE
+
+    target = int(SAMPLE_RATE * prefill)
+    max_pending = int(SAMPLE_RATE * 0.08)   # これを超えたら古い分を捨てる (遅延の積み上がり・時計ずれ対策)
+    lock = threading.Lock()
+    pending = np.zeros((0, 2), np.int16)
+    playing = False
+    if stats is not None:
+        stats.update(starved=0, dropped=0)
+
+    def callback(outdata, frames, _time, _status):
+        nonlocal pending, playing
+        with lock:
+            if not playing and len(pending) >= target:
+                playing = True
+            n = min(frames, len(pending)) if playing else 0
+            outdata[:n] = pending[:n]
+            pending = pending[n:]
+            if playing and n < frames:      # 底をついた: 無音で埋めて、また溜め直す
+                playing = False
+                if stats is not None:
+                    stats["starved"] += 1
+        outdata[n:] = 0
+
+    with sd.OutputStream(samplerate=round(SAMPLE_RATE), channels=2, dtype="int16",
+                         latency=latency, callback=callback):
+        while not stop.is_set() and cap.isOpened():
+            audio = cap.read_audio()
+            if len(audio):
+                with lock:
+                    pending = np.concatenate((pending, audio))
+                    if len(pending) > max_pending:
+                        pending = pending[-target:]
+                        if stats is not None:
+                            stats["dropped"] += 1
+            time.sleep(0.002)
+
+
+def _open_or_explain(opener):
+    """機器を開く。ファームウェアが無ければ取得してよいか尋ね、想定内のエラーはメッセージだけ出して終わる。"""
+    from . import FirmwareMissing, FTError, OptimizeError, download_firmware
+
+    while True:
+        try:
+            return opener()
+        except FirmwareMissing as e:
+            print(f"ファームウェアが見つかりません: {', '.join(e.names)}")
+            print("これらは cc3dsfs (https://github.com/Lorenzooone/cc3dsfs) で公開されているファイルです"
+                  " (著作権は各メーカー)。")
+            if input("cc3dsfs からダウンロードしますか? [y/N] ").strip().lower() != "y":
+                raise SystemExit(1)
+            download_firmware()
+        except (FTError, OptimizeError, RuntimeError) as e:
+            raise SystemExit(f"エラー: {e}")
+
+
+def main() -> None:
+    import cv2
+
+    from . import DEVICES, list_devices, open_capture
+
+    # OpenCV は小さな処理も複数スレッドに分け、終わった後もスレッドが空回りする。毎フレームの拡大・表示では
+    # これだけで 1 コアの 6 割ほどを食っていた (実機で計測) ので、1 スレッドにする
+    cv2.setNumThreads(1)
+
+    ap = argparse.ArgumentParser(description="chenpi viewer")
+    ap.add_argument("--list", action="store_true", help="接続されている機器の一覧を表示して終了")
+    ap.add_argument("--device", default="auto", choices=DEVICES, help="ds: Loopy DS, 3ds: Optimize Old 3DS")
+    ap.add_argument("--key", help="Optimize 3DS のプロダクトキー (省略時は環境変数 OPTIMIZE_3DS_KEY)")
+    ap.add_argument("--layout", default="vertical", choices=["vertical", "horizontal", "top", "bottom"])
+    ap.add_argument("--scale", type=int, default=2)
+    ap.add_argument("--swap-rb", action="store_true", help="赤と青が入れ替わって見えるとき")
+    ap.add_argument("--audio", action="store_true", help="音声も再生する (uv sync --extra audio が必要)")
+    ap.add_argument("--audio-latency", type=float, default=0.05,
+                    help="音声出力バッファ (秒)。音が途切れるなら大きく、映像より遅れるなら小さく")
+    ap.add_argument("--volume", type=float, default=1.0, help="音量の倍率 (再生中も + / - キーで変えられる)")
+    args = ap.parse_args()
+
+    if args.list:
+        infos = list_devices()
+        for info in infos:
+            print(f"{info.kind:3}  {info}")
+        if not infos:
+            print("キャプチャ機器が見つかりません")
+        return
+
+    cap = _open_or_explain(lambda: open_capture(args.device, key=args.key, layout=args.layout,
+                                                swap_rb=args.swap_rb))
+    with cap:
+        print(f"接続: {cap.description} (serial {cap.serial})  q で終了"
+              + ("、+ / - で音量" if args.audio else ""))
+        cap.volume = args.volume
+        stop = threading.Event()
+        if args.audio:
+            threading.Thread(target=_play_audio, args=(cap, stop, args.audio_latency), daemon=True).start()
+
+        def handle_key():
+            """押されたキーを処理する。終了なら True。"""
+            key = cv2.waitKey(1) & 0xFF
+            if key in (ord("+"), ord("="), ord(";")):    # JIS 配列では + は Shift+; なので ; も受け付ける
+                cap.volume = round(min(cap.volume + 0.1, 4.0), 2)
+                print(f"音量 {cap.volume:.1f}")
+            elif key == ord("-"):
+                cap.volume = round(max(cap.volume - 0.1, 0.0), 2)
+                print(f"音量 {cap.volume:.1f}")
+            return key == ord("q")
+
+        waiting = False
+        while True:
+            ok, frame = cap.read()
+            if not ok:
+                if not cap.isOpened():
+                    print(f"受信エラー: {cap._error}")
+                    break
+                if not waiting:
+                    print("信号待ち... (本体の電源が入っているか確認してください)")
+                    waiting = True
+                if handle_key():
+                    break
+                continue
+            waiting = False
+            cv2.imshow("chenpi", cv2.resize(frame, None, fx=args.scale, fy=args.scale,
+                                                      interpolation=cv2.INTER_NEAREST))
+            if handle_key():
+                break
+        stop.set()
+    cv2.destroyAllWindows()
+
+
+if __name__ == "__main__":
+    main()