douvo

KO | EN

gitlite — search

#tailwindcss #data-science #json #linux #awesome-list #computer-vision #android #cloud-native #web #claude

(★ 9)

Apple Silicon macOS voice input app with Doubao ASR and optional local/remote AI correction.

File Explorer

ZIP Download

- README.md
- - ci.yml
  - release.yml
- - mirrors.json
- Douvo.icns
- douvo.png
- - douvo-icon.png
- - all-models-10.json
  - prompt-lab.sample.json
  - prompt-lab.structured.json
  - prompt-lab.target.json
  - README.md
  - s1-mini.sample.json
  - spark-x25.sample.json
  - system-prompt.txt
  - user-message.txt
- - Siri27SiriAnimation-MIT.txt
- advanced-prompts.md
- advanced-prompts.zh.md
- asr-providers.md
- audio-input-processing.md
- dev-local-build.md
- trace-replay.md
- build-app.sh
- build-dmg.sh
- build-mlx-metallib.sh
- code-sign-import.sh
- commit_release.sh
- consume_changesets.sh
- ensure-local-code-signing-identity.sh
- install-dev-app.sh
- render_changesets.sh
- test_changesets.sh
- update_appcast.sh
- update_homebrew_cask.sh
- update_version.sh
- - AndroidASRContext.swift
  - AndroidASRSessionGate.swift
  - AppLanguage.swift
  - AppLog.swift
  - AppState.swift
  - ASRDemoDiagnosticRunner.swift
  - ASRErrorDiagnosticStore.swift
  - ASRLabCommand.swift
  - ASRParamsStore.swift
  - ASRProvider.swift
  - ASRRecognitionResult.swift
  - AudioCaptureManager.swift
  - AudioDeviceManager.swift
  - BageshuoASRClient.swift
  - BageshuoASRParamsStore.swift
  - BageshuoHotWords.swift
  - BageshuoWebViewManager.swift
  - ClipboardTransaction.swift
  - DoubaoAndroidASRClient.swift
  - DoubaoAndroidCredentialStore.swift
  - DoubaoAndroidPersonalLexicon.swift
  - DoubaoAndroidWaveClient.swift
  - DoubaoASRClient.swift
  - DouvoApp.swift
  - DouvoResourceLocator.swift
  - GPTFluidOrbShaders.metal
  - GPTFluidOrbView.swift
  - HotkeyManager.swift
  - HotkeyShortcut.swift
  - Info.plist
  - LanguageDisplay.swift
  - LaunchAtLoginStore.swift
  - LocalLLMDownloadManager.swift
  - LocalLLMPostProcessor.swift
  - LocalLLMSettingsStore.swift
  - LocalMLXRuntimeDiagnostic.swift
  - LogExportStore.swift
  - OverlayAppearanceStore.swift
  - OverlayPanel.swift
  - PasteHelper.swift
  - PromptEnvironmentContext.swift
  - PromptLabCommand.swift
  - PromptSnapshotStore.swift
  - RecentAudioRecorder.swift
  - RecentDictationContext.swift
  - RemoteLLMPostProcessor.swift
  - SelectedTextReader.swift
  - ShortcutCapturePanel.swift
  - SiriRibbonShaders.metal
  - SiriRibbonView.swift
  - Spark2_5Model.swift
  - StatusItemVisibilityDetector.swift
  - TraceReplayCommand.swift
  - TranscriptHistoryStore.swift
  - TranscriptionManager.swift
  - TranscriptionSession.swift
  - TranscriptionTrace.swift
  - WebViewManager.swift
- - AndroidASRContextTests.swift
  - AndroidASRResultParserTests.swift
  - AndroidASRSessionGateTests.swift
  - AppMenuTests.swift
  - ASRLabCommandTests.swift
  - ASRParamsStoreTests.swift
  - AudioInputConditionerTests.swift
  - BageshuoASRClientTests.swift
  - ClipboardTransactionTests.swift
  - DoubaoAndroidPersonalLexiconTests.swift
  - DoubaoASRClientTests.swift
  - EmotionSofteningPromptTests.swift
  - EnvironmentContextPromptTests.swift
  - GenerationProfileTests.swift
  - LocalLLMDownloadManagerTests.swift
  - MultiASRTests.swift
  - OutputStylePromptTests.swift
  - PunctuationStyleTests.swift
  - S1MiniModelTests.swift
  - SelectionEditingPromptTests.swift
  - SiriRibbonViewTests.swift
  - Spark2_5ModelTests.swift
  - StatusItemVisibilityDetectorTests.swift
  - TextInputFocusCheckTests.swift
  - TranscriptHistoryStoreTests.swift
  - TranscriptionSessionErrorTests.swift
  - UserIdentityPromptTests.swift
  - VocabularyCandidateTests.swift
.gitignore
AGENTS.md
appcast.xml
CONTRIBUTING.md
LICENSE
Package.resolved
Package.swift
README.md
README.zh.md
SPARKLE.md
VERSION

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<div align="center">
  <br />
  <img src="./docs/assets/douvo-icon.png" alt="Douvo icon" width="96" height="96" />
  <h1>Douvo</h1>
  <p>
    A lightweight macOS voice input app with Doubao ASR and optional AI post-processing.<br />
    Press a key, speak, clean up the transcript, and insert it into the app you are already using.
  </p>
  <p>
    <a href="./README.zh.md">中文</a>
    &nbsp;·&nbsp;
    <a href="./LICENSE">License</a>
    &nbsp;·&nbsp;
    <a href="./CONTRIBUTING.md">Contributing</a>
  </p>
  <br />
</div>

## Capabilities

<table>
  <tr>
    <td align="center">
      <img src="./docs/assets/readme/vocabulary-correction.gif" width="250" alt="Douvo applying vocabulary hints during AI post-processing" />
      <br />
      <sub>Apply vocabulary hints</sub>
    </td>
    <td align="center">
      <img src="./docs/assets/readme/mixed-language-no-punctuation.gif" width="250" alt="Douvo handling mixed Chinese and English without punctuation" />
      <br />
      <sub>Mixed Chinese/English without punctuation</sub>
    </td>
    <td align="center">
      <img src="./docs/assets/readme/reduce-emotion.gif" width="250" alt="Douvo reducing emotional wording in AI post-processing" />
      <br />
      <sub>Reduce emotional wording</sub>
    </td>
  </tr>
  <tr>
    <td align="center">
      <img src="./docs/assets/readme/selection-editing.gif" width="250" alt="Douvo editing selected text with AI post-processing" />
      <br />
      <sub>Edit selected text</sub>
    </td>
    <td align="center">
      <img src="./docs/assets/readme/translation.gif" width="250" alt="Douvo translating dictated text with AI post-processing" />
      <br />
      <sub>Translate</sub>
    </td>
    <td align="center">
      <img src="./docs/assets/readme/appearance-switching.gif" width="250" alt="Douvo switching appearance" />
      <br />
      <sub>Switch appearance</sub>
    </td>
  </tr>
</table>

## Features

- 🎙️ **Dictate into any app** — Short press to toggle recording, or use hold-to-talk, then insert the result at the current cursor.
- 🧠 **Clean up before paste** — Optional AI post-processing can fix wording, punctuation, filler words, tone, and output style.
- ✍️ **Edit selected text by voice** — Select text, speak an edit instruction, and let AI rewrite the selected text instead of replacing it.
- 🌐 **Translate on demand** — Press a configurable translation key while recording and insert the result in your target language.
- 🗂️ **Use your own vocabulary and context** — Add project terms, paths, names, user identity, current time, frontmost app, and optional window title.
- ⚙️ **Choose local or remote AI** — Run MLX models on device, use a local model folder, or connect a remote LLM provider.
- 🪶 **Keep the workflow lightweight** — Menu bar UI, floating recording overlay, appearance switching, clipboard-aware insertion, and local diagnostics.

## Why Douvo

Douvo was built for mixed Chinese/English input workflows. In those scenarios, many mainstream local speech models still struggle with recognition quality, while Doubao IME has been much stronger in my day-to-day use, especially for mixed-language dictation.

The problem is that Doubao IME is still an input-method product:

- Voice input is tied to the active IME state, so it only works naturally when the input method is active.
- The recognized text is committed live while you speak, which makes it hard to switch apps or recover cleanly if the input is lost.
- If a long dictation is lost, you often have to dictate the whole thing again.
- Customization is limited: user vocabulary, rewrite behavior, translation, selection editing, and prompt-level controls are not the focus of the original IME.

Douvo keeps the strong Doubao ASR path, but wraps it as an app-agnostic voice input tool with post-processing, vocabulary, translation, selected-text editing, clipboard-aware insertion, and local diagnostics.

If you do not run into these pain points, the original Doubao IME is likely the better and simpler choice.

## Disclaimer

This project depends on observed Doubao and Youdao Bage Shuo client behavior. It is **not** an official API, SDK, or integration for either service.

- You need a valid Doubao account and must log in yourself.
- Doubao may change its website, authentication flow, device registration, WebSocket protocols, ASR payload formats, rate limits, or access policy at any time.
- Youdao Bage Shuo may change its login flow, ticket signing, WebSocket protocol, audio format, rate limits, or access policy at any time.
- Audio sent for recognition is processed by Doubao's service. Review Doubao's own terms and privacy policy before using this app.
- Enabling Android Personal Lexicon uploads the configured vocabulary terms to Doubao; uploaded terms may persist remotely after local removal.
- Web/Bage Shuo login parameters and Android ASR credentials are stored locally so each selected provider can connect without keeping a browser window open.
- If remote AI post-processing is enabled, transcript text is sent to the provider and endpoint you configure.
- Local AI post-processing uses MLX models downloaded from Hugging Face or loaded from a local model folder.
- Use this project at your own risk. The maintainers are not responsible for service availability, account issues, data loss, policy violations, or other consequences.
- This project is not affiliated with, endorsed by, or sponsored by Doubao or ByteDance.

## How it works

Douvo supports three ASR paths: Doubao **Web**, Doubao **Android**, and Youdao **Bage Shuo**. Select one or more paths in Settings; multiple paths run in parallel and their results are merged with AI post-processing. The default is **Web**. The Android and Bage Shuo paths follow observed client behavior. See **[ASR Providers](./docs/asr-providers.md)** for the protocol details.

```mermaid
flowchart TD
    A[Choose one or more Web, Android, or Bage Shuo paths] --> B[Prepare credentials required by the selected paths]
    B --> C[Trigger recording from the menu bar app]
    C --> D[Capture microphone audio with AVAudioEngine]
    D --> E{Selected ASR path}
    E -- Web --> F[Stream 16 kHz PCM chunks to Doubao Web ASR]
    E -- Android --> G[Encode 16 kHz Opus and send Protobuf frames to Doubao Android ASR]
    E -- Multiple --> H[Send each selected audio format to its ASR path in parallel]
    E -- Bage Shuo --> I[Request a signed ticket and stream 16 kHz PCM to Youdao]
    F --> K[Show partial transcript in the floating overlay]
    G --> K
    H --> K
    I --> K
    K --> L[Receive final ASR transcript or transcripts from multiple paths]
    L --> M{AI post-processing enabled?}
    M -- No --> P[Apply deterministic punctuation and vocabulary fallback]
    M -- Local --> N[Run local MLX model on device]
    M -- Remote --> O[Send transcript to the configured remote LLM provider]
    N --> Q[Clean, validate, and normalize corrected text]
    O --> Q
    Q --> P
    P --> R[Insert final text with pasteboard and Command-V]
    R --> S[Restore clipboard when safe]
    L --> T[Write local traces, timings, and logs for diagnostics]
```

## Requirements

- Apple Silicon Mac.
- macOS 14.0 or newer.
- Due to limited test hardware, Douvo is only regularly tested on macOS Tahoe 26 with an Apple Silicon M5 Pro Mac; other setups may have compatibility issues.

## Install

Recommended: download the latest **`douvo-<version>-macos.dmg`** from **[GitHub Releases](https://github.com/rhinoc/douvo/releases)**.

1. Open the DMG.
2. Drag **`Douvo.app`** onto the **Applications** shortcut.
3. Eject the disk image.
4. If macOS blocks first launch, trust the installed app once:

```bash
   xattr -dr com.apple.quarantine /Applications/Douvo.app
   open /Applications/Douvo.app
   ```

The DMG contains `Douvo.app` and an **Applications** shortcut only. Current release builds are not notarized, so macOS may ask you to confirm first launch or remove quarantine manually.

Homebrew is also available if you prefer tap-based installs:

```bash
brew install --cask rhinoc/tap/douvo
```

Homebrew Cask installs the same DMG artifact from GitHub Releases, not a separately signed package.

In-app updates are handled by Sparkle and use the same DMG artifact published on GitHub Releases.

### First launch and Gatekeeper

Browser and Homebrew downloads can be tagged with Gatekeeper **quarantine** (`com.apple.quarantine`). If macOS warns that Douvo cannot be opened or is from an unidentified developer, remove quarantine after copying or installing the app to **Applications**, then open it once.

```bash
xattr -dr com.apple.quarantine /Applications/Douvo.app
open /Applications/Douvo.app
```

## Permissions

macOS needs two permissions before the app can work end to end:

1. **Microphone** — required to capture speech.
2. **Accessibility** — required for the global trigger key and Command-V insertion.

If the trigger key does not work after granting Accessibility, quit and reopen the built `.app`. If macOS still ignores the trigger, remove the old Douvo entry from **System Settings -> Privacy & Security -> Accessibility**, add the current app bundle again, then restart the app.

Local AI post-processing runs on device. Remote AI post-processing sends transcript text to the configured remote provider and stores that provider's API key in Keychain.

## Usage

1. Open the menu bar item and choose **Settings... -> Account -> Recognition**.
2. Choose one or more providers. Bage Shuo first imports the installed Bage Shuo app's cookies when Douvo has no usable login; if you log in through Douvo's official Youdao page, that login is kept as the active credential. Web still uses the Doubao login popup.
3. Place your cursor in any text field.
4. Press the trigger key to start recording, or hold the hold-to-talk key if configured.
5. Speak.
6. Press the trigger key again, or release the hold-to-talk key, to stop and insert the transcript.
7. Press the translation key while recording to switch the current recording into translation mode.
8. Press **Escape** while recording to cancel.

Use **Settings...** from the menu bar to change trigger keys, choose a microphone, choose one or more recognition paths, refresh login, configure AI features, copy diagnostics, or open the app log.

### AI Post-processing

Open **Settings... -> Features** to configure punctuation, vocabulary, and AI-backed features. Open **Settings... -> AI** to configure AI post-processing:

- Choose **Local** to download a built-in MLX model or add a local MLX model folder.
- Built-in **S1-mini by Superwhisper 4bit** (`s1Mini`) is an English-only, 335 MB ASR cleanup model. It is optimized for ordinary English dictation cleanup; use a Qwen3.5 model for Chinese, mixed-language, translation, or selection editing.
- Built-in **Spark-X2.5 1.7B and 4B** (`sparkX25OneSevenB`, `sparkX25FourB`) run the official open checkpoints locally through the native Swift/MLX Spark architecture. They are useful for Chinese correction and reasoning; the original BF16 checkpoints are about 3.4 GB and 8.2 GB.
- Choose **Remote** to add a provider, base URL, model name, and API key.
- Add vocabulary hints for project terms, file paths, product names, and common ASR mistakes.
- When Bage Shuo is selected and logged in, Douvo automatically merges its account hot-word list with the local correction vocabulary. New local terms are added to Bage Shuo after the local vocabulary changes; removing a local term does not delete the remote term.
- Choose output styles such as Natural, Concise, Structured, or Custom, and tune style strength.
- Configure a translation shortcut and target language.
- Configure optional context such as current time, frontmost app, and window title.
- Enable Selection Editing to use selected text as the edit target when AI post-processing is on. Selected text is capped at 500 characters.
- Tune punctuation, filler-word removal, emotion softening, and output style.
- Enable **Copy on Failure** to keep the generated text on the clipboard when the target app does not accept insertion.
- Use **Settings... -> Diagnose -> Debug Model** to test a sample input and inspect the local trace.

Advanced prompt overrides are available under **Settings... -> AI -> Advanced**. See [Advanced Prompts](./docs/advanced-prompts.md) for template variables and syntax.

## References

This project was built with reference to these open-source projects:

- [lilong7676/doubao-murmur](https://github.com/lilong7676/doubao-murmur)
  - WebView-based Doubao login.
  - Cookie and browser-identifier extraction for native ASR access.
  - Native WebSocket access to Doubao Web ASR.
  - 16 kHz PCM audio streaming and finish-frame behavior.
  - Menu bar voice-input interaction on macOS.
- [EvanDbg/doubao-ime-win](https://github.com/EvanDbg/doubao-ime-win)
  - Doubao IME Android client protocol reference.
  - Device registration and ASR token retrieval flow.
  - Protobuf-based ASR WebSocket task/session messages.
  - 16 kHz Opus audio framing for the Android IME ASR path.
- [Open-Less/openless](https://github.com/Open-Less/openless)
  - Product direction for app-agnostic voice input at the current cursor.
  - Menu bar / tray voice-input workflow.
  - Settings and diagnostics organization.
  - Text insertion reliability ideas, including paste fallback and clipboard restoration.
- [cjpais/Handy](https://github.com/cjpais/Handy)
  - Offline speech-to-text app architecture and recording pipeline reference.
  - Voice activity detection design with pre-roll, onset, and hangover smoothing.
  - Post-processing workflow ideas, including structured output and reasoning suppression.
  - Model, history, and diagnostics organization for a voice-input app.
- [WillSuo-Github/Siri27SiriAnimation](https://github.com/WillSuo-Github/Siri27SiriAnimation)
  - Metal shader structure and spectral wave treatment for the recording overlay.

Douvo includes an adapted portion of the Siri27SiriAnimation wave shader under its MIT License. The attribution and license text are in [docs/third-party-licenses/Siri27SiriAnimation-MIT.txt](./docs/third-party-licenses/Siri27SiriAnimation-MIT.txt). The original code and license remain owned by their respective author.

## Contributing

Development setup, coding conventions, testing, credential-handling rules, and release notes live in **[CONTRIBUTING.md](./CONTRIBUTING.md)**.

## License

Douvo is released under the **MIT License**. See **[LICENSE](./LICENSE)**.

douvo

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

douvo

Owner Repos

File Explorer

# Use via CDN

Was this content helpful?

Recent Feedback

Download README