# 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**.
- **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.
- **Clipboard & Settings GUI**: Direct clipboard image/path uploads, URL dialog uploads, and a built-in Settings dialog for configuring API keys, default tags, visibility, rating, and autostart.

---

## Prerequisites

Ensure the following system dependencies are installed:

| 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`)                  |

---

## ⚡ 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:
  - **Capture Region & Upload**
  - **Upload File...**
  - **Upload URL...**
  - **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
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.