Add documentation and basic tests
This commit is contained in:
jatinkrmalik
@@ -0,0 +1,93 @@
|
||||
# Installation Guide
|
||||
|
||||
This guide provides instructions for installing and setting up Ubuntu Voice Typing.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Ubuntu 22.04 or newer
|
||||
- Python 3.6 or newer
|
||||
- Dependencies for speech recognition and text injection
|
||||
|
||||
## Basic Installation
|
||||
|
||||
### 1. Install System Dependencies
|
||||
|
||||
```bash
|
||||
# For X11 environments
|
||||
sudo apt install xdotool python3-pip python3-gi gir1.2-appindicator3-0.1
|
||||
|
||||
# For Wayland environments
|
||||
sudo apt install wtype python3-pip python3-gi gir1.2-appindicator3-0.1
|
||||
# OR alternatively for Wayland
|
||||
sudo apt install ydotool python3-pip python3-gi gir1.2-appindicator3-0.1
|
||||
```
|
||||
|
||||
### 2. Clone the Repository
|
||||
|
||||
```bash
|
||||
git clone https://github.com/ubuntu-voice-typing/ubuntu-voice-typing.git
|
||||
cd ubuntu-voice-typing
|
||||
```
|
||||
|
||||
### 3. Install Python Dependencies
|
||||
|
||||
```bash
|
||||
# Basic installation
|
||||
pip3 install --user .
|
||||
|
||||
# With Whisper support (requires more resources)
|
||||
pip3 install --user ".[whisper]"
|
||||
|
||||
# For development
|
||||
pip3 install --user ".[dev]"
|
||||
```
|
||||
|
||||
### 4. Run the Application
|
||||
|
||||
```bash
|
||||
# Basic usage
|
||||
ubuntu-voice-typing
|
||||
|
||||
# With debug logging
|
||||
ubuntu-voice-typing --debug
|
||||
|
||||
# With Whisper instead of VOSK
|
||||
ubuntu-voice-typing --engine whisper
|
||||
|
||||
# Force Wayland mode
|
||||
ubuntu-voice-typing --wayland
|
||||
```
|
||||
|
||||
## Advanced Installation
|
||||
|
||||
### Custom Model Sizes
|
||||
|
||||
By default, a small model will be downloaded and used. You can use larger models for improved accuracy:
|
||||
|
||||
```bash
|
||||
ubuntu-voice-typing --model medium
|
||||
# or
|
||||
ubuntu-voice-typing --model large
|
||||
```
|
||||
|
||||
Note that larger models require more RAM and may have longer initialization times, but provide better recognition accuracy.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No audio input detected
|
||||
|
||||
- Check that your microphone is connected and working
|
||||
- Verify your system audio settings
|
||||
- Run with `--debug` flag to see detailed logs
|
||||
|
||||
### Text injection not working
|
||||
|
||||
- For X11: Ensure xdotool is installed
|
||||
- For Wayland: Ensure wtype or ydotool is installed
|
||||
- Some applications may have security measures that prevent text injection
|
||||
|
||||
### Recognition is inaccurate
|
||||
|
||||
- Try a larger model size (`--model medium` or `--model large`)
|
||||
- Ensure your microphone is positioned correctly
|
||||
- Speak clearly and at a moderate pace
|
||||
@@ -0,0 +1,78 @@
|
||||
# User Guide
|
||||
|
||||
This guide explains how to use Ubuntu Voice Typing effectively.
|
||||
|
||||
## Getting Started
|
||||
|
||||
After installing Ubuntu Voice Typing (see the [Installation Guide](INSTALL.md)), you can start the application from the terminal or add it to your startup applications.
|
||||
|
||||
## Basic Usage
|
||||
|
||||
### Starting and Stopping Voice Typing
|
||||
|
||||
1. **Launch the application**: Run `ubuntu-voice-typing` in a terminal or launch it from your application menu
|
||||
2. **Find the tray icon**: Look for the microphone icon in your system tray
|
||||
3. **Start voice typing**: Click the tray icon and select "Start Voice Typing" from the menu
|
||||
4. **Speak clearly**: As you speak, your words will be transcribed into the currently focused application
|
||||
5. **Stop voice typing**: Click the tray icon and select "Stop Voice Typing" when you're done
|
||||
|
||||
### Understanding the Status Icons
|
||||
|
||||
- **Microphone off** (gray): Voice typing is inactive
|
||||
- **Microphone on** (blue): Voice typing is active and listening
|
||||
- **Microphone processing** (orange): Voice typing is processing your speech
|
||||
|
||||
## Voice Commands
|
||||
|
||||
Ubuntu Voice Typing supports several commands that you can speak to control formatting:
|
||||
|
||||
| Command | Action |
|
||||
|---------|--------|
|
||||
| "new line" or "new paragraph" | Inserts a line break |
|
||||
| "period" or "full stop" | Types a period (.) |
|
||||
| "comma" | Types a comma (,) |
|
||||
| "question mark" | Types a question mark (?) |
|
||||
| "exclamation point" or "exclamation mark" | Types an exclamation point (!) |
|
||||
| "semicolon" | Types a semicolon (;) |
|
||||
| "colon" | Types a colon (:) |
|
||||
| "delete that" or "scratch that" | Deletes the last sentence |
|
||||
| "capitalize" or "uppercase" | Capitalizes the next word |
|
||||
| "all caps" | Makes the next word ALL CAPS |
|
||||
|
||||
## Tips for Better Recognition
|
||||
|
||||
1. **Use a good microphone**: A quality microphone significantly improves recognition accuracy
|
||||
2. **Speak clearly**: Enunciate your words clearly but naturally
|
||||
3. **Moderate pace**: Don't speak too quickly or too slowly
|
||||
4. **Quiet environment**: Minimize background noise when possible
|
||||
5. **Learn commands**: Familiarize yourself with voice commands for punctuation and formatting
|
||||
6. **Use larger models**: For better accuracy, use `ubuntu-voice-typing --model medium` or `--model large`
|
||||
|
||||
## Customization
|
||||
|
||||
### Keyboard Shortcuts
|
||||
|
||||
Ubuntu Voice Typing supports global keyboard shortcuts for starting and stopping voice typing:
|
||||
|
||||
1. Open the application settings from the tray icon menu
|
||||
2. Go to the "Shortcuts" tab
|
||||
3. Set your preferred keyboard shortcut (default is Alt+Shift+V)
|
||||
|
||||
### Model Settings
|
||||
|
||||
You can change the speech recognition model for better accuracy or faster performance:
|
||||
|
||||
1. Open settings from the tray icon menu
|
||||
2. Go to the "Recognition" tab
|
||||
3. Select your preferred model size
|
||||
4. Choose between VOSK (offline, faster) and Whisper (offline, more accurate)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
If you encounter issues, check the [Installation Guide](INSTALL.md) troubleshooting section or run the application with debug logging:
|
||||
|
||||
```bash
|
||||
ubuntu-voice-typing --debug
|
||||
```
|
||||
|
||||
Check the logs for error messages and possible solutions.
|
||||
@@ -0,0 +1,77 @@
|
||||
"""
|
||||
Basic tests for the Ubuntu Voice Typing application.
|
||||
"""
|
||||
|
||||
import unittest
|
||||
from unittest.mock import MagicMock, patch
|
||||
|
||||
from src.speech_recognition.recognition_manager import SpeechRecognitionManager, RecognitionState
|
||||
from src.text_injection.text_injector import TextInjector, DesktopEnvironment
|
||||
|
||||
|
||||
class TestSpeechRecognition(unittest.TestCase):
|
||||
"""Test cases for the speech recognition manager."""
|
||||
|
||||
@patch('src.speech_recognition.recognition_manager.os.makedirs')
|
||||
def test_init_state(self, mock_makedirs):
|
||||
"""Test the initial state of the speech recognition manager."""
|
||||
manager = SpeechRecognitionManager(engine="vosk", model_size="small")
|
||||
self.assertEqual(manager.state, RecognitionState.IDLE)
|
||||
self.assertEqual(manager.engine, "vosk")
|
||||
self.assertEqual(manager.model_size, "small")
|
||||
|
||||
@patch('src.speech_recognition.recognition_manager.os.makedirs')
|
||||
def test_callbacks(self, mock_makedirs):
|
||||
"""Test callback registration and invocation."""
|
||||
manager = SpeechRecognitionManager(engine="vosk", model_size="small")
|
||||
|
||||
# Mock callbacks
|
||||
text_callback = MagicMock()
|
||||
state_callback = MagicMock()
|
||||
|
||||
# Register callbacks
|
||||
manager.register_text_callback(text_callback)
|
||||
manager.register_state_callback(state_callback)
|
||||
|
||||
# Verify callbacks were registered
|
||||
self.assertIn(text_callback, manager.text_callbacks)
|
||||
self.assertIn(state_callback, manager.state_callbacks)
|
||||
|
||||
# Test state update
|
||||
manager._update_state(RecognitionState.LISTENING)
|
||||
state_callback.assert_called_once_with(RecognitionState.LISTENING)
|
||||
|
||||
|
||||
class TestTextInjection(unittest.TestCase):
|
||||
"""Test cases for the text injector."""
|
||||
|
||||
@patch('src.text_injection.text_injector.shutil.which')
|
||||
@patch('src.text_injection.text_injector.TextInjector._detect_environment')
|
||||
def test_init_x11(self, mock_detect, mock_which):
|
||||
"""Test initialization in X11 environment."""
|
||||
mock_detect.return_value = DesktopEnvironment.X11
|
||||
mock_which.return_value = '/usr/bin/xdotool' # Simulate xdotool exists
|
||||
|
||||
injector = TextInjector()
|
||||
self.assertEqual(injector.environment, DesktopEnvironment.X11)
|
||||
|
||||
@patch('src.text_injection.text_injector.subprocess.run')
|
||||
@patch('src.text_injection.text_injector.shutil.which')
|
||||
@patch('src.text_injection.text_injector.TextInjector._detect_environment')
|
||||
def test_inject_text_x11(self, mock_detect, mock_which, mock_run):
|
||||
"""Test text injection in X11 environment."""
|
||||
mock_detect.return_value = DesktopEnvironment.X11
|
||||
mock_which.return_value = '/usr/bin/xdotool'
|
||||
|
||||
injector = TextInjector()
|
||||
injector.inject_text("Hello, world!")
|
||||
|
||||
mock_run.assert_called_once()
|
||||
args, kwargs = mock_run.call_args
|
||||
self.assertEqual(args[0][0], "xdotool")
|
||||
self.assertEqual(args[0][2], "--clearmodifiers")
|
||||
self.assertEqual(args[0][3], "Hello, world!")
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
unittest.main()
|
||||
Reference in New Issue
Block a user