fala 0.0.1__tar.gz

fala-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivar Soares Urdalen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fala-0.0.1/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: fala
+Version: 0.0.1
+Summary: Voice dictation for Ubuntu/Wayland — hotkey-driven speech-to-text that types anywhere
+Author: Ivar Soares Urdalen
+Author-email: Ivar Soares Urdalen <ivar.urdalen@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Environment :: Console
+Requires-Dist: assemblyai
+Requires-Dist: peewee
+Requires-Dist: questionary
+Requires-Dist: openai
+Requires-Dist: rich
+Requires-Dist: secretstorage
+Requires-Dist: typer
+Requires-Dist: websockets>=14.0
+Requires-Dist: pyaudio>=0.2.11
+Requires-Dist: numpy>=1.24.0
+Requires-Python: >=3.11
+Project-URL: Source, https://github.com/ivarurdalen/fala
+Project-URL: Documentation, https://ivarurdalen.github.io/fala
+Project-URL: Changelog, https://github.com/ivarurdalen/fala/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# fala
+
+*fala* means "speak" in Portuguese.
+
+Voice dictation for Ubuntu/Wayland. Press a hotkey to start recording, press it again to stop — your speech is transcribed via the OpenAI API and typed wherever your cursor is.
+
+Works system-wide: terminals, browsers, text editors, anything.
+
+See [docs/architecture.md](docs/architecture.md) for a full diagram of how the components connect.
+
+## How it works
+
+1. Press your hotkey → recording starts (`parecord`)
+2. Speak
+3. Press hotkey again → recording stops, audio is sent to OpenAI for transcription, text is typed at the cursor via `ydotool`
+
+## System requirements
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+```bash
+sudo apt install -y ffmpeg portaudio19-dev pulseaudio-utils
+```
+
+`ydotool` needs access to the input subsystem. Add your user to the `input` group and create the udev rule:
+
+```bash
+sudo usermod -aG input $USER
+echo 'KERNEL=="uinput", MODE="0660", GROUP="input"' \
+    | sudo tee /etc/udev/rules.d/60-uinput.rules
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+Then log out and back in for the group change to take effect.
+
+### ydotool daemon
+
+The Ubuntu apt package for `ydotool` is too old to include `ydotoold`. Build and install the current version from source:
+
+```bash
+bash scripts/install_ydotool.sh
+```
+
+This clones, builds, installs, and starts the daemon as a systemd user service. Safe to re-run.
+
+## Installation
+
+Build and install `fala` as a global CLI tool using a wheel:
+
+```bash
+uv build
+uv tool install --force dist/*.whl
+```
+
+This makes `fala` available in your PATH everywhere, no virtualenv activation needed.
+
+To update after pulling changes:
+
+```bash
+uv build
+uv tool install --force dist/*.whl
+```
+
+## API key setup
+
+Store your OpenAI API key in the GNOME Keyring (encrypted at rest, unlocked automatically at login):
+
+```bash
+fala setup
+```
+
+You will be prompted to enter your key. It is stored securely and never written to disk in plaintext.
+
+Alternatively, set it as an environment variable (e.g. for CI or headless use):
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+The env var takes precedence over the keyring if both are set.
+
+## Hotkey setup
+
+Install/update helper scripts directly:
+
+```bash
+fala install-scripts
+```
+
+Or via guided setup:
+
+```bash
+fala setup
+```
+
+Register a GNOME keyboard shortcut. The script will ask you to physically press the key combination you want:
+
+```bash
+bash scripts/setup_keybinding.sh
+```
+
+To remove the shortcut:
+
+```bash
+bash scripts/setup_keybinding.sh --revert
+```
+
+`fala setup` is idempotent and safe to re-run.
+
+## CLI usage
+
+Record from microphone (press Enter to start, press Enter to stop):
+
+```bash
+fala record
+```
+
+Transcribe an existing audio file:
+
+```bash
+fala transcribe path/to/audio.wav
+```
+
+Live streaming transcription to terminal:
+
+```bash
+fala stream
+```
+
+By default, `fala stream` prints transcript deltas directly in the terminal and redirects noisy stderr output (for example ALSA/JACK warnings) to `~/.config/fala/stream.log`.
+Use `--type-into-active-window` to also inject text into the focused GUI input via `ydotool`.
+
+Create a high-clarity test fixture recording and generate a pytest integration test with the expected transcript baked into the test:
+
+```bash
+fala create-test-fixture clear_en_sentence --text "The quick brown fox jumps over the lazy dog."
+```
+
+Run integration tests (including realtime streaming integration with local WAV fixture):
+
+```bash
+just test-integration
+```
+
+Manual equivalent for all integration tests:
+
+```bash
+RUN_STREAMING_INTEGRATION=1 uv run pytest -m integration
+```
+
+Notes:
+- The integration test uses `tests/fixtures/clear_en_sentence.wav`.
+- It requires provider API keys to be available (`OPENAI_API_KEY` and/or `ASSEMBLYAI_API_KEY`); the `just` command loads both from keyring automatically if stored via `fala setup`.
+
+Show usage analytics from your transcription log:
+
+```bash
+fala stats
+fala stats --weeks 16
+fala stats --typing-wpm 45 --speaking-wpm 130
+```
+
+`fala stats` prints rich tables with weekly usage, average characters per transcription, provider mix, streaks, and activity trends. It also estimates time saved by speaking vs typing.
+
+Set defaults once (persisted in `~/.config/fala/config.toml`):
+
+```bash
+fala config --typing-wpm 40 --speaking-wpm 120 --avg-characters-per-word 5
+fala config --assemblyai-model u3-rt-pro
+```
+
+These defaults are used by `fala stats` unless you override them with command flags.

fala-0.0.1/README.md

@@ -0,0 +1,173 @@
+# fala
+
+*fala* means "speak" in Portuguese.
+
+Voice dictation for Ubuntu/Wayland. Press a hotkey to start recording, press it again to stop — your speech is transcribed via the OpenAI API and typed wherever your cursor is.
+
+Works system-wide: terminals, browsers, text editors, anything.
+
+See [docs/architecture.md](docs/architecture.md) for a full diagram of how the components connect.
+
+## How it works
+
+1. Press your hotkey → recording starts (`parecord`)
+2. Speak
+3. Press hotkey again → recording stops, audio is sent to OpenAI for transcription, text is typed at the cursor via `ydotool`
+
+## System requirements
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+
+```bash
+sudo apt install -y ffmpeg portaudio19-dev pulseaudio-utils
+```
+
+`ydotool` needs access to the input subsystem. Add your user to the `input` group and create the udev rule:
+
+```bash
+sudo usermod -aG input $USER
+echo 'KERNEL=="uinput", MODE="0660", GROUP="input"' \
+    | sudo tee /etc/udev/rules.d/60-uinput.rules
+sudo udevadm control --reload-rules && sudo udevadm trigger
+```
+
+Then log out and back in for the group change to take effect.
+
+### ydotool daemon
+
+The Ubuntu apt package for `ydotool` is too old to include `ydotoold`. Build and install the current version from source:
+
+```bash
+bash scripts/install_ydotool.sh
+```
+
+This clones, builds, installs, and starts the daemon as a systemd user service. Safe to re-run.
+
+## Installation
+
+Build and install `fala` as a global CLI tool using a wheel:
+
+```bash
+uv build
+uv tool install --force dist/*.whl
+```
+
+This makes `fala` available in your PATH everywhere, no virtualenv activation needed.
+
+To update after pulling changes:
+
+```bash
+uv build
+uv tool install --force dist/*.whl
+```
+
+## API key setup
+
+Store your OpenAI API key in the GNOME Keyring (encrypted at rest, unlocked automatically at login):
+
+```bash
+fala setup
+```
+
+You will be prompted to enter your key. It is stored securely and never written to disk in plaintext.
+
+Alternatively, set it as an environment variable (e.g. for CI or headless use):
+
+```bash
+export OPENAI_API_KEY="sk-..."
+```
+
+The env var takes precedence over the keyring if both are set.
+
+## Hotkey setup
+
+Install/update helper scripts directly:
+
+```bash
+fala install-scripts
+```
+
+Or via guided setup:
+
+```bash
+fala setup
+```
+
+Register a GNOME keyboard shortcut. The script will ask you to physically press the key combination you want:
+
+```bash
+bash scripts/setup_keybinding.sh
+```
+
+To remove the shortcut:
+
+```bash
+bash scripts/setup_keybinding.sh --revert
+```
+
+`fala setup` is idempotent and safe to re-run.
+
+## CLI usage
+
+Record from microphone (press Enter to start, press Enter to stop):
+
+```bash
+fala record
+```
+
+Transcribe an existing audio file:
+
+```bash
+fala transcribe path/to/audio.wav
+```
+
+Live streaming transcription to terminal:
+
+```bash
+fala stream
+```
+
+By default, `fala stream` prints transcript deltas directly in the terminal and redirects noisy stderr output (for example ALSA/JACK warnings) to `~/.config/fala/stream.log`.
+Use `--type-into-active-window` to also inject text into the focused GUI input via `ydotool`.
+
+Create a high-clarity test fixture recording and generate a pytest integration test with the expected transcript baked into the test:
+
+```bash
+fala create-test-fixture clear_en_sentence --text "The quick brown fox jumps over the lazy dog."
+```
+
+Run integration tests (including realtime streaming integration with local WAV fixture):
+
+```bash
+just test-integration
+```
+
+Manual equivalent for all integration tests:
+
+```bash
+RUN_STREAMING_INTEGRATION=1 uv run pytest -m integration
+```
+
+Notes:
+- The integration test uses `tests/fixtures/clear_en_sentence.wav`.
+- It requires provider API keys to be available (`OPENAI_API_KEY` and/or `ASSEMBLYAI_API_KEY`); the `just` command loads both from keyring automatically if stored via `fala setup`.
+
+Show usage analytics from your transcription log:
+
+```bash
+fala stats
+fala stats --weeks 16
+fala stats --typing-wpm 45 --speaking-wpm 130
+```
+
+`fala stats` prints rich tables with weekly usage, average characters per transcription, provider mix, streaks, and activity trends. It also estimates time saved by speaking vs typing.
+
+Set defaults once (persisted in `~/.config/fala/config.toml`):
+
+```bash
+fala config --typing-wpm 40 --speaking-wpm 120 --avg-characters-per-word 5
+fala config --assemblyai-model u3-rt-pro
+```
+
+These defaults are used by `fala stats` unless you override them with command flags.

fala-0.0.1/pyproject.toml

@@ -0,0 +1,107 @@
+[project]
+name = "fala"
+version = "0.0.1"
+description = "Voice dictation for Ubuntu/Wayland — hotkey-driven speech-to-text that types anywhere"
+license = "MIT"
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [
+    { name = "Ivar Soares Urdalen", email = "ivar.urdalen@gmail.com" }
+]
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Intended Audience :: Developers",
+    "Topic :: Multimedia :: Sound/Audio :: Speech",
+    "Operating System :: POSIX :: Linux",
+    "Environment :: Console",
+]
+dependencies = [
+    "assemblyai",
+    "peewee",
+    "questionary",
+    "openai",
+    "rich",
+    "secretstorage",
+    "typer",
+    "websockets>=14.0",
+    "pyaudio>=0.2.11",
+    "numpy>=1.24.0",
+]
+
+[project.scripts]
+fala = "fala.cli:main"
+
+[project.urls]
+Source = "https://github.com/ivarurdalen/fala"
+Documentation = "https://ivarurdalen.github.io/fala"
+Changelog = "https://github.com/ivarurdalen/fala/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.10.0,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "ty",
+    "coverage",
+    "pytest",
+    "pytest-cov",
+    "ruff",
+    "zensical>=0.0.24",
+]
+
+[tool.ruff]
+line-length = 100
+indent-width = 4
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors (style issues)
+    "F",      # Pyflakes (code errors)
+    "B",      # flake8-bugbear (bug prevention)
+    "S",      # bandit (security issues)
+    "RUF",    # ruff-specific rules
+    "N",      # pep8-naming (naming conventions)
+    "W",      # pycodestyle warnings
+    "I",      # isort (import formatting)
+    "C90",
+    "DOC",
+    "D",
+    "D213",
+    "PLE",
+    "UP",
+    "PERF",   # performance issues
+    "PIE",    # flake8-pie (unnecessary code)
+    "TID",    # flake8-tidy-imports (import best practices)
+    "ASYNC",  # async/await best practices
+    "RET",    # flake8-return (return improvements)
+]
+extend-ignore = [
+    "B008",
+    "D212",
+    "E501",
+    "S603",
+    "S101",
+    "C901",  # stream function is inherently complex due to async/audio handling
+    "S607",  # ydotool and wl-copy are standard system tools
+]
+
+fixable = ["ALL"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false
+line-ending = "auto"
+
+[tool.pytest.ini_options]
+markers = [
+    "integration: marks tests that call external transcription providers",
+]

fala-0.0.1/src/fala/__init__.py

@@ -0,0 +1,3 @@
+"""fala package."""
+
+__all__ = []

fala-0.0.1/src/fala/audio_capture.py

@@ -0,0 +1,156 @@
+"""Audio capture from microphone in real-time."""
+
+import threading
+import time
+from collections.abc import Iterator
+from pathlib import Path
+from typing import Self
+
+import pyaudio
+
+# Audio configuration for transcription APIs
+SAMPLE_RATE = 16000
+CHANNELS = 1
+FORMAT = pyaudio.paInt16
+FRAMES_PER_BUFFER = 800  # 50ms at 16kHz
+
+
+class AudioCapture:
+    """Captures audio from microphone and yields chunks in real-time."""
+
+    def __init__(
+        self,
+        device_index: int | None = None,
+        sample_rate: int = SAMPLE_RATE,
+        channels: int = CHANNELS,
+        frames_per_buffer: int = FRAMES_PER_BUFFER,
+    ) -> None:
+        """Initialize audio capture with device and format settings."""
+        self.sample_rate = sample_rate
+        self.channels = channels
+        self.frames_per_buffer = frames_per_buffer
+        self.device_index = device_index
+        self._pyaudio: pyaudio.PyAudio | None = None
+        self._stream: pyaudio.Stream | None = None
+        self._stop_event = threading.Event()
+
+    def __enter__(self) -> Self:
+        """Context manager entry: start capture."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Context manager exit: stop capture."""
+        self.stop()
+
+    def start(self) -> None:
+        """Open the audio stream for capture."""
+        self._pyaudio = pyaudio.PyAudio()
+        self._stream = self._pyaudio.open(
+            format=FORMAT,
+            channels=self.channels,
+            rate=self.sample_rate,
+            input=True,
+            frames_per_buffer=self.frames_per_buffer,
+            input_device_index=self.device_index,
+        )
+        self._stop_event.clear()
+
+    def stop(self) -> None:
+        """Stop capture and release resources."""
+        self.request_stop()
+        if self._stream:
+            try:
+                self._stream.stop_stream()
+                self._stream.close()
+            except Exception:  # noqa: S110
+                pass
+            finally:
+                self._stream = None
+        if self._pyaudio:
+            try:
+                self._pyaudio.terminate()
+            except Exception:  # noqa: S110
+                pass
+            finally:
+                self._pyaudio = None
+
+    def request_stop(self) -> None:
+        """Signal the capture loop to stop without tearing down audio resources."""
+        self._stop_event.set()
+
+    def chunks(self) -> Iterator[bytes]:
+        """Yield audio chunks from the microphone."""
+        if self._stream is None:
+            raise RuntimeError("AudioCapture not started. Call start() first.")
+        # Capture local reference to avoid None during iteration
+        stream = self._stream
+        while not self._stop_event.is_set():
+            try:
+                assert stream is not None  # for type checker
+                data = stream.read(self.frames_per_buffer, exception_on_overflow=False)
+                yield data
+            except Exception as e:
+                print(f"Audio capture error: {e}", flush=True)
+                if self._stop_event.is_set():
+                    break
+                time.sleep(0.01)
+
+    @staticmethod
+    def list_devices() -> list[dict]:
+        """Return list of available audio input devices."""
+        p = pyaudio.PyAudio()
+        devices = []
+        try:
+            for i in range(p.get_device_count()):
+                info = p.get_device_info_by_index(i)
+                # Cast to int to satisfy type checker
+                if int(info["maxInputChannels"]) > 0:
+                    devices.append(
+                        {
+                            "index": i,
+                            "name": info["name"],
+                            "channels": int(info["maxInputChannels"]),
+                            "sample_rate": int(info["defaultSampleRate"]),
+                        }
+                    )
+        finally:
+            p.terminate()
+        return devices
+
+
+def record_to_file(
+    device_index: int | None,
+    duration_seconds: float,
+    output_path: Path,
+    sample_rate: int = SAMPLE_RATE,
+    channels: int = CHANNELS,
+) -> None:
+    """Record audio for a fixed duration and save to WAV file."""
+    import wave
+
+    p = pyaudio.PyAudio()
+    try:
+        stream = p.open(
+            format=FORMAT,
+            channels=channels,
+            rate=sample_rate,
+            input=True,
+            frames_per_buffer=FRAMES_PER_BUFFER,
+            input_device_index=device_index,
+        )
+        frames = []
+        chunks_needed = int(duration_seconds * sample_rate / FRAMES_PER_BUFFER)
+        for _ in range(chunks_needed):
+            data = stream.read(FRAMES_PER_BUFFER, exception_on_overflow=False)
+            frames.append(data)
+        stream.stop_stream()
+        stream.close()
+
+        with wave.open(str(output_path), "wb") as wf:
+            wf.setnchannels(channels)
+            wf.setsampwidth(p.get_sample_size(FORMAT))
+            wf.setframerate(sample_rate)
+            wf.writeframes(b"".join(frames))
+    finally:
+        p.terminate()