### Start TalkType Python Backend (Installed)

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

If the TalkType Python backend is installed system-wide, start it using this command. The GNOME extension connects to this service.

```bash
talktype-tray
```

--------------------------------

### Build and Install GNOME Extension from ZIP

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Build a ZIP package of the extension and install it using the `gnome-extensions` command. This is an alternative to manual installation.

```bash
cd gnome-extension
zip -r talktype@ronb1964.github.io.zip talktype@ronb1964.github.io/
gnome-extensions install talktype@ronb1964.github.io.zip
gnome-extensions enable talktype@ronb1964.github.io
```

--------------------------------

### Install TalkType Prerequisites and Run

Source: https://github.com/ronb1964/talktype/blob/main/README.md

This bash script outlines the necessary prerequisites for installing TalkType on Fedora/Nobara, including packages like portaudio-devel and ffmpeg. It then proceeds to clone the repository, install dependencies using poetry, and run the application's tray interface.

```bash
# Prerequisites (Fedora/Nobara)
sudo dnf install -y portaudio-devel ffmpeg ydotool wl-clipboard \
                    python3-gobject libappindicator-gtk3 libnotify

# Clone and install
git clone https://github.com/ronb1964/TalkType.git
cd TalkType
poetry install

# Run
poetry run dictate-tray
```

--------------------------------

### Start TalkType Python Backend (AppImage)

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Run the TalkType Python backend using its AppImage. This must be started before the GNOME extension can connect.

```bash
./TalkType-v0.3.7-x86_64.AppImage
```

--------------------------------

### Install TalkType from Source

Source: https://context7.com/ronb1964/talktype/llms.txt

Dependencies and build commands for installing TalkType from the repository on Fedora/Nobara systems.

```bash
# Install dependencies (Fedora/Nobara)
sudo dnf install -y portaudio-devel ffmpeg ydotool wl-clipboard \
                    python3-gobject libappindicator-gtk3 libnotify

# Clone the repository
git clone https://github.com/ronb1964/TalkType.git
cd TalkType

# Install with Poetry
poetry install

# Run the tray application
poetry run dictate-tray
```

--------------------------------

### Install GNOME Extension Manually

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Use this command to copy the extension files to the local GNOME Shell extensions directory for manual installation during development.

```bash
cd gnome-extension
cp -r talktype@ronb1964.github.io ~/.local/share/gnome-shell/extensions/
```

--------------------------------

### Install and Run TalkType AppImage

Source: https://context7.com/ronb1964/talktype/llms.txt

Steps to download, set permissions, and execute the TalkType AppImage on any Linux distribution.

```bash
# Download the latest AppImage
wget https://github.com/ronb1964/TalkType/releases/latest/download/TalkType-v0.5.15.AppImage

# Make it executable
chmod +x TalkType-v*.AppImage

# Run it
./TalkType-v*.AppImage
```

--------------------------------

### Run TalkType AppImage

Source: https://github.com/ronb1964/talktype/blob/main/README.md

Download the AppImage, make it executable, and run it. Ensure FUSE 2 is installed if needed.

```bash
chmod +x TalkType-v*.AppImage
./TalkType-v*.AppImage
```

--------------------------------

### Reinstall TalkType Dependencies

Source: https://github.com/ronb1964/talktype/blob/main/DEV_SETUP.md

This sequence of commands removes the existing virtual environment, creates a new one, upgrades pip and Poetry, and then installs project dependencies using Poetry. Ensure you have Python 3 and Poetry installed.

```bash
rm -rf .venv
python3 -m venv .venv
.venv/bin/pip install --upgrade pip poetry
.venv/bin/poetry config virtualenvs.in-project true
.venv/bin/poetry install
```

--------------------------------

### Install TalkType via AUR

Source: https://github.com/ronb1964/talktype/blob/main/README.md

Use `yay` or `paru` to install the TalkType AppImage from the Arch User Repository.

```bash
yay -S talktype-appimage
# or
paru -S talktype-appimage
```

--------------------------------

### Run TalkType Dev Mode Script

Source: https://github.com/ronb1964/talktype/blob/main/DEV_SETUP.md

Execute this script to start TalkType in development mode from the command line. It replicates the functionality of the desktop launcher.

```bash
./run-dev.sh
```

--------------------------------

### Enable GNOME Extension

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

After manual installation, enable the extension using this command. A logout/login or GNOME Shell restart is required.

```bash
gnome-extensions enable talktype@ronb1964.github.io
```

--------------------------------

### Run TalkType System Tray Application via CLI

Source: https://context7.com/ronb1964/talktype/llms.txt

Start the TalkType system tray application, which automatically starts the dictation service and provides a visual indicator and quick access to preferences.

```bash
# Start tray (auto-starts dictation service)
dictate-tray

# The tray provides:
# - Visual status indicator
# - Quick access to preferences
# - Performance preset selection
```

--------------------------------

### Manually Start Dictation Service

Source: https://github.com/ronb1964/talktype/blob/main/DEV_SETUP.md

This command manually starts the dictation service, setting the PYTHONPATH to include the src directory. It's useful for debugging if the service doesn't start correctly from the tray.

```bash
PYTHONPATH=./src .venv/bin/python -m talktype.app
```

--------------------------------

### CI/CD Integration for Desktop Environment Testing

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Integrate TalkType's visual testing into a GitHub Actions workflow. This example demonstrates running tests without generating a report and then uploading the generated screenshots as an artifact.

```yaml
- name: Test across desktop environments
  run: ./test-all-de.sh --no-report
- name: Upload screenshots
  uses: actions/upload-artifact@v3
  with:
    name: screenshots
    path: test-screenshots/
```

--------------------------------

### Install FUSE 2 Dependency

Source: https://github.com/ronb1964/talktype/blob/main/README.md

AppImages require FUSE 2. Install it using your distribution's package manager if it's not already present.

```bash
# Fedora/RHEL
sudo dnf install fuse
# Ubuntu/Debian
sudo apt install libfuse2
# Arch/Manjaro
sudo pacman -S fuse2
# openSUSE
sudo zypper install libfuse2
```

--------------------------------

### Python D-Bus Integration

Source: https://context7.com/ronb1964/talktype/llms.txt

Example Python code demonstrating how to connect to TalkType via D-Bus, control its functions, query its status, and listen for signals.

```APIDOC
## Python D-Bus Integration

### Example Usage:

```python
import dbus
import dbus.mainloop.glib
from gi.repository import GLib

# Set up D-Bus main loop
dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)
bus = dbus.SessionBus()

# Get TalkType proxy
proxy = bus.get_object(
    'io.github.ronb1964.TalkType',
    '/io/github/ronb1964/TalkType'
)
interface = dbus.Interface(proxy, 'io.github.ronb1964.TalkType')

# Query status
is_recording = interface.IsRecording()
is_running = interface.IsServiceRunning()
model = interface.GetCurrentModel()
print(f"Recording: {is_recording}, Running: {is_running}, Model: {model}")

# Control recording
interface.ToggleRecording()

# Change settings
interface.SetModel("small")
interface.SetInjectionMode("auto")
interface.ApplyPerformancePreset("balanced")

# Listen for signals
def on_recording_changed(is_recording):
    print(f"Recording state changed: {is_recording}")

def on_transcription_complete(text):
    print(f"Transcription: {text}")

proxy.connect_to_signal("RecordingStateChanged", on_recording_changed)
proxy.connect_to_signal("TranscriptionComplete", on_transcription_complete)

# Run main loop to receive signals
loop = GLib.MainLoop()
loop.run()
```
```

--------------------------------

### TalkType Configuration Example

Source: https://github.com/ronb1964/talktype/blob/main/README.md

This TOML configuration file sets various parameters for TalkType, including the AI model, device, hotkeys, language mode, and audio feedback settings. Ensure the model and device settings match your hardware and performance needs.

```toml
model = "small"           # AI model: tiny, base, small, medium, large-v3
device = "cpu"            # "cpu" or "cuda" (GPU)
hold_hotkey = "F8"        # Hold-to-talk key (hold to record, release to stop)
toggle_hotkey = "F9"      # Tap-to-toggle key (press once start, press again stop)
# Both hotkeys are always active simultaneously
language_mode = "auto"    # "auto" or specific language code
beeps = true              # Audio feedback sounds
smart_quotes = true       # Use curly quotes " "
auto_space = true         # Auto-space between utterances
auto_period = true        # Add period at end of sentences
```

--------------------------------

### Configure CUDA GPU Acceleration

Source: https://context7.com/ronb1964/talktype/llms.txt

Detect NVIDIA GPUs and manage the installation of required CUDA libraries.

```python
from talktype.cuda_helper import (
    detect_nvidia_gpu,
    has_talktype_cuda_libraries,
    download_cuda_libraries,
    is_first_run,
    mark_first_run_complete
)

# Check for NVIDIA GPU
gpu_info = detect_nvidia_gpu()
if gpu_info:
    print(f"Found GPU: {gpu_info}")

# Check if CUDA libraries are installed
if has_talktype_cuda_libraries():
    print("CUDA libraries available - GPU acceleration enabled")
else:
    print("CUDA not installed - using CPU")

    # Download CUDA libraries (~800MB)
    success = download_cuda_libraries()
    if success:
        print("CUDA libraries installed successfully")

# First-run detection for onboarding
if is_first_run():
    print("First launch - showing setup wizard")
    # ... run onboarding ...
    mark_first_run_complete()
```

--------------------------------

### Configure ydotool Systemd Service

Source: https://github.com/ronb1964/talktype/blob/main/README.md

This bash script sets up a systemd user service for ydotool, which is required for text injection in TalkType. It creates the service file, enables it, and starts the service to ensure ydotool runs automatically on login.

```bash
# Create systemd service
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/ydotoold.service <<'EOF'
[Unit]
Description=ydotool daemon
After=graphical-session.target

[Service]
Environment=XDG_RUNTIME_DIR=%t
ExecStart=/usr/bin/ydotoold --socket-path=%t/.ydotool_socket
Restart=on-failure

[Install]
WantedBy=default.target
EOF

# Enable and start
systemctl --user daemon-reload
systemctl --user enable --now ydotoold.service
```

--------------------------------

### Check if GNOME Extension is Installed

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Verify if the TalkType extension is recognized by GNOME Shell using the `gnome-extensions list` command.

```bash
gnome-extensions list | grep talktype
```

--------------------------------

### Control Recording via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Commands to start, stop, and toggle the recording functionality of TalkType using D-Bus.

```APIDOC
## Control Recording via D-Bus

### Start Recording

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `StartRecording`

### Stop Recording

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `StopRecording`

### Toggle Recording

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `ToggleRecording`
```

--------------------------------

### Control TalkType Recording via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Use these commands to start, stop, or toggle the recording functionality of TalkType through D-Bus.

```bash
# Start recording
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.StartRecording
```

```bash
# Stop recording
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.StopRecording
```

```bash
# Toggle recording on/off
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.ToggleRecording
```

--------------------------------

### Increase DNF Install Timeout in Dockerfile

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Modify the Dockerfile to increase the network timeout for DNF package installations. This can help prevent 'Container build timeout' errors on slower network connections.

```dockerfile
# In Dockerfile
RUN dnf install -y --setopt=timeout=300 ...
```

--------------------------------

### Service Management via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Commands to manage the TalkType dictation service (start, stop, restart) using D-Bus.

```APIDOC
## Service Management via D-Bus

### Start Service

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `StartService`

### Stop Service

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `StopService`

### Restart Service

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `RestartService`
```

--------------------------------

### Manually Run Screenshot Test in Container

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

After starting a container interactively, manually execute the screenshot test runner script. This is useful for debugging screenshot generation issues within the container.

```bash
/usr/local/bin/test-runner.sh screenshot
```

--------------------------------

### Manage TalkType Service via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Control the dictation service of TalkType by starting, stopping, or restarting it using D-Bus commands.

```bash
# Start the dictation service
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.StartService
```

```bash
# Stop the dictation service
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.StopService
```

```bash
# Restart the dictation service
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.RestartService
```

--------------------------------

### Run Automated Pytest Suite

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Execute the test runner script to run the automated pytest suite within each containerized desktop environment. This verifies application logic across different setups.

```bash
cd docker-testing
./run-tests.sh test
```

--------------------------------

### Run All Desktop Environment Tests

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Execute the main script to build container images, take screenshots, generate a report, and open it in the browser. This is the primary entry point for the testing suite.

```bash
cd /home/ron/Dropbox/projects/TalkType
./test-all-de.sh
```

--------------------------------

### Command Line Interface - Run System Tray Application

Source: https://context7.com/ronb1964/talktype/llms.txt

Instructions for launching the TalkType system tray application, which provides a visual indicator and quick access to settings.

```APIDOC
## Command Line Interface - Run System Tray Application

### Launch Tray Application:

```bash
dictate-tray
```

### Features:

- Auto-starts the dictation service.
- Provides a visual status indicator.
- Offers quick access to preferences.
- Allows selection of performance presets.
```

--------------------------------

### Build All Container Images

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Manually build the Docker container images for GNOME, KDE, and XFCE environments. This command is typically run once or when environment configurations change.

```bash
cd docker-testing
./build-all.sh
```

--------------------------------

### Run TalkType Dictation Service via CLI

Source: https://context7.com/ronb1964/talktype/llms.txt

Launch the TalkType dictation service from the command line with various configuration options for model, device, hotkeys, and microphone.

```bash
# Run with default settings
dictate
```

```bash
# Override model and device
dictate --model medium --device cuda
```

```bash
# Custom hotkeys
dictate --hotkey F10 --toggle-hotkey F11 --mode toggle
```

```bash
# Specify microphone
dictate --mic "Blue Yeti"
```

```bash
# Disable beeps and notifications
dictate --beeps off --notify off
```

```bash
# Force specific language (skip auto-detection)
dictate --language en
```

--------------------------------

### Load and Save Configuration

Source: https://context7.com/ronb1964/talktype/llms.txt

Manage application settings by loading and updating the configuration object.

```python
from talktype.config import load_config, save_config, Settings

# Load current configuration
config = load_config()
print(f"Model: {config.model}")
print(f"Device: {config.device}")
print(f"Hotkey: {config.hotkey}")

# Modify and save configuration
config.model = "medium"
config.device = "cuda"
config.auto_timeout_minutes = 10
save_config(config)
```

--------------------------------

### Command Line Interface - Run Dictation Service

Source: https://context7.com/ronb1964/talktype/llms.txt

Instructions for running the TalkType dictation service from the command line, with options to customize model, device, hotkeys, microphone, and more.

```APIDOC
## Command Line Interface - Run Dictation Service

### Basic Usage:

```bash
dictate
```

### Options:

- `--model <model_name>`: Specify the Whisper model (e.g., `medium`, `small`).
- `--device <device_name>`: Specify the processing device (e.g., `cuda`, `cpu`).
- `--hotkey <key>`: Set a hotkey for a specific action.
- `--toggle-hotkey <key>`: Set a hotkey to toggle recording.
- `--mode <mode>`: Set the operating mode (e.g., `toggle`).
- `--mic <mic_name>`: Specify the microphone to use.
- `--beeps <on|off>`: Enable or disable audio beeps.
- `--notify <on|off>`: Enable or disable desktop notifications.
- `--language <lang_code>`: Force a specific language, skipping auto-detection.
```

--------------------------------

### Generate Comparison Report

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Create an HTML report that displays all captured screenshots side-by-side for visual comparison across desktop environments. The report is automatically opened in the default browser.

```bash
cd docker-testing
./generate-comparison-report.sh
```

--------------------------------

### Quick Theme Testing with CSS Changes

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

After making changes to CSS files (e.g., prefs_style.css), use this command for a fast re-test without rebuilding the container images. This is useful for iterating on theme adjustments.

```bash
# Make changes to prefs_style.css
./test-all-de.sh --no-build  # Fast re-test
```

--------------------------------

### Configure TalkType Settings

Source: https://context7.com/ronb1964/talktype/llms.txt

Default configuration file structure located at ~/.config/talktype/config.toml.

```toml
# TalkType config
model = "small"              # Whisper model: tiny, base, small, medium, large-v3
device = "cpu"               # Processing device: "cpu" or "cuda" (GPU)
hotkey = "F8"                # Hold-to-talk hotkey
toggle_hotkey = "F9"         # Tap-to-toggle hotkey
mode = "hold"                # Activation mode: "hold" or "toggle"
language = ""                # Language code (empty = auto-detect)
beeps = true                 # Audio feedback sounds
smart_quotes = true          # Use curly quotes " "
auto_space = true            # Auto-space between utterances
auto_period = true           # Add period at end of sentences
injection_mode = "auto"      # Text injection: "auto", "type", or "paste"
typing_delay = 12            # Milliseconds between keystrokes (5-50)
recording_indicator = true   # Show visual recording indicator
indicator_position = "center" # Position: center, top-left, top-right, etc.
auto_timeout_enabled = true  # Auto-stop after inactivity
auto_timeout_minutes = 5     # Minutes before auto-timeout
```

--------------------------------

### List Running Processes

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Lists all running processes on the system, useful for checking if Xvfb is active within the container.

```bash
ps aux | grep Xvfb
```

--------------------------------

### Launch TalkType Dev Mode

Source: https://github.com/ronb1964/talktype/blob/main/DEV_SETUP.md

Use this command to launch TalkType in development mode via the desktop launcher.

```bash
gtk-launch talktype-dev
```

--------------------------------

### Run Tests Without Rebuilding Containers

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Use this option after the initial build to skip the container image creation step and proceed directly to testing. This speeds up subsequent test runs.

```bash
./test-all-de.sh --no-build
```

--------------------------------

### Check GNOME Shell Logs

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

View live logs for GNOME Shell to troubleshoot extension issues. Use this command to see errors and activity.

```bash
journalctl -f -o cat /usr/bin/gnome-shell
```

--------------------------------

### Open Preferences Window

Source: https://context7.com/ronb1964/talktype/llms.txt

Use these commands to open the TalkType preferences window. You can open it directly or navigate to a specific tab like 'Updates'.

```bash
# Open preferences
dictate-prefs
```

```bash
# Open directly to Updates tab
dictate-prefs --tab=updates
```

--------------------------------

### Clean Up Podman System Resources

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

This command helps resolve 'No space left on device' errors by removing unused Podman images, containers, and networks. Use with caution as it prunes all unused data.

```bash
podman system prune -a
```

--------------------------------

### Open TalkType UI Windows via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Commands to open various user interface windows, including preferences, and help dialogs, using D-Bus.

```bash
# Open preferences window
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.OpenPreferences
```

```bash
# Open preferences directly to Updates tab
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.OpenPreferencesUpdates
```

```bash
# Show voice commands quick reference
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.ShowVoiceCommands
```

```bash
# Show help dialog
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.ShowHelp
```

```bash
# Quit TalkType
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.Quit
```

--------------------------------

### Run Container Interactively for Debugging

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Launch a container interactively to manually execute test commands and debug issues. This allows direct interaction with the container's environment and file system.

```bash
podman run -it --rm \
  -v $PWD:/app:ro \
  -v $PWD/test-screenshots:/screenshots:rw \
  talktype-test:gnome /bin/bash
```

--------------------------------

### Display X Server Information

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Queries the X server for information about displays, screens, and capabilities. Use with the display number :99 to check the virtual display.

```bash
xdpyinfo -display :99
```

--------------------------------

### Run Visual Tests Across Desktop Environments

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Execute visual tests for all configured desktop environments. Review the generated HTML report for visual discrepancies. This command is typically used before a release to ensure UI consistency.

```bash
./test-all-de.sh
```

--------------------------------

### Launch TalkType Components in Container

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Modify the test-runner.sh script to launch specific TalkType components for testing. This allows for focused testing of different parts of the application, such as the tray icon or dialogs.

```bash
# Launch main tray icon
python3 -m talktype.tray &

# Or launch specific dialog
python3 -m talktype.welcome_dialog &
```

--------------------------------

### Override Settings with Environment Variables

Source: https://context7.com/ronb1964/talktype/llms.txt

Use environment variables to override configuration file settings at runtime.

```bash
# Override model and device
export DICTATE_MODEL=medium
export DICTATE_DEVICE=cuda
export DICTATE_HOTKEY=F10

# Boolean overrides
export DICTATE_BEEPS=off
export DICTATE_AUTO_SPACE=true
export DICTATE_NOTIFY=on

# Run with overrides
./TalkType-v*.AppImage
```

--------------------------------

### Take Screenshots Across Environments

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Execute the test runner script to capture screenshots of the TalkType application in each configured desktop environment. Screenshots are saved to a shared volume.

```bash
cd docker-testing
./run-tests.sh screenshot
```

--------------------------------

### Build and Load Whisper Model

Source: https://context7.com/ronb1964/talktype/llms.txt

Check for cached models, download them if necessary, and perform transcription.

```python
from talktype.config import load_config, Settings
from talktype.model_helper import download_model_with_progress, is_model_cached

# Check if model is already downloaded
if is_model_cached("small"):
    print("Model already cached")
else:
    print("Model will be downloaded")

# Download model with progress dialog (GUI)
model = download_model_with_progress(
    model_name="small",
    device="cpu",
    compute_type="int8",
    show_confirmation=True  # Show download confirmation dialog
)

if model:
    print("Model loaded successfully")
    # Transcribe audio
    segments, info = model.transcribe(
        audio_array,  # numpy float32 array
        vad_filter=True,
        beam_size=1,
        language="en"  # or None for auto-detect
    )
    text = " ".join(seg.text for seg in segments)
    print(f"Transcription: {text}")
```

--------------------------------

### Query Status via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Use command-line tools to query the status of the TalkType service.

```bash
# Check if recording
dbus-send --session --print-reply \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.IsRecording

# Check if service is running
dbus-send --session --print-reply \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.IsServiceRunning

# Get current model
dbus-send --session --print-reply \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.GetCurrentModel

# Get comprehensive status
dbus-send --session --print-reply \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.GetStatus
```

--------------------------------

### Make Scripts Executable

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

This command resolves 'Permission denied' errors by setting execute permissions on shell scripts within the docker-testing directory and the main test script.

```bash
chmod +x docker-testing/*.sh
chmod +x test-all-de.sh
```

--------------------------------

### Configuration Management

Source: https://context7.com/ronb1964/talktype/llms.txt

Load, modify, and save TalkType configuration settings, including model, device, and hotkey.

```APIDOC
## Load Configuration

### Description
Loads the current configuration settings for TalkType.

### Method
Python function call

### Endpoint
N/A (Local configuration file)

### Parameters
None

### Request Example
```python
from talktype.config import load_config

config = load_config()
print(f"Model: {config.model}")
print(f"Device: {config.device}")
print(f"Hotkey: {config.hotkey}")
```

### Response
Returns a `Settings` object with configuration parameters.

## Save Configuration

### Description
Saves the current configuration settings for TalkType.

### Method
Python function call

### Endpoint
N/A (Local configuration file)

### Parameters
- **config** (Settings) - Required - The settings object to save.

### Request Example
```python
from talktype.config import load_config, save_config

config = load_config()
config.model = "medium"
config.device = "cuda"
config.auto_timeout_minutes = 10
save_config(config)
```

### Response
None
```

--------------------------------

### Debug Container Build Failures

Source: https://github.com/ronb1964/talktype/blob/main/docker-testing/README.md

Use Podman commands to inspect container images, running containers, and logs when the container build process fails. This helps diagnose issues with the Dockerfiles or build environment.

```bash
podman images  # List built images
podman ps -a   # List containers
podman logs <container-id>
```

--------------------------------

### Manage Custom Voice Commands

Source: https://context7.com/ronb1964/talktype/llms.txt

Load and update custom voice command mappings for the application.

```python
from talktype.config import load_custom_commands, save_custom_commands

# Load existing custom commands
commands = load_custom_commands()
print(commands)  # {"my email": "user@example.com", ...}

# Add new custom commands
commands["company name"] = "Acme Corporation"
commands["phone number"] = "+1 (555) 123-4567"
commands["legal disclaimer"] = '"This is provided as-is."'  # Quoted = literal

# Save custom commands
save_custom_commands(commands)
```

--------------------------------

### Open UI Windows via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Commands to open various UI windows and dialogs within TalkType using D-Bus.

```APIDOC
## Open UI Windows via D-Bus

### Open Preferences

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `OpenPreferences`

### Open Preferences (Updates Tab)

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `OpenPreferencesUpdates`

### Show Voice Commands

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `ShowVoiceCommands`

### Show Help Dialog

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `ShowHelp`

### Quit TalkType

- **Method**: D-Bus Call
- **Interface**: `io.github.ronb1964.TalkType`
- **Object Path**: `/io/github/ronb1964/TalkType`
- **Method Name**: `Quit`
```

--------------------------------

### Define Custom Voice Commands

Source: https://context7.com/ronb1964/talktype/llms.txt

Configuration format for custom phrase-to-text replacements in custom_commands.toml.

```toml
# TalkType Custom Voice Commands
# Format: "spoken phrase" = "replacement text"
# Use \n for line breaks, wrap in quotes for literal output

[commands]
"my email" = "user@example.com"
"my address" = "123 Main Street\nAnytown, USA 12345"
"signature" = "Best regards,\nJohn Doe"

# Use quotes for exact literal output (bypasses normalization)
"greeting" = "\"Hello, World!\""
```

--------------------------------

### Formatting Voice Commands

Source: https://context7.com/ronb1964/talktype/llms.txt

Reference for spoken commands that trigger formatting actions.

```text
Say "new line"           → Creates a line break (Shift+Enter)
Say "new paragraph"      → Creates double line break
Say "tab"                → Inserts tab character
Say "open parenthesis"   → (
Say "close parenthesis"  → )
Say "open bracket"       → [
Say "close bracket"      → ]
Say "open brace"         → {
Say "close brace"        → }
```

--------------------------------

### Detect Audio Input Devices

Source: https://context7.com/ronb1964/talktype/llms.txt

Identify microphone devices by name or index for audio input.

```python
from talktype.config import find_input_device

# Auto-detect best microphone (uses PipeWire if available)
device_idx = find_input_device(None)
print(f"Auto-detected device index: {device_idx}")

# Find specific microphone by name substring
device_idx = find_input_device("USB")
print(f"USB microphone index: {device_idx}")

# Find Blue Yeti microphone
device_idx = find_input_device("Yeti")
```

--------------------------------

### CUDA GPU Acceleration

Source: https://context7.com/ronb1964/talktype/llms.txt

Utilities for detecting NVIDIA GPUs, checking for TalkType CUDA libraries, and downloading them if necessary.

```APIDOC
## Detect NVIDIA GPU

### Description
Detects and retrieves information about available NVIDIA GPUs.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
None

### Request Example
```python
from talktype.cuda_helper import detect_nvidia_gpu

gpu_info = detect_nvidia_gpu()
if gpu_info:
    print(f"Found GPU: {gpu_info}")
```

### Response
Returns GPU information string if an NVIDIA GPU is found, otherwise None.

## Check TalkType CUDA Libraries

### Description
Checks if the necessary CUDA libraries for TalkType are installed and available.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
None

### Request Example
```python
from talktype.cuda_helper import has_talktype_cuda_libraries

if has_talktype_cuda_libraries():
    print("CUDA libraries available - GPU acceleration enabled")
else:
    print("CUDA not installed - using CPU")
```

### Response
Returns `True` if CUDA libraries are available, `False` otherwise.

## Download CUDA Libraries

### Description
Downloads and installs the necessary CUDA libraries for GPU acceleration.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
None

### Request Example
```python
from talktype.cuda_helper import download_cuda_libraries

success = download_cuda_libraries()
if success:
    print("CUDA libraries installed successfully")
```

### Response
Returns `True` if the download and installation were successful, `False` otherwise.

## First Run Detection

### Description
Checks if this is the first time the application is being run, typically used for onboarding.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
None

### Request Example
```python
from talktype.cuda_helper import is_first_run, mark_first_run_complete

if is_first_run():
    print("First launch - showing setup wizard")
    # ... run onboarding ...
    mark_first_run_complete()
```

### Response
Returns `True` if it's the first run, `False` otherwise.
```

--------------------------------

### TalkType Performance Presets

Source: https://context7.com/ronb1964/talktype/llms.txt

This Python dictionary defines available performance presets for TalkType, mapping preset names to their corresponding model, device, and optional timeout configurations.

```python
# Available presets and their configurations
PERFORMANCE_PRESETS = {
    "fastest": {"model": "tiny", "device": "cpu"},
    "light": {"model": "base", "device": "cpu"},
    "balanced": {"model": "small", "device": "cuda"},
    "quality": {"model": "medium", "device": "cuda"},
    "accurate": {"model": "large-v3", "device": "cuda"},
    "battery": {"model": "tiny", "device": "cpu", "timeout": 2}
}
```

--------------------------------

### Python D-Bus Integration for TalkType

Source: https://context7.com/ronb1964/talktype/llms.txt

Integrate TalkType control and monitoring into Python applications using the D-Bus library. Requires GLib main loop for signal handling.

```python
import dbus
import dbus.mainloop.glib
from gi.repository import GLib

# Set up D-Bus main loop
dbus.mainloop.glib.DBusGMainLoop(set_as_default=True)
bus = dbus.SessionBus()

# Get TalkType proxy
proxy = bus.get_object(
    'io.github.ronb1964.TalkType',
    '/io/github/ronb1964/TalkType'
)
interface = dbus.Interface(proxy, 'io.github.ronb1964.TalkType')

# Query status
is_recording = interface.IsRecording()
is_running = interface.IsServiceRunning()
model = interface.GetCurrentModel()
print(f"Recording: {is_recording}, Running: {is_running}, Model: {model}")

# Control recording
interface.ToggleRecording()

# Change settings
interface.SetModel("small")
interface.SetInjectionMode("auto")
interface.ApplyPerformancePreset("balanced")

# Listen for signals
def on_recording_changed(is_recording):
    print(f"Recording state changed: {is_recording}")

def on_transcription_complete(text):
    print(f"Transcription: {text}")

proxy.connect_to_signal("RecordingStateChanged", on_recording_changed)
proxy.connect_to_signal("TranscriptionComplete", on_transcription_complete)

# Run main loop to receive signals
loop = GLib.MainLoop()
loop.run()
```

--------------------------------

### Monitor D-Bus Signals

Source: https://context7.com/ronb1964/talktype/llms.txt

Instructions on how to monitor D-Bus signals emitted by TalkType to track changes in recording state, service status, and transcription events.

```APIDOC
## Monitor D-Bus Signals

### Monitor All TalkType Signals

- **Command**: `dbus-monitor --session "interface='io.github.ronb1964.TalkType'"`

### Emitted Signals:

- **`RecordingStateChanged(boolean is_recording)`**: Indicates a change in the recording status.
- **`ServiceStateChanged(boolean is_running)`**: Indicates a change in the dictation service status.
- **`TranscriptionComplete(string text)`**: Emitted when a transcription is finished, providing the transcribed text.
- **`ModelChanged(string model_name)`**: Indicates that the Whisper model has been changed.
- **`InjectionModeChanged(string mode)`**: Indicates that the text injection mode has been changed.
- **`ErrorOccurred(string error_type, string message)`**: Emitted when an error occurs, with details about the error type and message.
```

--------------------------------

### Whisper Model Management

Source: https://context7.com/ronb1964/talktype/llms.txt

Download, cache, and load Whisper models for speech-to-text transcription, with support for progress indication and GPU acceleration.

```APIDOC
## Check Model Cache

### Description
Checks if a specified Whisper model is already downloaded and cached locally.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
- **model_name** (string) - Required - The name of the Whisper model to check (e.g., "small", "medium").

### Request Example
```python
from talktype.model_helper import is_model_cached

if is_model_cached("small"):
    print("Model already cached")
else:
    print("Model will be downloaded")
```

### Response
Returns `True` if the model is cached, `False` otherwise.

## Download Model with Progress

### Description
Downloads a specified Whisper model with a progress dialog (GUI) and loads it.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
- **model_name** (string) - Required - The name of the Whisper model to download (e.g., "small").
- **device** (string) - Required - The device to load the model on (e.g., "cpu", "cuda").
- **compute_type** (string) - Required - The compute type for the model (e.g., "int8").
- **show_confirmation** (boolean) - Optional - Whether to show a download confirmation dialog.

### Request Example
```python
from talktype.model_helper import download_model_with_progress

model = download_model_with_progress(
    model_name="small",
    device="cpu",
    compute_type="int8",
    show_confirmation=True
)

if model:
    print("Model loaded successfully")
    # Transcribe audio
    # segments, info = model.transcribe(audio_array, vad_filter=True, beam_size=1, language="en")
    # text = " ".join(seg.text for seg in segments)
    # print(f"Transcription: {text}")
```

### Response
Returns the loaded model object if successful, otherwise None.
```

--------------------------------

### Custom Voice Commands

Source: https://context7.com/ronb1964/talktype/llms.txt

Manage custom voice commands and their corresponding text responses, including literal string handling.

```APIDOC
## Load Custom Commands

### Description
Loads existing custom voice commands from configuration.

### Method
Python function call

### Endpoint
N/A (Local configuration file)

### Parameters
None

### Request Example
```python
from talktype.config import load_custom_commands

commands = load_custom_commands()
print(commands)  # {"my email": "user@example.com", ...}
```

### Response
Returns a dictionary of custom commands.

## Save Custom Commands

### Description
Saves custom voice commands to configuration.

### Method
Python function call

### Endpoint
N/A (Local configuration file)

### Parameters
- **commands** (dict) - Required - A dictionary where keys are voice commands and values are their corresponding text responses.

### Request Example
```python
from talktype.config import load_custom_commands, save_custom_commands

commands = load_custom_commands()
commands["company name"] = "Acme Corporation"
commands["phone number"] = "+1 (555) 123-4567"
commands["legal disclaimer"] = '"This is provided as-is."'  # Quoted = literal
save_custom_commands(commands)
```

### Response
None
```

--------------------------------

### Watch TalkType Extension Logs

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Monitor GNOME Shell logs specifically for TalkType-related messages during development. This helps in debugging the extension's behavior.

```bash
journalctl -f -o cat /usr/bin/gnome-shell | grep -i talktype
```

--------------------------------

### Kill TalkType Processes

Source: https://github.com/ronb1964/talktype/blob/main/DEV_SETUP.md

Use these commands to terminate all running TalkType processes and remove the lock file, typically done before reinstalling dependencies or restarting.

```bash
pkill -f talktype
rm -f /run/user/$(id -u)/talktype-tray.lock
```

--------------------------------

### Audio Device Detection

Source: https://context7.com/ronb1964/talktype/llms.txt

Automatically detect the best available input audio device or find a specific microphone by name.

```APIDOC
## Find Input Device

### Description
Detects and returns the index of an audio input device.

### Method
Python function call

### Endpoint
N/A (Library function)

### Parameters
- **name_substring** (string) - Optional - A substring to search for in microphone names. If None, attempts to auto-detect the best device.

### Request Example
```python
from talktype.config import find_input_device

# Auto-detect best microphone
device_idx = find_input_device(None)
print(f"Auto-detected device index: {device_idx}")

# Find specific microphone by name substring
device_idx = find_input_device("USB")
print(f"USB microphone index: {device_idx}")

# Find Blue Yeti microphone
device_idx = find_input_device("Yeti")
```

### Response
Returns the index of the detected audio input device.
```

--------------------------------

### Monitor D-Bus Signals for TalkType

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Use `dbus-monitor` to observe D-Bus signals emitted by the TalkType service. This is useful for debugging communication between components.

```bash
dbus-monitor --session "interface='io.github.ronb1964.TalkType'"
```

--------------------------------

### Normalize Spoken Text

Source: https://context7.com/ronb1964/talktype/llms.txt

Convert spoken punctuation, time formats, and email addresses into standard written text.

```python
from talktype.normalize import normalize_text

# Convert spoken punctuation to symbols
raw_text = "Hello comma how are you question mark"
normalized = normalize_text(raw_text)
print(normalized)  # "Hello, how are you?"

# Handle new lines and paragraphs
raw_text = "First sentence period new line Second sentence period"
normalized = normalize_text(raw_text)
# Output: "First sentence.\nSecond sentence."

# Smart quote handling
raw_text = "He said open quote Hello close quote"
normalized = normalize_text(raw_text)
# Output: He said "Hello"

# Time formatting (fixes Whisper output)
raw_text = "The meeting is at 3. 30 p. m."
normalized = normalize_text(raw_text)
# Output: "The meeting is at 3:30 PM."

# Email formatting
raw_text = "Contact me at john at example dot com"
normalized = normalize_text(raw_text)
# Output: "Contact me at john@example.com"
```

--------------------------------

### Monitor TalkType D-Bus Signals

Source: https://context7.com/ronb1964/talktype/llms.txt

Monitor all D-Bus signals emitted by TalkType to track changes in recording state, service status, and transcriptions.

```bash
# Monitor all TalkType signals
dbus-monitor --session "interface='io.github.ronb1964.TalkType'"

# Signals emitted:
# - RecordingStateChanged(boolean is_recording)
# - ServiceStateChanged(boolean is_running)
# - TranscriptionComplete(string text)
# - ModelChanged(string model_name)
# - InjectionModeChanged(string mode)
# - ErrorOccurred(string error_type, string message)
```

--------------------------------

### Restart GNOME Shell

Source: https://github.com/ronb1964/talktype/blob/main/gnome-extension/README.md

Restart GNOME Shell to apply changes or resolve issues without logging out. Use the Alt+F2 shortcut, type 'r', and press Enter.

```bash
Alt+F2 → type 'r' → Enter
```

--------------------------------

### Change TalkType Settings via D-Bus

Source: https://context7.com/ronb1964/talktype/llms.txt

Modify application settings such as the Whisper model, text injection mode, and performance presets using D-Bus.

```bash
# Change Whisper model
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.SetModel \
    string:"medium"
```

```bash
# Set text injection mode (auto, paste, or type)
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.SetInjectionMode \
    string:"paste"
```

```bash
# Apply performance preset (fastest, light, balanced, quality, accurate, battery)
dbus-send --session \
    --dest=io.github.ronb1964.TalkType \
    /io/github/ronb1964/TalkType \
    io.github.ronb1964.TalkType.ApplyPerformancePreset \
    string:"balanced"
```