From 4059dbfea2fc7caaba759a68e07aa35278d3ad52 Mon Sep 17 00:00:00 2001 From: Kibi Kelburton Date: Tue, 11 Aug 2026 22:00:14 +0200 Subject: [PATCH] readme --- README.md | 166 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 112 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index dd5af8b..dadc0dd 100644 --- 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:///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.