Skip to content

Commit 3037c3f

Browse files
jorge-menjivarjorge-menjivar
authored
Merge pull request #3 from jorge-menjivar/install_script
[FEAT] Add quick installer
2 parents 9d35aeb + d0942be commit 3037c3f

File tree

5 files changed

+997
-59
lines changed

5 files changed

+997
-59
lines changed

‎.github/workflows/release.yml‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
tags:
6+
- "v*"
7+
workflow_dispatch:
8+
9+
env:
10+
CARGO_TERM_COLOR: always
11+
12+
jobs:
13+
build-linux:
14+
name: Build Linux Binaries
15+
strategy:
16+
matrix:
17+
include:
18+
# x86_64 builds
19+
- target: x86_64-unknown-linux-gnu
20+
features: ""
21+
suffix: cpu
22+
runner: ubuntu-latest
23+
- target: x86_64-unknown-linux-gnu
24+
features: "cuda"
25+
suffix: cuda
26+
runner: ubuntu-latest
27+
- target: x86_64-unknown-linux-gnu
28+
features: "cuda,cudnn"
29+
suffix: cuda-cudnn
30+
runner: ubuntu-latest
31+
32+
# aarch64 builds
33+
- target: aarch64-unknown-linux-gnu
34+
features: ""
35+
suffix: cpu
36+
runner: ubuntu-latest
37+
- target: aarch64-unknown-linux-gnu
38+
features: "cuda"
39+
suffix: cuda
40+
runner: ubuntu-latest
41+
- target: aarch64-unknown-linux-gnu
42+
features: "cuda,cudnn"
43+
suffix: cuda-cudnn
44+
runner: ubuntu-latest
45+
46+
runs-on: ${{ matrix.runner }}
47+
48+
steps:
49+
- uses: actions/checkout@v4
50+
51+
- name: Install system dependencies
52+
run: |
53+
sudo apt-get update
54+
sudo apt-get install -y \
55+
libxkbcommon-dev \
56+
libwayland-dev \
57+
libxkbcommon-x11-dev \
58+
libegl1-mesa-dev \
59+
libfontconfig1-dev \
60+
libfreetype6-dev \
61+
libglib2.0-dev \
62+
libgtk-4-dev \
63+
libspeechd-dev \
64+
libxrandr-dev \
65+
libxinerama-dev \
66+
libxcursor-dev \
67+
libxi-dev \
68+
libxss-dev \
69+
libasound2-dev \
70+
pkg-config
71+
72+
- name: Install cross-compilation tools for aarch64
73+
if: matrix.target == 'aarch64-unknown-linux-gnu'
74+
run: |
75+
sudo dpkg --add-architecture arm64
76+
sudo apt-get update
77+
sudo apt-get install -y gcc-aarch64-linux-gnu g++-aarch64-linux-gnu
78+
echo "CARGO_TARGET_AARCH64_UNKNOWN_LINUX_GNU_LINKER=aarch64-linux-gnu-gcc" >> $GITHUB_ENV
79+
echo "CC_aarch64_unknown_linux_gnu=aarch64-linux-gnu-gcc" >> $GITHUB_ENV
80+
echo "CXX_aarch64_unknown_linux_gnu=aarch64-linux-gnu-g++" >> $GITHUB_ENV
81+
echo "PKG_CONFIG_PATH=/usr/lib/aarch64-linux-gnu/pkgconfig" >> $GITHUB_ENV
82+
echo "PKG_CONFIG_ALLOW_CROSS=1" >> $GITHUB_ENV
83+
84+
- name: Install Rust
85+
uses: dtolnay/rust-toolchain@stable
86+
with:
87+
targets: ${{ matrix.target }}
88+
89+
- name: Install CUDA (if needed)
90+
if: contains(matrix.features, 'cuda')
91+
uses: Jimver/cuda-toolkit@7263c89f6aa4f1c5247a0947b8e9f8eedfce66a5
92+
with:
93+
cuda: "12.4.0"
94+
95+
- name: Cache dependencies
96+
uses: actions/cache@v3
97+
with:
98+
path: |
99+
~/.cargo/registry
100+
~/.cargo/git
101+
target
102+
key: ${{ runner.os }}-${{ matrix.target }}-cargo-${{ hashFiles('**/Cargo.lock') }}
103+
104+
- name: Build daemon binary
105+
run: |
106+
if [ -z "${{ matrix.features }}" ]; then
107+
cargo build --release --target ${{ matrix.target }} --bin super-stt
108+
else
109+
cargo build --release --target ${{ matrix.target }} --bin super-stt --features "${{ matrix.features }}"
110+
fi
111+
112+
- name: Build app binary
113+
run: |
114+
cargo build --release --target ${{ matrix.target }} --bin super-stt-app
115+
116+
- name: Build applet binary
117+
run: |
118+
cargo build --release --target ${{ matrix.target }} --bin super-stt-cosmic-applet
119+
120+
- name: Create tarball
121+
run: |
122+
mkdir -p dist
123+
cp target/${{ matrix.target }}/release/super-stt dist/
124+
cp target/${{ matrix.target }}/release/super-stt-app dist/
125+
cp target/${{ matrix.target }}/release/super-stt-cosmic-applet dist/
126+
127+
# Include systemd service files
128+
mkdir -p dist/systemd
129+
if [ -f super-stt/systemd/super-stt.service ]; then
130+
cp super-stt/systemd/super-stt.service dist/systemd/
131+
fi
132+
133+
# Create tarball with architecture and feature suffix
134+
tar -czf super-stt-${{ matrix.target }}-${{ matrix.suffix }}.tar.gz -C dist .
135+
136+
- name: Upload artifact
137+
uses: actions/upload-artifact@v3
138+
with:
139+
name: super-stt-${{ matrix.target }}-${{ matrix.suffix }}
140+
path: super-stt-${{ matrix.target }}-${{ matrix.suffix }}.tar.gz
141+
142+
create-release:
143+
name: Create Release
144+
needs: build-linux
145+
runs-on: ubuntu-latest
146+
if: startsWith(github.ref, 'refs/tags/')
147+
148+
steps:
149+
- uses: actions/checkout@v4
150+
151+
- name: Download all artifacts
152+
uses: actions/download-artifact@v3
153+
with:
154+
path: artifacts
155+
156+
- name: Create Release
157+
uses: softprops/action-gh-release@v1
158+
with:
159+
files: artifacts/**/*.tar.gz
160+
draft: false
161+
prerelease: false
162+
generate_release_notes: true
163+
env:
164+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

‎README.md‎

Lines changed: 118 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,73 @@
1919
- **🎵 Real-time audio visualization** in COSMIC panel
2020

2121
## 🚀 Installation
22+
23+
### Quick Install (Recommended)
24+
25+
Install with our automated installer that detects your system and downloads pre-built binaries:
26+
27+
```bash
28+
curl -sSL https://raw.githubusercontent.com/jorge-menjivar/super-stt/main/install.sh | bash
29+
```
30+
31+
The installer will show a menu where you can choose which components to install:
32+
- **All** [DEFAULT] - Everything (daemon, app, applet if on COSMIC, systemd service)
33+
- **Daemon + CLI** - Core functionality + systemd service
34+
- **Desktop App** - GUI for configuration only
35+
- **COSMIC Applet** - Panel integration only
36+
37+
The installer automatically:
38+
- Detects your system architecture (x86_64/ARM64) to download the optimal pre-built binary
39+
- Installs components to `~/.local/bin`
40+
- **Daemon**: Detects CUDA/cuDNN for automatic GPU acceleration
41+
- **Daemon**: Creates the `stt` group and adds the current user to it **(requires sudo)**
42+
- **Daemon**: Sets up systemd user service
43+
- **Daemon**: Creates required directories for logs and sockets
44+
- **COSMIC Desktop**: Offers to configure Super+Space keyboard shortcut automatically
45+
46+
## ⌨️ Setting Up Keyboard Shortcuts
47+
48+
For the best experience, add a keyboard shortcut to your desktop environment:
49+
50+
### COSMIC Desktop
51+
52+
**Automatic Setup**:
53+
- **Web Installer**: The installer automatically offers to configure Super+Space shortcut during daemon installation. Just answer "Y" when prompted!
54+
- **Building from source**:
55+
- Run `just install-daemon` - it will offer to set up the shortcut automatically
56+
- Or run `just setup-cosmic-shortcut` anytime (no separate scripts needed)
57+
58+
**What gets configured**:
59+
- The shortcut uses the full path for reliability: `/home/user/.local/bin/stt record --write`
60+
- Safely extends your existing COSMIC shortcuts without overwriting
61+
- Detects conflicts and warns if Super+Space is already in use
62+
63+
**Manual Setup**:
64+
1. Open COSMIC Settings
65+
2. Navigate to: **Input Devices** → **Keyboard** → **View and customize shortcuts** → **Custom**
66+
3. Click **Add Shortcut**
67+
4. Set command: `/home/user/.local/bin/stt record --write` (replace `/home/user` with your actual home path)
68+
5. Choose your preferred key combination (e.g., `Super+Space`)
69+
70+
### Other Desktop Environments
71+
72+
**GNOME:**
73+
```bash
74+
# Add via command line
75+
gsettings set org.gnome.settings-daemon.plugins.media-keys custom-keybindings "['/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/']"
76+
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ name 'Super STT'
77+
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'
78+
gsettings set org.gnome.settings-daemon.plugins.media-keys.custom-keybinding:/org/gnome/settings-daemon/plugins/media-keys/custom-keybindings/custom0/ binding '<Super>space'
79+
```
80+
81+
**KDE Plasma:**
82+
1. Open System Settings → Shortcuts → Custom Shortcuts
83+
2. Add new shortcut with command: `stt record --write`
84+
85+
**Or configure through your desktop environment's settings for custom keyboard shortcuts.**
86+
87+
### Building from Source
88+
2289
```bash
2390
git clone https://github.com/jorge-menjivar/super-stt.git
2491
cd super-stt
@@ -29,21 +96,17 @@ just install-app
2996
# (Optional) COSMIC Desktop applet to show visualizations
3097
just install-applet
3198

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

40-
## ⌨️ Shortcuts
41-
Add a shortcut that executes the following command to your desktop environment to start the app.
42-
```sh
43-
stt record --write
106+
# Or set up COSMIC keyboard shortcut separately
107+
just setup-cosmic-shortcut
44108
```
45109

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

48111
> **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.
49112
@@ -56,35 +119,60 @@ The following will then happen:
56119
5. The daemon will automatically replace the preview with the accurate transcription.
57120

58121
### Usage
122+
123+
After installation, manage the daemon with:
59124
```bash
60-
# Make sure Super STT is running.
125+
# Start the daemon
126+
systemctl --user start super-stt
127+
128+
# Enable auto-start with user session
129+
systemctl --user enable super-stt
130+
131+
# Check status
61132
systemctl --user status super-stt
62133

63-
# If not running, start it
64-
systemctl --user start super-stt
134+
# View logs
135+
journalctl --user -u super-stt -f
65136
```
66137

67-
### Troubleshooting
68-
69-
#### `super-stt` is not found
70-
You may need to log out and back in to update your PATH environment variable.
138+
Then use the `stt` command:
139+
```bash
140+
# Record and transcribe
141+
stt record
71142

72-
#### `stt` is not found
73-
Try rerunning the `just install-daemon` command.
143+
# Record, transcribe, and auto-type the result
144+
stt record --write
145+
```
74146

75-
### Model Selection
147+
### Troubleshooting
76148

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

79-
**When installing**:
154+
#### "sg: group 'stt' does not exist" error
155+
The `stt` group wasn't created properly. Run:
80156
```bash
81-
# Install with specific model
82-
just install-daemon --model whisper-large-v3
157+
sudo groupadd stt
158+
sudo usermod -a -G stt $(whoami)
159+
newgrp stt
160+
```
83161

84-
# Or specify during daemon start
85-
stt --model whisper-base
162+
#### "Operation not permitted" when using stt
163+
You need to be in the `stt` group. Either:
164+
- Log out and back in, or
165+
- Run: `newgrp stt`
166+
167+
#### Daemon not starting
168+
Check the logs for errors:
169+
```bash
170+
journalctl --user -u super-stt -n 50
86171
```
87172

173+
### Model Selection
174+
Open the Super STT app → Settings → Select model
175+
88176
## 🏗️ Architecture
89177

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

97185
Super STT implements comprehensive security controls:
98186

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

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

@@ -125,6 +213,12 @@ just run-app
125213
# Run the applet
126214
just run-applet
127215

216+
# Setup COSMIC keyboard shortcut (interactive)
217+
just setup-cosmic-shortcut
218+
219+
# Install daemon with automatic COSMIC shortcut setup
220+
just install-daemon
221+
128222
# Run security audit
129223
just audit
130224
```

0 commit comments

Comments
 (0)