Whisper-Input-Next - Enhanced Voice Transcription Tool

An intelligent voice-to-text tool that turns your speech into text in any input box, anywhere on your system — Cursor, Claude Code, Codex, Gemini, your browser, Slack, Notes, you name it. It's not tied to any single app.

🌟 Why Whisper-Input-Next?

🖐️ True hands-free, press-once toggle — Tap Ctrl+F once and it just keeps listening. Switch windows, scroll through docs, grab something from another app, then come back — the recording never stops. No need to hold a key down the whole time (like Typeless does), so both your hands stay free and your workflow is never interrupted.
🌍 Works everywhere — It types straight at your cursor in any app or input field, not just one editor. Code in Cursor / Claude Code / Codex, chat with Gemini, write an email — same hotkey, every box.
🕰️ Audio Archive = a time machine for your voice — Every recording is saved locally, forever. Open it a year from now and literally hear what you were building last June. It's your own spoken history, kept private on your own disk — there's something almost magical about traveling back to hear your past self.
💸 No middleman, ever — You pay the source vendors' APIs directly (Doubao / OpenAI), at cost. Top up a few bucks and it lasts for months. We take $0 — no subscription, no markup, nobody skimming in the middle.
🎯 Two-pass recognition — During speech pauses a higher-accuracy non-streaming model re-recognizes each sentence, noticeably improving quality (e.g. "广告位" → "光标位置").
🔌 Your choice of engine — Doubao Streaming ASR (default, super cheap), OpenAI GPT-4o transcribe, or fully offline local whisper.cpp.

🐧 Linux users: Linux desktop support lives on the linux branch, kindly contributed and maintained by @MiaoDX — many thanks! I'm on macOS and don't personally test/maintain the branch, so it may lag behind main. Track or contribute there.

💰 Why Pay $12/Month? Use Open Source Instead!

Typeless charges $12/month for their voice keyboard, but you know what? This open-source project does the same thing for FREE - you only pay for the underlying API costs (Doubao ASR or OpenAI GPT-4o transcribe), which is incredibly cheap compared to Typeless's subscription.

Typeless: $144/year subscription, press-and-hold to talk (ties up a hand, awkward to switch windows mid-sentence), and you don't own the service
Whisper-Input-Next: $0 + only pay for what you use (Doubao streaming ASR is super cheap!), press-once hands-free toggle, works in every app system-wide, and all your audio stays archived on your own machine

Stop renting your tools. Own them.

🚀 Project Background

This project is based on ErlichLiu/Whisper-Input for secondary development. The original project has been inactive for months, so we have made extensive feature expansions and architectural optimizations, adding important features like OpenAI GPT-4o transcribe integration, audio archiving, local whisper support, and more. Why use this project?

✨ Key Features

🔥 NEW in v3.3.0: Two-Pass Recognition & Accuracy Boost

Two-Pass Recognition: Enables enable_nonstream for sentence-level re-recognition using the higher-accuracy nostream model during speech pauses, significantly improving transcription quality
Deferred Text Output: All text stays in floating preview during recording; final text is pasted only after recording stops, allowing full ASR context optimization
DJI Wireless Mic Support: Auto-detects and prioritizes DJI Wireless Microphone as input device

Doubao Streaming ASR (since v3.2.0)

Real-time Streaming Transcription: Powered by ByteDance's Doubao Seed ASR 2.0, transcription appears as you speak
Floating Preview Window: Shows pending text in real-time near your input field, like an IME
Now Default for Ctrl+F: The best voice input experience, set as default (configurable)
👉 How to get your API keys

🎯 Core Functions

Multi-platform Transcription Services: Doubao Streaming ASR (default), OpenAI GPT-4o transcribe, local whisper.cpp
Smart Hotkeys: Ctrl+F (Doubao streaming, default) / Ctrl+I (local cost-saving mode)
Audio Archive: Automatically save all recordings, support history playback
Failure Retry: Intelligent error handling and retry mechanism

🔧 Technical Features

Dual Processor Architecture: Streaming + Batch processors working simultaneously
180s Long Audio Support: Support up to 3 minutes of continuous recording
Smart Status Indicators: Simple numeric status display (0, 1, !)
Cache System: Audio archive with transcription result caching
Cursor-safe hotkeys (macOS): The recording hotkey is intercepted at the Quartz event-tap layer so toggling never nudges your text caret (Ctrl+F/Ctrl+I no longer trigger the built-in forward-char/Tab), enabling precise mid-text insertion — adapts automatically to whatever hotkey you configure. Details

🌟 User Experience

No Clipboard Pollution: Clean status display without interfering with system clipboard
One-click Retry: Failed transcriptions can be retried without re-recording
Real-time Input: Transcription results appear directly at cursor position
Privacy Protection: Local processing option, data not uploaded

📦 Quick Start

Environment Requirements

Python 3.12+
macOS/Linux (Windows support in development)
Network connection (only required for cloud services)
Local whisper.cpp (required when using local transcription features)

Installation Steps

Clone Project

git clone https://github.com/Mor-Li/Whisper-Input-Next.git
cd Whisper-Input-Next

Create Virtual Environment

python -m .venv .venv
source .venv/bin/activate  # macOS/Linux
# or .venv\\Scripts\\activate  # Windows

Install Dependencies

pip install -r requirements.txt

Install Local whisper.cpp (Optional, required for local transcription)

# Clone whisper.cpp repository
git clone https://github.com/ggerganov/whisper.cpp.git
cd whisper.cpp

# Compile (macOS/Linux)
make

# Download model file (recommend large-v3)
bash ./models/download-ggml-model.sh large-v3

# Record whisper-cli path for later configuration in .env file
echo "Whisper CLI Path: $(pwd)/build/bin/whisper-cli"
cd ..

Configure Environment Variables

cp env.example .env
# Edit .env file, configure necessary parameters:
# - OFFICIAL_OPENAI_API_KEY: OpenAI API key (required)
# - WHISPER_CLI_PATH: whisper.cpp executable path (required for local transcription)
# - WHISPER_MODEL_PATH: whisper model file path (required for local transcription)

Run Program

python main.py
# or use startup script
chmod +x start.sh
./start.sh

⚠️ Important Notes

Required Configuration:

OFFICIAL_OPENAI_API_KEY: OpenAI GPT-4o transcribe API key
WHISPER_CLI_PATH: Local whisper.cpp executable absolute path
WHISPER_MODEL_PATH: whisper model file path (relative to whisper.cpp root directory)

whisper.cpp Installation Guide:

Clone and compile from whisper.cpp repository
Download large-v3 model: bash ./models/download-ggml-model.sh large-v3
Configure correct paths in .env

⚙️ Configuration Guide

Environment Variable Configuration

Configure the following parameters in the .env file:

# ============ Doubao Streaming ASR (Recommended, Default) ============
# Get your API keys from Volcengine Console (see screenshot below)
DOUBAO_APP_KEY=your_app_id_here        # APP ID from console
DOUBAO_ACCESS_KEY=your_access_token_here  # Access Token from console

# Transcription service selection: "doubao" (default, streaming) or "openai" (batch)
TRANSCRIPTION_SERVICE=doubao

# ============ OpenAI Configuration (Optional, for batch mode) ============
OFFICIAL_OPENAI_API_KEY=sk-proj-xxx

# ============ Local whisper.cpp (Optional, for Ctrl+I) ============
WHISPER_CLI_PATH=/path/to/whisper.cpp/build/bin/whisper-cli
WHISPER_MODEL_PATH=models/ggml-large-v3.bin

# ============ Keyboard & System Configuration ============
TRANSCRIPTIONS_BUTTON=f
TRANSLATIONS_BUTTON=ctrl
SYSTEM_PLATFORM=mac  # mac/win

# Feature switches
CONVERT_TO_SIMPLIFIED=false
ADD_SYMBOL=false
OPTIMIZE_RESULT=false

How to get Doubao API keys:

Go to Volcengine Console - Speech Recognition
Find your APP ID and Access Token in the "服务接口认证信息" section (see screenshot below)

Important Notes:

Doubao Streaming ASR is now the default and recommended transcription service
Set TRANSCRIPTION_SERVICE=openai to use OpenAI batch mode instead

🐛 Troubleshooting (Common Pitfalls)

Doubao streaming ASR fails with `403` on connect

If recording starts but you immediately see something like:

ERROR - 连接豆包 ASR 失败: 403, message='Invalid response status', url='wss://openspeech.bytedance.com/api/v3/sauc/bigmodel_async'
ERROR - ❌ Doubao streaming error: connection failed

This is almost always a missing capability on your Volcengine app, NOT a bug in the code or a wrong endpoint. The 403 is returned during the WebSocket handshake (at the gateway, before authentication), which is the tell-tale sign that the X-Api-Resource-Id your key requests is not enabled for your app.

This project uses the resource id volc.seedasr.sauc.duration, which maps to 豆包流式语音识别模型 2.0 · 小时版 (Doubao Streaming Speech Recognition Model 2.0 · Hourly). You must explicitly enable that exact capability:

Open the Volcengine console: https://console.volcengine.com/speech/app
Find your app and click 编辑应用 (Edit Application).
Under 接入能力 (Access Capabilities), locate 豆包流式语音识别模型 2.0 and check 豆包流式语音识别模型 2.0 小时版 (the box highlighted below).
Save, then run the program again.

Note: Do NOT "fix" this by downgrading the resource id to the older volc.bigasr.sauc.* namespace. The volc.seedasr.sauc.duration (2.0) endpoint is correct — the fix is enabling 2.0 on the console, not changing the code. Enabling 1.0 only masks the real permission problem and gives you a lower-accuracy model.

Quick Start with Aliases (Recommended)

Add these aliases to your shell profile (~/.bashrc, ~/.zshrc, etc.):

alias whisper_input='cd /path/to/Whisper-Input-Next && ./start.sh'
alias whisper_input_off='tmux kill-session -t whisper-input'

Replace /path/to/Whisper-Input-Next with your actual project path.

Hotkey Instructions

Hotkey	Function	Service	Features
`Ctrl+F`	Real-time streaming transcription	Doubao Seed ASR 2.0 (default)	Ultra-low latency, floating preview, text appears as you speak
`Ctrl+I`	Local transcription	whisper.cpp	Offline processing, privacy protection

Note: Set TRANSCRIPTION_SERVICE=openai in .env to use OpenAI GPT-4o transcribe instead of Doubao for Ctrl+F.

Status Indicators

The program displays concise status indicators at the cursor position during runtime:

Status	Meaning	Action
`0`	Recording	Press hotkey again to stop recording
`1`	Transcribing	Please wait for transcription to complete
`!`	Transcription failed/error	Press `Ctrl+F` again to retry (audio saved)

Design Optimizations:

Use concise numeric status, avoid complex emoji symbols
No system clipboard pollution, display only at cursor position
Clear and intuitive status, easy to quickly identify

Retry Mechanism Instructions:

When transcription fails, the system saves the recording and displays ! status
No need to re-record, simply press Ctrl+F to retry
Retry uses previously saved audio until transcription succeeds

📚 Feature Documentation

Features

🔊 Audio Archive & Transcription Cache - v3.0.0, hardened in v3.3.1
🛡️ Transcription Cache Data Safety - v3.3.1 — why the cache can no longer wipe itself, and how to rescue it if it ever does
⚡ Async Transcription Queue - v3.2.0
🔔 Audio Device Disconnect Notification
🖥️ macOS Status Bar Indicator - v3.3.0
📊 Status Display Improvements - v3.0.0

macOS hotkey pitfalls

🖱️ Cursor Drift Fix — why Ctrl+F/Ctrl+I no longer nudge your caret
🔧 Dead Event-Tap Self-Heal - v3.3.1 — read this first when hotkeys suddenly stop responding

Project background

🔄 Branch Differences vs Upstream - v3.0.0
📋 Version Control Documentation - v3.1.0
📝 Release Notes v3.1.0
✍️ Why This Project (Chinese blog post)

Deprecated

🛠️ Development Status

✅ Completed Features

🚧 In Development

No features currently in development

📋 Planned Features

No features currently planned

🧪 Experimental Features History

iOS Keyboard Extension Experiment (August 14, 2025)

Status: ❌ Discontinued due to Apple's restrictions
Attempted to create iOS keyboard extension but discovered that even Sogou Input Method cannot directly record audio in keyboard extensions due to Apple's system limitations. iOS voice input is currently not feasible as a seamless keyboard extension.

🤝 Contributing Guidelines

We welcome all forms of contributions! Whether it's:

🐛 Bug Reports: Found an issue? Create an Issue
💡 Feature Suggestions: Have great ideas? Start a Discussion
📝 Code Contributions: Submit Pull Requests
📚 Documentation Improvements: Help improve documentation
🌍 Translations: Help translate to more languages

Development Environment Setup

# Clone repository
git clone https://github.com/Mor-Li/Whisper-Input-Next.git
cd Whisper-Input-Next

# Create development environment
python -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start development
python main.py

🙏 Acknowledgments

Thanks to ErlichLiu/Whisper-Input for the original project foundation
Thanks to ByteDance/Volcengine for the excellent Doubao Seed ASR 2.0 streaming API
Thanks to OpenAI for providing excellent transcription API services
Thanks to whisper.cpp community for local processing support
Thanks to all contributors and users for their support

📞 Contact Information

Project Address: https://github.com/Mor-Li/Whisper-Input-Next
Issue Reports: Issues
Feature Suggestions: Discussions

📋 Changelog

v3.3.0 (2026-03-11)

Two-pass recognition: Enable enable_nonstream for sentence-level re-recognition with nostream model, significantly improving accuracy (e.g. "广告位" → "光标位置")
Deferred text output: All text stays in floating preview during recording; final text pasted only after stop, allowing full ASR context optimization
DJI Wireless Mic support: Auto-detect and prioritize DJI Wireless Microphone as highest priority input device
Lower latency: Reduce streaming chunk size from 200ms to 100ms
Faster streaming: Remove artificial delays in audio packet sending

v3.2.0 (2025-07-27)

Doubao Streaming ASR: Real-time streaming transcription powered by ByteDance Seed ASR 2.0
Floating preview window: Shows pending text in real-time near input field
Auto audio device switching: Priority-based microphone selection

v3.0.0

OpenAI GPT-4o transcribe integration
Audio archive system
Local whisper.cpp support
Dual processor architecture

⭐ If this project helps you, please give it a Star for support!

Name		Name	Last commit message	Last commit date
Latest commit History 149 Commits
assets		assets
docs		docs
src		src
test		test
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
control_ui.py		control_ui.py
env.example		env.example
main.py		main.py
requirements.txt		requirements.txt
start.sh		start.sh

Folders and files

Latest commit

History

Repository files navigation