# voiceType
Type with your voice.
## Features
- Press a hotkey (default: `Pause/Break` key) to start recording audio.
- Release the hotkey to stop recording.
- The recorded audio is transcribed to text (e.g., using OpenAI's Whisper model).
- The transcribed text is typed into the currently active application.
## Prerequisites
- Python 3.8+
- `pip` (Python package installer)
- For Linux installation: `systemd` (common in most modern Linux distributions).
- An OpenAI API Key (if using OpenAI for transcription).
## Installation
1. **Clone the repository (including submodules):**
```bash
git clone --recurse-submodules https://github.com/Adam-D-Lewis/voicetype.git
cd voicetype
```
If you already cloned without `--recurse-submodules`, initialize the submodules:
```bash
git submodule update --init --recursive
```
2. **Set up a Python virtual environment (recommended):**
```bash
python3 -m venv .venv
source .venv/bin/activate # On Windows, use `.venv\Scripts\activate`
```
3. **Install the package and its dependencies:**
This project uses `pyproject.toml` with `setuptools`. Install the `voicetype` package and its dependencies using pip:
```bash
pip install .
```
This command reads `pyproject.toml`, installs all necessary dependencies, and makes the `voicetype` script available (callable as `python -m voicetype`).
4. **Run the installation script (for Linux with systemd):**
If you are on Linux and want to run VoiceType as a systemd user service (recommended for background operation and auto-start on login), use the CLI entrypoint installed with the package. Ensure you're in the environment where you installed dependencies.
```bash
voicetype install
```
During install you'll be prompted to choose a provider [litellm, local]. If you choose `litellm` you'll then be prompted for your `OPENAI_API_KEY`. Values are stored in `~/.config/voicetype/.env` with restricted permissions.
The script will:
- Create a systemd service file at `~/.config/systemd/user/voicetype.service`.
- Store your OpenAI API key in `~/.config/voicetype/.env` (with restricted permissions).
- Reload the systemd user daemon, enable the `voicetype.service` to start on login, and start it immediately.
For other operating systems, or if you prefer not to use the systemd service on Linux, you can run the application directly after installation (see Usage).
## Configuration
VoiceType can be configured using a `settings.toml` file. The application looks for configuration files in the following locations (in priority order):
1. `./settings.toml` - Current directory
2. `~/.config/voicetype/settings.toml` - User config directory
3. `/etc/voicetype/settings.toml` - System-wide config
### Available Settings
Create a `settings.toml` file with any of the following options:
```toml
[voice]
# Provider for voice transcription (default: "local")
# Options: "litellm" (requires OpenAI API key) or "local" (uses faster-whisper locally)
provider = "local"
# Minimum duration (in seconds) of audio to process (default: 0.25)
# Filters out accidental hotkey presses
minimum_duration = 0.25
[hotkey]
# Global hotkey to trigger recording (default: "<pause>")
# Use pynput format, e.g., "<f12>", "<ctrl>+<alt>+r", "<pause>"
hotkey = "<pause>"
```
**Note:** If you used `voicetype install` and configured litellm during installation, your API key is stored separately in `~/.config/voicetype/.env`.
## Usage
- **If using the Linux systemd service:** The service will start automatically on login. VoiceType will be listening for the hotkey in the background.
- **To run manually (e.g., for testing or on non-Linux systems):**
Activate your virtual environment and run:
```bash
python -m voicetype
```
**Using the Hotkey:**
1. Press and hold the configured hotkey (default is `Pause/Break`).
2. Speak clearly.
3. Release the hotkey to stop recording.
4. The transcribed text should then be typed into your currently active application.
## Managing the Service (Linux with systemd)
If you used `voicetype install`:
- **Check service status:**
```bash
voicetype status
```
Alternatively:
```bash
systemctl --user status voicetype.service
```
- **View service logs:**
```bash
journalctl --user -u voicetype.service -f
```
- **Restart the service:**
(e.g., after changing the `OPENAI_API_KEY` in `~/.config/voicetype/.env`)
```bash
systemctl --user restart voicetype.service
```
- **Stop the service:**
```bash
systemctl --user stop voicetype.service
```
- **Start the service manually (if not enabled to start on login):**
```bash
systemctl --user start voicetype.service
```
- **Disable auto-start on login:**
```bash
systemctl --user disable voicetype.service
```
- **Enable auto-start on login (if previously disabled):**
```bash
systemctl --user enable voicetype.service
```
## Uninstallation (Linux with systemd)
To stop the service, disable auto-start, and remove the systemd service file and associated configuration:
```bash
voicetype uninstall
```
This will:
- Stop and disable the `voicetype.service`.
- Remove the service file (`~/.config/systemd/user/voicetype.service`).
- Remove the environment file (`~/.config/voicetype/.env` containing your API key).
- Attempt to remove the application configuration directory (`~/.config/voicetype`) if it's empty.
If you installed the package using `pip install .`, you can uninstall it from your Python environment with:
```bash
pip uninstall voicetype
```
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
## Architecture
VoiceType uses a pipeline-based architecture with resource-based concurrency control. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for:
- Complete system architecture diagram (Mermaid UML)
- Component descriptions and responsibilities
- Execution flow and lifecycle
- Design principles and extension points
## Development
Preferred workflow: Pixi
- Pixi is the preferred way to create and manage the development environment for this project. It ensures reproducible, cross-platform setups using the definitions in environment.yaml and pyproject.toml.
Setup Pixi
- Install Pixi:
- Linux/macOS (official installer):
- curl -fsSL https://pixi.sh/install.sh | bash
- macOS (Homebrew):
- brew install prefix-dev/pixi/pixi
- Verify:
- pixi --version
Create and activate the environment
- From the project root:
- pixi install -e local
- pixi shell -e local
Run the application
- pixi run voicetype
- Equivalent to:
- python -m voicetype
Run tests
- If a test task is defined:
- pixi run test
- Otherwise (pytest directly):
- pixi run python -m pytest
Lint and format
- If tasks are defined:
- pixi run lint
- pixi run fmt
- Or run tools directly:
- pixi run ruff format
- pixi run ruff check .
Pre-commit hooks (recommended)
- Install hooks:
- pixi run pre-commit install
- Run on all files:
- pixi run pre-commit run --all-files
Alternative: Python venv (fallback)
- Ensure Python 3.11+ is installed.
- Create and activate a venv:
- python -m venv .venv
- source .venv/bin/activate
- Editable install with dev dependencies:
- pip install -U pip
- pip install -e ".[dev]"
- Run the app:
- python -m voicetype
Notes
- Dependency definitions live in pyproject.toml; additional environment details may be in environment.yaml.
- After changing dependencies, update pyproject.toml (and environment.yaml if needed), then run:
- pixi install
## License
This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "voiceType2",
"maintainer": null,
"docs_url": null,
"requires_python": "<=3.12",
"maintainer_email": null,
"keywords": "accessibility, speech-recognition, transcription, voice-typing",
"author": "Adam Lewis",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/c5/1b/fbed99478b5843990a75905ff0b46b8b9bc522eaa43284ddbce86ab08642/voicetype2-0.1.6.tar.gz",
"platform": null,
"description": "# voiceType\n\n\n\nType with your voice.\n\n## Features\n\n- Press a hotkey (default: `Pause/Break` key) to start recording audio.\n- Release the hotkey to stop recording.\n- The recorded audio is transcribed to text (e.g., using OpenAI's Whisper model).\n- The transcribed text is typed into the currently active application.\n\n## Prerequisites\n\n- Python 3.8+\n- `pip` (Python package installer)\n- For Linux installation: `systemd` (common in most modern Linux distributions).\n- An OpenAI API Key (if using OpenAI for transcription).\n\n## Installation\n\n1. **Clone the repository (including submodules):**\n ```bash\n git clone --recurse-submodules https://github.com/Adam-D-Lewis/voicetype.git\n cd voicetype\n ```\n\n If you already cloned without `--recurse-submodules`, initialize the submodules:\n ```bash\n git submodule update --init --recursive\n ```\n\n2. **Set up a Python virtual environment (recommended):**\n ```bash\n python3 -m venv .venv\n source .venv/bin/activate # On Windows, use `.venv\\Scripts\\activate`\n ```\n\n3. **Install the package and its dependencies:**\n This project uses `pyproject.toml` with `setuptools`. Install the `voicetype` package and its dependencies using pip:\n ```bash\n pip install .\n ```\n This command reads `pyproject.toml`, installs all necessary dependencies, and makes the `voicetype` script available (callable as `python -m voicetype`).\n\n4. **Run the installation script (for Linux with systemd):**\n If you are on Linux and want to run VoiceType as a systemd user service (recommended for background operation and auto-start on login), use the CLI entrypoint installed with the package. Ensure you're in the environment where you installed dependencies.\n ```bash\n voicetype install\n ```\n During install you'll be prompted to choose a provider [litellm, local]. If you choose `litellm` you'll then be prompted for your `OPENAI_API_KEY`. Values are stored in `~/.config/voicetype/.env` with restricted permissions.\n\n The script will:\n - Create a systemd service file at `~/.config/systemd/user/voicetype.service`.\n - Store your OpenAI API key in `~/.config/voicetype/.env` (with restricted permissions).\n - Reload the systemd user daemon, enable the `voicetype.service` to start on login, and start it immediately.\n\n For other operating systems, or if you prefer not to use the systemd service on Linux, you can run the application directly after installation (see Usage).\n\n## Configuration\n\nVoiceType can be configured using a `settings.toml` file. The application looks for configuration files in the following locations (in priority order):\n\n1. `./settings.toml` - Current directory\n2. `~/.config/voicetype/settings.toml` - User config directory\n3. `/etc/voicetype/settings.toml` - System-wide config\n\n### Available Settings\n\nCreate a `settings.toml` file with any of the following options:\n\n```toml\n[voice]\n# Provider for voice transcription (default: \"local\")\n# Options: \"litellm\" (requires OpenAI API key) or \"local\" (uses faster-whisper locally)\nprovider = \"local\"\n\n# Minimum duration (in seconds) of audio to process (default: 0.25)\n# Filters out accidental hotkey presses\nminimum_duration = 0.25\n\n[hotkey]\n# Global hotkey to trigger recording (default: \"<pause>\")\n# Use pynput format, e.g., \"<f12>\", \"<ctrl>+<alt>+r\", \"<pause>\"\nhotkey = \"<pause>\"\n```\n\n**Note:** If you used `voicetype install` and configured litellm during installation, your API key is stored separately in `~/.config/voicetype/.env`.\n\n## Usage\n\n- **If using the Linux systemd service:** The service will start automatically on login. VoiceType will be listening for the hotkey in the background.\n- **To run manually (e.g., for testing or on non-Linux systems):**\n Activate your virtual environment and run:\n ```bash\n python -m voicetype\n ```\n\n**Using the Hotkey:**\n1. Press and hold the configured hotkey (default is `Pause/Break`).\n2. Speak clearly.\n3. Release the hotkey to stop recording.\n4. The transcribed text should then be typed into your currently active application.\n\n## Managing the Service (Linux with systemd)\n\nIf you used `voicetype install`:\n\n- **Check service status:**\n ```bash\n voicetype status\n ```\n Alternatively:\n ```bash\n systemctl --user status voicetype.service\n ```\n\n- **View service logs:**\n ```bash\n journalctl --user -u voicetype.service -f\n ```\n\n- **Restart the service:**\n (e.g., after changing the `OPENAI_API_KEY` in `~/.config/voicetype/.env`)\n ```bash\n systemctl --user restart voicetype.service\n ```\n\n- **Stop the service:**\n ```bash\n systemctl --user stop voicetype.service\n ```\n\n- **Start the service manually (if not enabled to start on login):**\n ```bash\n systemctl --user start voicetype.service\n ```\n\n- **Disable auto-start on login:**\n ```bash\n systemctl --user disable voicetype.service\n ```\n\n- **Enable auto-start on login (if previously disabled):**\n ```bash\n systemctl --user enable voicetype.service\n ```\n\n## Uninstallation (Linux with systemd)\n\nTo stop the service, disable auto-start, and remove the systemd service file and associated configuration:\n```bash\nvoicetype uninstall\n```\nThis will:\n- Stop and disable the `voicetype.service`.\n- Remove the service file (`~/.config/systemd/user/voicetype.service`).\n- Remove the environment file (`~/.config/voicetype/.env` containing your API key).\n- Attempt to remove the application configuration directory (`~/.config/voicetype`) if it's empty.\n\nIf you installed the package using `pip install .`, you can uninstall it from your Python environment with:\n```bash\npip uninstall voicetype\n```\n\n## Contributing\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n\n## Architecture\n\nVoiceType uses a pipeline-based architecture with resource-based concurrency control. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for:\n- Complete system architecture diagram (Mermaid UML)\n- Component descriptions and responsibilities\n- Execution flow and lifecycle\n- Design principles and extension points\n\n## Development\n\nPreferred workflow: Pixi\n\n- Pixi is the preferred way to create and manage the development environment for this project. It ensures reproducible, cross-platform setups using the definitions in environment.yaml and pyproject.toml.\n\nSetup Pixi\n- Install Pixi:\n - Linux/macOS (official installer):\n - curl -fsSL https://pixi.sh/install.sh | bash\n - macOS (Homebrew):\n - brew install prefix-dev/pixi/pixi\n - Verify:\n - pixi --version\n\nCreate and activate the environment\n- From the project root:\n - pixi install -e local\n - pixi shell -e local\n\nRun the application\n- pixi run voicetype\n - Equivalent to:\n - python -m voicetype\n\nRun tests\n- If a test task is defined:\n - pixi run test\n- Otherwise (pytest directly):\n - pixi run python -m pytest\n\nLint and format\n- If tasks are defined:\n - pixi run lint\n - pixi run fmt\n- Or run tools directly:\n - pixi run ruff format\n - pixi run ruff check .\n\nPre-commit hooks (recommended)\n- Install hooks:\n - pixi run pre-commit install\n- Run on all files:\n - pixi run pre-commit run --all-files\n\nAlternative: Python venv (fallback)\n- Ensure Python 3.11+ is installed.\n- Create and activate a venv:\n - python -m venv .venv\n - source .venv/bin/activate\n- Editable install with dev dependencies:\n - pip install -U pip\n - pip install -e \".[dev]\"\n- Run the app:\n - python -m voicetype\n\nNotes\n- Dependency definitions live in pyproject.toml; additional environment details may be in environment.yaml.\n- After changing dependencies, update pyproject.toml (and environment.yaml if needed), then run:\n - pixi install\n## License\nThis project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE) file for details.\n",
"bugtrack_url": null,
"license": null,
"summary": "Type with your voice using hotkey-activated speech recognition",
"version": "0.1.6",
"project_urls": null,
"split_keywords": [
"accessibility",
" speech-recognition",
" transcription",
" voice-typing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ccbc5c385be05ed4d9772610b494245ebb1471195c6775f2fc43d35207197909",
"md5": "d37a1416da544f92b574437628d97cfb",
"sha256": "936c598f0fa829f5a7615e3fb15c681459b1499aca32efc85a30e30b886d2a0f"
},
"downloads": -1,
"filename": "voicetype2-0.1.6-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d37a1416da544f92b574437628d97cfb",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": "<=3.12",
"size": 306883,
"upload_time": "2025-10-20T03:17:24",
"upload_time_iso_8601": "2025-10-20T03:17:24.499548Z",
"url": "https://files.pythonhosted.org/packages/cc/bc/5c385be05ed4d9772610b494245ebb1471195c6775f2fc43d35207197909/voicetype2-0.1.6-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c51bfbed99478b5843990a75905ff0b46b8b9bc522eaa43284ddbce86ab08642",
"md5": "e59fac5210db487f477f38e9929a1313",
"sha256": "b7d509ca7a929451675e1ed45ab4b471f27be83c21a41797ed39faf48e8e31d5"
},
"downloads": -1,
"filename": "voicetype2-0.1.6.tar.gz",
"has_sig": false,
"md5_digest": "e59fac5210db487f477f38e9929a1313",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<=3.12",
"size": 438225,
"upload_time": "2025-10-20T03:17:25",
"upload_time_iso_8601": "2025-10-20T03:17:25.841763Z",
"url": "https://files.pythonhosted.org/packages/c5/1b/fbed99478b5843990a75905ff0b46b8b9bc522eaa43284ddbce86ab08642/voicetype2-0.1.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-20 03:17:25",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "voicetype2"
}
JSON