♫ Mcaster1AMP Plugin SDK

The Mcaster1AMP Plugin SDK provides a stable C ABI for extending the player without recompiling the host. Plugins are loaded via dlopen on macOS/Linux and LoadLibrary on Windows. Because the interface is pure C, plugins can be written in any language that can export C functions and remain binary-compatible across C++ compiler versions and standard library implementations.

The constant AMP_PLUGIN_API_VERSION is bumped whenever the ABI changes in an incompatible way. The host rejects any plugin whose api_version field does not match exactly.

Every plugin, regardless of type, must export these three C functions. If any is missing, the host will refuse to load the plugin and log an error.

/* Return a pointer to a static AmpPluginInfo struct.
 * Must remain valid for the lifetime of the plugin. */
const AmpPluginInfo* amp_plugin_info(void);

/* Initialize the plugin. ctx is valid only during this call —
 * copy any needed fields (sample_rate, data_dir, log) to plugin-static storage.
 * Return 0 on success, non-zero on fatal error (host will dlclose). */
int amp_plugin_init(const AmpHostContext* ctx);

/* Shutdown: flush state, write config, free resources.
 * Called on the GUI thread before dlclose. */
void amp_plugin_shutdown(void);

Loading Sequence

The host follows this sequence when loading a plugin:

1. dlopen(path, RTLD_LAZY | RTLD_LOCAL) — load the shared library
2. dlsym("amp_plugin_info") — fetch and call; read api_version and type
3. Reject if api_version != AMP_PLUGIN_API_VERSION
4. Probe for type-specific symbols; log a warning for missing optional ones
5. dlsym("amp_plugin_init") — call with a populated AmpHostContext
6. If init returns non-zero: dlsym("amp_plugin_shutdown"), then dlclose
7. Register plugin in active chain / crossfader slot

Returned by amp_plugin_info(). Must be a static constant — the host may cache the pointer and dereference it at any time while the plugin is loaded.

typedef struct {
    const char* name;           /* "MC1 Crossfader"                      */
    const char* author;         /* "Mcaster1 Audio"                      */
    const char* description;    /* Human-readable one-line description   */
    const char* version;        /* Semantic version string "1.0.0"       */
    int         type;           /* AMP_PLUGIN_* constant                 */
    int         api_version;    /* Must equal AMP_PLUGIN_API_VERSION (2) */
} AmpPluginInfo;

Passed to amp_plugin_init(). The pointer is only valid during the init call — copy any fields you need into plugin-static storage before returning.

typedef void (*AmpLogCallback)(int level, const char* message);
/* Log levels: 1=CRITICAL  2=ERROR  3=WARNING  4=INFO  5=DEBUG */

typedef struct {
    int            sample_rate;      /* Host audio sample rate (e.g. 44100, 48000)      */
    int            channels;         /* Host channel count (1=mono, 2=stereo)           */
    int            buffer_size;      /* Frames per dsp_process/blend call               */
    const char*    app_version;      /* Host version string, e.g. "1.0.0"              */
    const char*    plugin_data_dir;  /* Writable per-plugin config directory           */
    AmpLogCallback log;              /* Host logging callback (thread-safe)            */
} AmpHostContext;

Storing Context Fields

/* Plugin-static storage — copy during amp_plugin_init() */
static int          g_sample_rate = 44100;
static int          g_channels    = 2;
static std::string  g_data_dir;
static AmpLogCallback g_log       = nullptr;

int amp_plugin_init(const AmpHostContext* ctx)
{
    if (!ctx) return -1;
    g_sample_rate = ctx->sample_rate;
    g_channels    = ctx->channels;
    g_data_dir    = ctx->plugin_data_dir ? ctx->plugin_data_dir : "/tmp/myplugin";
    g_log         = ctx->log;
    return 0;  /* 0 = success */
}

The Parameter API lets the host build a generic settings UI for any plugin without requiring a custom Qt widget. All parameter names use snake_case ASCII strings. The API is optional — plugins that provide a full custom UI via amp_plugin_create_ui() may omit it.

Exported Functions

/* Set a named parameter. Plugin may ignore unknown names silently. */
void   amp_plugin_set_param(const char* name, double value);

/* Get a named parameter value. Returns 0.0 for unknown names. */
double amp_plugin_get_param(const char* name);

/* Return the number of parameters this plugin exposes. */
int    amp_plugin_get_param_count(void);

/* Return a descriptor for parameter at index.
 * Pointer must remain valid for the lifetime of the plugin. */
const AmpParamInfo* amp_plugin_get_param_info(int param_index);

AmpParamInfo Struct

typedef struct {
    const char* name;           /* Internal key: "gain_db", "curve", etc.     */
    const char* label;          /* Display name: "Gain (dB)", "Curve Type"    */
    const char* unit;           /* "dB", "%", "Hz", "" (empty if unitless)    */
    double      min_value;
    double      max_value;
    double      default_value;
    int         is_enum;        /* 1 = integer index, show as dropdown        */
    const char* enum_names;     /* Pipe-separated: "Linear|Constant Power|..." */
} AmpParamInfo;

Example: Defining Parameters

static const AmpParamInfo kParams[] = {
    { "gain_db",  "Gain",       "dB",   -24.0, 24.0,  0.0, 0, nullptr },
    { "enabled",  "Enabled",    "",      0.0,   1.0,   1.0, 1, "Off|On" },
    { "freq_hz",  "Frequency",  "Hz",   20.0,  20000.0, 1000.0, 0, nullptr },
};

int amp_plugin_get_param_count() { return 3; }

const AmpParamInfo* amp_plugin_get_param_info(int i) {
    if (i < 0 || i >= 3) return nullptr;
    return &kParams[i];
}

Plugins may provide a fully custom QWidget-based settings panel shown in the Plugin Manager's "Configure" dialog. The host calls amp_plugin_create_ui(), embeds the returned widget, and calls amp_plugin_destroy_ui() when the dialog closes or the plugin is unloaded.

/* Create and return a QWidget* for this plugin's settings panel.
 * parent_qwidget: host passes QWidget* cast to void*.
 * Return new QWidget* cast to void*, or NULL if no UI available.
 * Host takes ownership and will call destroy_ui before unload. */
void* amp_plugin_create_ui(void* parent_qwidget);

/* Destroy the widget returned by create_ui. */
void  amp_plugin_destroy_ui(void* ui_widget);

Thread Safety

Both create_ui and destroy_ui are called on the GUI thread. The widget must not touch audio-thread state without an atomics barrier or QMetaObject::invokeMethod(..., Qt::QueuedConnection).

/* Correct pattern: update audio-thread state from widget signal */
QObject::connect(g_widget, &MyWidget::gainChanged,
    [](double db) {
        g_gain_linear.store(static_cast<float>(std::pow(10.0, db / 20.0)));
    });

Use these #define constants with dlsym()/GetProcAddress() to avoid typos when probing for optional symbols. They are defined in plugins/plugin_api.h.

/* Required — all plugin types */
#define AMP_SYM_INFO             "amp_plugin_info"
#define AMP_SYM_INIT             "amp_plugin_init"
#define AMP_SYM_SHUTDOWN         "amp_plugin_shutdown"

/* DSP (type 1) */
#define AMP_SYM_DSP_PROCESS      "amp_plugin_dsp_process"

/* Parameter API (types 1 and 4) */
#define AMP_SYM_SET_PARAM        "amp_plugin_set_param"
#define AMP_SYM_GET_PARAM        "amp_plugin_get_param"
#define AMP_SYM_GET_PARAM_COUNT  "amp_plugin_get_param_count"
#define AMP_SYM_GET_PARAM_INFO   "amp_plugin_get_param_info"

/* Custom Qt UI (shared Qt runtime only) */
#define AMP_SYM_CREATE_UI        "amp_plugin_create_ui"
#define AMP_SYM_DESTROY_UI       "amp_plugin_destroy_ui"

/* Crossfader (type 4) */
#define AMP_SYM_CROSSFADER_BLEND "amp_plugin_crossfader_blend"

/* Input decoder (type 2) */
#define AMP_SYM_INPUT_CAN        "amp_plugin_input_can_decode"
#define AMP_SYM_INPUT_OPEN       "amp_plugin_input_open"
#define AMP_SYM_INPUT_READ       "amp_plugin_input_read"
#define AMP_SYM_INPUT_CLOSE      "amp_plugin_input_close"

/* Visualization (type 3) */
#define AMP_SYM_VIS_PUSH         "amp_plugin_vis_push"

Usage in Plugin Host

void* lib = dlopen(path, RTLD_LAZY | RTLD_LOCAL);
auto info_fn = (AmpPluginInfoFn)dlsym(lib, AMP_SYM_INFO);
auto init_fn = (AmpPluginInitFn)dlsym(lib, AMP_SYM_INIT);
/* optional — check before calling */
auto set_p   = (AmpPluginSetParamFn)dlsym(lib, AMP_SYM_SET_PARAM);

Plugins are shared libraries. Include plugins/plugin_api.h (no other Mcaster1AMP headers are needed for a basic plugin). Link against any libraries your plugin uses. Do not link against libmcaster1amp — all communication goes through the C ABI at runtime.

macOS (dylib)

# Makefile excerpt — macOS ARM64 / x86_64
PLUGIN_NAME = dsp_myplugin
SRCS        = dsp_myplugin.cpp
SDK_INCLUDE = /path/to/Mcaster1AMP/src/Mcaster1AMP/plugins

QT6_CFLAGS  := $(shell pkg-config --cflags Qt6Widgets)
QT6_LIBS    := $(shell pkg-config --libs   Qt6Widgets)
YAML_LIBS   := $(shell pkg-config --libs   yaml-0.1)

CXXFLAGS = -std=c++17 -O2 -fvisibility=hidden \
           -I$(SDK_INCLUDE) $(QT6_CFLAGS)

$(PLUGIN_NAME).dylib: $(SRCS)
	$(CXX) $(CXXFLAGS) -dynamiclib -install_name @rpath/$@.dylib \
	    -o $@ $^ $(QT6_LIBS) $(YAML_LIBS)

Linux (shared object)

$(PLUGIN_NAME).so: $(SRCS)
	$(CXX) $(CXXFLAGS) -shared -fPIC -o $@ $^ $(QT6_LIBS) $(YAML_LIBS)

Windows (DLL, MinGW)

$(PLUGIN_NAME).dll: $(SRCS)
	$(CXX) $(CXXFLAGS) -shared -o $@ $^ $(QT6_LIBS) $(YAML_LIBS) \
	    -Wl,--out-implib,$(PLUGIN_NAME).lib

Installation Path

Drop the built .dylib / .so / .dll into one of the following directories — the Plugin Manager scans all of them at startup:

• macOS: ~/Library/Application Support/Mcaster1AMP/plugins/
• Linux: ~/.local/share/Mcaster1AMP/plugins/
• Windows: %APPDATA%\Mcaster1AMP\plugins\
• System-wide macOS: /Library/Application Support/Mcaster1AMP/plugins/

The following prompts are designed for use with Claude Code or any AI coding agent. Each prompt gives the agent enough context to generate a working plugin without further clarification. Paste them directly into your agent session with the Mcaster1AMP repo open.