screen-toolkit : full screen utility

screen-toolkit/README.md

@@ -0,0 +1,194 @@
+# Screen Toolkit
+
+A Noctalia v5 plugin for color picking, OCR, QR/barcode scanning, palette
+extraction, Google Lens search, annotation, pixel measuring, screen recording,
+and image sharing.
+
+## Attribution
+
+Screen Toolkit was originally created for Noctalia v4 by the author(s) of the
+[legacy screen-toolkit plugin](https://github.com/noctalia-dev/legacy-v4-plugins/tree/main/screen-toolkit).
+This repository is an independent Noctalia v5 remake/port by `alexander`; it is
+not the original implementation.
+
+## Plugin
+
+| Field | Value |
+| --- | --- |
+| ID | `alexander/screen-toolkit` |
+| Entries | Bar widget: `widget`; control-center shortcut: `toggle`; panels: `panel` (tools), `result` (result view); service: `service` |
+
+## Requirements
+
+Install the tools used by the features you want on `PATH`. Missing tools are
+reported when that feature is started.
+
+- **`slurp`** — region selection
+- **`grim`** — screen capture
+- **`hyprpicker`** — pixel color picking
+- **`tesseract`** — OCR engine (plus your language packs, e.g. `tesseract-data-eng`)
+- **`imagemagick`** — image processing
+- **`zbar`** — QR / barcode scanning (`zbarimg`)
+- **`curl`** + **`jq`** — image uploads (uguu.se / x02.me) and Google Lens
+- **`ffmpeg`** + **`ffprobe`** — recording / GIF conversion and thumbnail generation
+- **`bc`** — GIF duration and frame-rate calculations
+- **`stat`** — recording file size
+- **`pkill`** — stopping active recording backends
+- **`xdg-open`** — opening URLs, OCR search results, and shared-link targets
+
+Recording requires at least one backend:
+
+- **`gpu-screen-recorder`** — recommended for fullscreen recording, especially on NVIDIA (NVENC)
+- **`wl-screenrec`** — preferred for region recording and microphone audio
+- **`wf-recorder`** — fallback recorder for region and fullscreen capture
+
+Optional:
+
+- **`swappy`** / **`satty`** — annotation editor (Markup tool)
+- **`gimp`** — fallback annotation editor when swappy/satty are missing
+- **`translate-shell`** (`trans`) — OCR translation
+- **hyprctl** — annotate the focused window (Hyprland only)
+
+Compositor support: region tools, measure, annotate and recording work on any
+Wayland compositor with `wlroots` protocols. `Annotate Window` requires Hyprland
+(`hyprctl`).
+
+## Usage
+
+Add the `Screen Toolkit` widget to a bar, and/or the shortcut tile in
+Settings → Control Center shortcuts. Left-click either one opens the main panel
+(or stops a recording); right-clicking the bar widget quick-picks a color. While
+a recording is active, the widget and shortcut show a pulsing red dot.
+
+Open the main tools panel:
+
+```sh
+noctalia msg panel-toggle alexander/screen-toolkit:panel
+```
+
+Open the result panel (shows the last capture/recording output):
+
+```sh
+noctalia msg panel-toggle alexander/screen-toolkit:result
+```
+
+The tools panel contains the capture actions. When a capture tool finishes, a
+**result panel** opens with the output and its actions; close it to return to
+the tools panel.
+
+Region tools (Color, OCR, QR, Palette, Lens, Measure, GIF/MP4 record, Markup)
+draw a `slurp` crosshair — drag to select a region, then release. Recording
+starts immediately and the bar widget shows the pulsing dot; click the dot, the
+widget, the shortcut, or the panel's **Stop** button to end it. Unless "Skip
+Save Confirmation" is on, the panel then offers **Save MP4**, **Save GIF**,
+**Copy**, and **Discard**.
+
+The `hide-cursor` setting excludes the cursor from **recordings and screenshots**
+(default: hidden). Grim excludes the cursor by default; when the setting is
+disabled, the plugin passes grim's `-c` flag to include it. gpu-screen-recorder
+and wl-screenrec receive their corresponding cursor options. wf-recorder does
+not expose a portable cursor flag, so its behavior depends on the compositor.
+
+- **Markup** captures the region and opens it in `swappy` (or `satty`). Saving
+  happens in that editor; satty saves to your screenshot path automatically.
+  **Markup Window** shows a crosshair — click the window you want to annotate
+  and it captures that window (Hyprland only).
+- **Measure** reports the region's pixel size and copies it to the clipboard.
+- **OCR** extracts text and copies it to the clipboard. The result includes the
+  capture preview and an editable multiline text area, so you can correct, trim,
+  or extend the OCR output before copying, searching, translating, or sharing
+  it. Detected URLs can be opened directly and detected email addresses can
+  open a mail composer.
+- **QR** decodes a code and copies the text to the clipboard.
+- **Palette** copies the extracted hex colors (one per line) to the clipboard.
+- **Share** uploads the current capture and copies the link (uguu.se by default,
+  or up.x02.me with an API key).
+
+Results are delivered to the clipboard with a notification — the panel itself
+only holds the tools. Results persist across restarts in the plugin's data
+directory; the capture previews live in `/tmp` and are only kept for the
+session.
+
+## Settings
+
+All settings live in Settings → Plugins (gear on the plugin's row).
+
+| Setting | Type | Default | Description |
+| --- | --- | --- | --- |
+| `screenshot-path` | `folder` | `~/Pictures/Screenshots` | Where satty saves annotations. |
+| `video-path` | `folder` | `~/Videos` | Where recordings are saved. |
+| `filename-format` | `string` | `%Y-%m-%d_%H-%M-%S` | Filename template; the extension is added automatically. |
+| `selected-ocr-lang` | `string` | `eng` | Tesseract language code; combine with `+` (e.g. `eng+fra`). |
+| `search-engine-url` | `string` | *(Google)* | Search URL prefix, or a URL containing `{text}`. The OCR text is URL-encoded. |
+| `x02-api-key` | `string` | *(empty)* | up.x02.me key for longer-lived, larger uploads. |
+| `x02-expiry` | `select` | `7d` | Link lifetime when an x02 key is set: `1h`, `1d`, `7d`, `30d`, or `permanent`. |
+| `share-skip-popover` | `bool` | `false` | Compatibility setting retained from v4. The v5 result panel copies share links directly. |
+| `record-audio-out` | `bool` | `false` | Record the desktop's audio output. |
+| `record-audio-in` | `bool` | `false` | Record the default microphone. |
+| `hide-cursor` | `bool` | `true` | Exclude the cursor from recordings and screenshots. On Hyprland, screenshots briefly move the pointer off-screen during capture. |
+| `record-codec` | `select` | `h264` | Codec for `gpu-screen-recorder` fullscreen capture: `h264`, `hevc`, or `av1`. `h264` is the safest NVIDIA NVENC default; `av1` needs a recent GPU. |
+| `record-fps` | `int` | `60` | Frame rate for `gpu-screen-recorder` fullscreen capture (15–240). |
+| `record-skip-confirmation` | `bool` | `false` | Save automatically when a recording ends, skipping the save dialog. |
+| `record-copy-to-clipboard` | `bool` | `false` | Finalize to MP4 and copy the file URI when recording ends. |
+| `gif-max-seconds` | `int` | `30` | Cap for GIF recordings (1–600 s). |
+
+## IPC
+
+The service is a singleton with no output, so the IPC target is `all`:
+
+```sh
+noctalia msg plugin alexander/screen-toolkit:service all toggle
+noctalia msg plugin alexander/screen-toolkit:service all colorPicker
+noctalia msg plugin alexander/screen-toolkit:service all ocr
+noctalia msg plugin alexander/screen-toolkit:service all qr
+noctalia msg plugin alexander/screen-toolkit:service all palette
+noctalia msg plugin alexander/screen-toolkit:service all lens
+noctalia msg plugin alexander/screen-toolkit:service all measure
+noctalia msg plugin alexander/screen-toolkit:service all annotate
+noctalia msg plugin alexander/screen-toolkit:service all annotateFullscreen
+noctalia msg plugin alexander/screen-toolkit:service all annotateWindow
+noctalia msg plugin alexander/screen-toolkit:service all record
+noctalia msg plugin alexander/screen-toolkit:service all recordMp4
+noctalia msg plugin alexander/screen-toolkit:service all recordFullscreen
+noctalia msg plugin alexander/screen-toolkit:service all recordFullscreenMp4
+noctalia msg plugin alexander/screen-toolkit:service all recordStop
+noctalia msg plugin alexander/screen-toolkit:service all recordSave
+noctalia msg plugin alexander/screen-toolkit:service all recordDiscard
+```
+
+`ocrTranslate` takes a language code payload:
+
+```sh
+noctalia msg plugin alexander/screen-toolkit:service all ocrTranslate en
+```
+
+## Notes
+
+- This is a port of the legacy v4
+  [screen-toolkit](https://github.com/noctalia-dev/legacy-v4-plugins/tree/main/screen-toolkit)
+  plugin. Tools that relied on freeform v4 QML overlays are adapted: region
+  selection uses `slurp`, annotation hands off to `swappy`/`satty`, and measure
+  reports region dimensions instead of drawing a line overlay. **Pin** (floating
+  screen overlays) and **Webcam Mirror** could not be ported — the v5 plugin UI
+  has no canvas or always-on-top surfaces — so they are not included.
+- Recording auto-detects its backend: **fullscreen** uses `gpu-screen-recorder`
+  when installed (NVENC hardware encoding — the best option on NVIDIA GPUs,
+  where wl-screenrec's VAAPI path is unreliable), falling back to
+  `wl-screenrec` then `wf-recorder`. **Region** capture uses `wl-screenrec` then
+  `wf-recorder`, because `gpu-screen-recorder` cannot record an arbitrary
+  sub-region. Microphone audio is only supported by `wl-screenrec`; with
+  `wf-recorder` only system audio is available, and gpu-screen-recorder's audio
+  follows its own source selection.
+- Region coordinates are captured in physical pixels; `recordFullscreen`
+  multiplies the focused output's logical geometry by its scale.
+- Files are written to your configured screenshot/video directories and the
+  plugin's persistent data directory (state, color history). Captures in `/tmp`
+  are transient.
+- Network calls: Google Lens upload (uguu.se), share uploads (uguu.se or
+  up.x02.me), and `xdg-open` for search/URL results.
+
+## License
+
+This remake is released under the MIT license. It is an independent v5 port of
+the original legacy plugin; see [Attribution](#attribution) for the original
+project and source.

screen-toolkit/panel.luau

@@ -0,0 +1,162 @@
+--!nonstrict
+-- Screen Toolkit — main [[panel]].
+--
+-- Thin client for the toolkit: a header plus the tool grid grouped into
+-- Capture / Annotate / Record sections. It only dispatches actions to the
+-- [[service]] through the "command" state channel. Capture tools close the
+-- panel first so the capture never includes it.
+
+local panelOpen = false
+local recording = noctalia.state.get("recording") == true
+
+-- ── Helpers ────────────────────────────────────────────────────────────────
+
+local function tr(key, subst)
+  if subst then return noctalia.tr(key, subst) end
+  return noctalia.tr(key)
+end
+
+local function send(action, payload)
+  noctalia.state.set("command", { action = action, payload = payload })
+end
+
+-- Capture tools must not see the panel in the frame, so close it first.
+local CAPTURE_ACTIONS = {
+  colorPicker = true,
+  ocr = true,
+  qr = true,
+  palette = true,
+  lens = true,
+  measure = true,
+  annotate = true,
+  annotateFullscreen = true,
+  annotateWindow = true,
+  record = true,
+  recordMp4 = true,
+  recordFullscreen = true,
+  recordFullscreenMp4 = true,
+}
+
+local function runTool(action)
+  if CAPTURE_ACTIONS[action] then
+    panel.close()
+  end
+  send(action)
+end
+
+-- ── Header ─────────────────────────────────────────────────────────────────
+
+local function header()
+  local actions = {
+    ui.button({ glyph = "close", onClick = function() panel.close() end }),
+  }
+  if recording then
+    table.insert(actions, 1, ui.button({
+      glyph = "square",
+      variant = "destructive",
+      controlSize = "sm",
+      tooltip = tr("panel.stop"),
+      onClick = function() send("recordStop") end,
+    }))
+  end
+  return ui.row({ align = "center", gap = 8 }, {
+    ui.label({ text = tr("panel.title"), flexGrow = 1, fontSize = 16, fontWeight = "bold", color = "on_surface" }),
+    ui.row({ gap = 4 }, actions),
+  })
+end
+
+-- ── Tool grid ──────────────────────────────────────────────────────────────
+
+local TOOLS = {
+  { action = "colorPicker", label_key = "tools.colorpicker", glyph = "palette" },
+  { action = "ocr", label_key = "tools.ocr", glyph = "scan" },
+  { action = "qr", label_key = "tools.qr", glyph = "qrcode" },
+  { action = "palette", label_key = "tools.palette", glyph = "color-swatch" },
+  { action = "lens", label_key = "tools.lens", glyph = "search" },
+  { action = "measure", label_key = "tools.measure", glyph = "ruler" },
+}
+
+local ANNOTATE_TOOLS = {
+  { action = "annotate", label_key = "tools.annotate", glyph = "pencil" },
+  { action = "annotateFullscreen", label_key = "tools.annotate_fullscreen", glyph = "maximize" },
+  { action = "annotateWindow", label_key = "tools.annotate_window", glyph = "window" },
+}
+
+local RECORD_TOOLS = {
+  { action = "record", label_key = "tools.record_gif", glyph = "gif" },
+  { action = "recordMp4", label_key = "tools.record_mp4", glyph = "movie" },
+  { action = "recordFullscreen", label_key = "tools.record_fullscreen_gif", glyph = "video" },
+  { action = "recordFullscreenMp4", label_key = "tools.record_fullscreen_mp4", glyph = "video" },
+}
+
+local function toolTile(t)
+  return ui.column({
+    key = "tile-" .. t.action,
+    flexGrow = 1,
+    gap = 6,
+    align = "center",
+    paddingV = 6,
+    radius = 10,
+    fill = "surface_variant/0.28",
+    borderWidth = 1,
+    border = "outline",
+    onClick = function() runTool(t.action) end,
+  }, {
+    ui.column({ width = 30, height = 30, radius = 9, fill = "primary/0.12", align = "center", justify = "center" }, {
+      ui.glyph({ name = t.glyph, size = 16, color = "primary" }),
+    }),
+    ui.label({ text = tr(t.label_key), maxWidth = 100, maxLines = 1, textAlign = "center", fontSize = 11, color = "on_surface_variant" }),
+  })
+end
+
+local function toolsRow(tools)
+  local row = {}
+  for _, t in ipairs(tools) do
+    row[#row + 1] = toolTile(t)
+  end
+  return ui.row({ flexGrow = 1, gap = 6 }, row)
+end
+
+local function sectionLabel(text)
+  return ui.label({ text = text, fontSize = 11, fontWeight = "bold", color = "on_surface_variant" })
+end
+
+local function toolGrid()
+  return ui.column({ flexGrow = 1, gap = 4, justify = "space_between" }, {
+    sectionLabel(tr("panel.section_capture")),
+    toolsRow(TOOLS),
+    sectionLabel(tr("panel.section_annotate")),
+    toolsRow(ANNOTATE_TOOLS),
+    sectionLabel(tr("panel.section_record")),
+    toolsRow(RECORD_TOOLS),
+  })
+end
+
+-- ── Main render ────────────────────────────────────────────────────────────
+
+local function render()
+  panel.render(ui.column({ flexGrow = 1, gap = 10 }, {
+    header(),
+    toolGrid(),
+  }))
+end
+
+-- ── Lifecycle ──────────────────────────────────────────────────────────────
+
+function onOpen(_context)
+  panelOpen = true
+  render()
+end
+
+function onClose()
+  panelOpen = false
+end
+
+noctalia.state.watch("recording", function(v)
+  recording = v == true
+  if panelOpen then render() end
+end)
+
+function update()
+  noctalia.setUpdateInterval(500)
+end