chenpi 0.1.0__tar.gz

chenpi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lizz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chenpi-0.1.0/LICENSES/cc3dsfs.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Lorenzooone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

chenpi-0.1.0/PKG-INFO

@@ -0,0 +1,204 @@
+Metadata-Version: 2.4
+Name: chenpi
+Version: 0.1.0
+Summary: Read DS/3DS capture boards (Loopy DS, Optimize Old 3DS) as OpenCV/numpy images on Windows
+Author: Lizz
+License-Expression: MIT
+License-File: LICENSE
+License-File: LICENSES/cc3dsfs.txt
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Multimedia :: Video :: Capture
+Classifier: Development Status :: 3 - Alpha
+Requires-Dist: numpy>=1.26
+Requires-Dist: opencv-python>=4.9
+Requires-Dist: sounddevice>=0.5.6 ; extra == 'audio'
+Requires-Dist: pyvirtualcam>=0.15.0 ; extra == 'virtualcam'
+Requires-Python: >=3.12
+Provides-Extra: audio
+Provides-Extra: virtualcam
+Description-Content-Type: text/markdown
+
+# chenpi
+
+**chenpi** (陳皮) は、DS / 3DS 用キャプチャ機器の映像・音声を、公式ビューアやウィンドウキャプチャを使わずに
+numpy / OpenCV の画像として直接取り込むための Windows 用ライブラリです。
+`cv2.VideoCapture` と同じ `read()` で読めるので、OpenCV 前提のコードにそのまま渡せます。
+[cc3dsfs](https://github.com/Lorenzooone/cc3dsfs) (MIT License) の処理を Python に移植しています。
+
+| 機種 | 映像 | 音声 | 備考 |
+|---|---|---|---|
+| 新型 Loopy DS キャプチャ (USB Type-C 版) | 256x192 × 2 画面 / 60fps | あり | |
+| Optimize 3DS キャプチャ (Old 3DS 用) | 400x240 + 320x240 / 60fps | あり | 公式ソフトのプロダクトキーが必要 |
+
+Optimize の New 3DS 用 / 2DS 用、RGB888、3D 表示、Loopy 製 3DS キャプチャには未対応です。
+
+## 準備
+
+1. **ドライバ**: 各機器の公式ソフトに付属するドライバをそのまま使います (公式ソフトが動く環境なら導入済み)。
+   - Loopy DS: FTDI の D2XX ドライバ
+   - Optimize 3DS: 公式ドライバ (NSTDUSB3)
+   - Zadig などで WinUSB に差し替えると動きません。
+2. **インストール**
+
+   ```powershell
+   uv add "chenpi[audio,virtualcam]"     # 別のプロジェクトから使う場合 (pip install でも可。音声・仮想カメラが不要なら [] は省略)
+   uv sync                               # このリポジトリで開発する場合
+   ```
+
+3. **ファームウェアの取得**: 基板に書き込むファームウェアは同梱していないので、cc3dsfs から取得します
+   (理由は[ファームウェアについて](#ファームウェアについて))。ビューアは、無ければ取得してよいか尋ねます。
+
+   ```powershell
+   uv run scripts/fetch_firmware.py   # %LOCALAPPDATA%\chenpi\firmware に保存
+   ```
+
+4. **Optimize 3DS のプロダクトキー**: `--key` か環境変数 `OPTIMIZE_3DS_KEY` で渡します (カンマ区切りで複数可)。
+
+   ```powershell
+   setx OPTIMIZE_3DS_KEY "XXXX-XXXX-XXXX-XXXX-XXXX"   # VS Code / ターミナルを開き直すと有効
+   ```
+
+公式ソフトや cc3dsfs とは同時に使えません。先に閉じてください。
+
+## ビューアで試す
+
+```powershell
+uv run chenpi-view --list                 # 接続されている機器の一覧
+uv run chenpi-view                        # 見つかった機器を表示 (q で終了)
+uv run chenpi-view --device 3ds --audio   # 機種を指定し、音声も再生 (+ / - キーで音量)
+uv run chenpi-view --layout horizontal --scale 3
+```
+
+| オプション | 内容 |
+|---|---|
+| `--device auto\|ds\|3ds` | 機種 (既定 `auto`: DS → 3DS の順に探す) |
+| `--key` | Optimize 3DS のプロダクトキー |
+| `--layout vertical\|horizontal\|top\|bottom` | 画面の並べ方 |
+| `--scale` | 表示の拡大率 (既定 2) |
+| `--audio` / `--volume` / `--audio-latency` | 音声の再生 / 音量の倍率 / 出力バッファ (秒) |
+
+## ライブラリとして使う
+
+### OpenCV と同じように読む
+
+```python
+from chenpi import open_capture
+
+with open_capture("auto", layout="vertical") as cap:   # "ds" / "3ds" も指定できる
+    ok, frame = cap.read()        # BGR uint8。vertical なら DS は 256x384、3DS は 400x480 (下画面の左右は黒帯)
+    audio = cap.read_audio()      # 前回以降の音声 int16 (N, 2) [L, R]
+```
+
+機種ごとのクラス (`LoopyDSCapture` / `Optimize3DSCapture`) を直接使うこともできます。
+
+API の一覧・frame の大きさ・例外・注意点は [src/chenpi/USAGE.md](src/chenpi/USAGE.md) にまとめてあります。
+このファイルはパッケージにも入るので、chenpi を使う別のプロジェクトでは、その CLAUDE.md などに次のように書いておくと、
+コーディングエージェントが正しい使い方を参照できます。
+
+```markdown
+- キャプチャには chenpi を使う。使い方は `.venv/Lib/site-packages/chenpi/USAGE.md` を読むこと。
+```
+
+### 機器の一覧から選んで開く (GUI 向け)
+
+```python
+from chenpi import list_devices, open_device
+
+infos = list_devices()                # 機器には触らずに一覧だけ返す (ファーム書き込みなどはしない)
+for info in infos:
+    print(info, info.available)       # 例: "Optimize Old 3DS [使用中]" False
+cap = open_device(infos[0], key=["XXXX-...", "YYYY-..."])   # 3DS は保存してあるキーを全部渡せば合うものを使う
+print(cap.serial)                     # 3DS ならデバイス ID。キーとの対応を保存しておくとよい
+```
+
+- `info.status` は `ready` / `in_use` (他のプログラムが使用中) / `replug` (公式ソフト使用後で USB の抜き差しが必要)。
+- Optimize 3DS のデバイス ID は開くまで分からないので、一覧では `info.id` が `None` です。
+  挿した直後は「未初期化」と表示されます (Old 3DS 用 / New 3DS v2 用 / 2DS 用の区別は付きません)。
+- Optimize を 2 台つないでいても、キーの合う空いている方が開きます。
+- 同じ機器を 2 つのプログラムで同時に開くことはできません (cc3dsfs との間でも)。
+- 使用中の Loopy DS は、ID (シリアル) が大文字で表示されます (Windows の記録による)。比べるときは大文字小文字を区別しないでください。
+
+### 音声
+
+- DS・3DS とも `SAMPLE_RATE` (≒ 32728.5 Hz) のステレオ int16 です。
+- `read_audio()` は待たずに、溜まっている分を全部返します (読まれない分は約 2 秒で古い順に捨てます)。
+- 音量は `cap.volume` (倍率、既定 1.0) で変えられ、`read_audio()` の結果にかかります。再生中に変えてもすぐ反映されます。
+  1.0 より大きくすると増幅し、int16 をはみ出す分は頭打ちになります。GUI のスライダーなら `cap.volume = value / 100` のように使えます。
+
+### GUI に組み込むときの注意
+
+- **ファームウェアが無いとき**は `FirmwareMissing` (足りないファイル名は `e.names`) になります。
+  勝手にダウンロードせず、利用者に確認してから取得してください。
+
+  ```python
+  from chenpi import FirmwareMissing, download_firmware, open_device
+
+  try:
+      cap = open_device(info, key=keys)
+  except FirmwareMissing as e:
+      if ask_user(f"{e.names} を cc3dsfs から取得しますか?"):
+          download_firmware()
+  ```
+
+- **CPU 使用率**: 毎フレーム OpenCV で拡大や表示をするなら、アプリの最初で `cv2.setNumThreads(1)` を呼んでください。
+  OpenCV は小さな処理も複数スレッドに分け、その後スレッドが空回りするため、ビューアでは 1 コアの約 9 割 → 約 3 割に下がりました。
+  プロセス全体の設定なので、ライブラリ側では変えていません。
+- `read()` は新しいフレームが来るまで待つので、GUI のメインスレッドではなく別スレッドで回してください。
+- 機器を切り替えるときは、先に `cap.release()` を呼んでください。
+- 受信中に USB が抜かれると、`read()` が `(False, None)` を返し、`cap.isOpened()` が False になります (固まりません)。
+
+## 仮想カメラ
+
+OBS Studio (OBS Virtual Camera) が入っていれば、普通の Web カメラとして他のアプリから使えます。
+OBS 側の「仮想カメラ開始」は止めておいてください (同時には使えません)。
+
+```powershell
+uv run chenpi-virtualcam --device 3ds   # --layout / --scale / --audio / --key もビューアと同じ
+```
+
+```python
+import cv2
+cap = cv2.VideoCapture(3, cv2.CAP_DSHOW)  # 番号は環境による (OBS Virtual Camera の番号)
+```
+
+仮想カメラには音声は乗りません (OBS Virtual Camera は映像のみ)。
+
+## 機種ごとの注意
+
+### Optimize 3DS
+
+- 公式ソフトを使った後は、USB を抜き差ししてから開いてください (公式ソフトが別のファームウェアを書き込むため)。
+- 3DS 本体の「本体設定 → その他の設定 → サウンド」は **ステレオ** にしてください。
+  サラウンドのままだと、スピーカー用のサラウンド処理 (中音域を左右逆位相で混ぜる) がかかった音が届き、PC で聞くとこもって聞こえます。
+- 本体の音量スライダーはキャプチャの音には効きません。`cap.volume` か PC 側で調整してください。
+
+### Loopy DS
+
+- DS 本体の電源が切れていると、開くことはできますが映像が届きません (ビューアは「信号待ち」と表示します)。
+
+## ファームウェアについて
+
+キャプチャ基板に毎回書き込むファームウェア (と Optimize のキー計算用テーブル) は、このライブラリに **同梱していません**。
+これらは cc3dsfs で公開されているファイルですが、cc3dsfs の MIT ライセンスの対象外で、著作権は各メーカーにあります
+(Loopy DS 用は Loopy 社提供、Optimize 用は non-standard)。利用者自身が cc3dsfs から取得してください。
+
+- 取得元は動作確認した cc3dsfs のコミットに固定していて、SHA-256 が合わないファイルは保存しません。
+- 探す場所は、引数 `firmware_dir` → 環境変数 `CHENPI_FIRMWARE_DIR` → `./firmware` → このリポジトリの `firmware/` →
+  `%LOCALAPPDATA%\chenpi\firmware` の順です。
+
+## 開発
+
+```powershell
+uv sync
+uv run pytest   # 実機不要。ファームウェアが無い環境では、それを読む数件のテストはスキップされる
+```
+
+GitHub Actions では、Windows 上でファームウェアを取得してからテストを回します (`.github/workflows/test.yml`)。
+
+## ライセンス
+
+MIT License ([LICENSE](LICENSE))。
+cc3dsfs の処理を移植しているため、cc3dsfs のライセンス表示を [LICENSES/cc3dsfs.txt](LICENSES/cc3dsfs.txt) に含めています。
+ファームウェアは上記のとおり同梱していません。

chenpi-0.1.0/README.md

@@ -0,0 +1,182 @@
+# chenpi
+
+**chenpi** (陳皮) は、DS / 3DS 用キャプチャ機器の映像・音声を、公式ビューアやウィンドウキャプチャを使わずに
+numpy / OpenCV の画像として直接取り込むための Windows 用ライブラリです。
+`cv2.VideoCapture` と同じ `read()` で読めるので、OpenCV 前提のコードにそのまま渡せます。
+[cc3dsfs](https://github.com/Lorenzooone/cc3dsfs) (MIT License) の処理を Python に移植しています。
+
+| 機種 | 映像 | 音声 | 備考 |
+|---|---|---|---|
+| 新型 Loopy DS キャプチャ (USB Type-C 版) | 256x192 × 2 画面 / 60fps | あり | |
+| Optimize 3DS キャプチャ (Old 3DS 用) | 400x240 + 320x240 / 60fps | あり | 公式ソフトのプロダクトキーが必要 |
+
+Optimize の New 3DS 用 / 2DS 用、RGB888、3D 表示、Loopy 製 3DS キャプチャには未対応です。
+
+## 準備
+
+1. **ドライバ**: 各機器の公式ソフトに付属するドライバをそのまま使います (公式ソフトが動く環境なら導入済み)。
+   - Loopy DS: FTDI の D2XX ドライバ
+   - Optimize 3DS: 公式ドライバ (NSTDUSB3)
+   - Zadig などで WinUSB に差し替えると動きません。
+2. **インストール**
+
+   ```powershell
+   uv add "chenpi[audio,virtualcam]"     # 別のプロジェクトから使う場合 (pip install でも可。音声・仮想カメラが不要なら [] は省略)
+   uv sync                               # このリポジトリで開発する場合
+   ```
+
+3. **ファームウェアの取得**: 基板に書き込むファームウェアは同梱していないので、cc3dsfs から取得します
+   (理由は[ファームウェアについて](#ファームウェアについて))。ビューアは、無ければ取得してよいか尋ねます。
+
+   ```powershell
+   uv run scripts/fetch_firmware.py   # %LOCALAPPDATA%\chenpi\firmware に保存
+   ```
+
+4. **Optimize 3DS のプロダクトキー**: `--key` か環境変数 `OPTIMIZE_3DS_KEY` で渡します (カンマ区切りで複数可)。
+
+   ```powershell
+   setx OPTIMIZE_3DS_KEY "XXXX-XXXX-XXXX-XXXX-XXXX"   # VS Code / ターミナルを開き直すと有効
+   ```
+
+公式ソフトや cc3dsfs とは同時に使えません。先に閉じてください。
+
+## ビューアで試す
+
+```powershell
+uv run chenpi-view --list                 # 接続されている機器の一覧
+uv run chenpi-view                        # 見つかった機器を表示 (q で終了)
+uv run chenpi-view --device 3ds --audio   # 機種を指定し、音声も再生 (+ / - キーで音量)
+uv run chenpi-view --layout horizontal --scale 3
+```
+
+| オプション | 内容 |
+|---|---|
+| `--device auto\|ds\|3ds` | 機種 (既定 `auto`: DS → 3DS の順に探す) |
+| `--key` | Optimize 3DS のプロダクトキー |
+| `--layout vertical\|horizontal\|top\|bottom` | 画面の並べ方 |
+| `--scale` | 表示の拡大率 (既定 2) |
+| `--audio` / `--volume` / `--audio-latency` | 音声の再生 / 音量の倍率 / 出力バッファ (秒) |
+
+## ライブラリとして使う
+
+### OpenCV と同じように読む
+
+```python
+from chenpi import open_capture
+
+with open_capture("auto", layout="vertical") as cap:   # "ds" / "3ds" も指定できる
+    ok, frame = cap.read()        # BGR uint8。vertical なら DS は 256x384、3DS は 400x480 (下画面の左右は黒帯)
+    audio = cap.read_audio()      # 前回以降の音声 int16 (N, 2) [L, R]
+```
+
+機種ごとのクラス (`LoopyDSCapture` / `Optimize3DSCapture`) を直接使うこともできます。
+
+API の一覧・frame の大きさ・例外・注意点は [src/chenpi/USAGE.md](src/chenpi/USAGE.md) にまとめてあります。
+このファイルはパッケージにも入るので、chenpi を使う別のプロジェクトでは、その CLAUDE.md などに次のように書いておくと、
+コーディングエージェントが正しい使い方を参照できます。
+
+```markdown
+- キャプチャには chenpi を使う。使い方は `.venv/Lib/site-packages/chenpi/USAGE.md` を読むこと。
+```
+
+### 機器の一覧から選んで開く (GUI 向け)
+
+```python
+from chenpi import list_devices, open_device
+
+infos = list_devices()                # 機器には触らずに一覧だけ返す (ファーム書き込みなどはしない)
+for info in infos:
+    print(info, info.available)       # 例: "Optimize Old 3DS [使用中]" False
+cap = open_device(infos[0], key=["XXXX-...", "YYYY-..."])   # 3DS は保存してあるキーを全部渡せば合うものを使う
+print(cap.serial)                     # 3DS ならデバイス ID。キーとの対応を保存しておくとよい
+```
+
+- `info.status` は `ready` / `in_use` (他のプログラムが使用中) / `replug` (公式ソフト使用後で USB の抜き差しが必要)。
+- Optimize 3DS のデバイス ID は開くまで分からないので、一覧では `info.id` が `None` です。
+  挿した直後は「未初期化」と表示されます (Old 3DS 用 / New 3DS v2 用 / 2DS 用の区別は付きません)。
+- Optimize を 2 台つないでいても、キーの合う空いている方が開きます。
+- 同じ機器を 2 つのプログラムで同時に開くことはできません (cc3dsfs との間でも)。
+- 使用中の Loopy DS は、ID (シリアル) が大文字で表示されます (Windows の記録による)。比べるときは大文字小文字を区別しないでください。
+
+### 音声
+
+- DS・3DS とも `SAMPLE_RATE` (≒ 32728.5 Hz) のステレオ int16 です。
+- `read_audio()` は待たずに、溜まっている分を全部返します (読まれない分は約 2 秒で古い順に捨てます)。
+- 音量は `cap.volume` (倍率、既定 1.0) で変えられ、`read_audio()` の結果にかかります。再生中に変えてもすぐ反映されます。
+  1.0 より大きくすると増幅し、int16 をはみ出す分は頭打ちになります。GUI のスライダーなら `cap.volume = value / 100` のように使えます。
+
+### GUI に組み込むときの注意
+
+- **ファームウェアが無いとき**は `FirmwareMissing` (足りないファイル名は `e.names`) になります。
+  勝手にダウンロードせず、利用者に確認してから取得してください。
+
+  ```python
+  from chenpi import FirmwareMissing, download_firmware, open_device
+
+  try:
+      cap = open_device(info, key=keys)
+  except FirmwareMissing as e:
+      if ask_user(f"{e.names} を cc3dsfs から取得しますか?"):
+          download_firmware()
+  ```
+
+- **CPU 使用率**: 毎フレーム OpenCV で拡大や表示をするなら、アプリの最初で `cv2.setNumThreads(1)` を呼んでください。
+  OpenCV は小さな処理も複数スレッドに分け、その後スレッドが空回りするため、ビューアでは 1 コアの約 9 割 → 約 3 割に下がりました。
+  プロセス全体の設定なので、ライブラリ側では変えていません。
+- `read()` は新しいフレームが来るまで待つので、GUI のメインスレッドではなく別スレッドで回してください。
+- 機器を切り替えるときは、先に `cap.release()` を呼んでください。
+- 受信中に USB が抜かれると、`read()` が `(False, None)` を返し、`cap.isOpened()` が False になります (固まりません)。
+
+## 仮想カメラ
+
+OBS Studio (OBS Virtual Camera) が入っていれば、普通の Web カメラとして他のアプリから使えます。
+OBS 側の「仮想カメラ開始」は止めておいてください (同時には使えません)。
+
+```powershell
+uv run chenpi-virtualcam --device 3ds   # --layout / --scale / --audio / --key もビューアと同じ
+```
+
+```python
+import cv2
+cap = cv2.VideoCapture(3, cv2.CAP_DSHOW)  # 番号は環境による (OBS Virtual Camera の番号)
+```
+
+仮想カメラには音声は乗りません (OBS Virtual Camera は映像のみ)。
+
+## 機種ごとの注意
+
+### Optimize 3DS
+
+- 公式ソフトを使った後は、USB を抜き差ししてから開いてください (公式ソフトが別のファームウェアを書き込むため)。
+- 3DS 本体の「本体設定 → その他の設定 → サウンド」は **ステレオ** にしてください。
+  サラウンドのままだと、スピーカー用のサラウンド処理 (中音域を左右逆位相で混ぜる) がかかった音が届き、PC で聞くとこもって聞こえます。
+- 本体の音量スライダーはキャプチャの音には効きません。`cap.volume` か PC 側で調整してください。
+
+### Loopy DS
+
+- DS 本体の電源が切れていると、開くことはできますが映像が届きません (ビューアは「信号待ち」と表示します)。
+
+## ファームウェアについて
+
+キャプチャ基板に毎回書き込むファームウェア (と Optimize のキー計算用テーブル) は、このライブラリに **同梱していません**。
+これらは cc3dsfs で公開されているファイルですが、cc3dsfs の MIT ライセンスの対象外で、著作権は各メーカーにあります
+(Loopy DS 用は Loopy 社提供、Optimize 用は non-standard)。利用者自身が cc3dsfs から取得してください。
+
+- 取得元は動作確認した cc3dsfs のコミットに固定していて、SHA-256 が合わないファイルは保存しません。
+- 探す場所は、引数 `firmware_dir` → 環境変数 `CHENPI_FIRMWARE_DIR` → `./firmware` → このリポジトリの `firmware/` →
+  `%LOCALAPPDATA%\chenpi\firmware` の順です。
+
+## 開発
+
+```powershell
+uv sync
+uv run pytest   # 実機不要。ファームウェアが無い環境では、それを読む数件のテストはスキップされる
+```
+
+GitHub Actions では、Windows 上でファームウェアを取得してからテストを回します (`.github/workflows/test.yml`)。
+
+## ライセンス
+
+MIT License ([LICENSE](LICENSE))。
+cc3dsfs の処理を移植しているため、cc3dsfs のライセンス表示を [LICENSES/cc3dsfs.txt](LICENSES/cc3dsfs.txt) に含めています。
+ファームウェアは上記のとおり同梱していません。

chenpi-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "chenpi"
+version = "0.1.0"
+description = "Read DS/3DS capture boards (Loopy DS, Optimize Old 3DS) as OpenCV/numpy images on Windows"
+readme = "README.md"
+license = "MIT"
+license-files = [
+    "LICENSE",
+    "LICENSES/*",
+]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video :: Capture",
+    "Development Status :: 3 - Alpha",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=1.26",
+    "opencv-python>=4.9",
+]
+
+[[project.authors]]
+name = "Lizz"
+
+[project.scripts]
+chenpi-view = "chenpi.__main__:main"
+chenpi-virtualcam = "chenpi.virtualcam:main"
+
+[project.optional-dependencies]
+audio = ["sounddevice>=0.5.6"]
+virtualcam = ["pyvirtualcam>=0.15.0"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "chenpi[audio,virtualcam]",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"

chenpi-0.1.0/pyproject.toml.orig

@@ -0,0 +1,39 @@
+[project]
+name = "chenpi"
+version = "0.1.0"
+description = "Read DS/3DS capture boards (Loopy DS, Optimize Old 3DS) as OpenCV/numpy images on Windows"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "LICENSES/*"]   # LICENSES/cc3dsfs.txt: 移植元 cc3dsfs の MIT ライセンス (表示が条件)
+authors = [{ name = "Lizz" }]
+classifiers = [
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Multimedia :: Video :: Capture",
+    "Development Status :: 3 - Alpha",
+]
+requires-python = ">=3.12"
+dependencies = [
+    "numpy>=1.26",
+    "opencv-python>=4.9",
+]
+
+[project.scripts]
+chenpi-view = "chenpi.__main__:main"
+chenpi-virtualcam = "chenpi.virtualcam:main"
+
+[project.optional-dependencies]
+audio = [
+    "sounddevice>=0.5.6",
+]
+virtualcam = [
+    "pyvirtualcam>=0.15.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "chenpi[audio,virtualcam]"]
+
+[build-system]
+requires = ["uv_build>=0.11.32,<0.12.0"]
+build-backend = "uv_build"

chenpi-0.1.0/src/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` で使い方。