# Installation Guide

## Quick Install (Debian 12 / Ubuntu 22.04+)

### Automated Installation

Run the installation script:

```bash
chmod +x install.sh
./install.sh
```

The script will:
- Install all system dependencies
- Detect and configure NVIDIA GPU (if available)
- Create a Python virtual environment (optional)
- Install all Python packages
- Test GPU availability

---

## Manual Installation

### 1. System Dependencies

#### Debian 12 / Ubuntu 22.04+

```bash
sudo apt-get update
sudo apt-get install -y \
    python3-dev \
    python3-pip \
    python3-venv \
    libasound2-dev \
    build-essential \
    git \
    ffmpeg \
    curl \
    wget
```

#### For NVIDIA GPU Support

```bash
# Check if NVIDIA driver is installed
nvidia-smi

# If not installed:
sudo apt-get install -y nvidia-driver firmware-misc-nonfree

# Reboot after installation
sudo reboot
```

### 2. Python Environment (Recommended)

```bash
# Create virtual environment
python3 -m venv venv

# Activate it
source venv/bin/activate
```

### 3. Install Python Dependencies

#### macOS (Apple Silicon) / CPU-only Linux:
```bash
pip install -r requirements.txt --only-binary llvmlite,numba,numpy,scikit-learn,scipy,soxr
```

#### Linux with NVIDIA GPU (CUDA 12.8):
```bash
pip install -r requirements.txt --only-binary llvmlite,numba,numpy,scikit-learn,scipy,soxr --extra-index-url https://download.pytorch.org/whl/cu128
```

`--only-binary` keeps pip from falling back to a source build when no wheel
matches your platform: those builds need a compiler, and on an older macOS they
fail after a long download. With the flag, pip picks an earlier release that
does publish a wheel for your machine instead.

Note: The install.sh script detects your platform and GPU automatically.

### 4. Verify Installation

```bash
# Linux/NVIDIA GPU
python3 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')"

# macOS Apple Silicon
# Note: MPS is used for translation and the OpenAI Whisper backend. The default
# faster-whisper backend runs CPU int8 on Apple Silicon regardless of this result.
python3 -c "import torch; print(f'MPS available: {torch.backends.mps.is_available()}')"
```

---

## Running the Application

### Option 1: Watchdog — recommended for production

The Watchdog process manages STT with automatic crash recovery and auto-updates.
Run it headless (no GUI) so it keeps STT alive in the background.

**Binary install (downloaded release):**

```bash
# Linux / macOS
./STT-Watchdog --headless

# Windows
STT-Watchdog.exe --headless
```

The helper scripts handle logging automatically:

```bash
# Linux / macOS
./start_watchdog.sh

# Windows (cmd)
start_watchdog.bat

# Windows (PowerShell)
.\start_watchdog.ps1
```

Logs go to `~/.stt/logs/watchdog.log` — the data directory is the same for a binary and a
source install (override it with `STT_DATA_DIR`).

**Source install:**

```bash
# Activate virtual environment first if you use one
source .venv/bin/activate   # Linux / macOS
.venv\Scripts\activate      # Windows

python3 stt/watchdog.py --headless
```

### Option 2: Direct start — for development / testing

```bash
# If using virtual environment, activate it first:
source venv/bin/activate

# Run the application
python3 speech_to_text.py
```

### Access the Web UI

Open your browser to:
- **Local:** http://localhost:80
- **Network:** http://your-server-ip:80

### First Time Setup

1. Go to `/model-manager` to download Whisper models
2. Go to `/server-settings` to configure paths and network
3. Go to `/live-settings` to configure audio device and language
4. Start transcribing on the home page!

---

## Service Setup (Auto-start on Boot)

### Linux — systemd

```bash
sudo cp deploy/stt-watchdog.service /etc/systemd/system/
```

Open the file and set `User=` to your username. For a **source install** the `ExecStart`
line is already uncommented; for a **binary install** swap it with the commented binary line.

```bash
sudo systemctl daemon-reload
sudo systemctl enable --now stt-watchdog

# Useful commands
sudo systemctl status stt-watchdog
sudo journalctl -u stt-watchdog -f
```

### macOS — LaunchAgent

```bash
cp deploy/com.stt.watchdog.plist ~/Library/LaunchAgents/
```

Edit the file and replace every `INSTALL_DIR` placeholder with the full path to your
STT directory. For a **binary install** follow the comment in the plist to switch
`ProgramArguments` to the single binary path.

```bash
launchctl load ~/Library/LaunchAgents/com.stt.watchdog.plist

# Check it's running
launchctl list | grep stt

# View logs
tail -f ~/.stt/logs/watchdog.log
```

To stop and remove:

```bash
launchctl unload ~/Library/LaunchAgents/com.stt.watchdog.plist
```

### Windows — Task Scheduler

1. Open **Task Scheduler** → *Create Basic Task*
2. **Trigger:** At log on (or At startup for system-wide)
3. **Action:** Start a program
   - Binary install: `C:\path\to\STT-Watchdog.exe`, argument `--headless`
   - Source install: `pythonw.exe`, argument `"C:\path\to\stt\watchdog.py" --headless`
4. **Settings:** Enable *Run whether user is logged on or not* for true headless operation

Alternatively, run `start_watchdog.bat` or `start_watchdog.ps1` from the Startup folder
(`shell:startup` in Run dialog) for a simpler per-user setup.

---

## System Requirements

### Transcription only (minimum)
- **OS:** Debian 12, Ubuntu 22.04+, or similar Linux; Windows 10+; macOS 12+ (Apple Silicon only — see [Intel Macs](#intel-macs))
- **CPU:** 6 cores
- **RAM:** 12 GB
- **Storage:** 15 GB free space
- **Python:** 3.9 - 3.13

### Transcription + Translation (minimum)
- **CPU:** 8 cores
- **RAM:** 16 GB
- **Storage:** 25 GB free space
- The NLLB translation model adds several GB of RAM and disk.

### Example configurations

Actual requirements depend on which models you configure. A few representative setups to get a feel for the range:

| Setup | Whisper model | Translation | Est. memory | Suggested hardware |
|-------|---------------|-------------|-------------|--------------------|
| Light, CPU-only | `tiny` / `base` (faster-whisper) | off / remote | ~5 GB RAM | any modern 8 GB PC |
| Balanced, CPU-only | `small` (faster-whisper) | off / remote | ~5.5 GB RAM | 8 GB PC |
| Default install, CPU-only | `small` (openai-whisper) | NLLB-600M local | ~9.5 GB RAM | 12 GB PC |
| Accurate, NVIDIA GPU | `large-v3` (faster-whisper) | off / remote | ~4.5 GB VRAM + ~5 GB RAM | 6 GB GPU (RTX 2060 / 3050) |
| Full stack, NVIDIA GPU | `large-v3` (faster-whisper) | NLLB-1.3B on GPU | ~8 GB VRAM + ~6 GB RAM | 10-12 GB GPU (RTX 3060 12GB+) |
| Apple Silicon | `small` (CPU int8) | NLLB-600M on MPS | ~10 GB unified memory | M1 or later with 16 GB |

Estimates include a ~4 GB app/OS baseline. The faster-whisper backend (int8) needs roughly half the memory of openai-whisper (fp32); Apple Silicon shares one memory pool between CPU and GPU. Larger NLLB models raise requirements substantially (3.3B ≈ 15 GB RAM on CPU or 8 GB VRAM on GPU), while offloading translation to a remote machine (Live Translation → Remote) keeps the local footprint at transcription-only. The web UI shows a warning banner whenever the machine falls short of what the currently configured models need.

### Intel Macs

Not supported. PyTorch published its last macOS x86_64 wheels with 2.2.2, so the pinned
`torch` in `requirements.txt` can never resolve on an Intel Mac — `install.sh` and the
watchdog's setup both refuse one up front rather than failing partway through.

**26.2.233 was the last release with an Intel macOS package.** An install that is already
running on an Intel Mac keeps working at the version it has: its updater detects the
permanent condition and pauses updating ("Updates paused: This Mac has an Intel
processor…" in the control window and `~/.stt/logs/watchdog.log`) instead of stopping the
server for an install that cannot succeed. No newer version will install there — move the
install to an Apple Silicon Mac (M1 or newer), or to a Windows or Linux PC.

A separate Intel dependency set is possible and was declined, not overlooked: holding
`torch`/`torchaudio` at 2.2.2 and `transformers` below 5 (4.57.6 declares `torch>=2.2`;
5.x wants `torch>=2.5`) does resolve on `x86_64-apple-darwin`, and GitHub still offers
Intel macOS runners. The cost is what rules it out — a second `transformers` major to keep
the app working on, a second signed and notarized package every release, and an extra
build leg on a runner fleet Apple is winding down. Reopen it if enough Intel installs turn
up to outweigh that.

### Acceleration (optional, recommended)
- **NVIDIA minimum:** GPU with 4GB+ VRAM (RTX 2060 / RTX 3050) — enough for transcription with small/medium models
- **NVIDIA recommended:** GPU with 10GB+ VRAM (RTX 3060 12GB, RTX 4070 or better) — large models and transcription + translation on GPU
- **CUDA:** 12.8 compatible drivers (NVIDIA driver R570+), Python 3.10 - 3.13
- **Apple Silicon:** M1 or later, on **macOS Monterey (12) or later** — scipy and scikit-learn, which the audio stack depends on, publish no arm64 wheels for Big Sur, and there is no older release that does. Setup refuses an earlier macOS rather than spending two hours failing to build them from source. MPS is detected and used automatically for **translation** and for the non-default `whisper` (OpenAI) backend. The default `faster-whisper` backend is CTranslate2, which has no Metal support, so **transcription runs on the CPU** in int8 — fast and memory-efficient, but not GPU-accelerated.

> The minimum tiers run CPU-only, which is significantly slower than GPU — larger models add noticeable transcription latency. Lower-spec hardware may still work depending on configuration (e.g. smaller Whisper models, reduced settings), at the cost of accuracy and/or speed. Offloading translation to a remote machine (Live Translation → Remote) keeps the local requirements at the transcription-only tier.

---

## Troubleshooting

### NVIDIA GPU Not Detected

```bash
# Check driver installation
nvidia-smi

# Reinstall NVIDIA drivers
sudo apt-get install --reinstall nvidia-driver

# Reboot
sudo reboot
```

### Port 80 Permission Denied

Either:
1. Run with sudo (not recommended for production)
2. Change port in `config/config.json` to 8080 or higher
3. Use port forwarding/reverse proxy

### ImportError or Missing Modules

```bash
# Make sure virtual environment is activated
source venv/bin/activate

# Reinstall requirements
pip install -r requirements.txt --only-binary llvmlite,numba,numpy,scikit-learn,scipy,soxr --force-reinstall
```

---

## Configuration

### Main Config File
The live config is **`~/.stt/config/config.json`** (`%USERPROFILE%\.stt\config\config.json` on
Windows), created automatically on first run by copying the bundled
`config/config.default.json`. Set `STT_DATA_DIR` to put the data directory somewhere else.

This holds for a source checkout too, not just a packaged install: the `config/` directory in
the repo contains only the template, and editing it changes nothing about a running server.

To start from scratch: delete `~/.stt/config/config.json` and restart the app.
To update the default template for others: edit `config/config.default.json` and commit it.

### Sentry Error Reporting
Errors, logs, performance traces, and profiles are reported to the project's
[Sentry](https://sentry.io) by default (tagged `process: server|worker|watchdog`).
Local crash dumps in `logs/crashes/` are written regardless.

To **disable all remote reporting**, set in `config/config.json`:

```json
"crash_reporting": {
  "sentry_enabled": false
}
```

To report to your **own** Sentry project instead, create one with platform **Flask** and put
its DSN in `crash_reporting.sentry_dsn`. Sampling and PII knobs live in the same section
(see `config/config.default.json`); keep `sentry_traces_sample_rate` low — the web UI polls
about twice a second.

Key settings:
- Network host, port, and IP whitelist
- Audio device and capture backend
- Database paths and filename format
- Model selection and backend
- Audio backup paths and formats

### Web Interface
Most settings can be configured through the web UI:
- `/server-settings` - Server configuration
- `/live-settings` - Live transcription settings
- `/timezone-settings` - Timestamp configuration
- `/model-manager` - Download and manage AI models
- `/file-manager` - File management and backup settings

---

## Updating

```bash
# Pull latest changes
git pull

# Activate virtual environment if using one
source venv/bin/activate

# Update dependencies
pip install -r requirements.txt --only-binary llvmlite,numba,numpy,scikit-learn,scipy,soxr --upgrade

# Restart the application
```

---

## Uninstallation

```bash
# Stop the application (Ctrl+C)

# Remove virtual environment
rm -rf venv

# Remove downloaded models (optional)
rm -rf models

# Remove recordings and databases (optional)
rm -rf _AUTOMATIC_BACKUP

# Uninstall system packages (optional, be careful!)
# sudo apt-get remove python3-dev
```

---

## Support

For issues, questions, or feature requests:
- Check the configuration in `/server-settings`
- Review logs in the terminal
- Check the `config/config.json` file for errors

---

## License

See LICENSE file for details.