QuQu (蛐蛐)

The recommended way to initialize the project is using uv, a modern Python package manager that automatically manages Python versions and dependencies to avoid environment conflicts.

Prerequisites

• Node.js 18+ and pnpm
• macOS 10.15+, Windows 10+, or Linux

Installation Steps

1. Clone the repository and enter the directory.
2. Install Node.js dependencies using pnpm.
3. Install uv if you haven't already.
4. Use uv sync to initialize the Python environment (this will automatically download Python 3.11 and all required dependencies).
5. Download the FunASR models.
6. Start the application.

Note: uv handles the Python environment isolation for you.

# 1. 克隆项目
git clone https://github.com/yan5xu/ququ.git
cd ququ

# 2. 安装 Node.js 依赖
pnpm install

# 3. 安装 uv (如果尚未安装)
# macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows:
# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# 4. 初始化 Python 环境 (uv 会自动下载 Python 3.11 和所有依赖)
uv sync

# 5. 下载 FunASR 模型
uv run python download_models.py

# 6. 启动应用!
pnpm run dev

If you prefer using your existing system Python environment, follow these steps:

Prerequisites

• Node.js 18+ and pnpm
• Python 3.8+

Installation Steps

1. Clone the repository and enter the directory.
2. Install Node.js dependencies using pnpm.
3. Create and activate a virtual environment (recommended).
4. Install the required Python packages: funasr, modelscope, torch, torchaudio, librosa, and numpy.
5. Download the FunASR models.
6. Start the application.

Note: Manual installation requires you to manage the virtual environment and dependencies yourself.

# 1. 克隆项目
git clone https://github.com/yan5xu/ququ.git
cd ququ

# 2. 安装 Node.js 依赖
pnpm install

# 3. 创建虚拟环境 (推荐)
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate   # Windows

# 4. 安装 Python 依赖
pip install funasr modelscope torch torchaudio librosa numpy

# 5. 下载 FunASR 模型
python download_models.py

# 6. 启动应用!
pnpm run dev

The application uses an initializeApp function to configure the runtime environment. Key behaviors include:

• Electron Integration: Checks for window.electronAPI to determine if it is running in an Electron environment. If present, errors are logged via window.electronAPI.log('error', ...).
• Global Error Handling: Sets up listeners for error and unhandledrejection events to capture and log errors (to Electron or the console).
• UI/UX Defaults:
  • Sets the document language to zh-CN.
  • Disables default drag-and-drop behaviors (dragover, drop).
  • In production, disables the context menu (contextmenu).
• Theme Management: Detects and listens to system color scheme changes (prefers-color-scheme: dark) to toggle the .dark class on document.documentElement.
• Development Tools: In development mode, it enables Hot Module Replacement (HMR) for App.jsx and starts performance/memory monitoring (logging performance measures and heap usage every 30 seconds).

The application follows a specific initialization sequence in main.js to ensure all dependencies are ready before the UI is presented:

1. Environment Setup: The setupProductionPath() function runs first to ensure Python and other critical binaries are in the system PATH for production builds (macOS/Windows).
2. Logging & Error Handling: A LogManager is initialized, and global handlers for uncaughtException and unhandledRejection are attached to capture errors.
3. Manager Instantiation: Core managers (EnvironmentManager, WindowManager, DatabaseManager, etc.) are instantiated.
4. Database Initialization: The databaseManager is initialized using a directory provided by the environmentManager.
5. IPC Setup: IPCHandlers are initialized, receiving all manager instances to facilitate communication between the main process and renderer processes.
6. App Startup (startApp):
   • Initializes funasrManager (non-blocking).
   • Creates the Main Window and Control Panel Window via windowManager.
   • Sets up the System Tray via trayManager.

This sequence ensures that when the windows are created, the underlying services (database, clipboard, speech recognition) are already operational.

When stopRecording is called, the hook executes a multi-stage pipeline:

1. Audio Capture: The MediaRecorder collects audio chunks (WebM/Opus).
2. Format Conversion: The WebM Blob is converted to a WAV format (16000Hz, mono) using an AudioContext and a custom audioBufferToWav utility.
3. Transcription: The WAV data is sent to the backend via window.electronAPI.transcribeAudio.
4. Immediate UI Update: If window.onTranscriptionComplete is defined, the raw transcription is sent to the UI immediately.
5. AI Optimization (Optional): If the enable_ai_optimization setting is true, the hook calls window.electronAPI.processText(raw_text, 'optimize') to refine the text.
6. Persistence: The final transcription (either raw or optimized) is saved via window.electronAPI.saveTranscription.
7. Final UI Update: If window.onAIOptimizationComplete is defined, the final enhanced result is sent to the UI.

Note: This hook relies on the presence of window.electronAPI for backend communication. In a standard web environment, it falls back to mock results.