ubuntu not working. idk I'm just gonna use windows anyway
This commit is contained in:
@@ -0,0 +1,156 @@
|
||||
# Getting Started with StepForge on Linux
|
||||
|
||||
> ⚠️ **Work in progress.** Linux support is still under active development.
|
||||
> Expect rough edges — especially on Wayland (see the limitations below). X11 /
|
||||
> Xorg is the most complete path today. Please report issues.
|
||||
|
||||
StepForge was built on Windows, where the OS lets an app watch every click and
|
||||
grab the screen freely. Linux is more restrictive, and **how much works depends
|
||||
on whether you are running X11 (Xorg) or Wayland.** This guide explains the
|
||||
difference, how to get the best experience, and how to enable per-click capture.
|
||||
|
||||
## TL;DR
|
||||
|
||||
| | **X11 / "Ubuntu on Xorg"** | **Wayland (default on Ubuntu)** |
|
||||
|---|---|---|
|
||||
| Screenshot per click | ✅ Yes | ✅ Yes (needs `input` group) |
|
||||
| Red circle on the click | ✅ Yes | ❌ No (Wayland hides the cursor position) |
|
||||
| "Share your screen" prompt | Never | Once per recording session |
|
||||
| Setup needed | None | Add yourself to the `input` group |
|
||||
|
||||
**If you want the full Windows-like experience (click capture *with* the red
|
||||
marker), use an Xorg session — see [Option A](#option-a-best-experience--use-xorg).**
|
||||
|
||||
---
|
||||
|
||||
## 1. Check which session you are running
|
||||
|
||||
```bash
|
||||
echo $XDG_SESSION_TYPE
|
||||
```
|
||||
|
||||
- `x11` → you're on Xorg. Everything works, including the red click marker. No setup needed.
|
||||
- `wayland` → you're on Wayland. Read on.
|
||||
|
||||
---
|
||||
|
||||
## Option A (best experience) — use Xorg
|
||||
|
||||
On Xorg, StepForge captures a screenshot **on every click** and draws the **red
|
||||
marker** at the exact click position, exactly like Windows. No dependencies, no
|
||||
permissions, no portal dialogs.
|
||||
|
||||
To switch:
|
||||
|
||||
1. Log out.
|
||||
2. On the login (password) screen, click the **⚙ gear icon** in the bottom-right corner.
|
||||
3. Choose **"Ubuntu on Xorg"**.
|
||||
4. Log back in.
|
||||
|
||||
That's it — open StepForge and record. (To go back to Wayland later, pick
|
||||
"Ubuntu" at the gear menu again.)
|
||||
|
||||
---
|
||||
|
||||
## Option B — stay on Wayland
|
||||
|
||||
Wayland deliberately blocks apps from monitoring global input and from grabbing
|
||||
the screen silently. StepForge works around this as far as the platform allows:
|
||||
|
||||
### Screen capture
|
||||
|
||||
The first time you press **Start recording**, the system shows a **"Share your
|
||||
screen"** dialog (the XDG desktop portal). Pick your screen and click **Share**.
|
||||
This happens **once per recording session** — not per screenshot. The shared
|
||||
stream stays open until you stop recording.
|
||||
|
||||
> If you never see steps appear, make sure you actually picked a screen and
|
||||
> clicked **Share** in that dialog.
|
||||
|
||||
### Per-click capture (requires the `input` group)
|
||||
|
||||
By default on Wayland, StepForge cannot see your clicks, so it falls back to
|
||||
**capturing a screenshot every few seconds** (timed capture).
|
||||
|
||||
To get a screenshot **on every click** instead, give your user read access to
|
||||
the mouse devices by joining the `input` group:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG input "$USER"
|
||||
```
|
||||
|
||||
Then **log out and log back in** (group membership only applies to new sessions).
|
||||
Verify it took effect:
|
||||
|
||||
```bash
|
||||
groups | tr ' ' '\n' | grep input # should print: input
|
||||
```
|
||||
|
||||
Now StepForge reads mouse buttons directly from the kernel (`/dev/input`) and
|
||||
captures a screenshot on each click.
|
||||
|
||||
> **No red marker on Wayland.** Even with per-click capture working, Wayland
|
||||
> does not tell apps *where* the pointer is, so StepForge cannot draw the circle
|
||||
> at the click. The screenshot is still captured per click — just without the
|
||||
> marker. If you need the marker, use [Option A (Xorg)](#option-a-best-experience--use-xorg).
|
||||
|
||||
### Adjusting the timed-capture interval
|
||||
|
||||
If you don't enable the `input` group, StepForge captures on a timer. Change the
|
||||
fallback in **Settings → Capture**:
|
||||
|
||||
- `When clicks are unavailable` -> `Hotkey only` to use the Capture hotkey
|
||||
instead of a timer.
|
||||
- `When clicks are unavailable` -> `Timed interval`, then set
|
||||
`Timer interval (seconds)` (`capture.autoIntervalSec`, default 5 seconds)
|
||||
if you want timed captures.
|
||||
|
||||
---
|
||||
|
||||
## How StepForge picks a capture method (for reference)
|
||||
|
||||
On launch StepForge chooses the best available click source:
|
||||
|
||||
1. **Windows** — low-level mouse hook (position + timing).
|
||||
2. **X11** — `xinput` (position + timing → full red marker).
|
||||
3. **Linux evdev** (`/dev/input`) — button presses on X11 *and* Wayland, no
|
||||
position on Wayland. Used when `xinput` can't see clicks (i.e. Wayland), if
|
||||
you're in the `input` group.
|
||||
4. **Timed capture** — the always-works fallback (a screenshot every N seconds)
|
||||
when no click source is available.
|
||||
|
||||
Screen frames come from a single long-lived capture stream per recording, so
|
||||
clicks/timer ticks never re-open the screen-share dialog.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**"It asks to share my screen every time."**
|
||||
You're likely on an older build. Update to the current version — the screen
|
||||
stream is now opened once per recording session. If it persists, confirm
|
||||
`echo $XDG_SESSION_TYPE` and that you clicked **Share** (not Cancel) in the dialog.
|
||||
|
||||
**"Recording captures a couple of steps then stops."**
|
||||
Fixed in the current version (a slow, GPU-less PNG encode used to trip a
|
||||
failure guard and tear down the stream). Update and retry.
|
||||
|
||||
**"The window disappeared and I can't stop the recording."**
|
||||
On Linux the window **minimizes** while recording (GNOME's system tray is
|
||||
unreliable). Bring it back from the **taskbar / dock**, then click **Stop
|
||||
recording**.
|
||||
|
||||
**"No steps at all on Wayland, even after picking a screen."**
|
||||
Run from a terminal with logging and look for the diagnostic lines:
|
||||
|
||||
```bash
|
||||
STEPFORGE_CAPTURE_LOG=1 npm start
|
||||
```
|
||||
|
||||
- `[stepforge] screen-capture stream active …` — the stream is up.
|
||||
- `[stepforge] per-click capture via evdev on N device(s) …` — clicks are wired up.
|
||||
- `[stepforge] no readable mouse input devices …` — you need the `input` group (see above).
|
||||
|
||||
**Harmless console noise.** Lines like `vaInitialize failed`, `Frame latency is
|
||||
negative`, and `StatusNotifierItem … already exported` come from Chromium/GNOME,
|
||||
not StepForge, and don't affect recording.
|
||||
Reference in New Issue
Block a user