188 lines
7.5 KiB
Markdown
188 lines
7.5 KiB
Markdown
# f0ckm Uploader
|
||
|
||
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
|
||
|
||
- **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.
|
||
- **Dolphin Context Menu Integration**: Right-click any file in Dolphin -> **Actions** -> **Upload to f0ckm**.
|
||
- **Gwenview / KDE Share Menu Integration**: Native KDE Purpose plugin adding **Upload to f0ckm** directly to the **Share** menu in Gwenview, Spectacle, Okular, and other KDE apps.
|
||
- **Spectacle Screenshot Capture**: Region capture integration via hotkeys or menu trigger (`f0ckm-uploader-gui --spectacle`).
|
||
- **Browser Extension Addon (ShareX Style)**: Right-click any image, video, link, or URL on the web in Chrome, Firefox, Brave, or Edge -> **Upload with f0ckm**.
|
||
- **Custom Protocol Scheme (`f0ckm://`)**: Seamless URL handling (`f0ckm://upload?url=...`) delegating background remote file downloading & live tray progress directly to the system tray app.
|
||
- **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.
|
||
- **Multi-Instance Support**: Configure multiple f0ckm server instances (URL & API Key per instance) and switch between them instantly in Settings or directly from the System Tray menu.
|
||
- **Android System Share Integration**: Native Android app (`android/`) with `ACTION_SEND` intent filter for sharing files and URLs directly from any Android app to your f0ckm server.
|
||
- **Clipboard & Settings GUI**: Direct clipboard image/path uploads, URL dialog uploads, and a built-in Settings dialog for managing instances, API keys, default tags, visibility, rating, and autostart.
|
||
|
||
---
|
||
|
||
## Prerequisites
|
||
|
||
Ensure the following system dependencies are installed:
|
||
|
||
| Dependency | Purpose | Recommended Package (Arch / Fedora / Ubuntu) |
|
||
| :---------------------------------- | :---------------------------------- | :------------------------------------------- |
|
||
| **Python 3.9+** | Execution Runtime | `python` / `python3` |
|
||
| **PySide6** | GUI Framework & IPC | `python-pyside6` / `python3-pyside6` |
|
||
| **Spectacle** | Region Screenshot Capture | `spectacle` (KDE Utility) |
|
||
| **ffmpeg** _(Optional)_ | Video Thumbnail Generation | `ffmpeg` |
|
||
| **libnotify** | Desktop Notifications | `libnotify` (`notify-send`) |
|
||
| **Qt6 & KF6 Purpose** _(Optional)_ | Gwenview / Share Menu C++ Plugin | `qt6-base kf6-purpose kf6-kcoreaddons` |
|
||
|
||
### Install Dependencies via Package Manager
|
||
|
||
- **Arch Linux / Manjaro**:
|
||
```bash
|
||
sudo pacman -S python-pyside6 spectacle ffmpeg qt6-base kf6-purpose kf6-kcoreaddons
|
||
```
|
||
- **Fedora**:
|
||
```bash
|
||
sudo dnf install python3-pyside6 spectacle ffmpeg qt6-qtbase-devel kf6-purpose-devel kf6-kcoreaddons-devel
|
||
```
|
||
- **Ubuntu / Debian**:
|
||
```bash
|
||
sudo apt install python3-pyside6 spectacle ffmpeg qt6-base-dev libkf6purpose-dev libkf6kcoreaddons-dev
|
||
```
|
||
|
||
---
|
||
|
||
## ⚡ Quick Start (3-Step Setup)
|
||
|
||
Setting up f0ckm Uploader takes less than a minute:
|
||
|
||
### 1. Run the Automated Installer
|
||
|
||
```bash
|
||
git clone https://git.lat/kibi/f0ckm-uploader
|
||
cd f0ckm-uploader
|
||
./install.sh
|
||
```
|
||
|
||
### 2. Enter Your API Credentials
|
||
|
||
When `./install.sh` finishes, the **f0ckm Uploader Settings** GUI window will open automatically.
|
||
- Fill in your **API URL** (e.g. `https://your-f0ckm-site.com/api/v2/upload`)
|
||
- Paste your **API Key**
|
||
- Click **Test Connection** -> **Save Settings**
|
||
|
||
### 3. Start Uploading!
|
||
|
||
- **System Tray**: Click the tray icon to take a screenshot and upload instantly.
|
||
- **Dolphin**: Right-click any file -> **Actions** -> **Upload to f0ckm**.
|
||
- **Browser**: Install the extension in `browser-extension/` to right-click web media and upload directly.
|
||
|
||
---
|
||
|
||
The installer handles dependency checking (PySide6), desktop entry creation, Dolphin context menus, multi-resolution application icons, and system tray startup automatically.
|
||
|
||
---
|
||
|
||
## 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:
|
||
- **Instance: <Active Instance Name>** (Submenu to switch active f0ckm instance)
|
||
- **Capture Region & Upload**
|
||
- **Upload File...**
|
||
- **Upload URL...**
|
||
- **Upload from Clipboard**
|
||
- **Settings...**
|
||
- **Recent Uploads Gallery**
|
||
- **Quit**
|
||
- **Double Click**: Opens the Settings dialog.
|
||
|
||
### Dolphin File Manager
|
||
|
||
- Right-click any file -> **Actions** -> **Upload to f0ckm**.
|
||
|
||
### Gwenview & KDE Apps (Share Menu)
|
||
|
||
- Click the **Share** button in Gwenview, Spectacle, or Okular -> select **Upload to f0ckm**.
|
||
|
||
### Command Line Interface (CLI)
|
||
|
||
```bash
|
||
# Capture screen region and upload
|
||
f0ckm-uploader-gui --spectacle
|
||
|
||
# Upload a specific local file
|
||
f0ckm-uploader-gui --upload="/path/to/file.mp4"
|
||
|
||
# Upload a remote image or media URL
|
||
f0ckm-uploader-gui --upload="https://example.com/image.png"
|
||
|
||
# Launch via custom protocol handler
|
||
f0ckm-uploader-gui "f0ckm://upload?url=https://example.com/image.png"
|
||
|
||
# Open settings dialog
|
||
f0ckm-uploader-gui
|
||
```
|
||
|
||
---
|
||
|
||
## Browser Extension (ShareX Addon)
|
||
|
||
A WebExtension is provided in the `browser-extension/` directory.
|
||
|
||
### Installation
|
||
|
||
1. **Chrome / Brave / Edge**:
|
||
- Go to `chrome://extensions`, enable **Developer mode**.
|
||
- Click **Load unpacked** and select the `browser-extension` folder.
|
||
2. **Firefox**:
|
||
- Go to `about:debugging#/runtime/this-firefox`.
|
||
- Click **Load Temporary Add-on...** and select `browser-extension/manifest.json`.
|
||
|
||
### Features
|
||
|
||
- **Context Menu**: Right-click any image, video, audio link, or URL on any webpage -> **Upload to f0ckm**.
|
||
- **Toolbar Popup**: Click extension icon to upload active tab or paste a URL.
|
||
- **Keyboard Shortcut**: `Alt+Shift+U` to upload current tab URL.
|
||
|
||
---
|
||
|
||
## Configuration & Storage Paths
|
||
|
||
- **Configuration File**: `~/.config/f0ckm-uploader/config.json`
|
||
- **Environment File**: `~/.local/bin/.env`
|
||
- **Application Binary**: `~/.local/bin/f0ckm-uploader-gui`
|
||
- **Start Menu Entry**: `~/.local/share/applications/f0ckm-uploader-gui.desktop`
|
||
- **Dolphin Service Menu**: `~/.local/share/kio/servicemenus/f0ckm-uploader-servicemenu.desktop`
|
||
|
||
---
|
||
|
||
## Uninstallation
|
||
|
||
To remove all binaries, context menus, desktop entries, and icon assets:
|
||
|
||
```bash
|
||
./uninstall.sh
|
||
```
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT License.
|