# 桌面字幕系統 (Desktop Subtitle HUD)

這是一個為實況主、視訊會議、錄影教學設計的即時桌面字幕工具。它使用瀏覽器原生的 **Web Speech API** 做語音辨識，再透過本機 Electron API Bridge 把結果投射到透明桌面 HUD。

適合需要「不用 Whisper、不吃 GPU、啟動就能上字幕」的場景。

## 畫面展示

示範影片：[`snapshot/live_sub.mp4`](snapshot/live_sub.mp4)

### 啟動與語音辨識控制

![語音辨識控制畫面](snapshot/readme-live-sub-01-launch.jpg)

### 透明字幕疊在桌面上

![透明桌面字幕](snapshot/readme-live-sub-02-overlay.jpg)

### 字幕設定與即時預覽

![字幕設定與預覽](snapshot/readme-live-sub-03-settings.jpg)

### 長句字幕顯示效果

![長句字幕顯示](snapshot/readme-live-sub-04-longline.jpg)

## 特色功能

- **快速辨識**：使用 Chrome / Edge 的 Web Speech API，不需要安裝大型 AI 模型。
- **透明桌面 HUD**：字幕直接浮在桌面上，可用於直播、會議或錄影教學。
- **自訂樣式**：可調整字體大小、字色、背景色、透明度與字型，並支援預設風格。
- **狀態提示**：字幕視窗會顯示啟動中、正在聽取、停止等狀態。
- **全域快捷鍵**：`Shift + F2` 快速切換啟動 / 關閉。
- **拖曳定位**：按住 `Alt` 進入移動模式，可拖動字幕與設定視窗。
- **輕量化**：移除 ffmpeg / Whisper 依賴，大幅降低 CPU、記憶體與部署成本。

## 快速開始

### 1. 進入 Electron 專案

```bash
cd nodejs_project
```

### 2. 安裝依賴

```bash
npm install
```

### 3. 啟動程式

```bash
npm start
```

或直接執行：

```bash
run.bat
```

### 4. 開始辨識

1. 程式啟動後會自動開啟 Chrome 或 Edge 的語音辨識頁。
2. 在網頁中點擊 **「開始語音辨識」** 並授權麥克風。
3. 回到桌面或任意視窗，按 `Shift + F2` 啟動字幕 HUD。

## 快捷鍵

- **Shift + F2**：切換字幕顯示與語音服務狀態。
- **按住 Alt**：進入移動模式，可拖曳字幕視窗或設定視窗。

## 技術架構

```text
Chrome / Edge Web Speech API
        ↓
http://127.0.0.1:{80|443|5999}/subtitle
        ↓
Electron Local API Bridge
        ↓
Transparent Desktop Subtitle HUD
```

- **Frontend**：Electron、HTML5、CSS3、Vanilla JavaScript。
- **Recognition**：Web Speech API，主要依賴 Chrome / Edge backend。
- **Communication**：Local HTTP API Bridge，CORS enabled。
- **Keyboard Hook**：`uiohook-napi`，用於全域快捷鍵與 Alt 移動模式。
- **Settings**：`electron-store` 保存字幕樣式、位置與偏好。

## 專案結構

```text
.
├─ nodejs_project/        # Electron 主程式，目前主要版本
│  ├─ main.js             # Electron 視窗、API server、快捷鍵
│  ├─ voice.html          # 瀏覽器語音辨識頁
│  ├─ subtitle.html/js/css  # 透明字幕 HUD
│  ├─ settings.html/js    # 字幕樣式設定
│  └─ package.json
├─ C#_project/            # 早期/備用 C# 專案
└─ snapshot/              # README 展示圖與示範影片
```

## 打包

若要重新編譯 native hook：

```bash
npm run rebuild
```

產生 portable 版本：

```bash
npm run dist
```

## 常見問題

- **瀏覽器沒有開始聽取**：確認 Chrome / Edge 已開啟、麥克風授權已允許。
- **`Shift + F2` 沒反應**：檢查是否有其他軟體佔用快捷鍵，或 `uiohook-napi` 是否需要 rebuild。
- **API server port 被佔用**：程式會依序嘗試 `80 → 443 → 5999`。
- **辨識品質不穩**：Web Speech API 品質會受麥克風、環境噪音、網路與瀏覽器服務影響。

## 可補強項目

- **README 加 GIF 或短 mp4 預覽**：目前已附示範影片與截圖，之後可以補一張短 GIF，讓 GitHub 頁面不用點影片也能看懂動態效果。
- **設定說明再細化**：可以補一張「各 preset 差異」表，說明 Cyberpunk、Classic Dark、Modern Light、Anime Style 適合的情境。
- **Release 操作文件**：可補 `npm run dist` 後產物位置、檔名規則與發版 checklist。
- **權限檢查頁**：可以在語音辨識頁加入麥克風權限、瀏覽器支援度、API Bridge 狀態檢查。
- **快捷鍵可自訂**：目前固定 `Shift + F2`，後續可做成設定項，避免和其他軟體衝突。
- **字幕輸出紀錄**：可選擇保存字幕文字或輸出 SRT / TXT，方便會議紀錄與教學影片後製。

## 作者

**羽山秋人 (Akira Hayama)**

- Website: [https://3wa.tw](https://3wa.tw)

## 版本

V0.0.1 (Stable Beta)