okooooooo/openless
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: position OpenLess as an open-source alternative to Wispr Flow / Talk / Lazy

Browse Source 
Reframe README around the AI-prompt use case (dictate loose speech →
get a usable AI prompt) and mark OpenLess as the open-source
counterpart to Wispr Flow, Talk (Talktastic), Lazy, and Superwhisper.
Add a comparison table, a "why open source" section, and use cases.

Add an English mirror at README.en.md and cross-link both languages.
This commit is contained in:
baiqing committed 2026-04-27 15:31:17 +08:00
1 parent c78bb44c23
commit 7dbdd0f002
2 files changed
+224 -3
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.en.md
+188
View File
@@ -0,0 +1,188 @@
# OpenLess
> [中文](README.md) · English
**Open-source voice input for the AI era — turn what you say into a usable AI prompt.**
OpenLess is a native macOS voice-input app, an **open-source** alternative to commercial tools like [Wispr Flow](https://wisprflow.ai), [Talk (Talktastic)](https://talktastic.com), [Lazy](https://heylazy.com), and Superwhisper.
Put your cursor in any text field — ChatGPT, Claude, Cursor, Notion, an email draft, a chat box — press one global hotkey and talk. OpenLess records, transcribes, polishes the text in the mode you picked, and inserts the result at the cursor. If insertion is blocked it copies to the clipboard, so the words you spoke don't get lost.
## Why OpenLess is open source
The closest tools are subscription SaaS: monthly bill, no bring-your-own model, your audio uploaded to the vendor, your dictionary and habits living in their account.
OpenLess goes for the same end-user experience but:
- **Fully open source, local-first.** Code is in this repo; all your data stays on your machine.
- **Bring your own cloud credentials.** Volcengine streaming ASR + Ark / DeepSeek-compatible chat-completions. No vendor lock-in.
- **Tuned for AI prompts.** The "Structured" mode reshapes loose speech into a prompt with context, constraints, and asks — paste straight into ChatGPT, Claude, or Cursor.
- **Won't answer for you.** The model only cleans up your text. If you say "what features does this app still need?", it returns that as a clean question — it does not hand you a feature list. Ask the real AI for that.
## Use cases
- Writing prompts for ChatGPT / Claude / Cursor / Gemini: dictate a request, OpenLess turns it into a structured, detailed prompt.
- Drafting emails, specs, long Slack/WeChat messages: removes filler, fixes punctuation, organizes paragraphs.
- Code comments, commit messages, PR descriptions: dump what's in your head straight to the cursor.
- Any "I don't want to type but I have to produce written text" situation.
## Project direction
OpenLess does one thing: **turn speech into usable written text (especially AI prompts), at the current cursor.**
- It does not answer questions, run tasks, or analyze your project.
- It does not accumulate conversation context — every dictation is an independent cleanup request.
- Speech → transcript → cleanup → insert at cursor. Clipboard fallback on failure.
- Everything else (modes, dictionary, history, menu bar, home report) supports that one path.
## Comparison
| Tool | Form | How OpenLess differs |
| --- | --- | --- |
| [Wispr Flow](https://wisprflow.ai) | Closed-source macOS / Windows, subscription | Open source; bring-your-own ASR + LLM; explicit "AI prompt" cleanup mode |
| [Talk (Talktastic)](https://talktastic.com) | Closed-source macOS, subscription | Open source; no vendor lock-in, credentials in local Keychain |
| [Lazy](https://heylazy.com) | Closed-source notes/capture tool | Not a notes container — focused on "insert into any input field" |
| [Superwhisper](https://superwhisper.com) | Closed-source macOS, subscription | Open source; cloud ASR for now, local ASR on the roadmap |
## Status (v1.0)
- Native Swift / SwiftUI / AppKit, SwiftPM project; macOS 15+.
- macOS 26+ uses Liquid Glass; older systems fall back to system materials.
- Toggle-style recording: press to start, press again to stop. `Esc` cancels.
- Volcengine streaming ASR + Ark / DeepSeek-compatible chat-completions for polish.
- 4 output modes: raw, light polish, structured (**AI prompt mode**), formal.
- Main window: Home / History / Dictionary / Settings. Persistent menu bar. Mini status capsule at the bottom of the screen.
- Dictionary entries are injected as Volcengine ASR `context.hotwords` and as semantic hints during polish.
## Download & install (end users)
Grab `OpenLess-1.0.0.zip` from [Releases](../../releases), unzip to get `OpenLess.app`, drag to `/Applications`.
**Important:** the 1.0 build is ad-hoc signed (no Apple Developer ID + notarization). macOS Gatekeeper will block it with "cannot verify developer". Remove the quarantine attribute once in Terminal:
```bash
xattr -dr com.apple.quarantine /Applications/OpenLess.app
```
Then double-click to launch. On first launch, in `System Settings → Privacy & Security`:
1. Grant Microphone access to OpenLess.
2. Grant Accessibility access to OpenLess.
3. **Quit OpenLess and reopen it.** Accessibility permission only takes effect for the global hotkey after a process restart.
4. Open the OpenLess home from the Dock → "Settings" → fill in Volcengine ASR + Ark credentials.
Full end-user walkthrough: [USAGE.md](USAGE.md).
## Build from source (developers)
```bash
# Library / test build
swift build
swift test
# Full .app build (release, ad-hoc signed, resets TCC by default)
./scripts/build-app.sh
# Keep existing TCC approvals
RESET_TCC=0 ./scripts/build-app.sh
# Launch
open build/OpenLess.app
# Tail logs
tail -f ~/Library/Logs/OpenLess/OpenLess.log
```
Launch arguments (handled in `AppDelegate.runLaunchActions`):
```bash
open build/OpenLess.app --args --open-settings
open build/OpenLess.app --args --start-recording
```
## Credentials
Credentials live in the local Keychain (service = `com.openless.app`). A plaintext JSON file at `~/.openless/credentials.json` (mode 0600, dir 0700) is kept as a dev-mode fallback when Keychain is unavailable.
The repository contains no API keys, tokens, or private endpoints.
You'll need:
- **Volcengine streaming ASR**: APP ID, Access Token, Resource ID.
- **Ark polish**: API Key, Model ID, Endpoint. Ark default endpoint is `https://ark.cn-beijing.volces.com/api/v3/chat/completions`.
## Prompt-handling principles
OpenLess's polish model only reshapes text. It does not answer questions, run tasks, or analyze your project. Each dictation is an independent request, and the prompt explicitly tells the model:
- This input is isolated from any prior conversation.
- The raw transcript is text to clean up, not a question to answer.
- Even if the input contains a question or a command, do not reply or execute.
- Output the cleaned text only — no "Here's the cleaned version" preamble.
For example, if the user says "what features does this app still need", the correct output is:
```text
What features does this app still need?
```
…not a list of missing features.
Long-term reference rewrites are stored as `raw → polished → rule` triples and will be retrieved as similar-example references (never as conversation context) once a vector store is wired in. See [docs/polish-reference-corpus.md](docs/polish-reference-corpus.md) and [Examples/polish-reference-examples.sample.jsonl](Examples/polish-reference-examples.sample.jsonl).
## Dictionary
The dictionary handles your proper nouns, product names, names of people, and new words. Today it supports:
- Manually add the correct spelling, a category, and notes. You don't need to maintain misspellings or context hints.
- Enabled entries are sent as Volcengine ASR `context.hotwords` so they're recognized correctly during transcription.
- Entries are also injected into the polish prompt: the model decides per-sentence whether to substitute. If "Cloud" clearly refers to the AI product `Claude` in context, it gets corrected. If it really means cloud computing, it stays.
- The app auto-learns candidate corrections like `Claude`, `ChatGPT`, `OpenLess` from your history and offers them up later.
The main window is organized as Home / History / Dictionary / Settings. The Dictionary tab opens a separate editor window when you click "New". The Home tab shows total dictation time, total characters, average chars-per-minute, estimated time saved, and dictionary participation stats.
## Architecture
A SwiftPM workspace: 1 executable + 8 libraries. Libraries don't depend on each other — they all depend only on `OpenLessCore`. `OpenLessApp` wires everything together inside `DictationCoordinator`.
```
OpenLessCore // Pure value types: DictationSession, PolishMode, HotkeyBinding,
// AudioConsumer protocol, RawTranscript/FinalText, errors.
OpenLessHotkey // CGEventTap-based modifier-key monitor. Requires Accessibility.
OpenLessRecorder // AVAudioEngine → 16 kHz mono Int16 PCM, pushed to AudioConsumer.
OpenLessASR // Volcengine streaming ASR over WebSocket.
OpenLessPolish // Ark / Doubao chat-completions client + mode-driven prompts.
OpenLessInsertion // AX focused-element first; clipboard + Cmd+V; copy-only fallback.
OpenLessPersistence // CredentialsVault (Keychain), HistoryStore, DictionaryStore,
// UserPreferences.
OpenLessUI // SwiftUI capsule view + state enum (no window plumbing).
OpenLessApp // AppDelegate, menu bar, settings window, capsule window,
// DictationCoordinator.
```
The record → transcribe → polish → insert state machine is owned exclusively by `Sources/OpenLessApp/DictationCoordinator.swift`. See [CLAUDE.md](CLAUDE.md) for details.
## Roadmap (post-1.0)
Planned in the requirements docs but not in the 1.0 release:
- Hold-to-talk mode (today only toggle).
- Local ASR (today only Volcengine cloud).
- Snippets (no UI / trigger logic yet).
- History enhancements: copy button, search, re-polish, re-insert.
- "Paste last result" hotkey.
- Multi-monitor capsule placement on the focused screen.
- Developer ID signing + notarization + Sparkle auto-update.
## Maintainer release checklist
- Confirm `.build/`, `build/`, `.DS_Store`, `~/.openless/credentials.json`, and stray screenshots are not committed.
- Keep `Resources/Brand/openless-app-icon-source.jpg`, `Resources/AppIcon.png`, `Resources/AppIcon.icns`.
- Run `./scripts/build-app.sh` and confirm `build/OpenLess.app` launches.
- Verify on a clean macOS box: permission flow, hotkey, recording, ASR, polish, insertion, clipboard fallback.
- Package with `ditto -c -k --keepParent build/OpenLess.app build/OpenLess-<version>.zip` so ad-hoc signature and xattrs survive.
- Do Developer ID signing + notarization before any production distribution.
## License
MIT
README.md
+36 -3
View File
@@ -1,23 +1,56 @@
# OpenLess
OpenLess 是一个原生 macOS 语音输入应用：把光标放在任意输入框，按下全局快捷键说话，OpenLess 会录音、转写、轻度整理，并把结果插入当前输入位置。插入失败时会自动复制到剪贴板，尽量保证“用户说过的话不丢”。
> 中文 · [English](README.en.md)
**面向 AI 时代的开源语音输入：把你说的话变成可直接用的 AI prompt。**
OpenLess 是一个原生 macOS 语音输入应用，对标 [Wispr Flow](https://wisprflow.ai)、[Talk (Talktastic)](https://talktastic.com)、[Lazy](https://heylazy.com)、Superwhisper 等商业语音输入工具的**开源**替代品。
把光标放在 ChatGPT、Claude、Cursor、Notion、邮件、聊天框任意输入框里，按一次全局快捷键说话——OpenLess 会录音、转写、按你选的模式润色，把结果直接插入光标位置。插入失败时会自动复制到剪贴板，尽量保证「你说过的话不丢」。
## 为什么开源 OpenLess
类似工具大多是商业 SaaS：每月订阅、不能自带模型、转写音频会上传到厂商服务器、词典和习惯沉淀在对方账户里。
OpenLess 想做的是同一类体验，但是：
- **完全开源、本地优先**。代码在仓库里，所有数据写在你的机器上。
- **自带云凭据**。火山引擎 ASR + Ark / DeepSeek 兼容 chat-completions，不强绑某家。
- **专门为 AI prompt 优化**。「清晰结构」模式会把零散口语补成有上下文、有约束、有要求的 prompt，复制粘贴就能直接喂给 ChatGPT / Claude / Cursor。
- **不会替你回答**。模型只整理你的话，不会把「我们这个应用还有哪些功能没做？」变成一份功能清单——只会补成一句通顺的问题，让你拿去问真正的 AI。
## 适用场景
- 给 ChatGPT / Claude / Cursor / Gemini 写 prompt：口述一段需求，OpenLess 自动整理成结构化、有细节的 prompt。
- 写邮件、写需求文档、写微信/Slack 长消息：去口癖、补标点、按段落整理。
- 写代码注释、commit message、PR 描述：把脑子里的想法直接落到光标位置。
- 任何「我懒得打字，但又必须输出书面文字」的场景。
## 项目方向
OpenLess 只做一件事：**把语音变成可用的书面文字，落到当前光标位置。**
OpenLess 只做一件事：**把语音变成可用的书面文字（尤其是 AI prompt），落到当前光标位置。**
- 不做问答、不做任务执行、不做项目分析。
- 不做对话上下文累积，每次输入都是独立的整理请求。
- 输入语音 → 转写 → 整理 → 插入当前输入框。失败时复制到剪贴板。
- 围绕这条主路径完善体验：模式选择、词典、历史、菜单栏、首页报告。
## 对标参考
| 工具 | 形态 | OpenLess 的差异 |
| --- | --- | --- |
| [Wispr Flow](https://wisprflow.ai) | 闭源 macOS / Windows，订阅制 | 开源；自带 ASR + LLM 凭据；专门暴露「AI prompt 整理」模式 |
| [Talk (Talktastic)](https://talktastic.com) | 闭源 macOS，订阅制 | 开源；不绑厂商，凭据在本机 Keychain |
| [Lazy](https://heylazy.com) | 闭源笔记/捕获工具 | 不做笔记容器，专做「插入到任意输入框」 |
| [Superwhisper](https://superwhisper.com) | 闭源 macOS，订阅制 | 开源；目前云端 ASR 优先，本地 ASR 在 roadmap |
## 当前状态（v1.0）
- 原生 Swift / SwiftUI / AppKit，SwiftPM 项目；macOS 15+。
- macOS 26+ 使用 Liquid Glass 效果，旧系统回退到系统 material。
- 默认是切换式录音：按一次开始，再按一次结束；录音中按 `Esc` 取消。
- 接入火山引擎流式 ASR 和 Ark / DeepSeek 兼容 Chat Completions 进行润色。
- 4 种输出模式：原文、轻度润色、清晰结构、正式表达。
- 4 种输出模式：原文、轻度润色、清晰结构（**AI prompt 模式**）、正式表达。
- 主窗口按「首页 / 历史记录 / 词典 / 设置」组织；菜单栏常驻；底部有微型状态胶囊。
- 词典支持作为 ASR 热词注入和润色阶段的语义判断。