Skip to content

feat(docs): add quick installer and shortcut setup to README #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 19, 2025
Merged

feat(docs): add quick installer and shortcut setup to README #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
164 changes: 164 additions & 0 deletions .github/workflows/release.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,164 @@
name: Release

on:
push:
tags:
- "v*"
workflow_dispatch:

env:
CARGO_TERM_COLOR: always

jobs:
build-linux:
name: Build Linux Binaries
strategy:
matrix:
include:
# x86_64 builds
- target: x86_64-unknown-linux-gnu
features: ""
suffix: cpu
runner: ubuntu-latest
- target: x86_64-unknown-linux-gnu
features: "cuda"
suffix: cuda
runner: ubuntu-latest
- target: x86_64-unknown-linux-gnu
features: "cuda,cudnn"
suffix: cuda-cudnn
runner: ubuntu-latest

# aarch64 builds
- target: aarch64-unknown-linux-gnu
features: ""
suffix: cpu
runner: ubuntu-latest
- target: aarch64-unknown-linux-gnu
features: "cuda"
suffix: cuda
runner: ubuntu-latest
- target: aarch64-unknown-linux-gnu
features: "cuda,cudnn"
suffix: cuda-cudnn
runner: ubuntu-latest

runs-on: ${{ matrix.runner }}

steps:
- uses: actions/checkout@v4

- name: Install system dependencies
run: |
sudo apt-get update
sudo apt-get install -y \
libxkbcommon-dev \
libwayland-dev \
libxkbcommon-x11-dev \
libegl1-mesa-dev \
libfontconfig1-dev \
libfreetype6-dev \
libglib2.0-dev \
libgtk-4-dev \
libspeechd-dev \
libxrandr-dev \
libxinerama-dev \
libxcursor-dev \
libxi-dev \
libxss-dev \
libasound2-dev \
pkg-config

- name: Install cross-compilation tools for aarch64
if: matrix.target == 'aarch64-unknown-linux-gnu'
run: |
sudo dpkg --add-architecture arm64
sudo apt-get update
sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> $GITHUB_ENV
echo "CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc" >> $GITHUB_ENV
echo "CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++" >> $GITHUB_ENV
echo "PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig" >> $GITHUB_ENV
echo "PKG_CONFIG_ALLOW_CROSS=1" >> $GITHUB_ENV

- name: Install Rust
uses: dtolnay/rust-toolchain@stable
with:
targets: ${{ matrix.target }}

- name: Install CUDA (if needed)
if: contains(matrix.features, 'cuda')
uses: Jimver/cuda-toolkit@7263c89f6aa4f1c5247a0947b8e9f8eedfce66a5
with:
cuda: "12.4.0"

- name: Cache dependencies
uses: actions/cache@v3
with:
path: |
~/.cargo/registry
~/.cargo/git
target
key: ${{ runner.os }}-${{ matrix.target }}-cargo-${{ hashFiles('**/Cargo.lock') }}

- name: Build daemon binary
run: |
if [ -z "${{ matrix.features }}" ]; then
cargo build --release --target ${{ matrix.target }} --bin super-stt
else
cargo build --release --target ${{ matrix.target }} --bin super-stt --features "${{ matrix.features }}"
fi

- name: Build app binary
run: |
cargo build --release --target ${{ matrix.target }} --bin super-stt-app

- name: Build applet binary
run: |
cargo build --release --target ${{ matrix.target }} --bin super-stt-cosmic-applet

- name: Create tarball
run: |
mkdir -p dist
cp target/${{ matrix.target }}/release/super-stt dist/
cp target/${{ matrix.target }}/release/super-stt-app dist/
cp target/${{ matrix.target }}/release/super-stt-cosmic-applet dist/

# Include systemd service files
mkdir -p dist/systemd
if [ -f super-stt/systemd/super-stt.service ]; then
cp super-stt/systemd/super-stt.service dist/systemd/
fi

# Create tarball with architecture and feature suffix
tar -czf super-stt-${{ matrix.target }}-${{ matrix.suffix }}.tar.gz -C dist .

- name: Upload artifact
uses: actions/upload-artifact@v3
with:
name: super-stt-${{ matrix.target }}-${{ matrix.suffix }}
path: super-stt-${{ matrix.target }}-${{ matrix.suffix }}.tar.gz

create-release:
name: Create Release
needs: build-linux
runs-on: ubuntu-latest
if: startsWith(github.ref, 'refs/tags/')

steps:
- uses: actions/checkout@v4

- name: Download all artifacts
uses: actions/download-artifact@v3
with:
path: artifacts

- name: Create Release
uses: softprops/action-gh-release@v1
with:
files: artifacts/**/*.tar.gz
draft: false
prerelease: false
generate_release_notes: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
142 changes: 118 additions & 24 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,73 @@
- **🎵 Real-time audio visualization** in COSMIC panel

## 🚀 Installation

### Quick Install (Recommended)

Install with our automated installer that detects your system and downloads pre-built binaries:

```bash
curl -sSL https://raw.githubusercontent.com/jorge-menjivar/super-stt/main/install.sh | bash
```

The installer will show a menu where you can choose which components to install:
- **All** [DEFAULT] - Everything (daemon, app, applet if on COSMIC, systemd service)
- **Daemon + CLI** - Core functionality + systemd service
- **Desktop App** - GUI for configuration only
- **COSMIC Applet** - Panel integration only

The installer automatically:
- Detects your system architecture (x86_64/ARM64) to download the optimal pre-built binary
- Installs components to `~/.local/bin`
- **Daemon**: Detects CUDA/cuDNN for automatic GPU acceleration
- **Daemon**: Creates the `stt` group and adds the current user to it **(requires sudo)**
- **Daemon**: Sets up systemd user service
- **Daemon**: Creates required directories for logs and sockets
- **COSMIC Desktop**: Offers to configure Super+Space keyboard shortcut automatically

## ⌨️ Setting Up Keyboard Shortcuts

For the best experience, add a keyboard shortcut to your desktop environment:

### COSMIC Desktop

**Automatic Setup**:
- **Web Installer**: The installer automatically offers to configure Super+Space shortcut during daemon installation. Just answer "Y" when prompted!
- **Building from source**:
- Run `just install-daemon` - it will offer to set up the shortcut automatically
- Or run `just setup-cosmic-shortcut` anytime (no separate scripts needed)

**What gets configured**:
- The shortcut uses the full path for reliability: `/home/user/.local/bin/stt record --write`
- Safely extends your existing COSMIC shortcuts without overwriting
- Detects conflicts and warns if Super+Space is already in use

**Manual Setup**:
1. Open COSMIC Settings
2. Navigate to: **Input Devices** → **Keyboard** → **View and customize shortcuts** → **Custom**
3. Click **Add Shortcut**
4. Set command: `/home/user/.local/bin/stt record --write` (replace `/home/user` with your actual home path)
5. Choose your preferred key combination (e.g., `Super+Space`)

### Other Desktop Environments

**GNOME:**
```bash
# Add via command line
gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/']"
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ name 'Super STT'
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ command 'stt record --write'
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ binding '<Super>space'
```

**KDE Plasma:**
1. Open System Settings → Shortcuts → Custom Shortcuts
2. Add new shortcut with command: `stt record --write`

**Or configure through your desktop environment's settings for custom keyboard shortcuts.**

### Building from Source

```bash
git clone https://github.com/jorge-menjivar/super-stt.git
cd super-stt
Expand All @@ -29,21 +96,17 @@ just install-app
# (Optional) COSMIC Desktop applet to show visualizations
just install-applet

# The Daemon and CLI tool
# The Daemon and CLI tool (offers to set up COSMIC shortcut automatically)
just install-daemon
# (Suggestion) If you have an NVIDIA GPU with CUDA installed, build with CUDA acceleration instead to load models onto the GPU
# just install-daemon --cuda
# (Suggestion) If you have an NVIDIA GPU with CUDA and cuDNN installed, build with cuDNN acceleration instead for better performance
# just install-daemon --cudnn
```

## ⌨️ Shortcuts
Add a shortcut that executes the following command to your desktop environment to start the app.
```sh
stt record --write
# Or set up COSMIC keyboard shortcut separately
just setup-cosmic-shortcut
```

On COSMIC, you can add the shortcut in COSMIC Settings app: Input Devices -> Keyboard -> View and customize shortcuts -> Custom -> Add Shortcut

> **Note**: On first run, Super STT will automatically download the required AI model (~1-2GB). This may take a few minutes depending on your internet connection.

Expand All @@ -56,35 +119,60 @@ The following will then happen:
5. The daemon will automatically replace the preview with the accurate transcription.

### Usage

After installation, manage the daemon with:
```bash
# Make sure Super STT is running.
# Start the daemon
systemctl --user start super-stt

# Enable auto-start with user session
systemctl --user enable super-stt

# Check status
systemctl --user status super-stt

# If not running, start it
systemctl --user start super-stt
# View logs
journalctl --user -u super-stt -f
```

### Troubleshooting

#### `super-stt` is not found
You may need to log out and back in to update your PATH environment variable.
Then use the `stt` command:
```bash
# Record and transcribe
stt record

#### `stt` is not found
Try rerunning the `just install-daemon` command.
# Record, transcribe, and auto-type the result
stt record --write
```

### Model Selection
### Troubleshooting

**From UI**: Open app → Settings → Select model
#### `stt` command not found
The installer adds `~/.local/bin` to your PATH. Either:
- Restart your terminal, or
- Run: `export PATH="$HOME/.local/bin:$PATH"`

**When installing**:
#### "sg: group 'stt' does not exist" error
The `stt` group wasn't created properly. Run:
```bash
# Install with specific model
just install-daemon --model whisper-large-v3
sudo groupadd stt
sudo usermod -a -G stt $(whoami)
newgrp stt
```

# Or specify during daemon start
stt --model whisper-base
#### "Operation not permitted" when using stt
You need to be in the `stt` group. Either:
- Log out and back in, or
- Run: `newgrp stt`

#### Daemon not starting
Check the logs for errors:
```bash
journalctl --user -u super-stt -n 50
```

### Model Selection
Open the Super STT app → Settings → Select model

## 🏗️ Architecture

- **`super-stt`** - Background ML service
Expand All @@ -96,8 +184,8 @@ stt --model whisper-base

Super STT implements comprehensive security controls:

- **Group-based Access**: The `stt` group restricts who can connect to the daemon socket
- **Process Authentication**: Keyboard injection requires verification that the client is the legitimate `stt` binary
- **Group-based Access**: Production mode uses dedicated `stt` group for daemon access control

For detailed security information, see [`docs/SECURITY.md`](docs/SECURITY.md).

Expand Down Expand Up @@ -125,6 +213,12 @@ just run-app
# Run the applet
just run-applet

# Setup COSMIC keyboard shortcut (interactive)
just setup-cosmic-shortcut

# Install daemon with automatic COSMIC shortcut setup
just install-daemon

# Run security audit
just audit
```
Expand Down
Loading