RFC: Overall Implementation Framework of Plugin System

[jack9603301]

Note: This is a replacement for RFC #2529

**### RFC: Flameshot Plugin System Architecture
Status: Draft • Date: 2025-05-22 • Version: 0.1

1. Introduction

Flameshot requires a scalable plugin framework to enable modular extensions, empower user customization, and future-proof the application against evolving requirements. This RFC outlines the architectural design for a plugin system that balances flexibility, security, and performance.

2. Directory Structure

Plugins are organized under the user's configuration directory with a standardized naming convention:

~/.config/flameshot/
├── flameshot.ini              # Global configuration
└── plugins/                   # Plugin root directory
    └── {namespace}/           # Reverse-domain namespace (e.g., com.pub1)
        └── {plugin-id}/       # Unique plugin identifier
            ├── {plugin-id}.so # Shared library (C++ plugins)
            ├── {plugin-id}.py # Python script (Python plugins)
            ├── icon.svg       # Plugin icon (128x128 SVG)
            └── metadata.yaml  # Mandatory metadata

3. Plugin Configuration Model

3.1 Self-Managed Settings

Plugins have full autonomy over their internal configuration storage (e.g., INI files, JSON, databases). The core framework only mandates system-level metadata in metadata.yaml.

3.2 Standardized Metadata

global:
  name: "Watermark"            # Unique plugin ID
  type: "qt"                   # Plugin type (qt|python|binary)
  file: "libWatermark.so"      # Plugin binary/script
  version: "1.0.0"             # Semantic version
  author: "Developer Name"
metadata_fields:
  Watermark:
    type: str 
    description: "Path to watermark image"
    required: true
  Bottom:
    type: str 
    description: "Path to bottom overlay image"
    required: false
  PrintBG:
    type: str 
    description: "Path to background image for print mode"
  ColorBG:
    type: color
    description: "Background color when no image is specified (hex format)"
  PrintBG:
      type: subsection
      Frame:
          type: subsection
          Width:
            type: int 
            description: "Width of the print background frame"
            default: 3344                                                                                                                                                                                                                      
default_config:
  Watermark: "WM/Watermark.png"
  Bottom: "WM/Bottom.png"
  PrintBG: "WM/PrintBG.png"
  ColorBG: "#ffffff"
  PrintBG.Frame.Width: 3344

4. Process-Driven Execution Model

4.1 Configurable Workflows

Users can define custom processing pipelines for action/final_action plugins (e.g., upload, OCR). Pipelines specify:

• Plugin execution order
• Data transformation steps
• Conditional logic and error handling

4.2 Key Principles

1. Strict Protocol Adherence: Plugins execute in predefined sequences with standardized data passing.
2. Dynamic Reordering: Workflows support conditional steps based on runtime conditions.
3. Metadata Propagation: Plugins can modify both the image (QPixmap) and metadata (e.g., file format).

5. Interoperability Architecture

5.1 Bidirectional Communication

A layered model enables secure interaction between plugins and the core:

graph LR  
    A[Plugin A] -->|Request| B(Core API)  
    B -->|Response| A  
    C[Plugin B] -->|Request| B  
    B -->|Response| C  
    B -->|Event Trigger| D{Event Bus}  
    D -->|Broadcast| A  
    D -->|Broadcast| C  

Loading

5.2 Core Components

1. Core API Surface: Exposes controlled access to screenshot data, configuration, and events.
2. Communication Channels: Defines synchronous (method calls) and asynchronous (events) interaction patterns.

6. Security & Compatibility

1. Access Control: Plugins operate within a sandbox with restricted file system and network access.
2. Versioning: Semantic versioning ensures API backward compatibility.
3. Validation: Metadata schema validation prevents misconfiguration.

7. Core API

7.1 Plugin API

1. stdcall bool Initialization(int resource);
2. stdcall bool Deinitialization(int resource);
3. stdcall bool DeinitializationAll();
4. stdcall struct ResourcreInstance *RequestResource(int resource);

8. References

• Qt Plugin Architecture: https://doc.qt.io/qt-6/plugins-howto.html
• XDG Base Directory Specification: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
• Convention_over_configuration: https://en.wikipedia.org/wiki/Convention_over_configuration

Change Log:

• 2025-05-22: Initial draft
• [Future]: Incorporate community feedback **

[mmahmoudian]

I think it is safer to separate user configurable settings from the plugin yaml definition. This way we prevent manipulation of plugin stuff by the end user.

[jack9603301]

Yes, they should be separate, but plugins can choose to write configuration into the default settings in metadata

[jpetso]

If this is primarily about export to Imgur or OCR, I wonder if it makes sense to add a "Share (files/images/content)" portal to xdg-desktop-portals and use that in the long run. Then Flameshot could do without internet access entirely, and as an added bonus all other programs can use the same upload functionality too (or whatever the image gets shared with).

KDE has a Frameworks library called Purpose with the same goal of sharing data through plugins. This could be used to implement a portal on the KDE side, or if you don't like the portals concept, could be used by Flameshot directly.

[mmahmoudian]

@jpetso these are queued up for the plugins:

https://github.com/flameshot-org/flameshot/issues?q=state%3Aopen%20label%3APlugin

[OrcVole]

I've been working on an XBackBone upload plugin stub (reference: https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command/src/branch/main/plugins/xbackbone) which has given me a concrete perspective on what final_action plugins need from the core API. Posting these as requirements from a real-world use case, since the RFC currently specifies the plugin structure well but leaves the core API surface for final_action plugins largely unspecified.

What a final_action upload plugin needs from core
Based on implementing an XBackBone uploader, here are the specific capabilities that final_action plugins require that are not covered by the current RFC:

1. Clipboard write access
   After a successful upload, the plugin needs to copy a URL to the clipboard. On Wayland this must go through the compositor : QGuiApplication::clipboard() is the correct Qt approach, but the plugin needs either:

Direct access to QGuiApplication::clipboard() via the core API surface, or
A core.copyToClipboard(string) helper function exposed through the plugin API

This cannot be handled by the plugin independently without Qt access, and it is the single most common thing upload plugins need to do.

2. Desktop notification
   Similarly, notify-send is not available to a C++ .so plugin. The plugin needs either access to QSystemTrayIcon::showMessage() or a core.showNotification(title, body, type) helper. This is also extremely common, every upload plugin will want it.

3. Async process execution
   Upload operations must be non-blocking. A plugin that does a synchronous HTTP request will freeze Flameshot's UI. The core should either:

Expose QNetworkAccessManager or a wrapper for async HTTP, or
Make it clear that plugins are expected to spawn their own QThread or use QProcess for async work, with documentation on how to signal completion back to core

Without clarity here, every plugin author will independently discover the blocking problem.

Config UI gap
The RFC specifies that plugins manage their own configuration, which makes sense. But upload plugins need the user to enter a URL and an auth token. Without a standard settings UI hook, each plugin author will either write their own Qt dialog or rely on the user editing a YAML file by hand.

borgmanJeremy's sketch from #3661 shows plugin icons in the toolbar but doesn't address configuration. Even a minimal convention, "if a plugin exposes a settings() function, Flameshot opens a generated form from metadata_fields", would go a long way. The metadata schema in the RFC already has the metadata_fields structure; it just needs a corresponding UI.

AI-forward note
I've also written detailed API notes for the XBackBone upload case documenting non-obvious server-side behaviours (PHP silent truncation, 413 returning HTML, Wayland clipboard) that any upload plugin author will hit independently. These are at the link above. If the plugin system gains an official XBackBone plugin, those notes should feed directly into its error handling. Happy to contribute that as a plugin once the C API is stable enough to build against.

[OrcVole]

A few design concerns raised in good faith, before these decisions get locked in by implementation:

1. C ABI over C++ ABI at the boundary
   borgmanJeremy already flagged this in Initial implementation of the plugin framework #3661: "Using C++ as an interface to plugins is probably a bad idea in the long term since it does not have a stable ABI." I want to stress that this is worth solving now rather than later, because the migration tax is real. A plugin compiled against today's Flameshot will silently break (or worse, corrupt memory) when loaded by a future version compiled with a different Qt or GCC version. Every serious plugin system that starts with C++ eventually migrates to a C boundary. Starting there costs almost nothing.
   The minimum viable C boundary is small:
   c/* flameshot_plugin.h */
   #ifdef __cplusplus
   extern "C" {
   #endif

typedef struct FlameshotContext FlameshotContext;

/* Core API the plugin can call /
void fs_copy_to_clipboard(FlameshotContext, const char* text);
void fs_show_notification(FlameshotContext*, const char* title,
const char* body);
char* fs_get_config_value(FlameshotContext*, const char* key);
void fs_set_config_value(FlameshotContext*, const char* key,
const char* value);

/* Entry points every plugin must export /
typedef struct {
int api_version;
bool (execute)(const uint8_t png_data, size_t len,
FlameshotContext ctx);
} FlameshotPlugin;

FlameshotPlugin* flameshot_plugin_create(void);
void flameshot_plugin_destroy(FlameshotPlugin*);

#ifdef __cplusplus
}
#endif
Plugin authors can still write their implementation in C++ internally. The stable boundary is just the entry points and the context handle. The Qt-side implementation of FlameshotContext can be as rich as needed. This also makes Python and Lua bindings trivial to add later, since every FFI system knows how to cross a C boundary.

2. final_action naming encodes a pipeline assumption
   tessus raised this in Initial implementation of the plugin framework #3661 and I think the concern is valid enough to address before shipping. final_action implies there can only be one terminal step. If a user wants to watermark and then upload, under the current design both are separate manual steps rather than a composable chain.
   The rename costs nothing now and saves a breaking change later. A simple alternative:
   yamlplugins:

• name: com.example.xbackboneupload
  type: action
  terminates: true # closes CaptureWindow on success
  hover_text: Upload to XBackBone
  path: /path/to/plugin.so
  terminates: true captures borgmanJeremy's exact intent (behaviour matches save-to-file and copy-to-clipboard) without encoding it in the type name. A pipeline system later can simply check this flag rather than requiring a type rename.

3. plugins.yaml registry creates a split-brain problem
   If a plugin directory exists but is not in plugins.yaml, what happens? If plugins.yaml references a deleted plugin, what happens? The RFC does not address this, and in practice users will hit both cases.
   The simpler model: scan ~/.config/flameshot/plugins/ on startup and auto-register every directory that contains a valid metadata.yaml. No separate registry file. To disable a plugin without deleting it, add enabled: false to its metadata.yaml. This is how VS Code, Obsidian, and most modern plugin systems handle it, and it eliminates a whole class of sync errors.

4. Python in the schema without an implementation plan
   The RFC lists type: qt | python | binary but the PR and all subsequent discussion only implement C++ .so loading. Nobody has specified how Python plugins will be loaded, sandboxed, or given API access.
   If Python support is planned, the safest approach that also works for Lua, shell scripts, or any other language is a subprocess model: Flameshot writes the PNG to a temp file, spawns the plugin process with the path as an argument, reads a URL from stdout on exit 0. No CPython embedding, no pybind11, no ABI concerns. This also naturally sandboxes plugins since they run as separate processes.
   If Python is not planned for v1, removing it from the schema avoids setting expectations that will not be met.

5. KDE Purpose / xdg-desktop-portal for upload plugins specifically
   jpetso raised this and it did not get a substantive response. For final_action / upload plugins specifically, KDE Purpose and the xdg-desktop-portal Share interface already solve the problem: they let any application say "share this image" and the user's configured destinations (Nextcloud, Mastodon, email, etc.) handle the rest. Flameshot would not need to write or maintain a single upload plugin.
   The plugin system still makes clear sense for augmentation plugins (watermark, custom arrows, OCR). But it is worth a conscious decision on whether upload plugins should go through the platform sharing layer rather than Flameshot's own plugin API, rather than defaulting to reinventing it.

None of these are blockers for getting started. Items 3 and 4 in particular are low-effort to fix before shipping. Items 1 and 2 are worth a short discussion before the C++ class API gets too entrenched to change cheaply.
Reference implementation for an XBackBone upload plugin, including the API surface it needs from core, is at:
https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command/src/branch/main/plugins/xbackbone

[jack9603301]

I must say, I may not have read it carefully enough; I only skimmed through some of the content. However, I am very interested in your ideas, and it seems you have spent a lot of time thinking and exploring this issue.

plugins.yaml registry creates a split-brain problem
If a plugin directory exists but is not in plugins.yaml, what happens? If plugins.yaml references a deleted plugin, what happens? The RFC does not address this, and in practice users will hit both cases.
The simpler model: scan ~/.config/flameshot/plugins/ on startup and auto-register every directory that contains a valid metadata.yaml. No separate registry file. To disable a plugin without deleting it, add enabled: false to its metadata.yaml. This is how VS Code, Obsidian, and most modern plugin systems handle it, and it eliminates a whole class of sync errors.

I particularly found your idea regarding the plugins.yaml registry to be brilliant. You raised a question I hadn't considered and provided a seemingly good solution. I don't know how VS Code handles this, but your idea is clearly reasonable.

Python in the schema without an implementation plan
The RFC lists type: qt | python | binary but the PR and all subsequent discussion only implement C++ .so loading. Nobody has specified how Python plugins will be loaded, sandboxed, or given API access.
If Python support is planned, the safest approach that also works for Lua, shell scripts, or any other language is a subprocess model: Flameshot writes the PNG to a temp file, spawns the plugin process with the path as an argument, reads a URL from stdout on exit 0. No CPython embedding, no pybind11, no ABI concerns. This also naturally sandboxes plugins since they run as separate processes.
If Python is not planned for v1, removing it from the schema avoids setting expectations that will not be met.

Yes, this should be a subprocess model. Although the original RFC didn't discuss this, the following image I provided illustrates that the subprocess model is a viable option.

graph LR  
    A[Plugin A] -->|Request| B(Core API)  
    B -->|Response| A  
    C[Plugin B] -->|Request| B  
    B -->|Response| C  
    B -->|Event Trigger| D{Event Bus}  
    D -->|Broadcast| A  
    D -->|Broadcast| C  

Loading

KDE Purpose / xdg-desktop-portal for upload plugins specifically
jpetso raised this and it did not get a substantive response. For final_action / upload plugins specifically, KDE Purpose and the xdg-desktop-portal Share interface already solve the problem: they let any application say "share this image" and the user's configured destinations (Nextcloud, Mastodon, email, etc.) handle the rest. Flameshot would not need to write or maintain a single upload plugin.
The plugin system still makes clear sense for augmentation plugins (watermark, custom arrows, OCR). But it is worth a conscious decision on whether upload plugins should go through the platform sharing layer rather than Flameshot's own plugin API, rather than defaulting to reinventing it.

Perhaps we could utilize the dbus interface. In fact, for some reason, I once implemented a grim adapter for this, but it seems to have been removed; I don't know why. If dbus works correctly in Wayland, then of course, using the dbus model in Wayland now seems like a good option.

[mmahmoudian]

I'm very curious to know what @borgmanJeremy and @ElTh0r0 think.

I'm not experienced enough with designing a plugin system, but the points @OrcVole raised sounds logical, except the 1st point that I cannot assess it since my experience, as stated before, is insufficient.

[OrcVole]

A concrete reference implementation of this C ABI proposal (header,
XBackBone plugin in C++, and core-side stub) is at:

https://forgejo.wanderingmonster.dev/WanderingMonster/flameshot-post-capture-command/src/branch/main/plugin-api

[jack9603301]

@OrcVole I have forwarded your comment on this page to the project maintainers. @mmahmoudian

You can also join our matrix channel if you'd like.

[WanderingM0nster]

On dbus: I work with Wayland compositor IPC daily on
[wayland-spectre](https://github.com/WanderingM0nster/wayland-spectre)
(KWin, xdg-desktop-portal, PipeWire), and the pattern that holds up is:
dbus is reliable when you're talking to a service that is guaranteed to be
on the session bus already. It gets fragile as a general rendezvous
mechanism when the other end's presence isn't guaranteed, which is the
typical situation for a plugin that may or may not be running at capture
time.

For the subprocess model, my gut tells me keep stdin/stdout as the
primary IPC channel and treat dbus as an optional enhancement for plugins
that explicitly run as persistent session services. That keeps the baseline
portable and avoids requiring plugin authors to reason about bus activation
and name ownership.

The removed grim adapter is useful prior art here. Was it session-bus
based? Was the removal driven by reliability issues, scope, or something
else? Understanding what broke last time would directly inform where dbus
is safe to include and where it isn't.

Subprocess model and `plugins.yaml` as the discovery layer both still look
right to me as the foundation. It is good to hear those are aligned with where
the project is heading.

Thanks for the Matrix invitation. We would be happy to join at some point. What is the
link?

[mmahmoudian]

@WanderingM0nster here is the link to the Mateix space:

https://matrix.to/#/#flameshot-org:matrix.org

You can always find it in the footer of our website :)

https://flameshot.org