skills/docs/media/audio/audio-timeline/src/engine/clip/clip.md

Engine Clip Helpers

(no submodules)

Purpose

The clip.ts module contains the internal bridge between TimelineEngine public methods and the pure clip-operations.ts helpers. It wraps each operation with OTel span recording, histogram timing, and event emission so the engine class stays focused on orchestration.

Features

• engineAddClip appends a clip and emits clipChange
• engineRemoveClip filters a clip and emits clipChange
• engineMoveClip applies constrained drags, skips no-ops, and records duration
• engineTrimClip trims a boundary and records a timeline.clip_operation span
• engineSplitClip splits a clip and records a timeline.clip_operation span

Usage

These helpers are used internally by TimelineEngine. Consumers interact with the engine's public methods instead.

API Reference

Export	Signature	Description
engineAddClip	(deps, trackId, clip) => void	Add clip
engineRemoveClip	(deps, trackId, clipId) => void	Remove clip
engineMoveClip	(deps, trackId, clipId, delta) => number	Move clip
engineTrimClip	(deps, trackId, clipId, boundary, delta) => void	Trim clip
engineSplitClip	(deps, trackId, clipId, atSample) => void	Split clip

Implementation Notes

The ClipDeps interface decouples the helpers from the engine class, making them testable in isolation. Histograms record audio_timeline_clip_operation_duration_ms for every trim and split. No-op moves (where the constrained delta is zero) skip both the undo push and the event emission, keeping the history clean. OTel spans include the operation name, track id, and clip id so that performance traces can pinpoint slow interactions.