Doubao-powered voice input for Linux, Wayland and Omarchy
Doubao Say
macOS and Linux: A native Swift menu-bar client supports macOS 13+ on Apple Silicon and Intel, alongside the Linux GTK4 client. Developer ID signed, Apple notarized Mac installers are available. See the Mac usage guide (Chinese).
On macOS, dictation is delivered to the current cursor after the shortcut keys are released. Clipboard paste does not require the recording-time input field to remain focused. Auto mode uses the current accessible field when available, otherwise clipboard paste; Direct mode requires a current accessible input.
On macOS, closing the last settings or sign-in window keeps dictation available from the menu bar while removing the app from the Dock and Cmd+Tab. Opening a window restores both entries; minimized windows keep their Dock entry.

The Linux client is a standalone GTK4 voice-input application for Hyprland/Wayland and native X11. It uses Doubao web-account recognition by default and can optionally use the official Volcengine Seed ASR 2.0 API or Deepgram Nova-3 for English dictation. English by default. Settings offers System / English / 简体中文 and saves each choice automatically. System follows the session's language preferences, uses Simplified Chinese for Chinese locales, and falls back to English otherwise. Optional Omarchy integration manages the same application, not another engine.
Mac input behavior
The interface follows the system language by default, preserving existing explicit choices. Automatic input uses clipboard paste for web editors (including Electron), and direct accessibility input for supported native fields. Escape cancels recording, transcription, polishing or pending input and dismisses the overlay; you can record again immediately. Text already entered is not undone.
Install on Mac

Requires macOS 13 or later. Download the DMG for your processor: Apple Silicon (Feishu) or Intel (Feishu). Backup packages are on GitHub Releases; do not choose a Linux archive for Mac.
Drag Doubao Say to Applications and open it. Allow microphone, Accessibility and Input Monitoring access, choose Doubao sign-in or your own Volcengine / Deepgram API key, and complete the local microphone and speech checks. The default shortcut is Control+Option+Space; it can be changed in Settings.
Settings save automatically. Closing Settings keeps the app in the menu bar. Use Updates to check, download, verify, and install a compatible signed and notarized update. The Mac guide covers input methods, optional AI polishing, permissions, and recovery.
Get started
Use the application or Omarchy plugin archive in dist/. Archives include an
offline installer and Python dependency wheels for the platform in the filename.
System GTK, WebKit, PipeWire and clipboard libraries are not bundled.
See installation, upgrade and uninstall instructions.
After extracting an archive, run ./install.sh; it detects missing Arch/Omarchy
packages, asks before installing them, verifies the bundle and installs the bundled
Python dependencies. ./install.sh --check is read-only.
For a marketplace/Git installation, follow the Git / marketplace installation section there: add without enabling, run the installer, check the runtime, then finish onboarding. Removal differs from the offline archive. Do not mix both routes.
Open Doubao Say from your application launcher:
- Recognition — use the default Doubao web sign-in, or select Volcengine official API or Deepgram Nova-3 (English) in Settings and add your own speech API key. Credentials stay on this device.
- Microphone — choose a PipeWire input, then run a three-second, device-only check with actionable feedback. Device changes save immediately.
- Trigger key — choose Fn, Ctrl, Alt or a function-key preset and it takes effect immediately. Or choose Record a shortcut… as the final dropdown item; the recorded key combination completely replaces the current trigger.
- Voice test — speak into the real recognition engine. Results stay inside the app and overlay; this rehearsal never pastes or sends Enter. When it passes, choose Finish setup and use the trigger in another app.
The trigger starts a short local audio pre-roll immediately so the first word is not lost. Audio is handed to the selected recognition service only after the tap or hold gesture is confirmed; a double-tap, Escape or cancelled gesture discards the unconfirmed buffer.
Optional official Volcengine recognition
Open Settings → Recognition service, select Volcengine official API, and
enter the API key issued by the Volcengine Speech Recognition console. Changes
save automatically. Use Test API key before the voice test. This backend uses
the Seed ASR 2.0 bidirectional streaming endpoint and the hourly resource
volc.seedasr.sauc.duration; PCM audio is uploaded while you speak, incremental
text is returned live, and the final result arrives after recording stops.
Volcengine bills usage to your account.
The API key is stored in ~/.config/doubao-say/volcengine_api_key (or the
equivalent XDG_CONFIG_HOME path) with owner-only permissions. It is never added
to settings, diagnostics, logs, bundles, or reports. Clearing credentials removes
the key. Service activation and project access are managed in the Volcengine
console; an HTTP 401 from Test API key normally means that account-side access
is not ready yet.
See Doubao and the official Volcengine speech API for backend differences, new-console activation, bidirectional streaming limitations, and troubleshooting.
Optional Deepgram English recognition
Open Settings → Recognition service, select Deepgram Nova-3 (English), and enter an API key from the Deepgram console. Use Test API key before the voice test. Doubao Say streams 16 kHz mono PCM to Deepgram's Nova-3 live endpoint with US English, interim results, punctuation, and smart formatting enabled. Partial text appears while you speak and the finalized transcript is returned after recording stops. Deepgram bills usage to your account.
The API key is stored in ~/.config/doubao-say/deepgram_api_key (or the
equivalent XDG_CONFIG_HOME path) with owner-only permissions. It is excluded
from settings, diagnostics, logs, bundles, and reports. The app currently fixes
this provider to US English; other Deepgram languages and multilingual mode are
not exposed yet.
Optional voice polishing
During polishing, a separate status row and softly pulsing stars sit above the transcript. A shortcut hint appears after three seconds; reduced motion keeps the stars static.
Turn on the Voice polishing · Experimental switch on the Trigger key page to configure an OpenAI-compatible Base URL, API key, model and separate Chinese/English prompts. In the Linux GTK client, the polishing service can also be set to ChatGPT plan. Use Continue with ChatGPT to authorize Doubao Say, choose an account-specific model, then enable polishing. Account selection, disconnect, model refresh and Manage usage are available in the same panel. Credentials stay in an owner-only local store; the existing API endpoint, key and model settings are preserved. This option powers text polishing, while speech recognition continues through the selected speech service. The five-second original-text fallback also applies to connection, quota and renewal failures. If ChatGPT reports a plan usage limit, further polishing pauses and keeps the original text. Open Manage usage to review the plan or app limit, then use Retry plan usage when available; signing in again is not required for a quota error. The native macOS app also offers ChatGPT plan in Voice polishing. Its shared connection serves dictation, AI vocabulary organization and polishing comparisons; credentials stay in the app's Keychain. Recognition remains on the selected speech service, and existing API configuration is preserved. Choose a model from the dropdown; reconnect, add/disconnect accounts and refresh models through Account options. Usage-limit actions appear when needed. Doubao Say selects a prompt from each transcript's dominant language. The bundled prompts remove filler words and false starts, improves punctuation and organization, preserves meaning, and can be edited or restored to its default.
The built-in prompts use passage context to correct unambiguous accent-related recognition errors, including Chinese retroflex initials, nasal endings, and n/l or f/h confusions. Ambiguous wording is retained; names, quantities and negation are never guessed from sound alone. Updates migrate exact old defaults while preserving custom prompts.
Context includes grammar and action sequences: in a troubleshooting request, “确认附件验证解决” can become “确认、复现、验证、解决”. References to email attachments, deliberate quotations and ambiguous short phrases retain “附件”; this is model-based correction, not a global word replacement.
Explicitly spoken points such as 第一、第二、第三 are formatted as Markdown numbered lists, one item per line; ordinary references to days, rankings or counts stay as prose.
Polished text also gains restrained reading layout: related sentences stay together, clear topic changes can start a new paragraph, and paragraphs and lists are separated by one blank line. Short answers stay compact; formatting does not add headings or change the content order.
Choose a fast polishing model
Prefer a small, low-latency model with thinking disabled. Polishing only needs light text correction, not deep reasoning. Large reasoning models are a poor default for this task: polishing has a five-second total budget, after which Doubao Say uses your original text. Small models can still think, and a Flash/Lite name does not guarantee that thinking is off or can be disabled.
Start with one of these options on its official endpoint:
| Model | Base URL | Automatic thinking control |
|---|---|---|
DeepSeek Flash (deepseek-flash) |
https://api.deepseek.com |
Requests thinking: {"type": "disabled"} |
Gemini 2.5 Flash-Lite (gemini-2.5-flash-lite) |
https://generativelanguage.googleapis.com/v1beta/openai |
Requests reasoning_effort: "none" |
Gemini 2.5 Flash also has automatic thinking-off support. See the official DeepSeek thinking guide and Gemini OpenAI compatibility guide for the provider parameters. These are configuration suggestions, not measured latency guarantees; network, service load, and text length also affect speed. Use Test endpoint to check connectivity, then try a short recording to assess actual polishing latency and quality.
The settings page shows the thinking policy for your endpoint and model.
The verified qwen3.7-plus model on token-plan.cn-beijing.maas.aliyuncs.com
also requests enable_thinking: false; other Token Plan models keep their
provider defaults. See the Token Plan parameter guide.
Automatic control depends on the official hostname, not just the model name.
For gateways or providers without a verified policy (including OpenAI, Claude,
and Grok), confirm thinking is disabled in the provider configuration or choose
a non-reasoning model; Doubao Say otherwise leaves provider defaults in place.
Claude's native API is not supported by this OpenAI-compatible client.
Zhipu (open.bigmodel.cn) standard and Coding Plan APIs request thinking-off,
except for GLM-5.3 and GLM-5.3-Flash: these cannot disable thinking and request
reasoning_effort: "low" instead. Low effort is still thinking, so these are not
the preferred choices for this five-second workflow. See the
Zhipu thinking guide.
When enabled, 1.2 seconds of silence with stable recognized text starts provisional polishing. A separate status line stays visible while the overlay streams the result. The entire recording is lightly corrected using context, without inference or unnecessary rewriting. Pauses only produce a preview; recording continues until you tap again or release hold-to-talk. Only then is the final text pasted once. Changed recognized text invalidates old requests; microphone noise alone does not. Polishing is best-effort with a five-second total budget, including queued work; timeout uses the original segment and ignores late results. Tap-to-toggle recording ends when you tap again; hold-to-talk ends on release. Press the active trigger during final polishing to use the original transcript; endpoint errors also safely fall back to it.
The API key is stored separately with owner-only permissions and never appears in diagnostics. Use Test endpoint before enabling.
Desktop support
| Desktop session | Automatic clipboard paste | Direct typing |
|---|---|---|
| Hyprland / Wayland | wl-copy; known, unchanged window required |
Optional wtype |
| Native X11 | Optional xclip and xdotool; known, unchanged window/PID required |
Unavailable; choose Clipboard paste |
| Other Wayland compositors | Retain the result for manual copying when focus cannot be verified | No supported automatic path |
Native X11 uses Ctrl+V, or Ctrl+Shift+V for recognized terminal classes. Its
floating overlay does not request activation; the window manager chooses its
position. When GTK uses X11, optional wmctrl requests above-window stacking
each time the overlay is shown, without activating it or waiting on the GTK main loop.
If the helper is missing or fails, recording and input continue with the window
manager's normal stacking. Fullscreen coverage depends on the window manager.
Hyprland keeps its bottom-anchored layer-shell overlay. PipeWire
microphone selection works through pw-record on both desktops.
XWayland is not treated as a native X11 session. The X11 helpers are probed at
runtime; without xdotool or xclip, recognition still works and the result is retained
for manual copying. Install wmctrl separately for X11 overlay stacking
(sudo apt install wmctrl or sudo pacman -S --needed wmctrl).
Text input method
Settings → Input → Text input method defaults to Clipboard paste,
including for existing installations. Clipboard paste replaces the current
clipboard contents; clipboard managers may save the recognized text in history.
CopyQ is not required. The app attempts to restore one original clipboard payload
after paste if the clipboard still contains the dictation text; clipboard history
is not suppressed. Rich text is restored as plain text when both are available,
so formatting is lost. Choose Direct typing on Hyprland to keep the clipboard unchanged.
Install wtype separately; this mode requires a compatible
Wayland virtual-keyboard implementation and has been tested on Hyprland.
Direct typing sends characters gradually (about 8 seconds for 1,760 characters
in our local test). Newlines and tabs act as Enter and Tab keys and can submit
messages, execute terminal commands or move focus. Keep the target focused and
avoid typing at the same time. Escape cancels remaining input; text already
entered cannot be withdrawn. Focus changes stop further input on a best-effort
basis. If direct typing fails or wtype is unavailable, the result stays in the
app with no automatic clipboard fallback. Check for partial input before retrying.
Gestures
New installations default to Ctrl+; on every desktop. GNOME uses the desktop portal; other desktops use evdev. Existing saved shortcuts are retained, except that GNOME adapts unsupported saved evdev shortcuts (including Fn and modifier-only keys) to Ctrl+;. Modifier keys are logical choices: either the left or right physical key works. Your keyboard must report Fn as a Linux key; otherwise choose another key.
- Tap to start; tap again to finish and paste.
- On Linux, with Fn as the trigger, pressing another key while recording also finishes and pastes. Escape still cancels; the finishing key still reaches the foreground app.
- On macOS, keys other than Escape during voice input finishes dictation without performing its original action, including Enter and shortcut chords. Escape cancels immediately during recording, transcription, polishing or pending input; cancelled recognition is never pasted. Their releases are swallowed as well. Double-tap sends Enter only while idle.
- If two accidental taps leave a transcription pending, press Escape to cancel and record again immediately. In Linux portal mode, use Cancel input in the control center or tray instead.
- Hold past the threshold to speak; release to finish and paste.
- Select one preset, or choose Record a shortcut… to capture a custom combination such as Ctrl+Alt+Space. Only one trigger is active.
- Press the active trigger twice to send Enter without dictation. This can submit messages or execute terminal commands.
- Configure the hold threshold, double-tap interval, Enter gesture and startup.
If recognition is rejected, fails to connect, or times out, the overlay keeps the error visible until you choose Open settings or Close. While it is visible, the trigger starts no new recording and does not open Settings automatically.
The bottom overlay shows an audio-driven waveform and live text. Choose Classic bars, Soft waves, Concentric ripples, or Basketball rhythm under Settings → Appearance → Listening waveform. The basketball theme uses an fine wave strands that subtly form a dribbling figure and an orange ball. The figure stays at a fixed size with planted feet, a rhythmic rightward shoulder pop, and a hand that leads the bouncing ball. The phrase alternates anticipation, a fast downward push, a squashed impact, a shoulder snap with delayed head turn, a short hold and recovery. Dribbling speed follows an estimate of speech cadence from audio energy onsets, not volume or recognized words per minute. Pauses freeze the pose; volume only affects brightness. No solid character or ball outlines are drawn. Changes save automatically; use Preview appearance to try them. Classic bars remains the default. Reduced updates also stop travelling and bouncing motion in the new styles while retaining volume feedback. Final text is pasted after recording ends; target fields are not revised live. No green volume/progress bar is shown. The system tray waveform opens the existing app when clicked: blue when ready, red while recording, yellow while transcribing. Some desktops fold tray icons into an expandable drawer.
The application checks the repository's latest stable GitHub Release at startup and while running, with network checks limited to once every 24 hours. A newer version adds a small red dot to the recording overlay: hover or click for version information. Finish dictation, then use the control center's red Update button to download, verify and install the update, then restart. Checks are automatic; installation starts only when you choose it. Recording, polishing and text delivery must finish first. Settings and login data are retained. Linux supports official clean Git checkouts and managed app/plugin archives; package-manager and relocated installs report that their original installer is needed. Archives must match the CPU and Python version. Failed installation checks restore the previous app. On macOS, Settings → Updates shows download progress and cancellation; DMGs require SHA256SUMS, the same Developer ID, notarization and a matching bundle ID. See update packaging for release prerequisites.
Feedback
Report bugs and suggestions through GitHub Issues. Include the version, desktop environment, steps to reproduce, and expected versus actual behavior. Remove API keys, cookies and personal transcripts from attachments.
Control center and recovery
The control center contains the four setup pages, without a separate Home or completion page. Reopen it from the tray whenever you want to test or change a setting. The tray's Copy recent result action recovers the last in-memory result. Escape cancels recording or pending input. On Hyprland's Lua configuration, Escape is temporarily consumed during dictation, polishing and pending paste, so it does not also exit the foreground TUI. Idle Escape is unchanged. Existing global Escape bindings are not replaced; a warning is shown if protection cannot be enabled. Other compositors currently only observe Escape and cannot prevent it reaching the foreground. Paste and Enter are serialized on a background worker so clipboard waits do not block the GTK interface. Before clipboard paste, the app snapshots one primary MIME payload and restores its original bytes only if the clipboard still contains the dictation text. Plain-text formats take priority over HTML, so rich-text formatting is lost when both are available. An HTML-only clipboard still restores as HTML; images and URI lists retain their existing priority. This is best-effort restoration of one payload, not all original clipboard formats. A copy made by the user during delivery is never overwritten. Cancellation stops remaining input and cannot undo text already delivered. Standalone Enter does not change the previous dictation's history or word counts. On macOS, retries, new dictation and standalone Enter are disabled during a retry countdown or pending delivery. Use Escape or Cancel input to cancel it. Failed recognition can preserve partial text; failed paste preserves the result. The editable recent-text slot is memory-only. Completed dictation attempts are stored separately in a local 30-day history, with recognition original, final output, polishing and input status. History has no record-count cap and can be paused or cleared in Vocabulary & history; voice tests and cancelled recognition are excluded. Personal vocabulary is saved automatically (one term per line, up to 200 terms of 80 characters). Official Volcengine ASR sends a length-limited subset as session hotwords, prioritizing spellings you explicitly confirmed. The vocabulary page previews the actual subset. Doubao Web and other engines use this list only as context during AI polishing. This does not retrain the model. From an input-history entry, select the wrong term and choose Correct & remember…, or select it in the dialog to fill it in. Enter the correct spelling, review the preview, then confirm. Only that explicit action creates memory. Original recognition and polishing output are preserved. Future polishing receives relevant correction pairs and example contexts as reference data, never global replacements. You can forget pairs individually; clearing or expiring history retains vocabulary and correction memory. Local frequencies use sent, polished results and explicitly confirmed corrections; AI organization sends candidate terms and counts to the configured polishing service, not the full history. Review and select suggestions before adding. Data is local to each device; there is no cross-device sync.
For repeatable comparisons on the same recordings, use the opt-in personal speech evaluation CLI. It separately scores raw ASR, hotword ASR and optional polishing, including negative examples where Midjourney is correct. Offline scoring supports manually collected competitor outputs. No personal-accent improvement is claimed without actual recordings.
Automatic paste requires a known, unchanged Hyprland or native X11 window. On X11, missing window metadata, a closed window or the app's own window prevents paste. Unsupported desktops or unknown targets retain the result for manual copying. Focus is checked before paste and Enter, but focus checks and input delivery are not atomic. Moving the caret inside the same window is not detected. A sent paste shortcut is not proof that an app received it.
Settings includes hardware key capture with timeout/cancel, PipeWire microphone selection, lower-frequency waveform updates, account controls, and an allowlisted diagnostic preview/copy action. Input capture is paused during key assignment. Key recording accepts ordinary keyboard keys and modifier combinations. The left and right variants of Ctrl, Shift, Alt and Meta are treated as the same key. Automatic detection of every desktop shortcut conflict is not supported.
The Speech evaluation page in Mac Settings and Linux Vocabulary & history records local samples and compares the same audio with raw ASR, hotwords, and optional polishing. References are only used for scoring. Comparison explicitly uploads audio to your paid official ASR; drafts save automatically and recordings remain until deleted. Input history also shows stop-to-ASR, polishing, input and total waiting times, separately from recording duration and replay timing.
Privacy and limitations
After a recording gesture is confirmed, the default unofficial backend sends the locally buffered and live microphone audio to Doubao and depends on its web protocol. The optional API backends send it to Volcengine or Deepgram under the user's API account and terms. Cancelled, double-tap and microphone-only checks do not upload audio. The hosted sign-in website controls its own language. When optional polishing is enabled, recognized text—including provisional text sent after a pause—is transmitted to the OpenAI-compatible endpoint configured by the user. Its operator's retention, training and privacy terms apply. The update check sends a standard HTTPS request to GitHub at most once per day; GitHub receives the usual connection metadata. The cached release tag and check time contain no account, transcript or device identifier.
The default evdev trigger needs keyboard-device access. Adding your account to the
input group grants other processes running with that group access to keyboard
input too, including sensitive keystrokes; it is not an app-specific permission.
Do not run the app as root.
Permission-scoped shortcuts on GNOME
On GNOME, launch Doubao Say normally from its icon or existing command. It
selects the GlobalShortcuts portal automatically and requests Ctrl+; on a
fresh installation on every desktop. Unsupported saved evdev shortcuts, including Fn and modifier-only keys, also become Ctrl+; on GNOME;
portal-supported shortcuts and Disabled are preserved. No environment variable or
manual shortcut selection is needed. Approve the desktop's shortcut dialog.
Other desktops retain their existing evdev behavior. For explicit troubleshooting
only, DOUBAO_SAY_TRIGGER_BACKEND=portal or evdev overrides automatic selection.
Portal mode installs its md.lifeos.DoubaoSay.desktop identity launcher under the
XDG applications directory and registers that ID before requesting authorization.
Approve the shortcut in the desktop's GlobalShortcuts dialog. The desktop may
change the requested shortcut; its dialog is authoritative. This mode receives
only activation/deactivation of the authorized dictation action, without opening
/dev/input or requiring membership in input. Hold-to-talk, tap-to-toggle and
double-tap use the existing gesture timing. Denial, timeout or a missing portal
stops the listener without silently falling back to evdev. Restart the app to
retry authorization.
Portal mode does not support Fn/modifier-only shortcuts or raw key recording;
supported keys are semicolon, F8, F9, Space, Return or Tab with optional Ctrl/Shift/Alt/Meta.
Global Esc cancellation is not
registered in this mode, so use the control center or tray's Cancel action.
Vibekey is a separate, optional device listener and retains its own permissions.
Input delivery is separate: /dev/uinput access may still be needed for injected
shortcuts/paste. This change removes broad keyboard reading from the dictation
trigger, not every device permission from the app. It does not remove existing group
memberships or change system permissions.
The backend requires an implementation of org.freedesktop.portal.GlobalShortcuts.
GNOME backend availability varies by version. Full GNOME application support
(including overlay and text delivery) is not established by this trigger feature.
To explicitly retain raw keyboard behavior on GNOME, set the override to evdev.
Vibekey support is optional and off by default. When enabled in Settings, its three
transmitter buttons map to recording, Enter and cancel. Turning the dial right or
left sends Down or Up by default, and pressing it sends Meta+Backspace. All six
controls can keep their default or record a different keyboard shortcut in Settings;
the mapping controls stay hidden while Vibekey support is off. Its narrowly scoped
udev rule is documented in the installation guide. No
Vibekey software dependency is required.
Settings and sign-in
data are kept separately from installed files. Never publish credential files,
personal transcripts, recordings, or logs. The release builder uses an explicit
allowlist and excludes development environments and acceptance artifacts.
Use only one startup owner: standalone desktop autostart or the Omarchy plugin. Uninstalling preserves settings and sign-in data. See INSTALL.md for plugin lifecycle and recovery behavior.
Installation guide for AI agents
On macOS, follow Install on Mac and the Mac guide; the Linux package, evdev, and PipeWire steps below do not apply.
Use this section when a user asks you to install Doubao Say. The app and Omarchy plugin run the same Doubao cloud engine. Choose one installation route; do not install a local recognition engine or change another voice application's shortcuts.
- Inspect the machine and existing installation. Run
uname -m,python3 --version,id -nG, andcommand -v omarchy. Check${XDG_CONFIG_HOME:-$HOME/.config}/omarchy/plugins/md.lifeos.doubao-say,${XDG_DATA_HOME:-$HOME/.local/share}/doubao-say/app, and thedoubao-say.desktoplauncher under the XDG applications directory. Reuse the existing route. Abundle.jsonplus.doubao-managed.jsonidentifies an archive installation; a Git checkout uses the source route. Stop recording and disable the plugin, or quit the standalone application, before upgrading. - Select an available source. Prefer a user-provided checkout or matching
release archive. The intended repository is
https://github.com/quanru/doubao-say. If it is inaccessible, report that and use the provided local source. Do not invent a release URL or install an upstream project's package as Doubao Say. - Install using exactly one route below. Keep the checkout or extracted installer at a known location. Use a normal desktop user; system package installation may request administrator authentication.
Omarchy plugin from Git/source:
omarchy plugin add https://github.com/quanru/doubao-say.git
# Decline enablement if prompted. For an existing plugin, skip plugin add.
cd "${XDG_CONFIG_HOME:-$HOME/.config}/omarchy/plugins/md.lifeos.doubao-say"
./install.sh
./start.sh
Do not create .venv inside an installed plugin; Omarchy rejects symlinks there.
Let the user finish onboarding, quit the foreground app, and then run
omarchy plugin enable md.lifeos.doubao-say.
For an existing Git plugin, disable it before omarchy plugin update md.lifeos.doubao-say, then rerun setup/checks and enable it.
Standalone app from an existing checkout on Arch/Omarchy:
From the checkout directory, run the following. The installer uses omarchy pkg add
when available and otherwise uses sudo pacman -S --needed on Arch.
./install.sh
./start.sh
Keep this checkout in place: its desktop launcher points to it. Enable standalone startup in Settings only if the Omarchy plugin is disabled. For other distributions, resolve equivalent system packages first; automatic paste targets Hyprland and native X11. Run installation checks from the desktop session you intend to use so the correct clipboard and GTK backend dependencies are selected.
App or plugin release archive:
Select the app or plugin archive matching the CPU and Python version; run
sha256sum -c SHA256SUMS --ignore-missing from the directory containing the archive
and checksums, and require a successful check of the selected file. Extract into a
new directory, enter the extracted directory, and run:
./install.sh --check
./install.sh
The installer offers to add missing Arch/Omarchy system dependencies after showing
the exact list. The archive supplies offline Python wheels; the source route uses system packages.
For a plugin archive, finish onboarding before enabling the plugin. Upgrade archive
installs with a new matching archive, not omarchy plugin update. Uninstall with
the extracted installer's ./install.sh --uninstall; remove Git plugins with
omarchy plugin remove md.lifeos.doubao-say instead.
- Finish permissions and onboarding with the user. If keyboard or
/dev/uinputaccess is missing on this Omarchy setup, explain theinputgroup requirement and usesudo usermod -aG input "$(id -un)"when authorized; log out/in afterwards. The user completes Doubao web sign-in, the microphone check, trigger selection, and the voice test. Never print credentials or copy them into the repository. - Verify the real workflow and report the result.
--checkonly proves runtime prerequisites. In a disposable text-editor document, verify tap/start/tap/stop, hold/release, a single overlay, and exactly one paste after finishing. Test double-tap Enter only in that document. If polishing is enabled, verify that a pause previews text, finishing pastes it, and timeout falls back to the original. Report the installed version/path, startup owner, completed checks and any user steps still pending. Do not claim physical input or sign-in passed from unit tests.
Preserve user settings and sign-in data during upgrades. Retain LICENSE and
NOTICE in any redistributed copy. Read INSTALL.md for the
full lifecycle and recovery instructions.
Development and local packaging
Development and AI-assisted work follow DEVELOPMENT.md and CONTRIBUTING.md. Bug fixes require reproducible verification and before/after screenshots for each UI verification round, with test or log evidence for behavior that screenshots cannot prove. Report any unverified scope.
See CONTRIBUTING.md for make check,
security reporting, and
changes. The legacy Debian scripts are not the release path for
this candidate and have not passed the new installer acceptance.
make test
.venv/bin/python -m compileall -q src/doubao_input packaging
.venv/bin/python -m pip wheel -w dist/wheelhouse -r packaging/runtime-requirements.txt
python3 packaging/build-release.py
Native X11's opt-in desktop test creates a disposable Xephyr/XFWM session and checks Unicode/multiline paste, terminal shortcuts, cancellation, focus changes and overlay focus. It uses a separate clipboard without CopyQ; optional PyQt6 and Electron fixtures extend toolkit coverage. Avoid typing during the test:
timeout --kill-after=5s 50s env PYTHONPATH=src python3 tests/manual/x11.py --run
This requires Xephyr, xfwm4, xfce4-terminal, xdotool, xclip and /dev/uinput access.
Real microphone dictation, other window managers and Hyprland acceptance remain
separate checks.
Archives are local artifacts, not published releases. Validate both installation and real desktop workflows before distributing them. No GitHub upload is performed by any build or installation script.
Continuous integration and releases
Pull requests and pushes test core behavior on Python 3.11–3.14, run the complete GTK-aware suite, lint and compile the source, enforce whole-package branch coverage, validate package metadata and scan for secrets. The current whole-package branch coverage floor is 55%; desktop UI, WebKit and real-device paths remain included in the denominator.
The current release version is 1.8.2. A v1.8.2 tag must match every embedded
version before CI can publish. Tag releases rebuild both offline app and Omarchy
plugin archives for Python 3.11–3.14 and attach SHA-256 checksums. A manually started
release workflow builds artifacts for inspection but does not publish them. Real
login, microphone, global-key and desktop behavior still require the manual checklist.
Credits and licensing
Doubao Say maintains a separate Git history; inherited code retains its upstream attribution and license notices.
Based on wurong98/doubao-input-for-linux. Its inherited attribution identifies lilong7676/doubao-murmur as the source of ASR and sign-in components. Thank you to both projects and their contributors. Original copyright notices and the MIT text are retained in LICENSE. See NOTICE for known provenance, inherited MIT attribution, and the separate distinction between the software license and Doubao service terms, and the dependency inventory for bundled dependencies.