keyframe time resolves against the source clock, not the clip start, on trimmed media

[boldprojekte]

Summary

<keyframe time> on a media node is resolved against the source clock, not against the clip's start. For a trimmed clip the two differ by exactly sourceIn, so every keyframe fires sourceIn seconds early on the timeline.

reference/jsx/keyframes.md states the opposite:

• time is node-local: 0 is where the clip begins (its start). Timing props are parent-relative; keyframe times are not, so animation moves with the clip.

Repro

<scene name="T" width={960} height={540} active>
  <video src="footage/clip.mp4" width={960} height={540}
         start="0f" sourceIn="103f" sourceOut={17.5}>
    <keyframeTrack property="opacity">
      <keyframe time={0} value={0} />
      <keyframe time={5} value={0} />
      <keyframe time={5.04} value={1} />
    </keyframeTrack>
  </video>
</scene>

sourceIn is 103f = 3.433 s at 30 fps. The clip starts at timeline 0.

dapi capture <sceneId> -t 1.0 1.4 2.0 4.0 5.5

Expected (per the docs): frames black through 5.0 s, visible from ~5.04 s.
Actual: frames black at 1.0 s and 1.4 s, visible at 2.0 s, 4.0 s and 5.5 s. The step lands at ~1.57 s, which is 5 − 3.433.

Why it matters

It is silent, and it only appears once a clip is trimmed at the head - which is every real edit. The failure mode we hit was a volume automation:

<audio src="footage/clip.mp4" start={14.07} sourceIn={2.67} sourceOut="438f" end={26}>
  <keyframeTrack property="volume">
    <keyframe time={0} value={-48} />
    <keyframe time={0.08} value={0} />
  </keyframeTrack>
</audio>

Intended as an 80 ms fade-in over the clip's first frames to kill a seam click. On the source clock both keyframes sit 2.67 s before the clip's own start, so the ramp never plays and the value holds at the last keyframe for the whole clip. Nothing in dapi check flags it, and on audio there is no frame to look at.

A second track on the same edit (a width/height push written as 211f → 362f) ran 2.67 s early for the same reason.

Question

Which side is the defect - the docs or the resolution? They imply different things for authors:

• If the runtime is intended, the docs sentence should read that 0 is the start of the source, and that head-trimming a clip therefore keeps the animation on the same footage content rather than on the same clip-relative moment. That is arguably the better behaviour for footage-attached animation.
• If the docs are intended, correcting the runtime will shift every keyframe track authored against the current behaviour by sourceIn.

Version: dapi 0.200.0.

Repro

dapi capture <sceneId> -t 1.0 1.4 2.0 4.0 5.5

Environment

dapi	0.200.0
platform	darwin 25.5.0 (arm64)
node	v24.18.0
app	not checked