engine: timeline edit primitives and oak-cli transcode

- oakengine_sequence_add_track and add_footage_clip are the facade's
  first editing primitives: undoable track creation and clip placement
  with full range validation, clip enumeration, and gap filtering
- oak-cli transcode closes the loop: media file -> import -> clip ->
  render, producing scaled PPM frames and a WAV from just the C ABI
- engine fix uncovered by transcode: the render worker used an invalid
  empty AudioParams for IPC render frames, crashing any sequence that
  contains audio; it now derives them from the rendered node itself
- sequence_new hardens its defaults against missing audio config keys

engine/CMakeLists.txt

@@ -269,4 +269,9 @@ if (BUILD_TESTS)
     target_compile_definitions(oakengine_footage_test PRIVATE
             OAK_TEST_SOURCE_DIR="${CMAKE_SOURCE_DIR}"
     )
+
+    make_oakengine_test(oakengine_timeline_edit_test)
+    target_compile_definitions(oakengine_timeline_edit_test PRIVATE
+            OAK_TEST_SOURCE_DIR="${CMAKE_SOURCE_DIR}"
+    )
 endif ()

engine/include/oakengine/timeline.h

@@ -24,6 +24,7 @@
 #include <stdint.h>
 
 #include "export.h"
+#include "footage.h"
 #include "init.h"
 #include "project.h"
 
@@ -186,6 +187,97 @@ OAKENGINE_API int oakengine_sequence_marker_at(const OakEngineSequence *self,
 											   int index, int64_t *time,
 											   char *name, int name_size);
 
+/* ---- Timeline editing primitives ---------------------------------------- */
+
+/**
+ * @brief Track types, matching olive::Track::Type.
+ */
+#define OAKENGINE_TRACK_TYPE_VIDEO 0
+#define OAKENGINE_TRACK_TYPE_AUDIO 1
+#define OAKENGINE_TRACK_TYPE_SUBTITLE 2
+
+/**
+ * @brief Opaque clip handle (a ClipBlock on a track).
+ *
+ * Handles are borrowed from their owning project (QObject parent chain) and
+ * become invalid when the project is freed or the clip is removed (e.g. by
+ * undoing the add). There is no oakengine_clip_free().
+ */
+typedef struct OakEngineClip OakEngineClip;
+
+/**
+ * @brief Human-readable reason for the last failed editing call on this
+ * thread (buf/size convention). Editing calls return NULL or a negative
+ * OAKENGINE_E_* code; the text explains why.
+ */
+OAKENGINE_API int oakengine_sequence_last_error(char *buf, int buf_size);
+
+/**
+ * @brief Append a track of `track_type` (OAKENGINE_TRACK_TYPE_*) to the
+ * sequence and return its index in that type's track list.
+ *
+ * Uses the engine's TimelineAddTrackCommand without auto-merge: the first
+ * video/audio track is connected straight to the sequence's texture/samples
+ * input (tracks beyond the first stay unconnected until a merge node is
+ * added -- multi-track compositing is a later milestone). The add is
+ * undoable like the other editing primitives. Returns the new track index
+ * (>= 0) or a negative OAKENGINE_E_* code.
+ */
+OAKENGINE_API int oakengine_sequence_add_track(OakEngineSequence *self,
+											   int track_type);
+
+/**
+ * @brief Place a clip of `footage` on a track (undoable).
+ *
+ * Creates an olive::ClipBlock whose buffer input is fed by the footage node
+ * and places it on the track at `track_index` (within the track list of
+ * `track_type`, OAKENGINE_TRACK_TYPE_VIDEO or _AUDIO; subtitle clips are
+ * rejected with OAKENGINE_E_INVALID). The footage handle must be a borrowed
+ * import handle belonging to the same project as the sequence (probed
+ * handles carry no node and are rejected).
+ *
+ * `in`/`out` are the clip's timeline range and `media_in` the source in-
+ * point, all as frame timestamps in the sequence's frame-rate timebase
+ * (same convention as the rest of this family); `out` must be greater than
+ * `in` and `media_in` must be >= 0. No track is created implicitly: an
+ * out-of-range `track_index` fails with OAKENGINE_E_NOT_FOUND.
+ *
+ * The add mirrors the application's drop-import chain reduced to its
+ * editing core (NodeAddCommand + NodeEdgeAddCommand onto
+ * ClipBlock::k_buffer_in + TrackPlaceBlockCommand, pushed as one undoable
+ * MultiUndoCommand). Returns a borrowed clip handle, or NULL on failure
+ * (see oakengine_sequence_last_error()).
+ */
+OAKENGINE_API OakEngineClip *oakengine_sequence_add_footage_clip(
+	OakEngineSequence *seq, OakEngineFootage *footage, int track_type,
+	int track_index, int64_t in, int64_t out, int64_t media_in);
+
+/**
+ * @brief Number of clips on the track at `track_index` (within the
+ * `track_type` list). Gap blocks are not clips and are not counted.
+ * Returns the count (>= 0) or a negative OAKENGINE_E_* code
+ * (OAKENGINE_E_NOT_FOUND when the track does not exist).
+ */
+OAKENGINE_API int oakengine_sequence_clip_count(OakEngineSequence *self,
+												int track_type,
+												int track_index);
+
+/**
+ * @brief Borrowed handle of the clip at `clip_index` on the track (gap
+ * blocks are skipped), or NULL when out of range.
+ */
+OAKENGINE_API OakEngineClip *oakengine_sequence_clip_at(
+	OakEngineSequence *self, int track_type, int track_index, int clip_index);
+
+/**
+ * @brief The clip's timeline range (`in`/`out`) and source in-point
+ * (`media_in`) as frame timestamps in the sequence's frame-rate timebase.
+ * Any pointer may be NULL.
+ */
+OAKENGINE_API int oakengine_clip_get_range(const OakEngineClip *self,
+										   int64_t *in, int64_t *out,
+										   int64_t *media_in);
+
 #ifdef __cplusplus
 }
 #endif

engine/src/capi/footage.cpp

@@ -126,6 +126,19 @@ QString filename_of(const OakEngineFootageState *s)
 
 } // namespace
 
+// Internal cross-family accessor (not part of the public C ABI): returns
+// the borrowed project node of an import handle, or nullptr for probe
+// handles and NULL. Used by the timeline editing primitives.
+extern "C" __attribute__((visibility("hidden"))) void *
+oakengine_capi_footage_node(OakEngineFootage *h)
+{
+	if (!h) {
+		return nullptr;
+	}
+	const OakEngineFootageState *s = impl(h);
+	return s->node;
+}
+
 extern "C"
 {
 

engine/src/capi/timeline.cpp

@@ -27,15 +27,23 @@
 #include <QString>
 
 #include "coreengine.h"
+#include "node/block/clip/clip.h"
 #include "node/nodeundo.h"
 #include "node/project.h"
 #include "node/project/folder/folder.h"
 #include "node/project/sequence/sequence.h"
 #include "timeline/timelinemarker.h"
+#include "timeline/timelineundogeneral.h"
+#include "timeline/timelineundopointer.h"
 #include "timeline/timelineworkarea.h"
 #include "undo/undocommand.h"
 #include "undo/undostack.h"
 
+// Internal cross-family accessor (not part of the public C ABI), defined in
+// footage.cpp: borrowed project node of an import handle, nullptr otherwise.
+extern "C" __attribute__((visibility("hidden"))) void *
+oakengine_capi_footage_node(OakEngineFootage *h);
+
 namespace
 {
 
@@ -102,6 +110,33 @@ int64_t time_to_ts(const olive::Rational &time, const olive::Rational &tb)
 		time, tb, olive::core::Timecode::k_round);
 }
 
+// ---- Editing primitive helpers -------------------------------------------
+
+// Last editing error per thread (editing calls return NULL/negative codes).
+thread_local QString g_seq_last_error;
+
+void set_seq_error(const QString &error)
+{
+	g_seq_last_error = error;
+}
+
+olive::Track::Type to_track_type(int track_type)
+{
+	switch (track_type) {
+	case OAKENGINE_TRACK_TYPE_VIDEO:
+		return olive::Track::k_video;
+	case OAKENGINE_TRACK_TYPE_AUDIO:
+		return olive::Track::k_audio;
+	default:
+		return olive::Track::k_subtitle;
+	}
+}
+
+OakEngineClip *wrap_clip(olive::ClipBlock *c)
+{
+	return reinterpret_cast<OakEngineClip *>(c);
+}
+
 } // namespace
 
 extern "C"
@@ -119,6 +154,30 @@ OakEngineSequence *oakengine_sequence_new(OakEngineProject *project,
 	sequence->set_default_parameters();
 	sequence->set_label(QString::fromUtf8(name ? name : ""));
 
+	// set_default_parameters() reads the sequence defaults from the user
+	// config; a config that lacks those keys yields invalid parameters
+	// (e.g. sample rate 0), which later aborts the render worker. Backfill
+	// hard defaults for anything invalid.
+	if (sequence->get_audio_params().sample_rate() <= 0) {
+		sequence->set_audio_params(
+			olive::AudioParams(48000, olive::core::k_channel_layout_stereo,
+							   olive::core::SampleFormat::f32_p));
+	}
+	{
+		const olive::VideoParams vp = sequence->get_video_params();
+		const olive::Rational frame_rate = vp.frame_rate();
+		if (vp.width() <= 0 || vp.height() <= 0 || frame_rate.isNull() ||
+			frame_rate.isNaN()) {
+			const olive::PixelFormat::Format format =
+				vp.format() == olive::PixelFormat::invalid ?
+					olive::PixelFormat::f32 :
+					static_cast<olive::PixelFormat::Format>(vp.format());
+			sequence->set_video_params(olive::VideoParams(
+				1920, 1080, olive::Rational(1001, 30000), format,
+				olive::VideoParams::k_internal_channel_count));
+		}
+	}
+
 	// Same undoable creation as the application's "Create New Sequence"
 	// action (app/core.cpp), minus opening a viewer. Without an EngineCore
 	// (library not initialized) the command is executed non-undoably.
@@ -347,4 +406,197 @@ int oakengine_sequence_marker_at(const OakEngineSequence *self, int index,
 	return OAKENGINE_OK;
 }
 
+/* ---- Timeline editing primitives ---------------------------------------- */
+
+int oakengine_sequence_last_error(char *buf, int buf_size)
+{
+	return string_to_buf(g_seq_last_error, buf, buf_size);
+}
+
+int oakengine_sequence_add_track(OakEngineSequence *self, int track_type)
+{
+	set_seq_error(QString());
+	if (!self || track_type < OAKENGINE_TRACK_TYPE_VIDEO ||
+		track_type > OAKENGINE_TRACK_TYPE_SUBTITLE) {
+		set_seq_error(QStringLiteral("invalid sequence or track type"));
+		return OAKENGINE_E_INVALID;
+	}
+
+	olive::TrackList *list =
+		impl(self)->track_list(to_track_type(track_type));
+	// TimelineAddTrackCommand without auto-merge: the first video/audio
+	// track connects straight to the sequence output; further tracks stay
+	// unconnected (compositing is a later milestone).
+	auto *command = new olive::TimelineAddTrackCommand(list, false);
+	if (olive::EngineCore::instance()) {
+		olive::EngineCore::instance()->undo_stack()->push(
+			command, QStringLiteral("Add Track"));
+	} else {
+		command->redo_now();
+		delete command;
+	}
+	return list->get_track_count() - 1;
+}
+
+OakEngineClip *oakengine_sequence_add_footage_clip(
+	OakEngineSequence *seq, OakEngineFootage *footage, int track_type,
+	int track_index, int64_t in, int64_t out, int64_t media_in)
+{
+	set_seq_error(QString());
+	olive::Sequence *sequence = reinterpret_cast<olive::Sequence *>(seq);
+	auto *footage_node =
+		static_cast<olive::Footage *>(oakengine_capi_footage_node(footage));
+
+	if (!sequence || !footage) {
+		set_seq_error(QStringLiteral("invalid sequence or footage handle"));
+		return nullptr;
+	}
+	if (!footage_node) {
+		set_seq_error(QStringLiteral(
+			"footage must be imported into the project first "
+			"(oakengine_project_import_footage)"));
+		return nullptr;
+	}
+	if (track_type != OAKENGINE_TRACK_TYPE_VIDEO &&
+		track_type != OAKENGINE_TRACK_TYPE_AUDIO) {
+		set_seq_error(QStringLiteral(
+			"clips are only supported on video and audio tracks"));
+		return nullptr;
+	}
+	olive::Project *project =
+		olive::Project::get_project_from_object(sequence);
+	if (!project ||
+		olive::Project::get_project_from_object(footage_node) != project) {
+		set_seq_error(QStringLiteral(
+			"footage and sequence belong to different projects"));
+		return nullptr;
+	}
+	if (in < 0 || out <= in || media_in < 0) {
+		set_seq_error(QStringLiteral("invalid clip range (need 0 <= in < out "
+									 "and media_in >= 0)"));
+		return nullptr;
+	}
+	olive::TrackList *list = sequence->track_list(to_track_type(track_type));
+	if (track_index < 0 || track_index >= list->get_track_count()) {
+		set_seq_error(QStringLiteral("track index %1 out of range (%2 tracks)")
+					  .arg(track_index)
+					  .arg(list->get_track_count()));
+		return nullptr;
+	}
+	olive::Rational tb;
+	if (!time_base_of(sequence, &tb)) {
+		set_seq_error(QStringLiteral("sequence has no valid frame rate"));
+		return nullptr;
+	}
+
+	const olive::Rational in_time =
+		olive::core::Timecode::timestamp_to_time(in, tb);
+	const olive::Rational out_time =
+		olive::core::Timecode::timestamp_to_time(out, tb);
+	const olive::Rational media_in_time =
+		olive::core::Timecode::timestamp_to_time(media_in, tb);
+
+	// The application's drop-import chain reduced to its editing core (see
+	// ImportTool::place_at()): clip with media in-point and length, footage
+	// onto the buffer input, placed on the track -- all undoable.
+	auto *clip = new olive::ClipBlock();
+	clip->set_media_in(media_in_time);
+	clip->set_length_and_media_out(out_time - in_time);
+
+	olive::MultiUndoCommand *command = new olive::MultiUndoCommand();
+	command->add_child(new olive::NodeAddCommand(project, clip));
+	command->add_child(new olive::NodeEdgeAddCommand(
+		footage_node, olive::NodeInput(clip, olive::ClipBlock::k_buffer_in)));
+	command->add_child(new olive::TrackPlaceBlockCommand(list, track_index,
+													   clip, in_time));
+
+	if (olive::EngineCore::instance()) {
+		olive::EngineCore::instance()->undo_stack()->push(
+			command, QStringLiteral("Add Clip"));
+	} else {
+		command->redo_now();
+		delete command;
+	}
+	return wrap_clip(clip);
+}
+
+int oakengine_sequence_clip_count(OakEngineSequence *self, int track_type,
+								  int track_index)
+{
+	if (!self || track_type < OAKENGINE_TRACK_TYPE_VIDEO ||
+		track_type > OAKENGINE_TRACK_TYPE_SUBTITLE) {
+		return OAKENGINE_E_INVALID;
+	}
+	olive::TrackList *list =
+		impl(self)->track_list(to_track_type(track_type));
+	if (track_index < 0 || track_index >= list->get_track_count()) {
+		return OAKENGINE_E_NOT_FOUND;
+	}
+	// Only real clips count; gap blocks on the track are skipped.
+	int count = 0;
+	for (const olive::Block *b : list->get_track_at(track_index)->blocks()) {
+		if (dynamic_cast<const olive::ClipBlock *>(b)) {
+			count++;
+		}
+	}
+	return count;
+}
+
+OakEngineClip *oakengine_sequence_clip_at(OakEngineSequence *self,
+										  int track_type, int track_index,
+										  int clip_index)
+{
+	if (!self || track_type < OAKENGINE_TRACK_TYPE_VIDEO ||
+		track_type > OAKENGINE_TRACK_TYPE_SUBTITLE || clip_index < 0) {
+		return nullptr;
+	}
+	olive::TrackList *list =
+		impl(self)->track_list(to_track_type(track_type));
+	if (track_index < 0 || track_index >= list->get_track_count()) {
+		return nullptr;
+	}
+	// Skip gap blocks: indexes address clips only.
+	int seen = 0;
+	for (olive::Block *b : list->get_track_at(track_index)->blocks()) {
+		if (olive::ClipBlock *clip = dynamic_cast<olive::ClipBlock *>(b)) {
+			if (seen == clip_index) {
+				return wrap_clip(clip);
+			}
+			seen++;
+		}
+	}
+	return nullptr;
+}
+
+int oakengine_clip_get_range(const OakEngineClip *self, int64_t *in,
+							 int64_t *out, int64_t *media_in)
+{
+	const olive::ClipBlock *clip =
+		reinterpret_cast<const olive::ClipBlock *>(self);
+	if (!clip) {
+		return OAKENGINE_E_INVALID;
+	}
+	// The clip's sequence (clip -> track -> sequence) provides the timebase
+	// for the timestamp conversion.
+	const olive::Sequence *sequence =
+		clip->track() ? clip->track()->sequence() : nullptr;
+	if (!sequence) {
+		return OAKENGINE_E_STATE;
+	}
+	olive::Rational tb;
+	if (!time_base_of(sequence, &tb)) {
+		return OAKENGINE_E_STATE;
+	}
+	if (in) {
+		*in = time_to_ts(clip->in(), tb);
+	}
+	if (out) {
+		*out = time_to_ts(clip->out(), tb);
+	}
+	if (media_in) {
+		*media_in = time_to_ts(clip->media_in(), tb);
+	}
+	return OAKENGINE_OK;
+}
+
 } // extern "C"

engine/tests/oakengine_timeline_edit_test.cpp

@@ -0,0 +1,277 @@
+/***
+
+  Oak - Non-Linear Video Editor
+  Copyright (C) 2026 Oak Team
+
+  This program is free software: you can redistribute it and/or modify
+  it under the terms of the GNU General Public License as published by
+  the Free Software Foundation, either version 3 of the License, or
+  (at your option) any later version.
+
+  This program is distributed in the hope that it will be useful,
+  but WITHOUT ANY WARRANTY; without even the implied warranty of
+  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+  GNU General Public License for more details.
+
+  You should have received a copy of the GNU General Public License
+  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+***/
+
+// Pure C ABI test for the liboakengine timeline editing primitives:
+// add_track, add_footage_clip and the clip accessors, including their
+// undo/redo behavior and failure paths. Uses the real media file
+// tests/demo.mp4. No GL required.
+
+#include <assert.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+#if defined(_WIN32)
+#include <direct.h>
+#include <windows.h>
+#else
+#include <unistd.h>
+#endif
+
+#include "oakengine/footage.h"
+#include "oakengine/init.h"
+#include "oakengine/project.h"
+#include "oakengine/timeline.h"
+
+#ifndef OAK_TEST_SOURCE_DIR
+#define OAK_TEST_SOURCE_DIR "."
+#endif
+
+static char g_tmpdir[4096];
+
+static void make_tmpdir(void)
+{
+#if defined(_WIN32)
+	char base[MAX_PATH];
+	const DWORD len = GetTempPathA(MAX_PATH, base);
+	assert(len > 0 && len < MAX_PATH);
+	snprintf(g_tmpdir, sizeof(g_tmpdir), "%soakengine_tl_edit_test_%lu", base,
+			 (unsigned long)GetCurrentProcessId());
+	assert(_mkdir(g_tmpdir) == 0);
+#else
+	strcpy(g_tmpdir, "/tmp/oakengine_tl_edit_test_XXXXXX");
+	assert(mkdtemp(g_tmpdir) != NULL);
+#endif
+}
+
+static void demo_path(char *dst, size_t cap)
+{
+	const int n = snprintf(dst, cap, "%s/tests/demo.mp4", OAK_TEST_SOURCE_DIR);
+	assert(n > 0 && (size_t)n < cap);
+}
+
+static void test_add_track(OakEngineProject *project, OakEngineSequence *seq)
+{
+	int video = -1, audio = -1, subtitle = -1;
+
+	assert(oakengine_sequence_track_count(seq, &video, &audio, &subtitle) ==
+		   OAKENGINE_OK);
+	assert(video == 0 && audio == 0 && subtitle == 0);
+
+	assert(oakengine_sequence_add_track(seq, OAKENGINE_TRACK_TYPE_VIDEO) == 0);
+	assert(oakengine_sequence_add_track(seq, OAKENGINE_TRACK_TYPE_AUDIO) == 0);
+	assert(oakengine_sequence_add_track(seq, OAKENGINE_TRACK_TYPE_SUBTITLE) ==
+		   0);
+	assert(oakengine_sequence_add_track(seq, OAKENGINE_TRACK_TYPE_VIDEO) == 1);
+
+	assert(oakengine_sequence_track_count(seq, &video, &audio, &subtitle) ==
+		   OAKENGINE_OK);
+	assert(video == 2 && audio == 1 && subtitle == 1);
+
+	// Invalid track types are rejected.
+	assert(oakengine_sequence_add_track(seq, -1) == OAKENGINE_E_INVALID);
+	assert(oakengine_sequence_add_track(seq, 3) == OAKENGINE_E_INVALID);
+	assert(oakengine_sequence_add_track(NULL, OAKENGINE_TRACK_TYPE_VIDEO) ==
+		   OAKENGINE_E_INVALID);
+
+	// Track adds are undoable: undo the second video track, then redo it.
+	assert(oakengine_project_undo(project) == OAKENGINE_OK);
+	video = audio = subtitle = -1;
+	assert(oakengine_sequence_track_count(seq, &video, &audio, &subtitle) ==
+		   OAKENGINE_OK);
+	assert(video == 1 && audio == 1 && subtitle == 1);
+	assert(oakengine_project_redo(project) == OAKENGINE_OK);
+	video = audio = subtitle = -1;
+	assert(oakengine_sequence_track_count(seq, &video, &audio, &subtitle) ==
+		   OAKENGINE_OK);
+	assert(video == 2 && audio == 1 && subtitle == 1);
+}
+
+static void test_add_clip(OakEngineProject *project, OakEngineSequence *seq,
+						  const char *media_path)
+{
+	char err[512];
+
+	// Probe handles carry no project node and cannot be placed.
+	OakEngineFootage *probed = oakengine_footage_probe(media_path);
+	assert(probed != NULL);
+	assert(oakengine_sequence_add_footage_clip(seq, probed,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   0, 30, 0) == NULL);
+	assert(oakengine_sequence_last_error(err, sizeof(err)) > 0);
+	oakengine_footage_free(probed);
+
+	// Import the media into the project.
+	OakEngineFootage *footage =
+		oakengine_project_import_footage(project, media_path);
+	assert(footage != NULL);
+
+	// No subtitle clips.
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_SUBTITLE,
+											   0, 0, 30, 0) == NULL);
+
+	// Out-of-range track indexes are rejected without creating tracks.
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 5,
+											   0, 30, 0) == NULL);
+	assert(oakengine_sequence_last_error(err, sizeof(err)) > 0);
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, -1,
+											   0, 30, 0) == NULL);
+
+	// Bad ranges: out <= in, negative in / media_in.
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   30, 30, 0) == NULL);
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   30, 10, 0) == NULL);
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   -1, 30, 0) == NULL);
+	assert(oakengine_sequence_add_footage_clip(seq, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   0, 30, -1) == NULL);
+
+	// NULL safety.
+	assert(oakengine_sequence_add_footage_clip(NULL, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   0, 30, 0) == NULL);
+	assert(oakengine_sequence_add_footage_clip(seq, NULL,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   0, 30, 0) == NULL);
+
+	// clip_count reports OAKENGINE_E_NOT_FOUND for a missing track.
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_VIDEO,
+										 99) == OAKENGINE_E_NOT_FOUND);
+	assert(oakengine_sequence_clip_count(NULL, OAKENGINE_TRACK_TYPE_VIDEO,
+										 0) == OAKENGINE_E_INVALID);
+
+	// Place a video clip on track 0: frames 10..40, media in-point 5.
+	OakEngineClip *clip = oakengine_sequence_add_footage_clip(
+		seq, footage, OAKENGINE_TRACK_TYPE_VIDEO, 0, 10, 40, 5);
+	assert(clip != NULL);
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_VIDEO,
+										 0) == 1);
+	OakEngineClip *at = oakengine_sequence_clip_at(
+		seq, OAKENGINE_TRACK_TYPE_VIDEO, 0, 0);
+	assert(at == clip);
+	assert(oakengine_sequence_clip_at(seq, OAKENGINE_TRACK_TYPE_VIDEO, 0,
+									  1) == NULL);
+	assert(oakengine_sequence_clip_at(seq, OAKENGINE_TRACK_TYPE_VIDEO, 9,
+									  0) == NULL);
+
+	int64_t in = -1, out = -1, media_in = -1;
+	assert(oakengine_clip_get_range(clip, &in, &out, &media_in) ==
+		   OAKENGINE_OK);
+	assert(in == 10 && out == 40 && media_in == 5);
+	assert(oakengine_clip_get_range(NULL, &in, &out, &media_in) ==
+		   OAKENGINE_E_INVALID);
+
+	// And an audio clip on audio track 0 (same footage, whole range).
+	OakEngineClip *aclip = oakengine_sequence_add_footage_clip(
+		seq, footage, OAKENGINE_TRACK_TYPE_AUDIO, 0, 0, 30, 0);
+	assert(aclip != NULL);
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_AUDIO,
+										 0) == 1);
+
+	// Undo/redo both clip adds (the audio clip is on top of the undo stack,
+	// the video clip right below it).
+	assert(oakengine_project_undo(project) == OAKENGINE_OK);
+	assert(oakengine_project_undo(project) == OAKENGINE_OK);
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_AUDIO,
+										 0) == 0);
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_VIDEO,
+										 0) == 0);
+	assert(oakengine_project_redo(project) == OAKENGINE_OK);
+	assert(oakengine_project_redo(project) == OAKENGINE_OK);
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_VIDEO,
+										 0) == 1);
+	assert(oakengine_sequence_clip_count(seq, OAKENGINE_TRACK_TYPE_AUDIO,
+										 0) == 1);
+
+	oakengine_footage_free(footage); // wrapper only; node stays
+	assert(oakengine_project_footage_count(project) == 1);
+}
+
+// Footage imported into one project must not be placed into another.
+static void test_cross_project_rejected(const char *media_path)
+{
+	OakEngineProject *a = oakengine_project_create();
+	OakEngineProject *b = oakengine_project_create();
+	assert(a != NULL && b != NULL);
+	assert(oakengine_project_new(a) == OAKENGINE_OK);
+	assert(oakengine_project_new(b) == OAKENGINE_OK);
+
+	OakEngineFootage *footage =
+		oakengine_project_import_footage(a, media_path);
+	assert(footage != NULL);
+
+	OakEngineSequence *seq_b = oakengine_sequence_new(b, "B");
+	assert(seq_b != NULL);
+	assert(oakengine_sequence_add_track(seq_b, OAKENGINE_TRACK_TYPE_VIDEO) ==
+		   0);
+
+	char err[512];
+	assert(oakengine_sequence_add_footage_clip(seq_b, footage,
+											   OAKENGINE_TRACK_TYPE_VIDEO, 0,
+											   0, 30, 0) == NULL);
+	assert(oakengine_sequence_last_error(err, sizeof(err)) > 0);
+	assert(oakengine_sequence_clip_count(seq_b, OAKENGINE_TRACK_TYPE_VIDEO,
+										 0) == 0);
+
+	oakengine_footage_free(footage);
+	oakengine_project_free(a);
+	oakengine_project_free(b);
+}
+
+int main(void)
+{
+	make_tmpdir();
+
+	// Sandbox the config/cache/data locations (see oakengine_init_test).
+#if !defined(_WIN32)
+	assert(setenv("XDG_CONFIG_HOME", g_tmpdir, 1) == 0);
+	assert(setenv("XDG_CACHE_HOME", g_tmpdir, 1) == 0);
+	assert(setenv("XDG_DATA_HOME", g_tmpdir, 1) == 0);
+#endif
+
+	assert(oakengine_init(OAKENGINE_INIT_HEADLESS) == OAKENGINE_OK);
+
+	OakEngineProject *project = oakengine_project_create();
+	assert(project != NULL);
+	assert(oakengine_project_new(project) == OAKENGINE_OK);
+	OakEngineSequence *seq = oakengine_sequence_new(project, "Edit");
+	assert(seq != NULL);
+
+	char path[4096];
+	demo_path(path, sizeof(path));
+
+	test_add_track(project, seq);
+	test_add_clip(project, seq, path);
+	test_cross_project_rejected(path);
+
+	oakengine_project_free(project);
+	assert(oakengine_shutdown() == OAKENGINE_OK);
+
+	printf("oakengine_timeline_edit_test: all assertions passed\n");
+	return 0;
+}