mirror of
https://github.com/andwati/kget-capture.git
synced 2026-10-18 03:02:56 +00:00
Refactor README for distro install docs, fix release archive
Trim intro fluff, add per-distro dependency install commands, and make the Chrome Web Store the primary extension install path with unpacked install demoted to a dev-only section. Also switch the release workflow to archive the whole repo instead of just extension/, since install.sh and native-host/ are now what the README points users at downloading.
This commit is contained in:
@@ -15,10 +15,12 @@ jobs:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Package extension
|
||||
run: |
|
||||
cd extension
|
||||
zip -r "../kget-capture-${GITHUB_REF_NAME}.zip" .
|
||||
- name: Package source
|
||||
# Users need the whole repo (install.sh, native-host/, keys/), not
|
||||
# just extension/ -- the extension itself now ships via the Chrome
|
||||
# Web Store. git archive only includes tracked files, so the
|
||||
# gitignored private key (never committed) can't end up in it.
|
||||
run: git archive --format=zip -o "kget-capture-${GITHUB_REF_NAME}.zip" HEAD
|
||||
|
||||
- name: Create release
|
||||
uses: softprops/action-gh-release@v2
|
||||
|
||||
@@ -1,56 +1,84 @@
|
||||
# KGet Capture
|
||||
|
||||
A Chrome (and other Chromium-browser) extension that sends downloads to
|
||||
[KGet](https://apps.kde.org/kget/), KDE's download manager, instead of (or in
|
||||
addition to) the browser's built-in downloader.
|
||||
A Chromium browser extension that sends downloads to
|
||||
[KGet](https://apps.kde.org/kget/), KDE's download manager, instead of the
|
||||
browser's built-in downloader.
|
||||
|
||||
- Right-click any link, image, video, or audio element and choose
|
||||
**"Download with KGet"** to send it straight to KGet — it starts
|
||||
downloading immediately into your Downloads folder, no dialog.
|
||||
- A toolbar toggle enables **auto-capture**: while on, every download Chrome
|
||||
starts is cancelled and handed off to KGet the same way, automatically,
|
||||
with the correct filename (resolved by Chrome itself, so it's right even
|
||||
for URLs whose path is just an opaque ID). Defaults to ON.
|
||||
- A "Download complete" desktop notification appears once a capture actually
|
||||
finishes downloading. This is driven by the extension itself (not KGet's
|
||||
own per-transfer notification, which KGet silently skips for downloads
|
||||
that finish very quickly — see Troubleshooting), so it fires reliably
|
||||
regardless of file size or speed.
|
||||
- Right-click a link/image/video/audio and choose **"Download with KGet"**.
|
||||
- Or toggle **auto-capture** from the toolbar so every download is handed off
|
||||
automatically, with the correct filename.
|
||||
- A desktop notification fires when a capture finishes downloading.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Linux with KGet installed (and running, or set to autostart)
|
||||
- One of: Google Chrome, Chromium, Brave, Vivaldi, Microsoft Edge
|
||||
- `python3` and `dbus-send` on `PATH` (standard on virtually all Linux/KDE
|
||||
systems already)
|
||||
- `notify-send` (ships with most Linux desktops via libnotify) — optional,
|
||||
only used for the download-complete notification; captures still work
|
||||
without it, just silently
|
||||
- `kwriteconfig6` (ships with KDE Plasma) — optional, only used to disable
|
||||
KGet's own unreliable per-transfer notification so it doesn't double up
|
||||
with the extension's; install still works without it
|
||||
- Linux with KGet installed and running (or set to autostart)
|
||||
- A Chromium-based browser: Chrome, Chromium, Brave, Vivaldi, or Edge
|
||||
- `python3`, `dbus-send`
|
||||
- `notify-send`, optional, for the completion notification
|
||||
- `kwriteconfig6` (KDE Frameworks), optional, silences KGet's own duplicate
|
||||
notification
|
||||
|
||||
Install everything on your distro:
|
||||
|
||||
**Fedora**
|
||||
```bash
|
||||
sudo dnf install kget python3 dbus-tools libnotify kf6-kconfig
|
||||
```
|
||||
|
||||
**Arch / Manjaro**
|
||||
```bash
|
||||
sudo pacman -S kget python dbus libnotify kconfig
|
||||
```
|
||||
|
||||
**Debian / Ubuntu / KDE neon**
|
||||
```bash
|
||||
sudo apt install kget python3 dbus-bin libnotify-bin kf6-kconfig-bin
|
||||
```
|
||||
|
||||
**openSUSE**
|
||||
```bash
|
||||
sudo zypper install kget python3 dbus-1 libnotify-tools kconfig-tools
|
||||
```
|
||||
|
||||
(`notify-send` and `kwriteconfig6` package names shift around between distro
|
||||
versions. If a command above fails, drop that one package and search your
|
||||
package manager for the binary name instead. Everything else still works
|
||||
without them.)
|
||||
|
||||
## Install
|
||||
|
||||
1. Install the extension from the Chrome Web Store: **`<CHROME_WEB_STORE_URL>`**
|
||||
*(placeholder, fill in once the listing is live)*.
|
||||
2. Install the native messaging host that lets the extension talk to KGet.
|
||||
Download and extract the latest release from the
|
||||
[Releases page](https://github.com/andwati/kget-capture/releases), then
|
||||
from inside that folder:
|
||||
```bash
|
||||
./install.sh
|
||||
```
|
||||
3. Open your browser's download settings (`chrome://settings/downloads`,
|
||||
`brave://settings/downloads`, etc.) and turn **off** "Ask where to save
|
||||
each file before downloading". Chrome shows this dialog itself, before the
|
||||
extension gets a chance to intercept the download, so this one-time change
|
||||
is required.
|
||||
|
||||
`install.sh` registers the native host for every supported browser it finds
|
||||
installed and prints any remaining setup warnings.
|
||||
|
||||
### Building from source
|
||||
|
||||
Contributing, or want to run an unreleased version? Load the extension
|
||||
unpacked instead of step 1 above:
|
||||
|
||||
```bash
|
||||
git clone <this-repo-url> kget-capture
|
||||
git clone https://github.com/andwati/kget-capture.git
|
||||
cd kget-capture
|
||||
./install.sh
|
||||
```
|
||||
|
||||
`install.sh` registers a native messaging host for every supported browser it
|
||||
finds installed, then prints the extension's fixed ID and next steps:
|
||||
|
||||
1. Open `chrome://extensions` (or your browser's equivalent).
|
||||
2. Enable **Developer mode** (top-right toggle).
|
||||
3. Click **Load unpacked** and select this repo's `extension/` directory.
|
||||
4. Confirm the loaded extension's ID matches the one `install.sh` printed.
|
||||
5. Open `chrome://settings/downloads` (or your browser's equivalent, e.g.
|
||||
`brave://settings/downloads`, `edge://settings/downloads`) and turn **off**
|
||||
"Ask where to save each file before downloading". Chrome shows this dialog
|
||||
itself, before the extension ever gets a chance to intercept the download —
|
||||
no extension API can read or suppress it, so this one-time setting change
|
||||
is required for captures to work without an extra prompt.
|
||||
Then in `chrome://extensions`: enable **Developer mode**, click **Load
|
||||
unpacked**, and select this repo's `extension/` directory. `install.sh`
|
||||
prints the extension's fixed ID so you can confirm it loaded correctly.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -64,44 +92,33 @@ finds installed, then prints the extension's fixed ID and next steps:
|
||||
./uninstall.sh
|
||||
```
|
||||
|
||||
This removes the native messaging host registrations and the installed host
|
||||
script. You'll still need to remove the unpacked extension yourself via
|
||||
`chrome://extensions` — that step can't be scripted.
|
||||
Removes the native messaging host registrations and installed host script.
|
||||
Remove the extension itself via `chrome://extensions` (or the Chrome Web
|
||||
Store listing); that step can't be scripted.
|
||||
|
||||
## Releases
|
||||
|
||||
Pushing a tag matching `v*.*.*` (e.g. `v1.0.0`) triggers a GitHub Actions
|
||||
workflow ([.github/workflows/release.yml](.github/workflows/release.yml))
|
||||
that zips `extension/` and publishes it as a GitHub Release with
|
||||
auto-generated release notes. Bump `"version"` in `extension/manifest.json`
|
||||
before tagging so the packaged extension's version matches.
|
||||
|
||||
```bash
|
||||
git tag v1.0.0
|
||||
git push origin v1.0.0
|
||||
```
|
||||
Prebuilt releases are published on the
|
||||
[Releases page](https://github.com/andwati/kget-capture/releases); each
|
||||
`vX.Y.Z` tag push builds and publishes one automatically.
|
||||
|
||||
## Known limitations
|
||||
|
||||
- **`blob:`/`data:`/`file:`/`filesystem:` URLs can't be captured.** There's
|
||||
no real network URL to hand to KGet — this includes saving a page you
|
||||
navigated to directly via `file://` (Ctrl+S on it is still a "download" as
|
||||
far as Chrome is concerned) — so these downloads proceed normally through
|
||||
Chrome (a console warning is logged in the extension's service worker).
|
||||
no real network URL to hand to KGet, so these proceed normally through
|
||||
Chrome.
|
||||
- **Auto-capture has a brief head start.** Manifest V3 removed blocking
|
||||
`webRequest`, so Chrome begins the download before the extension can cancel
|
||||
it. A small/partial temp file may transiently appear before it's erased.
|
||||
- **No editable dialog.** Captures start immediately with no chance to
|
||||
rename the file or pick a different folder beforehand — rename/move it
|
||||
afterward in KGet or your file manager if needed. This is intentional: KGet
|
||||
only skips its interactive "New Download" dialog when given a real
|
||||
destination path up front, so instant capture and an editable prompt are
|
||||
mutually exclusive given KGet's D-Bus API.
|
||||
- **Chrome may still show its own "Save As" dialog** if you skipped step 5 of
|
||||
Install above — see there for why and how to fix it.
|
||||
- **KGet must already be running.** If it's not, captures fail silently from
|
||||
the user's perspective — check the service worker console for the actual
|
||||
error (see Troubleshooting).
|
||||
rename the file or pick a folder beforehand: KGet only skips its
|
||||
interactive dialog when given a destination path up front, so instant
|
||||
capture and an editable prompt are mutually exclusive.
|
||||
- **Chrome may still show its own "Save As" dialog** if you skipped step 3 of
|
||||
Install above.
|
||||
- **KGet must already be running.** If it's not, captures fail silently;
|
||||
check the service worker console for the actual error (see
|
||||
Troubleshooting).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -118,19 +135,17 @@ git push origin v1.0.0
|
||||
```
|
||||
If this fails with `ServiceUnknown`, KGet isn't running.
|
||||
- **Download-complete notification not showing?** Confirm `notify-send` is
|
||||
installed (`command -v notify-send`) — without it, `kget_capture_host.py`
|
||||
installed (`command -v notify-send`); without it, `kget_capture_host.py`
|
||||
skips the notification entirely rather than erroring. Otherwise, check that
|
||||
the transfer actually reached 100%: `kget_capture_host.py` polls
|
||||
`org.kde.kget.transfer.percent` on the new transfer's D-Bus object path
|
||||
(e.g. `/KGet/Transfers/9`, printed by the `addTransfer` call above) until it
|
||||
hits 100, so a stuck/erroring transfer never fires one. Note this
|
||||
notification is separate from KGet's own built-in "Download Finished"
|
||||
event — `install.sh` disables that one (`kwriteconfig6 --file knotifyrc
|
||||
--group "Event/kget/finished" --key Action None`) because KGet only fires
|
||||
it for transfers it observed in a non-finished state at least once, so it
|
||||
silently skips small/fast downloads that complete before that first
|
||||
observation.
|
||||
hits 100, so a stuck/erroring transfer never fires one. This notification
|
||||
is separate from KGet's own built-in "Download Finished" event.
|
||||
`install.sh` disables that one because KGet only fires it for transfers it
|
||||
observed in a non-finished state at least once, so it silently skips
|
||||
small/fast downloads that complete before that first observation.
|
||||
|
||||
## License
|
||||
|
||||
MIT — see [LICENSE](LICENSE).
|
||||
MIT, see [LICENSE](LICENSE).
|
||||
|
||||
Reference in New Issue
Block a user