app: PlaybackController + playhead subscription migration (issues 0c, 1-4)

New app/playback/playbackcontroller.{h,cpp}: a lazily created
process-wide singleton whose set_playhead() forwards to
oakengine_viewer_set_playhead and re-broadcasts playhead_changed as a
plain Qt signal. Every app-side oakengine_viewer_set_playhead call site
(17 across viewer, timelinewidget, timelineview, import tool,
timebasedwidget, keyframecontrol, export dialog, mainwindow) now goes
through it.

Migrate the first four playhead subscribers off the raw C event
subscription / EngineEventBridge to the controller signal:
- TimeBasedView (issue 1)
- NodeParamViewWidgetBridge (issue 2)
- NodeParamViewKeyframeControl (issue 3)
- NodeParamViewConnectedLabel (issue 4)

Each stores a QMetaObject::Connection filtered on its viewer node and
disconnects on teardown; the viewer_sub_ members are gone. Plan docs
mark issues 0c and 1-4 as done.

Closes #30, closes #31, closes #32, closes #51, closes #52.

app/CMakeLists.txt

@@ -24,6 +24,8 @@ set(OLIVE_SOURCES
         common/colorcodingapp.h
         common/colorcodingapp.cpp
         common/nodevaluehandle.h
+        playback/playbackcontroller.h
+        playback/playbackcontroller.cpp
 )
 
 #set(OLIVE_RESOURCES)

app/dialog/export/export.cpp

@@ -47,6 +47,7 @@
 #include "oakengine/encoding.h"
 #include "oakengine/timeline.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "ui/icons/icons.h"
 #include "widget/timeruler/timeruler.h"
 #include "common/configwrapper.h"
@@ -319,7 +320,7 @@ ExportDialog::ExportDialog(OakEngineNode *viewer_node, bool stills_only_mode,
 		this);
 	connect(video_tab_, &ExportVideoTab::time_changed, this,
 			[viewer_node](const Rational &time) {
-				oakengine_viewer_set_playhead(
+				PlaybackController::instance()->set_playhead(
 					viewer_node,
 					time.numerator(), time.denominator());
 			});

app/playback/playbackcontroller.cpp

@@ -0,0 +1,38 @@
+#include "playbackcontroller.h"
+
+namespace olive
+{
+
+PlaybackController *PlaybackController::instance_ = nullptr;
+
+PlaybackController *PlaybackController::instance()
+{
+	if (!instance_) {
+		instance_ = new PlaybackController();
+	}
+	return instance_;
+}
+
+PlaybackController::PlaybackController(QObject *parent)
+	: QObject(parent)
+{
+}
+
+void PlaybackController::set_playhead(OakEngineNode *viewer,
+									  const core::Rational &time)
+{
+	if (!viewer) {
+		return;
+	}
+	oakengine_viewer_set_playhead(viewer, time.numerator(),
+								  time.denominator());
+	emit playhead_changed(viewer, time);
+}
+
+void PlaybackController::set_playhead(OakEngineNode *viewer, int64_t num,
+									  int64_t den)
+{
+	set_playhead(viewer, core::Rational(num, den));
+}
+
+}

app/playback/playbackcontroller.h

@@ -0,0 +1,50 @@
+#ifndef OAK_PLAYBACKCONTROLLER_H
+#define OAK_PLAYBACKCONTROLLER_H
+
+#include <QObject>
+
+#include "oakengine/viewer.h"
+#include "olive/core/util/rational.h"
+
+namespace olive
+{
+
+/**
+ * @brief App-internal hub for playhead changes (issue 0c of the
+ * EventBridge elimination plan).
+ *
+ * Every app-side `oakengine_viewer_set_playhead` call site goes through
+ * set_playhead(), which forwards to the engine and re-broadcasts
+ * playhead_changed as a plain Qt signal. Widgets subscribe to that signal
+ * instead of OAKENGINE_EVENT_VIEWER_PLAYHEAD_CHANGED via EngineEventBridge
+ * or raw oakengine_event_subscribe callbacks.
+ */
+class PlaybackController : public QObject {
+	Q_OBJECT
+public:
+	/**
+	 * @brief Lazily created process-wide instance (leaked at exit, like
+	 * Core). Widget tests construct widgets without Core::Start(), so the
+	 * instance must not depend on explicit startup.
+	 */
+	static PlaybackController *instance();
+
+	/**
+	 * @brief Move the playhead and notify app subscribers.
+	 */
+	void set_playhead(OakEngineNode *viewer, const core::Rational &time);
+	void set_playhead(OakEngineNode *viewer, int64_t num, int64_t den);
+
+signals:
+	void playhead_changed(OakEngineNode *viewer,
+						  const olive::core::Rational &time);
+
+private:
+	explicit PlaybackController(QObject *parent = nullptr);
+
+	static PlaybackController *instance_;
+};
+
+}
+
+#endif // OAK_PLAYBACKCONTROLLER_H

app/widget/nodeparamview/nodeparamviewconnectedlabel.cpp

@@ -21,6 +21,8 @@
 
 #include "nodeparamviewconnectedlabel.h"
 
+#include "playback/playbackcontroller.h"
+
 #include <QHBoxLayout>
 
 #include "oakutil/qtutils.h"
@@ -112,30 +114,26 @@ NodeParamViewConnectedLabel::NodeParamViewConnectedLabel(const oak::Input &input
 
 NodeParamViewConnectedLabel::~NodeParamViewConnectedLabel()
 {
-	// Raw C-API subscription carries `this` as userdata; not covered by
+	// Drop the PlaybackController connection (Qt would auto-disconnect
-	// Qt's auto-disconnect. Unsubscribe or the next playhead event calls
+	// anyway, but keep the symmetric teardown).
-	// into a dead object.
 	set_viewer_node(nullptr);
 }
 
 void NodeParamViewConnectedLabel::set_viewer_node(OakEngineNode *viewer)
 {
-	if (viewer_) {
+	disconnect(viewer_conn_);
-		oakengine_event_unsubscribe(viewer_sub_);
-		viewer_sub_ = 0;
-	}
 
 	viewer_ = viewer;
 
 	if (viewer_) {
-		viewer_sub_ = oakengine_event_subscribe(
+		viewer_conn_ = connect(
-			viewer_,
+			PlaybackController::instance(),
-			OAKENGINE_EVENT_VIEWER_PLAYHEAD_CHANGED,
+			&PlaybackController::playhead_changed, this,
-			[](const oakengine_event *, void *userdata) {
+			[this](OakEngineNode *n, const core::Rational &) {
-				static_cast<NodeParamViewConnectedLabel *>(userdata)
+				if (n == viewer_) {
-					->update_value_tree();
+					update_value_tree();
-			},
+				}
-			this);
+			});
 		update_value_tree();
 	}
 }

app/widget/nodeparamview/nodeparamviewconnectedlabel.h

@@ -72,7 +72,7 @@ private:
 
 	EngineEventBridge *bridge_ = nullptr;
 
-	int64_t viewer_sub_ = 0;
+	QMetaObject::Connection viewer_conn_;
 
 private slots:
 	void set_value_tree_visible(bool e);

app/widget/nodeparamview/nodeparamviewkeyframecontrol.cpp

@@ -28,6 +28,7 @@
 #include "oakengine/events.h"
 #include "oakengine/undo.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "oakengine/node.h"
 #include "ui/icons/icons.h"
 
@@ -159,13 +160,9 @@ NodeParamViewKeyframeControl::NodeParamViewKeyframeControl(bool right_align,
 
 NodeParamViewKeyframeControl::~NodeParamViewKeyframeControl()
 {
-	// Raw C-API subscription carries `this` as userdata; it is not covered
+	// Qt auto-disconnect covers the PlaybackController connection; make it
-	// by Qt's auto-disconnect. Without this, a playhead event delivered
+	// explicit for symmetry with TimeTargetDisconnectEvent.
-	// after destruction calls update_state() on a dead object.
+	disconnect(viewer_conn_);
-	if (viewer_sub_ > 0) {
-		oakengine_event_unsubscribe(viewer_sub_);
-		viewer_sub_ = 0;
-	}
 	// Drop the keyframe_* bridge subscriptions too (same raw-userdata
 	// mechanism underneath).
 	set_input(oak::Input());
@@ -211,22 +208,18 @@ void NodeParamViewKeyframeControl::set_input(const oak::Input &input)
 
 void NodeParamViewKeyframeControl::TimeTargetDisconnectEvent(OakEngineNode *v)
 {
-	if (viewer_sub_ > 0) {
+	disconnect(viewer_conn_);
-		oakengine_event_unsubscribe(viewer_sub_);
-		viewer_sub_ = 0;
-	}
 }
 
 void NodeParamViewKeyframeControl::TimeTargetConnectEvent(OakEngineNode *v)
 {
-	viewer_sub_ = oakengine_event_subscribe(
+	viewer_conn_ = connect(
-		v,
+		PlaybackController::instance(), &PlaybackController::playhead_changed,
-		OAKENGINE_EVENT_VIEWER_PLAYHEAD_CHANGED,
+		this, [this, v](OakEngineNode *n, const core::Rational &) {
-		[](const oakengine_event *, void *userdata) {
+			if (n == v) {
-			static_cast<NodeParamViewKeyframeControl *>(userdata)
+				update_state();
-				->update_state();
+			}
-		},
+		});
-		this);
 	update_state();
 }
 
@@ -391,7 +384,7 @@ void NodeParamViewKeyframeControl::go_to_previous_key()
 							  &previous_time) &&
 		get_time_target()) {
 		Rational key_time = convert_to_viewer_time(previous_time);
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(get_time_target()),
 			key_time.numerator(), key_time.denominator());
 	}
@@ -408,7 +401,7 @@ void NodeParamViewKeyframeControl::go_to_next_key()
 							  &next_time) &&
 		get_time_target()) {
 		Rational key_time = convert_to_viewer_time(next_time);
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(get_time_target()),
 			key_time.numerator(), key_time.denominator());
 	}

app/widget/nodeparamview/nodeparamviewkeyframecontrol.h

@@ -77,7 +77,7 @@ private:
 	int64_t keyframe_removed_sub_ = 0;
 	int64_t keyframe_time_sub_ = 0;
 
-	int64_t viewer_sub_ = 0;
+	QMetaObject::Connection viewer_conn_;
 
 private slots:
 	void show_buttons_from_keyframe_enable(bool e);

app/widget/nodeparamview/nodeparamviewwidgetbridge.cpp

@@ -21,6 +21,8 @@
 
 #include "nodeparamviewwidgetbridge.h"
 
+#include "playback/playbackcontroller.h"
+
 #include <QCheckBox>
 #include <QFontComboBox>
 #include <QUrl>
@@ -192,10 +194,7 @@ NodeParamViewWidgetBridge::~NodeParamViewWidgetBridge()
 {
 	// oakengine_dragger_create() ownership is ours (no-op on NULL)
 	oakengine_dragger_free(dragger_);
-	// Raw viewer subscription carries `this` as userdata
+	disconnect(viewer_conn_);
-	if (viewer_sub_ > 0) {
-		oakengine_event_unsubscribe(viewer_sub_);
-	}
 }
 
 int get_slider_count(NodeValueType::Type type)
@@ -1131,22 +1130,18 @@ void NodeParamViewWidgetBridge::set_timebase(const Rational &timebase)
 
 void NodeParamViewWidgetBridge::TimeTargetDisconnectEvent(OakEngineNode *v)
 {
-	if (viewer_sub_ > 0) {
+	disconnect(viewer_conn_);
-		oakengine_event_unsubscribe(viewer_sub_);
-		viewer_sub_ = 0;
-	}
 }
 
 void NodeParamViewWidgetBridge::TimeTargetConnectEvent(OakEngineNode *v)
 {
-	viewer_sub_ = oakengine_event_subscribe(
+	viewer_conn_ = connect(
-		v,
+		PlaybackController::instance(), &PlaybackController::playhead_changed,
-		OAKENGINE_EVENT_VIEWER_PLAYHEAD_CHANGED,
+		this, [this, v](OakEngineNode *n, const core::Rational &) {
-		[](const oakengine_event *, void *userdata) {
+			if (n == v) {
-			static_cast<NodeParamViewWidgetBridge *>(userdata)
+				update_widget_values();
-				->update_widget_values();
+			}
-		},
+		});
-		this);
 }
 
 void NodeParamViewWidgetBridge::input_value_changed(OakEngineNode *source,

app/widget/nodeparamview/nodeparamviewwidgetbridge.h

@@ -121,7 +121,7 @@ private:
 
 	EngineEventBridge *bridge_ = nullptr;
 
-	int64_t viewer_sub_ = 0;
+	QMetaObject::Connection viewer_conn_;
 
 private slots:
 	void widget_callback();

app/widget/timebased/timebasedview.cpp

@@ -21,6 +21,8 @@
 
 #include "timebasedview.h"
 
+#include "playback/playbackcontroller.h"
+
 #include <QGraphicsRectItem>
 #include <QMouseEvent>
 #include <QScrollBar>
@@ -157,21 +159,19 @@ void TimeBasedView::set_y_scale(const double &y_scale)
 
 void TimeBasedView::set_viewer_node(OakEngineNode *v)
 {
-	if (viewer_) {
+	disconnect(viewer_conn_);
-		oakengine_event_unsubscribe(viewer_sub_);
-		viewer_sub_ = 0;
-	}
 
 	viewer_ = v;
 
 	if (viewer_) {
-		viewer_sub_ = oakengine_event_subscribe(
+		viewer_conn_ = connect(
-			viewer_,
+			PlaybackController::instance(),
-			OAKENGINE_EVENT_VIEWER_PLAYHEAD_CHANGED,
+			&PlaybackController::playhead_changed, this,
-			[](const oakengine_event *, void *userdata) {
+			[this](OakEngineNode *n, const core::Rational &) {
-				static_cast<TimeBasedView *>(userdata)->viewport()->update();
+				if (n == viewer_) {
-			},
+					viewport()->update();
-			this);
+				}
+			});
 	}
 }
 

app/widget/timebased/timebasedview.h

@@ -148,7 +148,7 @@ private:
 
 	OakEngineNode *viewer_;
 
-	int64_t viewer_sub_ = 0;
+	QMetaObject::Connection viewer_conn_;
 };
 
 }

app/widget/timebased/timebasedwidget.cpp

@@ -34,6 +34,7 @@
 #include "oakengine/node.h"
 #include "oakengine/timeline.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "oakengine/timeline.h"
 #include "oakengine/undo.h"
 #include "widget/keyframeview/keyframehandle.h"
@@ -552,7 +553,7 @@ void TimeBasedWidget::go_to_prev_cut()
 		}
 	}
 
-	oakengine_viewer_set_playhead(sequence_node,
+	PlaybackController::instance()->set_playhead(sequence_node,
 		closest_cut.numerator(), closest_cut.denominator());
 }
 
@@ -619,7 +620,7 @@ void TimeBasedWidget::go_to_next_cut()
 	}
 
 	if (closest_cut < RATIONAL_MAX) {
-		oakengine_viewer_set_playhead(sequence_node,
+		PlaybackController::instance()->set_playhead(sequence_node,
 		closest_cut.numerator(), closest_cut.denominator());
 	}
 }
@@ -627,7 +628,7 @@ void TimeBasedWidget::go_to_next_cut()
 void TimeBasedWidget::go_to_start()
 {
 	if (viewer_node_) {
-		oakengine_viewer_set_playhead(get_connected_node(), 0, 1);
+		PlaybackController::instance()->set_playhead(get_connected_node(), 0, 1);
 	}
 }
 
@@ -643,7 +644,7 @@ void TimeBasedWidget::prev_frame()
 		}
 		{
 			Rational _pt = qMax(Rational(0), proposed_time);
-			oakengine_viewer_set_playhead(get_connected_node(),
+			PlaybackController::instance()->set_playhead(get_connected_node(),
 				_pt.numerator(), _pt.denominator());
 		}
 	}
@@ -659,7 +660,7 @@ void TimeBasedWidget::next_frame()
 			// Catch rounding error, assume this time is snapped and just add a timebase
 			proposed_time += timebase();
 		}
-		oakengine_viewer_set_playhead(get_connected_node(),
+		PlaybackController::instance()->set_playhead(get_connected_node(),
 			proposed_time.numerator(), proposed_time.denominator());
 	}
 }
@@ -668,7 +669,7 @@ void TimeBasedWidget::go_to_end()
 {
 	if (viewer_node_) {
 		const Rational length = viewer_output_length(viewer_node_.data());
-		oakengine_viewer_set_playhead(get_connected_node(),
+		PlaybackController::instance()->set_playhead(get_connected_node(),
 			length.numerator(), length.denominator());
 	}
 }
@@ -1006,7 +1007,7 @@ void TimeBasedWidget::go_to_in()
 		oakengine_viewer_workarea wa;
 		oakengine_viewer_get_workarea(get_connected_node(), &wa);
 		if (wa.enabled) {
-			oakengine_viewer_set_playhead(get_connected_node(),
+			PlaybackController::instance()->set_playhead(get_connected_node(),
 				wa.in_num, wa.in_den);
 		} else {
 			go_to_start();
@@ -1020,7 +1021,7 @@ void TimeBasedWidget::go_to_out()
 		oakengine_viewer_workarea wa;
 		oakengine_viewer_get_workarea(get_connected_node(), &wa);
 		if (wa.enabled) {
-			oakengine_viewer_set_playhead(get_connected_node(),
+			PlaybackController::instance()->set_playhead(get_connected_node(),
 				wa.out_num, wa.out_den);
 		} else {
 			go_to_end();

app/widget/timelinewidget/timelinewidget.cpp

@@ -56,6 +56,7 @@
 #include "oakengine/proxy.h"
 #include "oakengine/timeline.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "common/configwrapper.h"
 #include "tool/add.h"
 #include "tool/beam.h"
@@ -555,7 +556,7 @@ TimelineWidget::TimelineWidget(QWidget *parent)
 				start = std::min(start, block_in(b));
 			}
 			if (start != RATIONAL_MAX) {
-				oakengine_viewer_set_playhead(
+				PlaybackController::instance()->set_playhead(
 					reinterpret_cast<OakEngineNode *>(get_connected_node()),
 					start.numerator(), start.denominator());
 			}
@@ -758,7 +759,7 @@ void TimelineWidget::ConnectNodeEvent(OakEngineNode *n)
 
 	connect(timecode_label_, &RationalSlider::value_changed, this,
 			[handle](const Rational &time) {
-				oakengine_viewer_set_playhead(
+				PlaybackController::instance()->set_playhead(
 					handle, time.numerator(), time.denominator());
 			});
 	{
@@ -1076,7 +1077,7 @@ void TimelineWidget::DeleteSelected(bool ripple)
 	clear_ghosts();
 
 	if (ripple && rippled && new_playhead != RATIONAL_MAX) {
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(get_connected_node()),
 			new_playhead.numerator(), new_playhead.denominator());
 	}
@@ -1308,7 +1309,7 @@ void TimelineWidget::delete_in_to_out(bool ripple)
 
 	// Playhead move is not undoable and stays here (same as before).
 	if (ripple) {
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(get_connected_node()),
 			wa_in.numerator(), wa_in.denominator());
 	}
@@ -3196,14 +3197,14 @@ void TimelineWidget::ripple_to(TimelineApp::MovementMode mode)
 
 	// If we rippled, ump to where new cut is if applicable
 	if (mode == TimelineApp::k_trim_in) {
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(get_connected_node()),
 			closest_point_to_playhead.numerator(),
 			closest_point_to_playhead.denominator());
 	} else if (mode == TimelineApp::k_trim_out &&
 			   closest_point_to_playhead ==
 				   viewer_playhead(reinterpret_cast<OakEngineNode *>(get_connected_node()))) {
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(get_connected_node()),
 			playhead_time.numerator(), playhead_time.denominator());
 	}

app/widget/timelinewidget/tool/import.cpp

@@ -36,6 +36,7 @@
 #include "oakengine/timeline.h"
 #include "oakengine/undo.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "oakengine/project.h"
 #include "widget/timelinewidget/cliphandle.h"
 #include "window/mainwindow/mainwindow.h"
@@ -252,7 +253,7 @@ void ImportTool::place_at(const DraggedFootageData &footage,
 	drop_ghosts(insert, command);
 
 	if (jump_to_end) {
-		oakengine_viewer_set_playhead(
+		PlaybackController::instance()->set_playhead(
 			reinterpret_cast<OakEngineNode *>(this->sequence()),
 			max.numerator(), max.denominator());
 	}

app/widget/timelinewidget/view/timelineview.cpp

@@ -35,6 +35,7 @@
 #include "oakengine/preview.h"
 #include "oakengine/timeline.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "panel/panelmanager.h"
 #include "panel/timeline/timeline.h"
 #include "widget/timelinewidget/cliphandle.h"
@@ -268,7 +269,7 @@ void TimelineView::mousePressEvent(QMouseEvent *event)
 		 it++) {
 		if (it.value().contains(scene_pos)) {
 			const Rational marker_in = marker_time_range(it.key()).in();
-			oakengine_viewer_set_playhead(get_viewer_node(),
+			PlaybackController::instance()->set_playhead(get_viewer_node(),
 			marker_in.numerator(),
 			marker_in.denominator());
 			break;

app/widget/viewer/viewer.cpp

@@ -47,6 +47,7 @@
 #include "oakengine/display.h"
 #include "widget/viewer/displaybuffer.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "oakengine/videoparams.h"
 #include "panel/multicam/multicampanel.h"
 #include "panel/panelmanager.h"
@@ -402,7 +403,7 @@ void ViewerWidget::ConnectNodeEvent(OakEngineNode *handle)
 	// Connect controls to set_playhead via facade
 	connect(controls_, &PlaybackControls::time_changed, this,
 			[handle](const Rational &time) {
-				oakengine_viewer_set_playhead(
+				PlaybackController::instance()->set_playhead(
 					handle, time.numerator(), time.denominator());
 			});
 
@@ -649,7 +650,7 @@ void ViewerWidget::set_gizmos(OakEngineNode *node)
 void ViewerWidget::start_capture(TimelineWidget *source, const TimeRange &time,
 								const TrackReference &track)
 {
-	oakengine_viewer_set_playhead(get_connected_node(),
+	PlaybackController::instance()->set_playhead(get_connected_node(),
 		time.in().numerator(), time.in().denominator());
 	arm_for_recording();
 
@@ -1349,10 +1350,10 @@ void ViewerWidget::play_internal(int speed, bool in_to_out_only)
 		if (!in_to_out_only &&
 			viewer_output_playhead(get_connected_node()) >= last_frame) {
 			if (speed > 0) {
-				oakengine_viewer_set_playhead(get_connected_node(),
+				PlaybackController::instance()->set_playhead(get_connected_node(),
 				0, 1);
 			} else {
-				oakengine_viewer_set_playhead(get_connected_node(),
+				PlaybackController::instance()->set_playhead(get_connected_node(),
 				last_frame.numerator(), last_frame.denominator());
 			}
 		}
@@ -2118,7 +2119,7 @@ void ViewerWidget::play(bool in_to_out_only)
 				OAKENGINE_OK &&
 			wa.enabled) {
 			// Jump to in point
-			oakengine_viewer_set_playhead(get_connected_node(),
+			PlaybackController::instance()->set_playhead(get_connected_node(),
 				wa.in_num, wa.in_den);
 		} else {
 			in_to_out_only = false;
@@ -2347,7 +2348,7 @@ void ViewerWidget::playback_timer_update()
 	// pausing. Even if we pause it later with `end_of_line`, we prefer pausing after setting the time
 	// so that an audio scrub event, etc. isn't sent.
 	time_changed_from_timer_ = true;
-	oakengine_viewer_set_playhead(get_connected_node(),
+	PlaybackController::instance()->set_playhead(get_connected_node(),
 		time_to_set.numerator(), time_to_set.denominator());
 	time_changed_from_timer_ = false;
 	if (end_of_line) {

app/window/mainwindow/mainwindow.cpp

@@ -40,6 +40,7 @@
 #include "common/configwrapper.h"
 #include "oakengine/project.h"
 #include "oakengine/viewer.h"
+#include "playback/playbackcontroller.h"
 #include "oakengine/undo.h"
 
 #include "widget/viewer/vieweroutpututils.h"
@@ -619,7 +620,7 @@ void MainWindow::reveal_viewer_in_footage_viewer(OakEngineNode *r,
 	}
 	oakengine_undo_push(command, tr("Set Footage Workarea").toUtf8().constData());
 
-	oakengine_viewer_set_playhead(
+	PlaybackController::instance()->set_playhead(
 		r,
 		range.in().numerator(), range.in().denominator());
 }

docs/plans/eliminate-event-bridge-issues.md

@@ -64,7 +64,7 @@ C callbacks just queue to the GUI thread and re-emit typed Qt signals.
   later (b) migrations must use it instead of their own subscriptions.
 - **Required: build + ctest all green.**
 
-### issue 0c — App-internal PlaybackController (1 day)
+### issue 0c ✅ (done) — App-internal PlaybackController (1 day)
 Create `app/playback/playbackcontroller.{h,cpp}` with a
 `playhead_changed(oak::Node viewer, Rational)` signal. Route every
 `oakengine_viewer_set_playhead` call site in the app (ViewerWidget playback
@@ -82,26 +82,26 @@ In other words: one app-side controller that every
 
 ## Playhead migrations (pattern A, about half a day each)
 
-### issue 1 — timebasedview playhead subscription
+### issue 1 ✅ (done) — timebasedview playhead subscription
 `app/widget/timebased/timebasedview.cpp:168` (raw C callback). Reconnect to
 `PlaybackController::playhead_changed`.
 - Acceptance: the ruler playhead line moves during playback; no raw C
   subscription remains.
 - **Required: build + ctest all green.**
 
-### issue 2 — NodeParamViewWidgetBridge playhead
+### issue 2 ✅ (done) — NodeParamViewWidgetBridge playhead
 `app/widget/nodeparamview/nodeparamviewwidgetbridge.cpp:1140` (raw C).
 - Acceptance: keyframe-interpolated slider values follow the playhead
   during playback.
 - **Required: build + ctest all green.**
 
-### issue 3 — NodeParamViewKeyframeControl playhead
+### issue 3 ✅ (done) — NodeParamViewKeyframeControl playhead
 `app/widget/nodeparamview/nodeparamviewkeyframecontrol.cpp:222` (raw C).
 - Acceptance: prev/next/toggle keyframe buttons have the correct state as
   the playhead moves.
 - **Required: build + ctest all green.**
 
-### issue 4 — NodeParamViewConnectedLabel playhead
+### issue 4 ✅ (done) — NodeParamViewConnectedLabel playhead
 `app/widget/nodeparamview/nodeparamviewconnectedlabel.cpp:131` (raw C).
 - Acceptance: the value tree refreshes with the playhead.
 - **Required: build + ctest all green.**

docs/zh/plans/eliminate-event-bridge-issues.md

@@ -67,7 +67,7 @@ events; C callbacks just queue to the GUI thread and re-emit typed Qt signals.
   must use it instead of their own subscriptions.
 - **必做 / Required：build + ctest 全绿。**
 
-### issue 0c — 建 app 内 PlaybackController（1 天）
+### issue 0c ✅ (done) — 建 app 内 PlaybackController（1 天）
 新建 `app/playback/playbackcontroller.{h,cpp}`，信号
 `playhead_changed(oak::Node viewer, Rational)`。
 把 app 内所有 `oakengine_viewer_set_playhead` 调用点（ViewerWidget 播放循环、
@@ -83,23 +83,23 @@ goes through; it re-broadcasts `playhead_changed` as an app-internal Qt signal.
 
 ## playhead 族迁移 / Playhead migrations（模式 A，约半天/个）
 
-### issue 1 — timebasedview 的 playhead 订阅
+### issue 1 ✅ (done) — timebasedview 的 playhead 订阅
 `app/widget/timebased/timebasedview.cpp:168`（裸 C 回调）。改连
 PlaybackController::playhead_changed。
 - 验收 / Acceptance：播放时 ruler 播放头线正常移动；无裸 C 订阅残留。
 - **必做 / Required：build + ctest 全绿。**
 
-### issue 2 — NodeParamViewWidgetBridge playhead
+### issue 2 ✅ (done) — NodeParamViewWidgetBridge playhead
 `app/widget/nodeparamview/nodeparamviewwidgetbridge.cpp:1140`（裸 C）。
 - 验收 / Acceptance：播放时关键帧插值滑条值随播放头更新。
 - **必做 / Required：build + ctest 全绿。**
 
-### issue 3 — NodeParamViewKeyframeControl playhead
+### issue 3 ✅ (done) — NodeParamViewKeyframeControl playhead
 `app/widget/nodeparamview/nodeparamviewkeyframecontrol.cpp:222`（裸 C）。
 - 验收 / Acceptance：播放头移动时 prev/next/toggle 关键帧按钮状态正确。
 - **必做 / Required：build + ctest 全绿。**
 
-### issue 4 — NodeParamViewConnectedLabel playhead
+### issue 4 ✅ (done) — NodeParamViewConnectedLabel playhead
 `app/widget/nodeparamview/nodeparamviewconnectedlabel.cpp:131`（裸 C）。
 - 验收 / Acceptance：值树随播放头刷新。
 - **必做 / Required：build + ctest 全绿。**