Media Events

To react to the player — a file loading, a seek completing, the title changing — override OnMediaEvent. The host decodes the underlying FFmpeg event stream into a curated, ABI-stable MediaEvent so plugins never touch FFmpeg or its types.

void OnMediaEvent(const MediaEvent& e) override
{
    if (e.type == MediaEventType::FileLoaded)
    {
        // tracks and metadata are now available
    }
}

The relevant types live in <framelift/platform/IMediaPlayer.h>, included via the <framelift/platform.h> umbrella (and transitively by <framelift/core.h>).

Event types

MediaEvent::type is a MediaEventType:

Type	Meaning
`StartFile`	A new file is starting to load.
`FileLoaded`	The file is loaded; tracks and metadata are ready.
`PlaybackRestart`	Playback resumed — fires after a seek completes.
`Seek`	A seek was requested.
`EndFile`	The current file ended.
`VideoReconfig`	The video output was reconfigured.
`AudioReconfig`	The audio output was reconfigured.
`PropertyChange`	An observed player property changed (see below).
`Other`	An event the host does not surface distinctly — safe to ignore.

Property changes

When type == PropertyChange, the changed property is described by e.property. The active value is a tagged union: e.property.type says which member of e.property.value is live.

`PropertyType`	Read from
`Flag`	`e.property.value.flag` (bool)
`Double`	`e.property.value.dbl`
`Int64`	`e.property.value.i64`
`String`	`e.property.value.str` (NUL-terminated, copied)

e.property.prop is a PlayerProperty identifying which property changed (e.g. Path, MediaTitle, HwDecCurrent).

void OnMediaEvent(const MediaEvent& e) override
{
    if (e.type == MediaEventType::PropertyChange &&
        e.property.prop == PlayerProperty::MediaTitle &&
        e.property.type == PropertyType::String)
    {
        Log::Info("[MyPlugin] now playing: {}", e.property.value.str);
    }
}

Lifetime

String payloads (and any const char* in an event) are valid only for the duration of the OnMediaEvent call. If you need to keep the value, copy it into your own storage — do not stash the pointer.

Media events vs app events

There are two distinct event channels, and they are easy to mix up:

OnMediaEvent(const MediaEvent&) — the player's state (this page).
OnEvent(const AppEvent&) — platform/window input: key presses, mouse, window exposure, file drops. OnEvent dispatches KeyDown to OnKeyDownEvent for convenience. See Keybinds and AppEvent.

For player actions (open a file, react to a file opening across plugins) you usually want the pub/sub events like FileOpenedEvent, which are higher-level than the raw media stream.

Event types​

Property changes​

Media events vs app events​

Event types

Property changes

Media events vs app events