Skip to main content

FrameLift Plugin SDK

FrameLift is a lightweight video player whose features are not baked into the executable. Each feature — the playlist, the history panel, the on-screen overlay, the settings menu, the auto-updater — is a plugin: a standalone DLL the host loads at runtime from its Plugins/ directory. This SDK is the public surface external authors use to write their own.

Why a plugin SDK​

The host ↔ plugin boundary is a COM-like binary ABI: pure abstract interfaces, POD-only method signatures, and extern "C" entry points. A plugin built with any compatible Windows compiler interoperates with the host regardless of how the host itself was built. Concretely, that buys you:

  • A dependency-free build. A plugin needs only a C++23 compiler and CMake. You do not link imgui, spdlog, stb, or a JSON library — none of those types cross the boundary.
  • Toolchain independence. No standard-library types are shared across the DLL edge, so there is no requirement to match the host's compiler or its standard-library build flags.
  • A versioned contract. Every plugin reports the major.minor.patch ABI it was built against (plus its name and version). The host checks it before touching a vtable — same major, host minor ≥ plugin minor — and refuses to load a mismatch, so an out-of-date plugin fails loudly instead of corrupting memory.

What a plugin can do​

Through the plugin context a plugin can:

  • Run one-time setup when it is installed, and tear down cleanly on shutdown.
  • Read and write settings, and contribute its own page to the settings menu.
  • Register keybinds that show up in the shared keybind UI.
  • Render its own ImGui UI each frame (optional).
  • React to media events from the player — file loaded, seek completed, property changes such as the current title.
  • Talk to other plugins through typed services (IHistory, …) and a publish/subscribe event bus.

How the pieces fit​

┌─────────────────────────────────────────────┐
│                  FrameLift.exe (host)             │
│                                              │
│   loads Plugins/*.dll  ◄── ABI compat gate   │
│   passes IPluginContext& into each plugin    │
└───────────────┬──────────────────────────────┘
                │  pure abstract interfaces, POD signatures
                ▼
┌─────────────────────────────────────────────┐
│   YourPlugin.dll : public PluginBase         │
│                                              │
│   OnInstall(ctx)   ── wire up services       │
│   RenderSettings() ── settings page          │
│   OnMediaEvent()   ── react to the player    │
│   Render()         ── draw UI (optional)     │
└─────────────────────────────────────────────┘

Where to go next​

  • Installation — get the SDK and build the bundled example.
  • Your First Plugin — write, build, and load a minimal plugin from scratch.
  • Guides — settings, keybinds, UI, media events, and cross-plugin communication, one topic at a time.
  • Reference — the full SDK API surface.