references/cuda-wsl.md
# CUDAとWSLの確認
2026-10-20の確認結果。Windows用とWSL用のToolkitは別々に管理する。
今回の自動セットアップはWindows版s2.cpp用。WSLへ移すだけで高速化するとは判断していない。
| 項目 | 確認結果 |
| --- | --- |
| GPU | RTX 3080、VRAM 10GB。確認時の空きは約5.7GB |
| Windowsドライバー | 610.47 |
| Windowsの`nvcc` | CUDA 11.8。s2.cppの要求する12.4以上を満たさない |
| `CUDA/v12.4` | フォルダーはあるがコンパイラー・ヘッダー・ライブラリーがなく、利用可能なToolkitではない |
| `%USERPROFILE%/.wslconfig` | `[wsl2]`、`memory=16GB` |
| WSLの状態・ディストリビューション | この実行環境では`Wsl/E_ACCESSDENIED`になり確認できない |
インストール・アンインストール・WSL設定変更はまだ実行していない。
この実行環境は管理者ではなく、外部DNSとWSL操作が制限されている。
この制限をWSL自体の故障と判断しない。
## WindowsのToolkitを更新する
1. [NVIDIA公式のCUDA 12.9 Update 1](https://developer.nvidia.com/cuda-12-9-1-download-archive?target_os=Windows&target_arch=x86_64&target_version=11&target_type=exe_local)を候補にする。s2.cppの要求12.4以上を満たし、既存ドライバー610.47を更新せずに試す構成。このリポジトリでのビルドは未検証で、MSVCとの適合は構成・ビルド時に確認する。13系が必要と判明したら、その根拠に合わせて選び直す。
2. カスタムインストールでToolkitとVisual Studio統合を選ぶ。GPUドライバー更新は別途必要性を判断する。
3. 新しいPowerShellで、インストールした実際のパスを指定して確認・ビルドする。以下は12.9を標準の場所へ入れた場合。
```powershell
& "<presenter>/tools/scripts/setup-s2.ps1" -CudaRoot 'C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.9' -CheckOnly
& "<presenter>/tools/scripts/setup-s2.ps1" -CudaRoot 'C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.9'
uv run --project "<presenter>/tools" presenter-tts server start
```
`-CheckOnly`はファイルとコンパイラーバージョンの確認で、MSVCとの組み合わせやGPU実行まで保証しない。
ビルド成功時に選択したToolkitの場所を記録し、`server start`はそのDLLをプロセス内のPATHで優先する。永続的なPATHは変更しない。
同じビルドディレクトリを異なるToolkitへ変更してCMakeが拒否した場合は、既存ビルドを別名で保管してから再構成する。
古いToolkitを削除するかはユーザーが決める。削除する場合は、新しい版でビルドと音声生成を確認してから、Windowsの「インストールされているアプリ」で行う。このスキルからは削除しない。
GPUドライバーは残す。フォルダーを直接削除しない。
既存プロジェクトが11.8のコンパイラーを参照していないか確認し、削除後にPATHと`CUDA_PATH`を確認する。
## 検証結果をまとめて保存する
通常のPowerShellで以下を実行する（`<presenter>`はpresenterスキルのフォルダ）。モデルのダウンロード・インストール・WSL停止は行わない。
```powershell
uv run --project "<presenter>/tools" python "<presenter>/tools/scripts/verify_local.py"
```
テスト、SSML解析、環境診断、WSLの状態を`<home>/cache/validation/<日時>/report.json`へ保存する。
依存関係は`uv run --project`が初回に`<presenter>/tools/.venv`へそろえる。
`checks_passed`がtrueでも、doctorに記録された通信や依存関係の警告・テストのスキップを確認する。実機での音声合成成功とは区別する。
Toolkit導入とセットアップ後、`uv run --project "<presenter>/tools" presenter-tts server start`でTTSサーバーを起動してから、以下を実行する。
```powershell
uv run --project "<presenter>/tools" python "<presenter>/tools/scripts/verify_local.py" --synthesize --input "<presenter>/tools/examples/latency.ssml" --runs 3
uv run --project "<presenter>/tools" python "<presenter>/tools/scripts/verify_local.py" --synthesize --input "<presenter>/tools/examples/presentation.ssml"
```
音声は`outputs/validation-<日時>/`へ保存する。再生せずに最初のPCMまでの時間とRTFを測る。
最初の試行は初回処理の影響を含む可能性があるため、2・3回目とも比較する。
速度だけでなく、保存した音声で読み抜け、音切れ、声の一貫性、間、強調を聴いて確認する。
10層・18層・36層などを比較するときは、`server stop`で止めてから`<home>/config.toml`の`[server] gpu_layers`を変えて起動し直す。同時に複数起動しない。
## WSLの確認
通常のPowerShellで次を実行する。設定の変更や停止は行わない。
```powershell
wsl --version
wsl --status
wsl --list --verbose
Get-Content "$env:USERPROFILE\.wslconfig"
```
使用するディストリビューションがWSL **2**であることを確認する。
必要なら`wsl --update`でWSLを更新する。WSL内で、presenterスキルのフォルダを指定して読み取り専用診断を実行する。
```bash
bash "/mnt/c/<presenterスキルのフォルダ>/tools/scripts/check-wsl.sh"
```
診断スクリプトのWSL上での実行は未検証。この実行環境ではWSLとGit Bashの起動が拒否されており、Bashによる構文検証も実施できていない。
WSLでs2.cppをビルドする場合:
- NVIDIAの[WSLガイド](https://docs.nvidia.com/cuda/wsl-user-guide/index.html)に従い、Linux用CUDA Toolkitを用意する。GPUドライバーはWindows側を共有する。WSL内へLinux用NVIDIAドライバーを入れない。
- WSL-Ubuntu用のインストーラーか、`cuda-toolkit-X-Y`パッケージを選ぶ。ドライバーを含む`cuda`、`cuda-X-Y`、`cuda-drivers`を選ばない。Windowsの11.8を消してもLinuxのToolkitは更新されない。
- Linux側の`nvcc --version`が12.4以上で、`nvidia-smi`がGPUを認識することを確認する。PATHにWindowsの`nvcc.exe`が混ざっていないか確認する。
- ソース・モデル・ビルド出力はLinuxのホーム配下に置く。Windows版と同じCMakeビルドディレクトリを共用しない。ビルド方法は[s2.cppの上流手順](https://github.com/rodrigomatta/s2.cpp)に従う。
- Linux側のサーバーは`127.0.0.1:3030`に限定して起動する。Windows側のコントローラーから`uv run --project "<presenter>/tools" presenter-tts doctor`で到達性を確認する。localhost転送は既定で有効。届かない場合はWSLバージョンとネットワーク設定を確認してから変更する。
`memory=16GB`はWSL全体のシステムRAM上限で、GPUのVRAMを増やす設定ではない。
今回のQ4モデルでまず維持し、Linux側の`free -h`やOOMログを確認してから調整する。
物理RAMの余裕を確認できていないため、上限引き上げやswap増量を自動では行わない。swapはVRAM不足による遅延の解消策にはならない。
`processors`やネットワークモードも、診断結果なしに固定しない。
`.wslconfig`の変更反映にはWSLの停止・再起動が必要になる。
`wsl --shutdown`は全ディストリビューションを止めるため、Dockerや実行中の処理を保存してから行う。
参考: [MicrosoftのWSL詳細設定](https://learn.microsoft.com/en-us/windows/wsl/wsl-config)、[NVIDIA Windowsインストールガイド](https://docs.nvidia.com/cuda/cuda-installation-guide-microsoft-windows/index.html)。
SKILL.md
---
name: presenter-setup
description: presenterスキル（ローカルのFish Audio S2 Pro音声合成）をWindows/CUDAまたはApple Silicon Mac/Metalで使える状態にする。前提ソフトの確認と導入、ライセンス確認、s2.cppのビルド、モデル取得、動作確認、必要なら声の登録までを進める。「presenterをセットアップして」「音声合成を使えるようにして」「TTSのエンジンを入れて」「doctorでエラーが出た」「ビルドし直して」で使う。
license: MIT
compatibility: Windows 10/11＋NVIDIA GPU/CUDA 12.4以上、またはApple Silicon Mac＋Metalに対応。uv、Git、FFmpeg、CMake、WindowsはVisual Studio C++、MacはXcode Command Line Tools、GitHub/Hugging Face接続が必要。presenterスキルと同じ場所にインストールされていること。
---
# presenter-setup
presenterのエンジン（s2.cpp）とモデルを用意し、音が出るところまで確かめる。
ユーザーにやってもらうのは、**ソフトの導入とライセンスへの同意の承認**だけにする。それ以外のコマンドはこちらで実行する。
## 0. presenterスキルを見つける
このスキルのフォルダの隣にある`presenter/`（例: `.claude/skills/presenter/`）を`<presenter>`とする。
`<presenter>/tools/pyproject.toml`がなければ止めて、presenterスキルも入れるよう伝える（`npx skills add`で両方入れる）。
コマンドはすべて`uv run --project "<presenter>/tools" presenter-tts ...`で呼ぶ。パスは引用符で囲む。
## 1. いまの状態を調べる
```console
uv run --project "<presenter>/tools" presenter-tts doctor
```
uv自体がない場合はこのコマンドが動かないので、先に手順2でuvを入れる。
出力のJSONから次を読む。**`engine.ready`がtrueなら手順5（動作確認）へ飛ぶ。**
| 項目 | 必要な状態 |
|---|---|
| `prerequisites.platform` | `windows`または`macos`。それ以外は未対応 |
| Macの`prerequisites.architecture` | Apple Siliconを示す`arm64` |
| Windowsの`gpu` | NVIDIAのGPUがあり、合計のVRAM（2つ目の値、MB）が6000以上 |
| Windowsの`prerequisites.cuda_version` | 12.4以上 |
| Windowsの`prerequisites.visual_studio_cpp` | パスがある（C++のビルドツールが入っている） |
| Macの`prerequisites.metal` | `xcrun --find metal`で見つかる |
| `prerequisites.git`、`prerequisites.uv` | パスがある |
| `ffmpeg`、`ffplay` | パスがある |
| Macの`swiftc` | パスがある（再生用の補助プログラムをビルドする。なければ再生はFFplayを使う） |
| `huggingface.co`、`github.com` | `DNS available` |
WindowsでGPUがない、またはVRAMが足りない場合は、セットアップを進めずにその旨を伝える（CPUだけでは実用的な速度にならない）。MacはApple SiliconとMetalが必要。
## 2. 足りないソフトを入れる
足りないものだけを一覧にし、**何を・どこから・どれくらいの容量で入れるか**を見せて、承認を得てから入れる。
大きなもの（Visual Studio、CUDA）は管理者権限が必要で、ダウンロードも数GBある。承認なしに入れない。
Windows:
| ソフト | 導入コマンド | 備考 |
|---|---|---|
| uv | `winget install --id astral-sh.uv -e` | |
| Git | `winget install --id Git.Git -e` | |
| FFmpeg（FFplayを含む） | `winget install --id Gyan.FFmpeg -e` | |
| Visual Studio 2022 C++ビルドツール | `winget install --id Microsoft.VisualStudio.2022.BuildTools -e --override "--wait --passive --add Microsoft.VisualStudio.Workload.VCTools --includeRecommended"` | CMakeも含まれる。数GB |
| CUDA Toolkit | `winget show --id Nvidia.CUDA --versions`で版を確かめ、12.4以上を`winget install --id Nvidia.CUDA -e --version <版>` | 約3 GB。GPUドライバーの更新は別に判断する |
- 導入後は、新しく開いたシェルでないとPATHが反映されないことがある。もう一度`doctor`を実行し、見つからない場合はフルパスで確かめる。
- CUDAが複数入っていて、PATHの先頭が古い版（11.xなど）のことがある。`C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\`の下で12.4以上の最も新しい版を選び、手順4で`-CudaRoot`に渡す。PATHは書き換えない。
- CUDAやWSLの細かい確認は[cuda-wsl.md](references/cuda-wsl.md)を読む。
Mac:
| ソフト | 導入コマンド | 備考 |
|---|---|---|
| Xcode Command Line Tools | `xcode-select --install` | GUIでの承認と完了待ちが必要。Git、clang++、Metalを含む |
| uv | `brew install uv` | Homebrewがない場合は、公式インストーラーを提示して承認を得る |
| FFmpeg（FFplayを含む） | `brew install ffmpeg` | Homebrewがない場合は、先に導入方法をユーザーと決める |
`xcode-select -p`、`xcrun --find clang++`、`xcrun --find metal`を確認する。CMakeがなければ`setup-s2.sh`がuvxで一時的に用意するため、CMakeだけをHomebrewへ追加しない。
## 3. ライセンスに同意をもらう
s2.cppのエンジンとS2 Proのモデルは**Fish Audio Research License**で提供される。ダウンロードの前に、次をユーザーに伝えて同意を得る。
- 研究・非商用の利用は無償。**商用利用にはFish Audioとの別途の契約が必要**（business@fish.audio）
- 配布するときはライセンス文と帰属表示（"This model is licensed under the Fish Audio Research License, Copyright © 39 AI, INC. All Rights Reserved."）が必要
- 全文は取得後の`<home>/cache/s2.cpp/LICENSE.md`
同意がなければ、ここで止める。
## 4. エンジンをビルドし、モデルを取得する
`doctor`の`prerequisites.platform`に従い、対応する片方だけで確認する（数秒）。
```powershell
& "<presenter>/tools/scripts/setup-s2.ps1" -CheckOnly -CudaRoot "<CUDAのフォルダ>"
```
```bash
"<presenter>/tools/scripts/setup-s2.sh" --check-only
```
確認結果がreadyなら、本番を**バックグラウンドで**実行する。s2.cppの取得とビルドに約20分、モデルのダウンロードに数分かかる。始める前に目安の時間を伝える。
```powershell
& "<presenter>/tools/scripts/setup-s2.ps1" -CudaRoot "<CUDAのフォルダ>"
```
```bash
"<presenter>/tools/scripts/setup-s2.sh"
```
- 置き場所は`%LOCALAPPDATA%\presenter-tts\cache\`（Windows）または`~/.local/share/presenter-tts/cache/`（Mac）。`PRESENTER_TTS_HOME`があればその下。どのプロジェクトからも共有される。
- Windowsのビルド中に大量に出る`warning C4819`（文字コード）や`C4244`（型変換）は無害。どちらのOSも終わりに`Setup finished`が出れば成功。
- 失敗したら、出力の`error`を含む行を探す。WindowsはCUDA、MacはXcode/Metal/CMakeを確認する。同じビルド先を別のバックエンドで構成し直して拒否された場合は、`cache/s2-build`を消してからやり直す（ユーザーに確認してから）。
- モデルのダウンロードだけが失敗した場合、ビルドは残っている。もう一度同じコマンドを実行すればダウンロードから再開する。
設定ファイルがなければ、見本をコピーする（既存のものは上書きしない）。
```powershell
$ttsHome = if ($env:PRESENTER_TTS_HOME) { $env:PRESENTER_TTS_HOME } else { Join-Path $env:LOCALAPPDATA 'presenter-tts' }
$config = Join-Path $ttsHome 'config.toml'
if (-not (Test-Path -LiteralPath $config)) {
New-Item -ItemType Directory -Path $ttsHome -Force | Out-Null
Copy-Item "<presenter>/tools/presenter.example.toml" -Destination $config
}
```
Macでは同じ見本を`~/.local/share/presenter-tts/config.toml`へ置く。既存ファイルは上書きしない。
```bash
tts_home="${PRESENTER_TTS_HOME:-$HOME/.local/share/presenter-tts}"
mkdir -p "$tts_home"
test -e "$tts_home/config.toml" || cp "<presenter>/tools/presenter.example.toml" "$tts_home/config.toml"
```
## 5. 音が出るか確かめる
```console
uv run --project "<presenter>/tools" presenter-tts doctor
uv run --project "<presenter>/tools" presenter-tts say "こんにちは。音声合成のテストです。"
```
`engine.ready`がtrueで、`say`がエラーなく終わったら、**ユーザーに聞こえたかを尋ねる**。
生成も再生も成功しているのに聞こえない場合は、OSの出力デバイスとミュートを確かめてもらう（よくある原因）。
サーバーの起動に失敗したら`<home>/cache/s2-server.log`の末尾を読む。GPUメモリまたはMacのユニファイドメモリ不足なら、`config.toml`の`[server] gpu_layers`を減らす（例: 18）。
確かめ終わったら、続けて使う予定がなければサーバーを止める（GPUのメモリを約4 GB使うため）。
```console
uv run --project "<presenter>/tools" presenter-tts server stop
```
## 6. 声を登録する（任意）
既定の声はモデル自身の声で、文ごとに声質が変わることがある。発表に使うなら、声を1つ登録しておくとよい。
ユーザーが望んだ場合だけ、presenterスキルの「声を登録する」の手順に従う（本人の声か許可を得た声だけ）。
登録したら、`config.toml`の先頭の`voice = "<名前>"`を有効にすると既定の声になる。
## 7. 報告する
次をまとめて伝える。
- 入れたソフトと版、ビルドしたバックエンド（CUDAまたはMetal）
- 置き場所（Windowsは`%LOCALAPPDATA%\presenter-tts`、Macは`~/.local/share/presenter-tts`）と使った容量
- 動作確認の結果（聞こえたかどうかを含む）
- 次にできること（presenterでスライドの音声を作る、`say`で話させる）と、片付けの方法（presenterの`references/cleanup.md`）
## やり直すとき
- CUDA/Xcodeを更新した、ビルドが壊れた: `cache/s2-build`を消して手順4から。
- モデルを消した: 手順4をもう一度実行する（ビルドは使い回され、ダウンロードだけが走る）。
- 別のPCに移る: そのPCでこのスキルを最初から実行する。声は`<home>/voices/`をコピーすれば持っていける。