VoiceCode Assistant

Voice-Powered AI Coding Assistant

English | 한국어 | 中文 | 日本語 | Español

---

English

Overview

VoiceCode Assistant is an interactive voice-controlled coding tool that enables hands-free programming. It integrates VibeVoice (Microsoft's speech AI) with OpenCode (AI coding agent) to provide a seamless voice-to-code experience.

Key Features

• Voice-Controlled Coding: Speak your coding instructions naturally
• Real-time Voice Feedback: Hear status updates while AI works (file writes, test runs)
• Voice Interruption: Interrupt AI mid-speech to modify or cancel tasks
• Continuous Task Iteration: Automatic error fixing and test retrying until success
• Multi-language Support: Korean, English input/output combinations
• Rich TUI Interface: Beautiful terminal UI with real-time status display

Architecture

┌─────────────┐    ┌─────────┐    ┌──────────────────┐    ┌───────────────┐
│  Microphone │───▶│   VAD   │───▶│  VibeVoice-ASR   │───▶│  Text Command │
└─────────────┘    └─────────┘    └──────────────────┘    └───────┬───────┘
                                                                   │
                                                                   ▼
┌─────────────┐    ┌──────────────────┐    ┌───────────────┐    ┌─────────────────┐
│   Speaker   │◀───│  VibeVoice-TTS   │◀───│  AI Response  │◀───│  OpenCode API   │
└─────────────┘    └──────────────────┘    └───────────────┘    └─────────────────┘
                            ▲
                            │ (Interruptible)
                   ┌────────┴────────┐
                   │ Interrupt Monitor│
                   └─────────────────┘

System Requirements

Component	Requirement
Python	3.10 or higher
bun	Required for OpenCode server (npm not supported)
GPU	CUDA recommended (CPU/MPS supported but slower)
RAM	8GB minimum, 16GB recommended
Audio	Microphone and speakers

Installation

Step 1: Install bun (Required)

OpenCode uses bun's catalog: protocol, so bun is mandatory.

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Linux/macOS:

curl -fsSL https://bun.sh/install | bash

Step 2: Install Python Dependencies

cd VoiceCodeAssistant

# Option 1: Using requirements.txt
pip install -r requirements.txt

# Option 2: Editable install
pip install -e .

Step 3: Install VibeVoice

# VibeVoice project should be in the same parent directory
pip install -e ../VibeVoice

Step 4: Install OpenCode Dependencies

cd ../opencode
bun install

Quick Start

Method 1: Using Launcher Scripts (Recommended)

The launcher scripts automatically:

• Install bun if not present
• Install OpenCode dependencies
• Start the OpenCode server
• Launch VoiceCode Assistant

Windows (PowerShell):

.\run.ps1

Windows (CMD):

run.bat

Linux/macOS:

chmod +x run.sh
./run.sh

Method 2: Manual Start

1. Start OpenCode Server:

   cd opencode
   bun dev serve --port 4096

2. Launch VoiceCode Assistant:

   cd VoiceCodeAssistant
   python -m voice_code_assistant --no-auto-start

Command-Line Options

python -m voice_code_assistant [OPTIONS]

Options:
  --lang {ko-ko,ko-en,en-en}   Language mode (default: ko-ko)
                                ko-ko: Korean input → Korean output
                                ko-en: Korean input → English output
                                en-en: English input → English output

  --opencode-url URL           OpenCode server URL (default: http://localhost:4096)
  --directory PATH             Working directory for coding tasks
  --device {cuda,cpu,mps,auto} AI model execution device (default: auto)
  --no-tui                     Disable Rich TUI, use simple console output
  --no-auto-start              Don't auto-start OpenCode server
  --asr-model PATH             ASR model path (default: microsoft/VibeVoice-ASR)
  --tts-model PATH             TTS model path (default: microsoft/VibeVoice-Realtime-0.5B)
  --log-level LEVEL            Logging level (DEBUG, INFO, WARNING, ERROR)

Keyboard Shortcuts (TUI Mode)

Key	Action
Space	Start/stop voice recording
Tab	Cycle through language modes
F	Toggle voice feedback mode (OFF → ON → DETAILED)
Q	Quit application
Ctrl+C	Force quit

Voice Commands

Interrupt Commands

Say these while AI is speaking to interrupt:

Command	Action
"Stop", "Cancel", "그만", "취소"	Cancel current task
"Wait", "Hold on", "잠깐"	Pause and listen for new command
"Change", "Modify", "수정", "바꿔"	Modify current task
"Continue", "Resume", "계속"	Resume from where stopped

Voice Feedback Toggle

• "피드백 켜" / "Feedback on" - Enable voice status updates
• "피드백 꺼" / "Feedback off" - Disable voice status updates
• "상세 모드" / "Detailed mode" - Enable detailed explanations

Configuration

Environment Variables

Variable	Description	Default
VOICE_CODE_LANG	Language mode (ko-ko, ko-en, en-en)	ko-ko
VOICE_CODE_DEVICE	Compute device (cuda, cpu, mps, auto)	auto
VOICE_CODE_SAMPLE_RATE	Audio sample rate	24000
VOICE_CODE_BUFFER_SIZE	Audio buffer size	3
VIBEVOICE_ASR_MODEL	ASR model path	microsoft/VibeVoice-ASR
VIBEVOICE_TTS_MODEL	TTS model path	microsoft/VibeVoice-Realtime-0.5B
OPENCODE_URL	OpenCode server URL	http://localhost:4096
OPENCODE_DIRECTORY	Working directory	Current directory

Configuration Classes

# Audio settings
AudioConfig:
  sample_rate: 24000
  chunk_size: 2400  # 100ms at 24kHz
  channels: 1

# Voice Activity Detection
VADConfig:
  energy_threshold: 0.01
  silence_duration: 1.0  # seconds
  min_speech_duration: 0.3

# Voice Interrupt
InterruptConfig:
  enabled: True
  detection_threshold: 0.02
  min_interrupt_duration: 0.2
  cooldown_seconds: 0.5

# Voice Feedback
VoiceFeedbackConfig:
  enabled: True
  mode: "on"  # off, on, detailed
  priority_threshold: 2
  min_feedback_interval_ms: 500

# Task Iteration
TaskIterationConfig:
  enabled: True
  max_iterations: 5
  auto_verify: True
  auto_test: True

Project Structure

VoiceCodeAssistant/
├── voice_code_assistant/
│   ├── __init__.py
│   ├── __main__.py              # Entry point
│   ├── main.py                   # Main orchestrator
│   ├── config.py                 # Configuration management
│   ├── startup.py                # Auto-start manager
│   ├── audio/
│   │   ├── microphone.py         # Microphone input with non-blocking read
│   │   ├── speaker.py            # Audio output with streaming support
│   │   └── vad.py                # Voice Activity Detection
│   ├── speech/
│   │   ├── asr_engine.py         # VibeVoice ASR wrapper
│   │   ├── tts_engine.py         # VibeVoice TTS wrapper
│   │   └── language_mode.py      # Language mode management
│   ├── coding/
│   │   ├── opencode_client.py    # OpenCode HTTP client with retry
│   │   ├── session_manager.py    # Session state management
│   │   └── response_formatter.py # Response formatting
│   ├── core/
│   │   ├── interrupt_monitor.py  # Voice interrupt detection
│   │   ├── interrupt_manager.py  # Interrupt action coordination
│   │   ├── event_stream_manager.py # SSE event parsing
│   │   ├── voice_feedback.py     # Voice feedback controller
│   │   └── task_iteration.py     # Continuous task iteration
│   └── ui/
│       └── tui.py                # Rich TUI interface
├── run.ps1                       # Windows PowerShell launcher
├── run.bat                       # Windows CMD launcher
├── run.sh                        # Linux/macOS launcher
├── requirements.txt              # Python dependencies
├── pyproject.toml                # Python package config
└── README.md                     # This file

Troubleshooting

"Could not find bun executable"

Install bun and restart your terminal:

# Windows
irm bun.sh/install.ps1 | iex

# Linux/macOS
curl -fsSL https://bun.sh/install | bash

"Cannot connect to OpenCode server"

1. Check if server is running:

   curl http://localhost:4096/global/health

2. Start manually:

   cd opencode && bun dev serve --port 4096

"ModuleNotFoundError: No module named 'vibevoice'"

Install VibeVoice:

pip install -e ../VibeVoice

"CUDA out of memory"

Use CPU mode:

python -m voice_code_assistant --device cpu

"Port 4096 already in use"

Kill existing process:

# Windows
netstat -ano | findstr :4096
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :4096
kill <PID>

"No audio input device"

1. Check microphone connection
2. Set default input device in system settings
3. Install audio drivers if needed

---

한국어

개요

VoiceCode Assistant는 음성으로 코딩 지시를 하고 음성으로 응답받는 인터랙티브 코딩 도구입니다. VibeVoice (Microsoft 음성 AI)와 OpenCode (AI 코딩 에이전트)를 통합하여 핸즈프리 코딩 경험을 제공합니다.

주요 기능

• 음성 코딩 제어: 자연스럽게 말하면서 코딩 지시
• 실시간 음성 피드백: AI 작업 중 상태 업데이트를 음성으로 안내 (파일 작성, 테스트 실행 등)
• 음성 인터럽트: AI가 말하는 중에 음성으로 중단/수정 가능
• 연속 작업 반복: 오류 발생 시 자동 수정 및 테스트 재시도
• 다국어 지원: 한국어, 영어 입출력 조합 지원
• Rich TUI 인터페이스: 실시간 상태 표시가 있는 터미널 UI

아키텍처

┌─────────┐    ┌───────┐    ┌────────────────┐    ┌──────────┐
│  마이크  │───▶│  VAD  │───▶│ VibeVoice-ASR │───▶│ 텍스트 명령│
└─────────┘    └───────┘    └────────────────┘    └────┬─────┘
                                                       │
                                                       ▼
┌─────────┐    ┌────────────────┐    ┌──────────┐    ┌────────────────┐
│ 스피커   │◀───│ VibeVoice-TTS │◀───│ AI 응답   │◀───│ OpenCode API  │
└─────────┘    └────────────────┘    └──────────┘    └────────────────┘
                       ▲
                       │ (인터럽트 가능)
              ┌────────┴────────┐
              │  인터럽트 모니터  │
              └─────────────────┘

시스템 요구 사항

구성 요소	요구 사항
Python	3.10 이상
bun	OpenCode 서버 실행 필수 (npm 미지원)
GPU	CUDA 권장 (CPU/MPS 지원되나 느림)
RAM	최소 8GB, 권장 16GB
오디오	마이크 및 스피커

설치

1단계: bun 설치 (필수)

OpenCode는 bun의 catalog: 프로토콜을 사용하므로 bun이 필수입니다.

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Linux/macOS:

curl -fsSL https://bun.sh/install | bash

2단계: Python 의존성 설치

cd VoiceCodeAssistant

# 방법 1: requirements.txt 사용
pip install -r requirements.txt

# 방법 2: 개발 모드 설치
pip install -e .

3단계: VibeVoice 설치

# VibeVoice 프로젝트가 같은 상위 디렉토리에 있어야 합니다
pip install -e ../VibeVoice

4단계: OpenCode 의존성 설치

cd ../opencode
bun install

빠른 시작

방법 1: 런처 스크립트 사용 (권장)

런처 스크립트는 자동으로:

• bun이 없으면 설치
• OpenCode 의존성 설치
• OpenCode 서버 시작
• VoiceCode Assistant 실행

Windows (PowerShell):

.\run.ps1

Windows (CMD):

run.bat

Linux/macOS:

chmod +x run.sh
./run.sh

방법 2: 수동 실행

1. OpenCode 서버 시작:

   cd opencode
   bun dev serve --port 4096

2. VoiceCode Assistant 실행:

   cd VoiceCodeAssistant
   python -m voice_code_assistant --no-auto-start

명령줄 옵션

python -m voice_code_assistant [옵션]

옵션:
  --lang {ko-ko,ko-en,en-en}   언어 모드 (기본: ko-ko)
                                ko-ko: 한국어 입력 → 한국어 출력
                                ko-en: 한국어 입력 → 영어 출력
                                en-en: 영어 입력 → 영어 출력

  --opencode-url URL           OpenCode 서버 URL (기본: http://localhost:4096)
  --directory PATH             작업 디렉토리
  --device {cuda,cpu,mps,auto} AI 모델 실행 장치 (기본: auto, 자동 감지)
  --no-tui                     Rich TUI 비활성화, 단순 콘솔 출력 사용
  --no-auto-start              OpenCode 서버 자동 시작 비활성화
  --asr-model PATH             ASR 모델 경로 (기본: microsoft/VibeVoice-ASR)
  --tts-model PATH             TTS 모델 경로 (기본: microsoft/VibeVoice-Realtime-0.5B)
  --log-level LEVEL            로깅 레벨 (DEBUG, INFO, WARNING, ERROR)

키보드 단축키 (TUI 모드)

키	동작
Space	음성 녹음 시작/중지
Tab	언어 모드 순환
F	음성 피드백 모드 토글 (OFF → ON → DETAILED)
Q	프로그램 종료
Ctrl+C	강제 종료

음성 명령

인터럽트 명령

AI가 말하는 중에 다음을 말하면 인터럽트:

명령	동작
"그만", "취소", "스톱", "멈춰"	현재 작업 취소
"잠깐", "기다려"	일시 중지하고 새 명령 대기
"수정", "바꿔", "변경해"	현재 작업 수정
"계속", "이어서", "진행해"	중단된 곳부터 재개

음성 피드백 토글

• "피드백 켜" - 음성 상태 업데이트 활성화
• "피드백 꺼" - 음성 상태 업데이트 비활성화
• "상세 모드" / "자세히 설명해" - 상세 설명 모드 활성화

설정

환경 변수

변수	설명	기본값
VOICE_CODE_LANG	언어 모드 (ko-ko, ko-en, en-en)	ko-ko
VOICE_CODE_DEVICE	연산 장치 (cuda, cpu, mps, auto)	auto
VOICE_CODE_SAMPLE_RATE	오디오 샘플 레이트	24000
VOICE_CODE_BUFFER_SIZE	오디오 버퍼 크기	3
VIBEVOICE_ASR_MODEL	ASR 모델 경로	microsoft/VibeVoice-ASR
VIBEVOICE_TTS_MODEL	TTS 모델 경로	microsoft/VibeVoice-Realtime-0.5B
OPENCODE_URL	OpenCode 서버 URL	http://localhost:4096
OPENCODE_DIRECTORY	작업 디렉토리	현재 디렉토리

사용 예시

# 기본 실행 (한국어 → 한국어, TUI 모드)
python -m voice_code_assistant

# 영어 모드
python -m voice_code_assistant --lang en-en

# CPU 사용 (GPU 없는 경우)
python -m voice_code_assistant --device cpu

# 단순 콘솔 모드
python -m voice_code_assistant --no-tui

# 특정 디렉토리에서 작업
python -m voice_code_assistant --directory /path/to/project

문제 해결

"bun을 찾을 수 없음"

bun을 설치하고 터미널을 재시작하세요:

# Windows
irm bun.sh/install.ps1 | iex

# Linux/macOS
curl -fsSL https://bun.sh/install | bash

"OpenCode 서버 연결 실패"

1. 서버 실행 확인:

   curl http://localhost:4096/global/health

2. 수동으로 서버 시작:

   cd opencode && bun dev serve --port 4096

"ModuleNotFoundError: vibevoice 모듈을 찾을 수 없음"

VibeVoice를 설치하세요:

pip install -e ../VibeVoice

"CUDA 메모리 부족"

CPU 모드 사용:

python -m voice_code_assistant --device cpu

"포트 4096이 이미 사용 중"

기존 프로세스 종료:

# Windows
netstat -ano | findstr :4096
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :4096
kill <PID>

---

中文

概述

VoiceCode Assistant 是一款交互式语音控制编程工具，可实现免手动编程。它集成了 VibeVoice（微软语音AI）和 OpenCode（AI编程代理），提供无缝的语音编程体验。

主要功能

• 语音编程控制：自然地说出编程指令
• 实时语音反馈：AI工作时语音播报状态更新（文件写入、测试运行等）
• 语音中断：可在AI说话时通过语音中断/修改任务
• 持续任务迭代：错误时自动修复并重试测试直到成功
• 多语言支持：支持韩语、英语输入/输出组合
• Rich TUI界面：带有实时状态显示的精美终端界面

系统要求

组件	要求
Python	3.10 或更高版本
bun	OpenCode服务器必需（不支持npm）
GPU	推荐CUDA（支持CPU/MPS但较慢）
内存	最低8GB，推荐16GB
音频	麦克风和扬声器

安装

步骤1：安装 bun（必需）

OpenCode 使用 bun 的 catalog: 协议，因此必须安装 bun。

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Linux/macOS:

curl -fsSL https://bun.sh/install | bash

步骤2：安装 Python 依赖

cd VoiceCodeAssistant

# 方法1：使用 requirements.txt
pip install -r requirements.txt

# 方法2：可编辑安装
pip install -e .

步骤3：安装 VibeVoice

# VibeVoice 项目应在同一父目录中
pip install -e ../VibeVoice

步骤4：安装 OpenCode 依赖

cd ../opencode
bun install

快速开始

方法1：使用启动脚本（推荐）

启动脚本会自动：

• 如果没有bun则安装
• 安装OpenCode依赖
• 启动OpenCode服务器
• 启动VoiceCode Assistant

Windows (PowerShell):

.\run.ps1

Windows (CMD):

run.bat

Linux/macOS:

chmod +x run.sh
./run.sh

方法2：手动启动

1. 启动OpenCode服务器：

   cd opencode
   bun dev serve --port 4096

2. 启动VoiceCode Assistant：

   cd VoiceCodeAssistant
   python -m voice_code_assistant --no-auto-start

命令行选项

python -m voice_code_assistant [选项]

选项:
  --lang {ko-ko,ko-en,en-en}   语言模式（默认：ko-ko）
                                ko-ko: 韩语输入 → 韩语输出
                                ko-en: 韩语输入 → 英语输出
                                en-en: 英语输入 → 英语输出

  --opencode-url URL           OpenCode服务器URL（默认：http://localhost:4096）
  --directory PATH             工作目录
  --device {cuda,cpu,mps,auto} AI模型执行设备（默认：auto）
  --no-tui                     禁用Rich TUI，使用简单控制台输出
  --no-auto-start              不自动启动OpenCode服务器
  --asr-model PATH             ASR模型路径（默认：microsoft/VibeVoice-ASR）
  --tts-model PATH             TTS模型路径（默认：microsoft/VibeVoice-Realtime-0.5B）
  --log-level LEVEL            日志级别（DEBUG, INFO, WARNING, ERROR）

键盘快捷键（TUI模式）

按键	操作
Space	开始/停止语音录制
Tab	循环切换语言模式
F	切换语音反馈模式（OFF → ON → DETAILED）
Q	退出应用
Ctrl+C	强制退出

语音命令

中断命令

在AI说话时说这些词可以中断：

命令	操作
"Stop", "Cancel", "停止", "取消"	取消当前任务
"Wait", "等一下"	暂停并等待新命令
"Change", "Modify", "修改", "改变"	修改当前任务
"Continue", "Resume", "继续"	从中断处继续

使用示例

# 默认运行（韩语 → 韩语，TUI模式）
python -m voice_code_assistant

# 英语模式
python -m voice_code_assistant --lang en-en

# 使用CPU（无GPU时）
python -m voice_code_assistant --device cpu

# 简单控制台模式
python -m voice_code_assistant --no-tui

# 在特定目录工作
python -m voice_code_assistant --directory /path/to/project

故障排除

"找不到bun可执行文件"

安装bun并重启终端：

# Windows
irm bun.sh/install.ps1 | iex

# Linux/macOS
curl -fsSL https://bun.sh/install | bash

"无法连接到OpenCode服务器"

1. 检查服务器是否运行：

   curl http://localhost:4096/global/health

2. 手动启动服务器：

   cd opencode && bun dev serve --port 4096

"CUDA内存不足"

使用CPU模式：

python -m voice_code_assistant --device cpu

---

日本語

概要

VoiceCode Assistantは、ハンズフリープログラミングを可能にする対話型音声制御コーディングツールです。VibeVoice（Microsoft音声AI）とOpenCode（AIコーディングエージェント）を統合し、シームレスな音声からコードへの体験を提供します。

主な機能

• 音声コーディング制御：自然に話しながらコーディング指示
• リアルタイム音声フィードバック：AI作業中のステータス更新を音声で案内（ファイル書き込み、テスト実行など）
• 音声割り込み：AIが話している最中に音声で中断/修正可能
• 継続タスク反復：エラー時の自動修正と成功までのテスト再試行
• 多言語サポート：韓国語、英語の入出力組み合わせ対応
• Rich TUIインターフェース：リアルタイムステータス表示付きの美しいターミナルUI

システム要件

コンポーネント	要件
Python	3.10以上
bun	OpenCodeサーバーに必須（npmは非対応）
GPU	CUDA推奨（CPU/MPSもサポートされますが遅い）
RAM	最低8GB、推奨16GB
オーディオ	マイクとスピーカー

インストール

ステップ1：bunのインストール（必須）

OpenCodeはbunのcatalog:プロトコルを使用するため、bunが必須です。

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Linux/macOS:

curl -fsSL https://bun.sh/install | bash

ステップ2：Python依存関係のインストール

cd VoiceCodeAssistant

# 方法1：requirements.txtを使用
pip install -r requirements.txt

# 方法2：編集可能インストール
pip install -e .

ステップ3：VibeVoiceのインストール

# VibeVoiceプロジェクトは同じ親ディレクトリにある必要があります
pip install -e ../VibeVoice

ステップ4：OpenCode依存関係のインストール

cd ../opencode
bun install

クイックスタート

方法1：ランチャースクリプトを使用（推奨）

ランチャースクリプトは自動的に：

• bunがなければインストール
• OpenCode依存関係をインストール
• OpenCodeサーバーを起動
• VoiceCode Assistantを起動

Windows (PowerShell):

.\run.ps1

Windows (CMD):

run.bat

Linux/macOS:

chmod +x run.sh
./run.sh

方法2：手動起動

1. OpenCodeサーバーを起動：

   cd opencode
   bun dev serve --port 4096

2. VoiceCode Assistantを起動：

   cd VoiceCodeAssistant
   python -m voice_code_assistant --no-auto-start

コマンドラインオプション

python -m voice_code_assistant [オプション]

オプション:
  --lang {ko-ko,ko-en,en-en}   言語モード（デフォルト：ko-ko）
                                ko-ko: 韓国語入力 → 韓国語出力
                                ko-en: 韓国語入力 → 英語出力
                                en-en: 英語入力 → 英語出力

  --opencode-url URL           OpenCodeサーバーURL（デフォルト：http://localhost:4096）
  --directory PATH             作業ディレクトリ
  --device {cuda,cpu,mps,auto} AIモデル実行デバイス（デフォルト：auto）
  --no-tui                     Rich TUIを無効化、シンプルなコンソール出力を使用
  --no-auto-start              OpenCodeサーバーの自動起動を無効化
  --asr-model PATH             ASRモデルパス（デフォルト：microsoft/VibeVoice-ASR）
  --tts-model PATH             TTSモデルパス（デフォルト：microsoft/VibeVoice-Realtime-0.5B）
  --log-level LEVEL            ログレベル（DEBUG, INFO, WARNING, ERROR）

キーボードショートカット（TUIモード）

キー	動作
Space	音声録音開始/停止
Tab	言語モードを循環
F	音声フィードバックモード切替（OFF → ON → DETAILED）
Q	アプリ終了
Ctrl+C	強制終了

音声コマンド

割り込みコマンド

AIが話している間にこれらを言うと割り込み：

コマンド	動作
"Stop", "Cancel", "止めて", "キャンセル"	現在のタスクをキャンセル
"Wait", "ちょっと待って"	一時停止して新しいコマンドを待機
"Change", "Modify", "変更", "修正"	現在のタスクを修正
"Continue", "Resume", "続けて"	中断したところから再開

使用例

# デフォルト実行（韓国語 → 韓国語、TUIモード）
python -m voice_code_assistant

# 英語モード
python -m voice_code_assistant --lang en-en

# CPU使用（GPUがない場合）
python -m voice_code_assistant --device cpu

# シンプルコンソールモード
python -m voice_code_assistant --no-tui

# 特定のディレクトリで作業
python -m voice_code_assistant --directory /path/to/project

トラブルシューティング

「bunが見つかりません」

bunをインストールしてターミナルを再起動：

# Windows
irm bun.sh/install.ps1 | iex

# Linux/macOS
curl -fsSL https://bun.sh/install | bash

「OpenCodeサーバーに接続できません」

1. サーバーが実行中か確認：

   curl http://localhost:4096/global/health

2. 手動でサーバーを起動：

   cd opencode && bun dev serve --port 4096

「CUDAメモリ不足」

CPUモードを使用：

python -m voice_code_assistant --device cpu

---

Español

Descripción General

VoiceCode Assistant es una herramienta de codificación interactiva controlada por voz que permite programar sin usar las manos. Integra VibeVoice (IA de voz de Microsoft) con OpenCode (agente de codificación IA) para proporcionar una experiencia fluida de voz a código.

Características Principales

• Codificación por Voz: Dicta tus instrucciones de codificación naturalmente
• Retroalimentación de Voz en Tiempo Real: Escucha actualizaciones de estado mientras la IA trabaja (escritura de archivos, ejecución de pruebas)
• Interrupción por Voz: Interrumpe a la IA mientras habla para modificar o cancelar tareas
• Iteración Continua de Tareas: Corrección automática de errores y reintento de pruebas hasta el éxito
• Soporte Multilingüe: Combinaciones de entrada/salida en coreano e inglés
• Interfaz Rich TUI: Hermosa interfaz de terminal con visualización de estado en tiempo real

Requisitos del Sistema

Componente	Requisito
Python	3.10 o superior
bun	Requerido para el servidor OpenCode (npm no soportado)
GPU	CUDA recomendado (CPU/MPS soportado pero más lento)
RAM	Mínimo 8GB, recomendado 16GB
Audio	Micrófono y altavoces

Instalación

Paso 1: Instalar bun (Requerido)

OpenCode usa el protocolo catalog: de bun, por lo que bun es obligatorio.

Windows (PowerShell):

irm bun.sh/install.ps1 | iex

Linux/macOS:

curl -fsSL https://bun.sh/install | bash

Paso 2: Instalar Dependencias de Python

cd VoiceCodeAssistant

# Opción 1: Usando requirements.txt
pip install -r requirements.txt

# Opción 2: Instalación editable
pip install -e .

Paso 3: Instalar VibeVoice

# El proyecto VibeVoice debe estar en el mismo directorio padre
pip install -e ../VibeVoice

Paso 4: Instalar Dependencias de OpenCode

cd ../opencode
bun install

Inicio Rápido

Método 1: Usando Scripts de Lanzamiento (Recomendado)

Los scripts de lanzamiento automáticamente:

• Instalan bun si no está presente
• Instalan dependencias de OpenCode
• Inician el servidor OpenCode
• Lanzan VoiceCode Assistant

Windows (PowerShell):

.\run.ps1

Windows (CMD):

run.bat

Linux/macOS:

chmod +x run.sh
./run.sh

Método 2: Inicio Manual

1. Iniciar Servidor OpenCode:

   cd opencode
   bun dev serve --port 4096

2. Lanzar VoiceCode Assistant:

   cd VoiceCodeAssistant
   python -m voice_code_assistant --no-auto-start

Opciones de Línea de Comandos

python -m voice_code_assistant [OPCIONES]

Opciones:
  --lang {ko-ko,ko-en,en-en}   Modo de idioma (predeterminado: ko-ko)
                                ko-ko: Entrada coreano → Salida coreano
                                ko-en: Entrada coreano → Salida inglés
                                en-en: Entrada inglés → Salida inglés

  --opencode-url URL           URL del servidor OpenCode (predeterminado: http://localhost:4096)
  --directory PATH             Directorio de trabajo
  --device {cuda,cpu,mps,auto} Dispositivo de ejecución del modelo IA (predeterminado: auto)
  --no-tui                     Deshabilitar Rich TUI, usar salida de consola simple
  --no-auto-start              No iniciar automáticamente el servidor OpenCode
  --asr-model PATH             Ruta del modelo ASR (predeterminado: microsoft/VibeVoice-ASR)
  --tts-model PATH             Ruta del modelo TTS (predeterminado: microsoft/VibeVoice-Realtime-0.5B)
  --log-level LEVEL            Nivel de registro (DEBUG, INFO, WARNING, ERROR)

Atajos de Teclado (Modo TUI)

Tecla	Acción
Space	Iniciar/detener grabación de voz
Tab	Ciclar entre modos de idioma
F	Alternar modo de retroalimentación de voz (OFF → ON → DETAILED)
Q	Salir de la aplicación
Ctrl+C	Forzar salida

Comandos de Voz

Comandos de Interrupción

Di estos mientras la IA habla para interrumpir:

Comando	Acción
"Stop", "Cancel", "Para", "Cancela"	Cancelar tarea actual
"Wait", "Espera"	Pausar y esperar nuevo comando
"Change", "Modify", "Cambia", "Modifica"	Modificar tarea actual
"Continue", "Resume", "Continúa"	Reanudar desde donde se detuvo

Ejemplos de Uso

# Ejecución predeterminada (Coreano → Coreano, modo TUI)
python -m voice_code_assistant

# Modo inglés
python -m voice_code_assistant --lang en-en

# Usar CPU (sin GPU)
python -m voice_code_assistant --device cpu

# Modo consola simple
python -m voice_code_assistant --no-tui

# Trabajar en directorio específico
python -m voice_code_assistant --directory /path/to/project

Solución de Problemas

"No se puede encontrar el ejecutable bun"

Instala bun y reinicia tu terminal:

# Windows
irm bun.sh/install.ps1 | iex

# Linux/macOS
curl -fsSL https://bun.sh/install | bash

"No se puede conectar al servidor OpenCode"

1. Verifica si el servidor está ejecutándose:

   curl http://localhost:4096/global/health

2. Inicia manualmente:

   cd opencode && bun dev serve --port 4096

"Memoria CUDA insuficiente"

Usa modo CPU:

python -m voice_code_assistant --device cpu

"Puerto 4096 ya en uso"

Termina el proceso existente:

# Windows
netstat -ano | findstr :4096
taskkill /PID <PID> /F

# Linux/macOS
lsof -i :4096
kill <PID>

---

License / 라이선스 / 许可证 / ライセンス / Licencia

This project integrates the following open-source projects:

• VibeVoice: Microsoft open-source speech AI
• OpenCode: Open-source AI coding agent

MIT License - See LICENSE for details.

---

Made with voice and AI

Report Bug · Request Feature