affaan-m/ECC · error · ValueError

source/audio placement must preserve native timing

Error message

source/audio placement must preserve native timing

What it means

Raised by _binding when the binding's source_range does not map onto its declared timeline_range under the clip's native offset mapping (mapped = clip.start + f - left_offset), or when an audio binding's timeline_range is not the clip's full [start, end]. Placement must preserve the native clip's timing exactly.

Solutions

1. Set source_range within [left_offset, left_offset+duration] and timeline_range = [clip['start'] + f - clip['left_offset'] for f in source_range].
2. For audio bindings, ensure timeline_range equals exactly [clip['start'], clip['end']] with no trimming.
3. Remove or externalize any speed/retime edits so the mapping is identity before calling build_application_bundle.

Example fix

// before
source_range=[10, 50], timeline_range=[0, 40]  # shifted, not native-aligned
// after
source_range=[10, 50], timeline_range=[clip['start'] - clip['left_offset'] + 10, clip['start'] - clip['left_offset'] + 50]

for item in bindings:
    clip = snapshot['timeline_readback'][item['track']][item['clip_index']]
    duration = clip['end'] - clip['start']
    src = item['source_range']; tgt = item['timeline_range']
    assert clip['left_offset'] <= src[0] and src[1] <= clip['left_offset'] + duration
    mapped = [clip['start'] + f - clip['left_offset'] for f in src]
    assert mapped == tgt, 'placement does not preserve native timing'

def placement_is_native(item, clip) -> bool:
    src = item['source_range']; tgt = item['timeline_range']
    mapped = [clip['start'] + f - clip['left_offset'] for f in src]
    return mapped == tgt

try:
    bundle = build_application_bundle(...)
except ValueError as e:
    if 'source/audio placement must preserve native timing' in str(e):
        log.error('non-native placement; remove speed/trim edits from binding', item=item)
    raise

When it happens

Trigger: source_range that starts after left_offset or extends past left_offset+duration; timeline_range shifted, trimmed, or speed-changed relative to [clip.start, clip.end]; an audio binding with a partial timeline_range.

Common situations: Templates applying speed ramps or trims that native application cannot represent; bindings generated with slip/slide edits; audio elements trimmed to a sub-range of the underlying clip.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Missing artifact binding
• source capacity does not match native offsets
• wrong source/audio track kind
• -32602
• a claim token is required

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/45848419c77ae4dc. Report an issue: GitHub.

Appendix: source

Thrown at skills/taste-application/scripts/tasteforge/integration.py:261

    if not track.startswith("audio" if audio else "video"):
        raise ValueError("wrong source/audio track kind")
    if track not in tracks or index >= len(tracks[track]):
        raise ValueError("source binding has no native clip")
    clip = tracks[track][index]
    _artifact(item["media"])
    if item["media"]["path"] != clip["path"]:
        raise ValueError("source path does not match native clip")
    if _rate(item["fps"]) != _rate(baseline["fps"]):
        raise ValueError("source fps/retime ambiguity")
    duration = clip["end"] - clip["start"]
    capacity = _integer(item["media_frames"], 1)
    if capacity != clip["left_offset"] + duration + clip["right_offset"]:
        raise ValueError("source capacity does not match native offsets")
    source = _range(item["source_range"], [clip["left_offset"], clip["left_offset"] + duration])
    target = _range(item["timeline_range"], [clip["start"], clip["end"]])
    mapped = [clip["start"] + f - clip["left_offset"] for f in source]
    if mapped != target or (audio and target != [clip["start"], clip["end"]]):
        raise ValueError("source/audio placement must preserve native timing")
    return track, index


def _preserved_stack(protected: Any, tracks: dict, bounds: list[int]) -> list[dict]:
    if not isinstance(protected, list) or not protected:
        raise ValueError("protected intervals must be explicit and nonempty")
    for item in protected:
        _object(item, {"range", "reason"})
        _range(item["range"], bounds)
        _text(item["reason"])
        if not any(_overlap(item["range"], [c["start"], c["end"]])
                   for key, clips in tracks.items() if key.startswith("video") for c in clips):
            raise ValueError("protected interval has no original video stack")
    return [{"track": track, "clip_index": index, "clip": copy.deepcopy(clip),
             "clip_sha256": _digest(clip)}
            for track, clips in sorted(tracks.items()) for index, clip in enumerate(clips)
            if any(_overlap(p["range"], [clip["start"], clip["end"]]) for p in protected)]

View on GitHub (pinned to 8321021c54)