View on GitHub

cat-oscillator-sync

cat-oscillator-sync

Go版 実装計画書

概要

Python版のcat-oscillator-syncをGoで実装する計画書です。 Windows環境でのローカル実行を前提とし、PortAudio系のライブラリを使用します。

目標

ライブラリ選定

1. オーディオ出力ライブラリ

選択肢A: gordonklaus/portaudio (推奨)

選択肢B: hajimehoshi/oto

選択肢C: ebitengine/oto (oto v3)

結論:

2. マウス位置取得ライブラリ

選択: go-vgo/robotgo

代替案: micmonay/keybd_event + システムコール

代替案: Windows API直接呼び出し (syscall)

3. 数値計算

選択: 標準ライブラリ (math パッケージ)

プロジェクト構成

src/go/
├── go.mod                  # Go モジュール定義
├── go.sum                  # 依存関係のチェックサム
├── IMPLEMENTATION_PLAN.md  # 本ドキュメント
├── README.md              # 実装後のREADME
├── cmd/
│   ├── sync_simple/
│   │   └── main.go        # シンプル版エントリポイント
│   └── sync_smooth/
│       └── main.go        # スムーズ版エントリポイント
└── internal/
    ├── synth/
    │   ├── simple.go      # シンプル版実装
    │   └── smooth.go      # スムーズ版実装
    └── mouse/
        └── position.go    # マウス位置取得

依存関係 (go.mod)

オプション1: PortAudio使用

module github.com/cat2151/cat-oscillator-sync/go

go 1.21

require (
    github.com/gordonklaus/portaudio v0.0.0-20230709114228-aafa478834f5
    github.com/go-vgo/robotgo v0.100.10
)

オプション2: Pure Go (oto使用)

module github.com/cat2151/cat-oscillator-sync/go

go 1.21

require (
    github.com/ebitengine/oto/v3 v3.1.0
    github.com/go-vgo/robotgo v0.100.10
)

実装計画

Phase 1: 基本構造の実装

  1. Go modulesの初期化
  2. ライブラリの選定と動作確認
  3. オーディオ出力の基本動作確認

Phase 2: シンプル版の実装

  1. マウス位置取得モジュールの実装
  2. 周波数マッピング関数の実装
  3. ハードシンク・オシレータの実装
    • マスターオシレータ（位相管理）
    • スレーブオシレータ（位相リセット）
  4. オーディオストリームコールバックの実装
  5. メインループの実装
  6. 動作確認とデバッグ

Phase 3: スムーズ版の実装

  1. 指数平滑化アルゴリズムの実装
  2. サンプルごとの周波数補間
  3. パラメータ設定構造体の実装
  4. 動作確認とデバッグ

Phase 4: ドキュメント整備

  1. README.mdの更新
  2. コードコメントの追加（GoDoc形式）
  3. ビルド・実行手順の文書化

インストール手順（想定）

前提条件

オプション1: PortAudio使用の場合

  1. Go 1.21以上
    • https://golang.org/dl/ からインストール
  2. PortAudio DLL (Windows)
    • 方法A: 自動ダウンロード（推奨） 
      cd src/go
python download_portaudio.py

      このスクリプトは GitHub spatialaudio/portaudio-binaries から libportaudio64bit.dll を自動ダウンロードします。 python-sounddeviceも同じソースから入手しており、安全性と可用性が高いと判断しています。

    • 方法B: MSYS2でビルド
      1. MSYS2をインストール: https://www.msys2.org/
      2. MinGW-w64環境を構築
      3. PortAudioをソースからビルド 
        pacman -S mingw-w64-x86_64-portaudio
  3. GCC (CGO用)
    • MinGW-w64またはMSYS2のGCC
    • TDM-GCC: https://jmeubank.github.io/tdm-gcc/

オプション2: Pure Go (oto)の場合

  1. Go 1.21以上のみ
    • 外部DLL不要
    • CGOも不要（ただしrobotgoはCGO使用）

ビルドと実行

# リポジトリのクローン
git clone https://github.com/cat2151/cat-oscillator-sync.git
cd cat-oscillator-sync/src/go

# 依存関係のダウンロード
go mod download

# ビルド - シンプル版
go build -o bin/sync_simple.exe ./cmd/sync_simple

# ビルド - スムーズ版
go build -o bin/sync_smooth.exe ./cmd/sync_smooth

# 実行
.\bin\sync_simple.exe
.\bin\sync_smooth.exe

または直接実行:

go run ./cmd/sync_simple
go run ./cmd/sync_smooth

開発環境構築の複雑度評価

オプション1: PortAudio使用 ⭐⭐⭐ (中程度)

複雑な点:

  1. PortAudio DLLのインストール:
    • 手作業でDLLをダウンロード・配置
    • またはMSYS2環境の構築
  2. CGOのための GCC:
    • MinGW-w64のインストールが必要
    • 環境変数の設定

手順数:

  1. Goのインストール
  2. GCCのインストール（MinGW-w64）
  3. PortAudio DLLの配置
  4. go buildの実行

Python版との比較:

オプション2: Pure Go (oto使用) ⭐⭐⭐⭐ (比較的簡単)

理由:

  1. 外部DLL不要: oto自体はPure Go
  2. ただしrobotgoはCGO使用: GCCが依然として必要
  3. PortAudioではない: 要件から外れる

手順数:

  1. Goのインストール
  2. GCCのインストール（robotgo用）
  3. go buildの実行

オプション3: 完全Pure Go (マウス位置もsyscall) ⭐⭐⭐⭐⭐ (最もシンプル)

変更点:

手順数:

  1. Goのインストール
  2. go buildの実行

結論: 最もシンプルだが、Windows専用コードになる

技術的課題と対策

1. PortAudio DLLの配布

課題: ユーザーがDLLを手動インストールする必要 対策:

2. CGO依存

課題: クロスコンパイルが困難 対策:

3. ゴルーチンとオーディオコールバック

課題: リアルタイム処理での同期 対策:

パフォーマンス期待値

メリット

Python版との比較

リスクと軽減策

リスク1: PortAudio DLLの配布・インストールの複雑さ

軽減策:

リスク2: CGO依存によるビルドの複雑さ

軽減策:

リスク3: robotgoの安定性

軽減策:

成功基準

  1. ✅ Windows環境で動作すること
  2. ✅ Python版と同等の音質・レスポンスを実現
  3. ⚠️ インストール手順が5ステップ以内
  4. ❌ 外部DLLの手動インストールが必要（PortAudio使用時）
  5. ✅ ビルド時間が3分以内

推奨実装アプローチ

アプローチA: 要件準拠（PortAudio）

アプローチB: シンプル重視（Pure Go寄り）

アプローチC: ハイブリッド

推奨: アプローチC

参考資料

公式ドキュメント

Windows API参照

タイムライン（想定）

まとめ

Go版の実装は技術的に実現可能ですが、開発環境構築がやや複雑です。

課題:

推奨:

優先度評価: ⭐⭐⭐ (中程度)

Python版やRust版と比較すると、開発環境構築の複雑さが若干高くなります。 ただし、実装自体はGoの豊富な標準ライブラリにより、比較的スムーズに進むと予想されます。