readme

2026-08-11 22:00:14 +02:00
parent 0f0d04af63
commit 4059dbfea2
1 changed files with 112 additions and 54 deletions
--- a/README.md
+++ b/README.md
@@ -1,84 +1,142 @@
-# f0ckm-uploader
+# f0ckm Uploader

-A KDE Plasma integration for uploading files directly to a f0ckm instance via the API. Adds an **"Upload to f0ckm"** action to Dolphin's right-click context menu and Spectacle's export/share menu.
+A modern, high-contrast **KDE Plasma System Tray Uploader** and desktop integration suite for [f0ckm](https://git.lat/kibi/f0ckm). Features real-time digit progress icons, single-instance IPC, Dolphin context menus, Spectacle screenshot capture, and smart preview notifications.
+
+---

 ## Features

- **Dolphin integration** — right-click any file and upload it via the Actions/Service Menu
- **Spectacle integration** — export screenshots directly from the share menu
- **Clipboard support** — the resulting URL is automatically copied to your clipboard
- **Wayland & X11** — uses `wl-copy` or `xclip` depending on the session
- **KDE notifications** — upload progress and results via `kdialog` passive popups
- **Accurate MIME detection** — uses `file --mime-type` to avoid API rejections
+- **System Tray App with Live Progress**: Dynamic system tray icon displaying live upload percentage (`0`–`99`%).
+- **Single-Instance IPC Architecture**: 100% Python-based daemon (`PySide6`). Multiple invocations (hotkeys, Dolphin context menu) delegate directly to the running tray instance without spawning duplicates.
+- **Black Sun Branding & Themes**: Features sharp "Black Sun" graphics with a choice between Dark and Light tray themes, plus a solid white-background Start Menu launcher icon.
+- **Dolphin Context Menu Integration**: Right-click any file in Dolphin -> **Actions** -> **Upload to f0ckm**.
+- **Spectacle Screenshot Capture**: Region capture integration via hotkeys or menu trigger (`kde-uploader-gui --spectacle`).
+- **Smart Notification Previews**:
+  - **Images**: Fast native scaling via PySide6.
+  - **Videos** (`.mp4`, `.webm`, etc.): Automatic frame extraction at `00:00:01` via `ffmpeg`.
+  - **Other Files**: Sleek placeholder file badges showing the file extension.
+- **Clipboard & Settings GUI**: Direct clipboard image/path uploads and a built-in Settings dialog for configuring API keys, default tags, visibility, rating, and autostart.

-## Requirements
+---

-| Dependency                 | Purpose                     |
-| -------------------------- | --------------------------- |
-| `bash`                     | Script runtime              |
-| `curl`                     | HTTP uploads                |
-| `kdialog`                  | Desktop notifications (KDE) |
-| `wl-clipboard` (`wl-copy`) | Clipboard on Wayland        |
-| `xclip`                    | Clipboard on X11            |
-| `file` (libmagic)          | MIME type detection         |
+## Prerequisites

-## Configuration
+Ensure the following system dependencies are installed:

-Before installing, edit `uploader.sh` and set your API endpoint and key:
+| Dependency | Purpose | Recommended Package (Fedora / Arch / Ubuntu) |
+| :--- | :--- | :--- |
+| **Python 3.9+** | Execution Runtime | `python3` |
+| **PySide6** | GUI Framework & IPC | `python3-pyside6` or `pip install PySide6` |
+| **Spectacle** | Region Screenshot Capture | `spectacle` (KDE Utility) |
+| **ffmpeg** *(Optional)* | Video Thumbnail Generation | `ffmpeg` |
+| **libnotify** | Desktop Notifications | `libnotify` (`notify-send`) |

-```bash
-API_URL="http://<your-f0ckm-instance>/api/v2/upload"
-API_KEY="your_api_key_here"
-```
+---

-## Installation
+## Quick Setup & Installation

+### 1. Clone the Repository
 ```bash
 git clone https://git.lat/kibi/f0ckm-uploader
 cd f0ckm-uploader
-# Edit uploader.sh — set API_URL and API_KEY
+```
+
+### 2. Install Python Dependencies
+```bash
+pip install PySide6
+```
+*(Or install via system package manager: `sudo dnf install python3-pyside6` / `sudo apt install python3-pyside6`)*
+
+### 3. Environment Configuration *(Optional)*
+You can set up a `.env` file prior to installation, or configure settings later via the GUI:
+```bash
+cp .env.example .env
+```
+Edit `.env`:
+```env
+API_URL=https://your-f0ckm-instance.com/api/v2/upload
+API_KEY=your_secret_api_key
+DEFAULT_RATING=s
+DEFAULT_TAGS=screenshot
+DEFAULT_VISIBILITY=0
+DEFAULT_IS_OC=false
+```
+
+### 4. Run the Installer
+```bash
 chmod +x install.sh
 ./install.sh
 ```

-The installer will:
+The installer will automatically:
+1. Copy binaries to `~/.local/bin/kde-uploader-gui` and `~/.local/bin/kde-uploader`.
+2. Generate multi-resolution icons (`32x32`, `48x48`, `64x64`, `128x128`, `256x256`) for KRunner & Start Menu compatibility.
+3. Register the Dolphin context menu action in `~/.local/share/kio/servicemenus/`.
+4. Register the `.desktop` application launchers and rebuild the KDE Plasma cache (`kbuildsycoca6`).

-1. Copy `uploader.sh` → `~/.local/bin/kde-uploader`
-2. Install the `.desktop` application entry for Spectacle → `~/.local/share/applications/`
-3. Install the KDE Service Menu for Dolphin → `~/.local/share/kio/servicemenus/` (and the legacy KF5 path)
+---

-> [!NOTE]
-> You may need to restart Dolphin or log out/in for the service menu entry to appear.
+## Configuring a Global Hotkey (Screenshot Shortcut)
+
+To bind a keyboard shortcut to capture a screen region and upload it immediately:
+
+1. Open **KDE System Settings** -> **Shortcuts**.
+2. Search for **f0ckm Uploader** under **Applications** (or click **Add New** -> **Application** -> **f0ckm Uploader**).
+3. Select **Capture Region & Upload**.
+4. Click **Add Shortcut** and press your desired hotkey combination (e.g. `Print`, `Meta+Shift+S`, or `Ctrl+Alt+S`).
+5. Click **Apply** in the bottom right corner.
+
+---
+
+## Usage
+
+### System Tray
+- **Single Click**: Triggers region screenshot capture & upload.
+- **Right Click**: Opens context menu for:
+  - **Capture Region & Upload**
+  - **Upload File...**
+  - **Upload from Clipboard**
+  - **Settings...**
+  - **Quit**
+- **Double Click**: Opens the Settings dialog.
+
+### Dolphin File Manager
+- Right-click any file -> **Actions** -> **Upload to f0ckm**.
+
+### Command Line Interface (CLI)
+```bash
+# Capture screen region and upload
+kde-uploader-gui --spectacle
+
+# Upload a specific file
+kde-uploader-gui --upload="/path/to/file.mp4"
+
+# Open settings dialog
+kde-uploader-gui
+```
+
+---
+
+## Configuration & Storage Paths
+
+- **Configuration File**: `~/.config/f0ckm-uploader/config.json`
+- **Environment File**: `~/.local/bin/.env`
+- **Application Binary**: `~/.local/bin/kde-uploader-gui`
+- **Start Menu Entry**: `~/.local/share/applications/kde-uploader-gui.desktop`
+- **Dolphin Service Menu**: `~/.local/share/kio/servicemenus/kde-uploader-servicemenu.desktop`
+
+---

 ## Uninstallation

+To remove all binaries, context menus, desktop entries, and icon assets:
+
 ```bash
 ./uninstall.sh
 ```

-## Usage
-
-### Dolphin
-
-Right-click any file → **Actions** → **Upload to f0ckm**
-
-### Spectacle
-
-After capturing a screenshot → **Export** or **Share** → **Upload to f0ckm**
-
-A notification will confirm the upload and the link will be in your clipboard.
-
-## File Structure
-
-```
-f0ckm-uploader/
-├── uploader.sh                      # Main upload script
-├── kde-uploader.desktop             # Application entry (Spectacle)
-├── kde-uploader-servicemenu.desktop # Dolphin right-click action
-├── install.sh                       # Installer
-└── uninstall.sh                     # Uninstaller
-```
+---

 ## License

-MIT
+MIT License.