Skip to content

TuxFlow 0.1.0a1 — first alpha

Pre-release
Pre-release

Choose a tag to compare

View all tags
@Robertg761 Robertg761 released this 27 Jul 02:51
v0.1.0a1
29f11e5

TuxFlow is a free, local-first voice dictation app for Linux and macOS. Hold a
global shortcut, speak, release it, and a local Whisper model transcribes and
pastes into whatever app you were already in. No account, no subscription, no
API key, and no audio leaves the machine.

This is the first alpha. It works end to end, but it has had one user on one
machine — expect rough edges, and please file issues.

Install

Linux — download the AppImage

chmod +x TuxFlow-0.1.0a1-x86_64.AppImage
./TuxFlow-0.1.0a1-x86_64.AppImage doctor
./TuxFlow-0.1.0a1-x86_64.AppImage          # opens the control center

It carries its own Python, GTK 4, libadwaita, and faster-whisper. It needs glibc
2.39 or newer, so Ubuntu 24.04+, Fedora 40+, or Debian 13+.

A recorder (pw-record, arecord, or ffmpeg), a clipboard tool
(wl-clipboard or xclip), and ydotool/wtype for automatic paste stay on
the host deliberately — they talk to PipeWire, the compositor, and /dev/uinput,
and the host's own copies do that far better than a bundled one could. Most
desktop installs already have all three, and doctor names anything missing.

The AppImage does not start at login by itself; run ./TuxFlow-*.AppImage daemon
from your session's autostart, or use the installer below for a managed service.

No macOS binary yet — building one that macOS will actually open needs an Apple
Developer signature. macOS installs from source for now.

Either platform — install from source

git clone https://github.com/Robertg761/TuxFlow.git
cd TuxFlow
./scripts/install.sh

The installer never touches system Python. It installs desktop packages with
dnf/apt/pacman/zypper or Homebrew, builds an isolated environment under
~/.local/share/tuxflow/venv, links ~/.local/bin/tuxflow, adds a launcher
entry, starts a login service, and finishes with tuxflow doctor.

Remove it again with ./scripts/uninstall.sh (--purge also deletes settings,
models, and history).

What works

  • Hold-to-dictate global shortcut — the XDG Desktop Portal on Linux, a Quartz
    event tap (hold 🌐 fn) on macOS
  • Recording via PipeWire, ALSA, or FFmpeg on Linux; AVFoundation or SoX on macOS
  • Local transcription with tiny through large-v3 and turbo
  • Clipboard and automatic paste on Wayland, X11, and macOS
  • GTK 4 / Libadwaita control center, local history, dictionary replacements,
    voice snippets, filler-word cleanup, spoken punctuation
  • A CLI: tuxflow toggle, status, transcribe, doctor

Known limitations

  • macOS is essentially unverified. Every macOS backend was written and
    tested on Fedora. CI runs the test suite, imports, and tuxflow doctor on
    macOS runners, but nothing has exercised the event tap, the keycodes, the
    permission prompts, or real recording on a Mac. Treat macOS as experimental
    and please report what breaks.
  • Linux is verified on Fedora 44 / Wayland / PipeWire only. Other distributions
    and X11 should work but have not been run.
  • Automatic paste on Wayland needs /dev/uinput access for ydotool. Without it
    TuxFlow copies to the clipboard and tells you to press Ctrl+V. Rerun the
    installer with --with-uinput to set it up.
  • The first dictation downloads the model (~500 MB for the default small).
  • The AppImage is x86_64 only, and it has been run on Fedora 44 / KDE / Wayland
    and on an Ubuntu 24.04 CI runner — nowhere else yet.
  • No Flatpak, no Homebrew tap, no distro packages, and no macOS binary yet.

Requirements

Python 3.11+, a desktop session, and a microphone. Linux: GTK 4, Libadwaita,
PyGObject, a recorder, and wl-clipboard — the installer handles these on Fedora,
Ubuntu/Debian, Arch, and openSUSE. macOS: 12 or newer with Homebrew.

Start troubleshooting with tuxflow doctor; it names your platform and checks
each integration point separately.

Assets 3
Loading