▋
creative/footage-index/references/resolve-import.md

Resolve sub-range import

Read this before emitting or importing selects into DaVinci Resolve. The index contract remains authoritative for source identity and timing.

Direct source ranges

Resolve accepts a range of an existing media file through:

AddItemListToMediaPool([
    {"media": source_path, "startFrame": start_frame, "endFrame": end_frame}
])

On Resolve Studio 21.0.3.7, frames 2531 through 2648 produce a subclip with Start 2531, End 2648, and Frames 118, while File Path still points to the original. The bounds are therefore inclusive in this verified version. Re-run the smoke test after a Resolve upgrade rather than treating version-specific behavior as permanent.

Direct ranges cost no duplicate media or encode time, and the source remains available behind the subclip for slipping. They also make source location part of the project state: keep canonical paths stable or retain asset_id, path, and range data for deliberate relinking.

Add configurable handles—one second per side is a useful default—and clamp them to the source extent.

Eligibility

Import an original as a frame-numbered sub-range only when:

  • The source is a CFR candidate and its timing path is verified.
  • Exact rational FPS and source-relative seconds are present.
  • The current source matches the manifest's asset identity.
  • The codec/container is readable by the target Resolve installation.

VFR or incompatible media uses a normalized-select path. Do not derive frames from a nominal VFR rate.

Project and timeline rates

Resolve locks the project's default frame rate when the first media enters the pool. A timeline can still use custom settings: set useCustomSettings to 1 and then set timelineFrameRate. On Studio 21.0.3.7, a 60 fps custom timeline works inside a 120 fps project that already contains media. A wrong timeline rate therefore requires a replacement timeline, not automatically a replacement project. Revalidate this after major Resolve upgrades.

Smoke test

Never validate this mechanism in the real project because importing the first clip mutates frame-rate state.

  1. Create a scratch project using the owning Resolve helper's safe naming and cleanup conventions.
  2. Set the intended project defaults before importing media.
  3. Import a short known source range with nonzero start and end frames.
  4. Read back Start, End, Frames, and File Path.
  5. Assert inclusive length, the expected source path, and usable handles.
  6. Test the first and last legal source ranges to verify clamping.
  7. Delete only the scratch project created for the test.

The importer also validates manifest contract version, asset identity, import mode, frame-bound semantics, and HDR color notes before creating media-pool items.