Skip to main content

Architecture Overview

FrameLift's host application (framelift) owns only the main loop and a few core subsystems. Every capability is a module the host loads or compiles in. Three terms describe the model precisely.

Feature, Module, Plugin​

Plugin   ── runtime Qt plugin DLL/SO in plugins/, declared by one .Plugin.json
Module   ── built-in host component, compiled in, declared by a .Module.json
Feature  ── capability string id used for dependency resolution
  • Feature — a named capability: a string id like media.playback.ffmpeg or playlist.panel. It is the currency of dependency resolution — a plugin or module provides, requires, or optionally uses features. It is not a binary and has no runtime object.
  • Module — a built-in host component compiled into the host, declared by a .Module.json: a dotted id and the features it provides, requires, or optionally uses. Modules are the host capabilities plugins build on (playback, audio, graphics, the window). Their JSON is consumed at configure time, and each gets a FRAMELIFT_MODULE_<NAME> CMake option so it can be compiled out — see Lean Builds and Built-in Modules.
  • Plugin — a user-facing feature extension built with the SDK and shipped as exactly one runtime Qt plugin DLL/SO in plugins/, declared by a single .Plugin.json. A plugin has one id, one enablement row in plugins.ini, and one IModule instance returned by its IPlugin factory. The bundled features (playlist, history, overlay, …) are plugins — see Plugins. The artifact name is the lowercase plugin id, e.g. framelift.playlist.so.

Runtime loading​

At startup the host scans plugins/ next to the executable. For each plugin DLL/SO it reads the embedded metadata, checks the ABI before touching any vtable, resolves dependencies, and only then instantiates the plugin's IModule — unless its id is disabled in plugins.ini. The host has no compile-time knowledge of any specific plugin.

The contract that makes this safe is the host ↔ plugin ABI.