Metadata-Version: 2.4
Name: handsfreed
Version: 0.2.0
Summary: Handsfree speech-to-text daemon for Linux
Author-email: Achyudh Ram <mail@achyudh.me>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/achyudh/handsfree
Project-URL: Repository, https://github.com/achyudh/handsfreed
Project-URL: Issues, https://github.com/achyudh/handsfreed/issues
Keywords: speech-to-text,speech recognition,whisper,transcription,dictation,vad,daemon,linux,offline,real-time
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: No Input/Output (Daemon)
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Multimedia :: Sound/Audio :: Speech
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: sounddevice>=0.5
Requires-Dist: numpy>=2.2
Requires-Dist: faster-whisper>=1.2.1
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.26; extra == "dev"
Dynamic: license-file

# handsfreed

[![CI](https://github.com/achyudh/handsfreed/actions/workflows/ci.yml/badge.svg)](https://github.com/achyudh/handsfreed/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/handsfreed.svg)](https://pypi.org/project/handsfreed/)
[![Python Versions](https://img.shields.io/pypi/pyversions/handsfreed.svg)](https://pypi.org/project/handsfreed/)
[![License](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)

`handsfreed` is a local, real-time speech-to-text daemon for Linux. It uses the `faster-whisper` library to provide high-quality, offline transcription.

This package is the daemon component of the [Handsfree](https://github.com/achyudh/handsfree) project. It is controlled by the [`handsfreectl`](https://crates.io/crates/handsfreectl) command-line tool.

## Installation

### Manual Installation

`handsfreed` requires `PortAudio`, which is a dependency of the `sounddevice` Python library. You must install the `PortAudio` library and its development headers using your system's package manager.

*   **Debian/Ubuntu:**
    ```bash
    sudo apt-get install libportaudio2 libportaudiocpp0 portaudio19-dev
    ```

*   **Fedora/CentOS/RHEL:**
    ```bash
    sudo dnf install portaudio-devel
    ```

*   **Arch Linux:**
    ```bash
    sudo pacman -S portaudio
    ```

The `handsfreed` daemon is controlled by the `handsfreectl` command-line tool. You must install it separately.

*   You can download pre-compiled binaries from the [handsfreectl releases page](https://github.com/achyudh/handsfreectl/releases).

*   If you have the Cargo installed, you can install `handsfreectl` from Crates.io:
    ```bash
    cargo install handsfreectl
    ```

Once the dependencies are installed, you can install `handsfreed` using `pip`:

```bash
pip install handsfreed
```

### Nix Flake

If you use the [Nix package manager](https://nixos.org/) with flakes enabled, the [Handsfree flake](https://github.com/achyudh/handsfree) provides both `handsfreectl` and `handsfreed` packages along with a Home Manager module to configure and manage the `handsfreed` daemon as a systemd service.

For detailed instructions on how to add the flake to your system and configure the service, please refer to the Handsfree flake's **[README](https://github.com/achyudh/handsfreed/blob/main/README.md)**.

## Usage

`handsfreed` is designed to be run as a background service.

1.  **Create a configuration file:**
    Create a configuration file at `~/.config/handsfree/config.toml`. You can start with the [example configuration](https://github.com/achyudh/handsfreed/blob/main/example.config.toml).

2.  **Run the daemon:** The daemon will start listening for commands from `handsfreectl`.
    ```bash
    handsfreed
    ```

3.  **Control with `handsfreectl`:**
    Use the `handsfreectl` CLI to start/stop transcription and check the status of the daemon.

## Configuration

`handsfreed` is configured via a TOML file located at `~/.config/handsfree/config.toml`. The configuration allows you to set up your audio input, Whisper model, VAD parameters, and more.

For a full list of configuration options, please see the [example configuration file](https://github.com/achyudh/handsfreed/blob/main/example.config.toml).

## License

This project is licensed under the GNU General Public License v3.0.
