aivee 0.0.0-stage → 0.1.0-dev.59872e1

package/docs/usage.md

@@ -0,0 +1,1193 @@
+# Video Editing Usage Guide
+
+This guide covers generic project creation, media registration, editing, rendering, transcripts, and OpenTimelineIO interchange. Avatar artwork and speech-driven character animation belong to consuming studios; use generic image and audio tracks in Engine timelines.
+
+## Create a project
+
+```sh
+npm run new-video -- my-video
+npm run new-video -- vertical-video 1080x1920 30 15
+npm run new-video -- short-video --preset vertical --fit cover
+node src/cli.mjs presets list
+```
+
+The default canvas is 1920×1080 at 30 fps for 10 seconds. Named presets are
+`vertical` (9:16), `portrait-feed` (4:5), `square` (1:1), and `landscape`
+(16:9). Use `presets list` to inspect their default dimensions and destinations.
+Custom dimensions remain available with `WIDTHxHEIGHT`. A preset is recorded as
+`canvasPreset` in project metadata. See
+[`docs/aspect-ratio-presets.md`](aspect-ratio-presets.md) for the baseline
+and platform references. Source media uses `contain` by default to preserve the
+whole frame; select `cover` to crop overflow or `fill` to stretch. Set a
+project-wide policy with `--fit`, then override it for individual video clips
+with their `fit` field. Projects are created under `video-projects/` and
+existing project folders are never overwritten. Each project starts with a
+valid `timeline.json` containing ordered video, audio, and overlay tracks plus
+all currently registered project assets. For an existing project missing that
+file, initialize one from its metadata and media catalog with:
+
+```sh
+node src/cli.mjs timeline create video-projects/my-video
+```
+
+Use the reviewable `set-project-state` operation to change timeline duration,
+the project-wide `sourceFit`, or the canvas background color; validation
+refuses a duration that would clip any existing timeline item. `sourceFit: null`
+clears the project override. `backgroundColor: null` makes the canvas
+transparent; existing timelines without a background retain their black render
+background. New projects default to `#10141c`.
+Canvas width, height, and frame rate remain tied to project metadata and are
+not editable through a timeline-only operation.
+
+```json
+{ "type": "set-project-state", "state": { "sourceFit": "cover", "durationSeconds": 30, "backgroundColor": "#f3f0eb" } }
+```
+
+The optional output path can create a separate timeline. Pass a duration as the
+second argument to keep the default output path, or as the final argument after
+an output path to override the project default.
+
+Frame rates accept integers and rational values such as `30000/1001` for
+NTSC-style 29.97 fps. Rendering passes the project frame rate to HyperFrames
+and checks the output rate. Select MP4, WebM, MOV, or GIF by the output file
+extension:
+
+```sh
+node src/cli.mjs render video-projects/my-video renders/final.webm high
+node src/cli.mjs timeline render video-projects/my-video timeline.json renders/final.mov standard
+node src/cli.mjs timeline render video-projects/my-video timeline.json renders/final.mp4 high render-options.json
+node src/cli.mjs timeline render-range video-projects/my-video timeline.json 12.5 24 renders/segment.mp4 standard
+node src/cli.mjs render video-projects/my-video renders/frames high png-options.json
+```
+
+`timeline render-range` renders a selected project-time window from the source
+timeline without editing it. JavaScript consumers can use
+`renderTimelineRangeAsync(projectPath, timeline, startSeconds, endSeconds,
+outputPath, quality, options)` or extract a reusable segment with
+`extractTimelineRange(timeline, startSeconds, endSeconds)` and pass it to
+`renderTimelineAsync`. The synchronous `renderTimelineRange` API is also
+available. A range must include at least one project frame and cannot cut
+through a clip fade or edge transition.
+
+`render-options.json` can choose a video `codec`, integer encoder `crf`, or
+`videoBitrate`, for example `{ "encoder": { "codec": "h265", "crf": 26 } }`
+or `{ "encoder": { "codec": "vp9", "videoBitrate": "8M" } }`. Bound
+render resources with `{ "workers": 2, "lowMemoryMode": true }`; `workers`
+also accepts `"auto"`, while numeric values must be 1–64. MP4 supports
+H.264/H.265, MOV supports H.264/H.265/ProRes, and WebM supports VP9. ProRes
+uses its HQ profile and does not accept CRF or bitrate overrides. The codec
+override runs as a verified FFmpeg final encode. With an explicit codec and no
+CRF/bitrate override, FFmpeg's codec default is used. Add `"timeoutSeconds": 900`
+to bound rendering (1–86400 seconds). `renderTimelineAsync` includes FFmpeg
+audio alignment, speed/reverse/effect proxy generation, sidechain processing,
+HyperFrames capture, final encoding, output probing, and audio mastering in
+that deadline. `renderProjectAsync` also applies cancellation and timeouts to
+capture, final encoding, and output probing. Timeout terminates the active
+media process and removes temporary output. The JavaScript async APIs
+`renderProjectAsync`, `renderTimelineAsync`, and `renderEditedProjectAsync` accept an
+`AbortSignal` as `signal`. CLI renders handle Ctrl+C by cancelling the active
+render and its FFmpeg preprocessing processes. The synchronous `renderProject`
+and `renderTimeline` APIs remain available without cancellation. JavaScript
+consumers can pass an `onProgress` callback to async render APIs. Events report
+pipeline stages such as proxy resolution, audio alignment, playback processing,
+audio effects, sidechain processing, HyperFrames capture, encoding, output
+validation, publishing, timeline audio validation, and mastering analysis,
+encoding, validation, and publication. Each event
+includes `stage` and `phase` (`started`, `completed`, or `skipped`); capture
+events include HyperFrames phase progress, while FFmpeg video and audio
+mastering events report elapsed media time and a percentage. Events may include stage details such as
+codec, target, or completed/total counts. Callback failures emit a warning and
+do not cancel the render. To render PNG frames, set
+`{ "format": "png-sequence" }`; the output path is a new directory. Defaults
+remain controlled by HyperFrames quality (`draft`, `standard`, or `high`).
+Set `"colorProfile": "rec709"` or `"colorProfile": "rec2020-sdr"` to convert
+the rendered SDR video from the renderer's BT.709 working output and write
+matching color metadata. This requires FFmpeg's `colorspace` filter and
+performs a final video encode. Set `"colorProfile": "hdr10"` for MP4 or MOV to
+convert the BT.709 SDR render to 10-bit BT.2020/PQ and encode with HEVC Main 10.
+This SDR-to-HDR conversion maps reference white to 203 nits; it cannot recover
+highlight detail absent from the SDR render. HDR10 output requires FFmpeg's
+`zscale` filter and `libx265`. `npm run doctor` reports filter and encoder
+availability. Before rendering, the Engine checks required final encoders and
+filters and reports a setup error before generating timeline proxies or
+starting browser capture when one is missing.
+
+For long renders, add `{ "resumeCheckpoint": true }` to the render options.
+After a complete HyperFrames capture, the async renderer keeps a validated
+intermediate if final encoding is interrupted or fails; retry the same render
+to reuse it. The cache is content-fingerprinted, SHA-256 checked, removed after
+success, limited to 8 GiB per capture by default, and expires after 72 hours.
+Override those bounds with `checkpointMaxBytes` (1 MiB–100 GiB) and
+`checkpointMaxAgeHours` (1–720). An interruption during browser capture still
+requires that capture stage to run again. PNG sequences and synchronous render
+APIs do not support checkpoints.
+
+`createCaptionTrack` also accepts reusable text styling options such as
+`fontFamily`, `fontWeight`, `lineHeight`, `verticalAlign`, `paddingPixels`,
+`textOutline`, and `textShadow`. These settings compile to validated CSS values;
+raw CSS is not accepted. `textOutline` uses `{ color, widthPixels }`, while
+`textShadow` uses `{ color, blurPixels, offsetXPixels, offsetYPixels }`.
+Choose `layoutPreset: 'subtitle' | 'social' | 'socialPop' | 'socialStack' | 'speechBubble' | 'lowerThird'`
+for reusable placement and styling defaults; explicit options override the
+selected preset.
+`socialPop` enables timed word highlighting by default, with a brief pop when
+each word becomes active. `socialStack` provides a two-line social caption
+layout with three words per line and six words per caption by default. Set
+`wordsPerLine` and `wordsPerCaption` to customize line and caption lengths.
+For other layouts, word-timed transcripts can set
+`wordHighlight: true` and choose `wordHighlightAnimation: 'scale' | 'pop'`;
+`wordHighlightColor` customizes the highlight. Explicit options override preset
+defaults. Caption presets wrap long text at word boundaries by default; set
+`wordWrap: false` to keep a single line. Wrapped words preserve the layout's
+horizontal alignment and vertical placement. Use `listCaptionLayoutPresets()`
+or `resolveCaptionLayoutPreset(name)` to inspect available layouts. Cue-level
+transcripts do not contain enough timing detail for word animations.
+
+`speechBubble` renders each timed phrase on a rounded panel with a directional
+tail. Customize its placement, typography, foreground, and fill with the same
+caption options, and customize the tail with a partial `bubble` object. For
+example, `{ "layoutPreset": "speechBubble", "x": 0.34, "backgroundColor":
+"#ffffff", "bubble": { "tailSide": "left", "tailPosition": 0.35,
+"tailSizePixels": 24, "cornerRadiusPixels": 30 } }`. `tailSide` accepts
+`top`, `right`, `bottom`, or `left`; `tailPosition` is normalized from 0.08 to
+0.92 along that edge. The layout defaults can be changed per generated caption
+track through `timeline captions` options, or per existing overlay through the
+JavaScript API and `timeline edit`. Standard overlay keyframes and transitions
+can animate the bubble entrance, exit, and position.
+
+GIF cannot carry audio, so timeline rendering rejects GIF requests when audio
+clips are present. PNG image sequences export full-resolution RGBA frames to a
+new directory and cannot carry audio or audio mastering. Optional CRF and
+video-bitrate overrides are available for MP4, MOV, and WebM exports; the
+default is still controlled by HyperFrames quality.
+
+Media probes retain the container and separate audio/video stream start times
+and time bases. Timeline source times use the media presentation timeline;
+frame rounding helpers are available in the JavaScript API. If a linked video
+and audio stream has a meaningful start/duration offset, rendering creates and
+cleans a temporary timestamp-aligned audio proxy without changing the source.
+Standalone audio with a non-zero stream start is also normalized to timeline
+zero through a temporary proxy. Variable-frame-rate sources remain seconds-based. A synthetic 30/15 fps source
+has been verified rendering at 30 fps on Windows; cross-platform VFR behavior
+still needs validation.
+
+## Editing workflow
+
+```sh
+# Inspect media and create a project
+node src/cli.mjs probe path/to/source.mp4
+node src/cli.mjs project create my-video 1080x1920 30 15 --background-color '#f3f0eb'
+
+# Create or import a transcript
+node src/cli.mjs transcribe video-projects/my-video path/to/source.mp4
+node src/cli.mjs import-transcript video-projects/my-video path/to/source.mp4 path/to/captions.srt
+node src/cli.mjs transcript export video-projects/my-video/transcripts/transcript.json vtt output/captions.vtt
+
+# Propose edits, review the EDL, then apply approved cuts
+node src/cli.mjs plan-silence video-projects/my-video/transcripts/transcript.json video-projects/my-video/edits/silence-edl.json
+node src/cli.mjs mistake-candidates video-projects/my-video/transcripts/transcript.json
+node src/cli.mjs apply-edl path/to/source.mp4 path/to/approved-edl.json path/to/clean-cut.mp4
+node src/cli.mjs retime video-projects/my-video/transcripts/transcript.json path/to/approved-edl.json video-projects/my-video/transcripts/retimed.json
+
+# Lint, preview, and render the composition
+node src/cli.mjs lint video-projects/my-video
+node src/cli.mjs preview video-projects/my-video
+node src/cli.mjs render video-projects/my-video
+```
+
+### Assemble an edited video in one render
+
+The generic timeline workflow can copy and fingerprint a source, use an
+imported or generated transcript, apply a reviewed EDL, retime the transcript,
+generate captions, and render the final composition:
+
+```sh
+node src/cli.mjs project create my-edit --preset landscape
+node src/cli.mjs asset register video-projects/my-edit path/to/source.mp4 camera
+node src/cli.mjs asset register-many video-projects/my-edit path/to/camera.mp4 path/to/music.wav path/to/logo.png
+node src/cli.mjs transcribe video-projects/my-edit video-projects/my-edit/assets/camera.mp4
+
+# Check copied media and restore a moved or damaged asset under its existing ID.
+node src/cli.mjs asset verify video-projects/my-edit
+node src/cli.mjs asset relink video-projects/my-edit camera path/to/replacement.mp4
+node src/cli.mjs asset preview video-projects/my-edit camera
+
+# Create a reusable draft proxy; request proxy use in timeline render options.
+node src/cli.mjs asset proxy create video-projects/my-edit camera 960 28
+# Normalize a VFR source proxy to the 30 fps project timeline.
+node src/cli.mjs asset proxy create video-projects/my-edit camera 960 28 30
+node src/cli.mjs timeline render video-projects/my-edit timeline.json renders/review.mp4 draft render-options.json
+
+# Generate a proposal, review it, then save approved decisions as approved.json.
+node src/cli.mjs detect-silence video-projects/my-edit/assets/camera.mp4 video-projects/my-edit/edits/silence-proposal.json
+# Find candidate shot boundaries; inspect the analysis before editing.
+node src/cli.mjs detect-scenes video-projects/my-edit/assets/camera.mp4 video-projects/my-edit/edits/scene-candidates.json
+node src/cli.mjs edit video-projects/my-edit camera video-projects/my-edit/transcripts/transcript.json path/to/approved.json
+```
+
+Consumers can inject a transcription provider without coupling the Engine to
+one cloud vendor or credential store. The provider returns word/cue objects;
+the Engine validates and normalizes them against the probed source duration:
+
+```js
+await transcribeWithProvider(projectPath, mediaPath, {
+  id: 'my-provider',
+  async transcribe({ mediaPath, durationSeconds, options }) {
+    return providerClient.transcribe(mediaPath, { ...options, durationSeconds });
+  },
+}, { granularity: 'word', providerOptions: { language: 'en' } });
+```
+
+Provider credentials stay inside the consumer's provider client and are not
+written to project metadata or the normalized transcript.
+
+The JavaScript API exports `probeMediaAsync(path, { signal })` for cancellable
+FFprobe inspection when a consumer needs media metadata without registering the
+asset first. The CLI `probe` command uses the same asynchronous path and Ctrl+C
+stops its active FFprobe process.
+
+`asset register` probes and copies sources asynchronously. Ctrl+C cancels the
+probe or staged copy and cleans the incomplete registration; source files and
+existing project assets are left untouched. When `timeline.json` exists, the
+new asset's probed metadata is added to its asset catalog without adding a clip;
+the editing agent can then place it on a track. JavaScript consumers can use
+`await registerMediaAssetAsync(projectPath, sourcePath, { id, signal, onProgress })`
+to receive byte-based copy progress plus probe and publish stages. The CLI prints
+copy progress to stderr and keeps the registered asset JSON on stdout.
+Both synchronous and asynchronous registration now probe and fingerprint the
+staged copy, so the recorded metadata describes the bytes committed to the
+project. Registration prefers hard-link publication and falls back to an
+exclusive copy when the filesystem does not support hard links; the async path
+supports cancellation and reports fallback copy progress through the publish
+stage.
+`asset register-many` and `registerMediaAssetsAsync(projectPath, sources, {
+signal, onProgress })` add multiple sources sequentially. Each source is an
+independent transaction; the batch continues after per-source errors and
+returns `{ registered, failed }` so partial success is explicit. Duplicate IDs
+and existing destination conflicts are rejected before any files are copied.
+The CLI prints batch and per-asset stage progress to stderr, writes the complete
+result on stdout, and exits with status 1 if any source failed. Batch
+registration does not add clips to the timeline. The async API returns batch
+progress events at `asset-batch` and `asset-batch-item` stages.
+`asset relink` emits the same copy/hash, probe, and publish progress for the
+replacement source. Its CLI progress stays on stderr.
+
+`asset verify` checks registered source and proxy SHA-256 identities against
+the manifest and reports missing or modified files. The CLI hashes media
+asynchronously and reports byte-based scan progress on stderr. Ctrl+C cancels
+the scan; JavaScript consumers can pass `onProgress(event)` to
+`verifyProjectAssetsAsync(projectPath, { signal, onProgress })` for the same
+overall progress in their UI.
+The synchronous `verifyProjectAssets(projectPath)` API remains available.
+`asset relink` replaces
+the media for an existing asset ID, refreshes its probe metadata and
+fingerprint, and keeps
+the project-relative path stable so existing timeline references continue to
+work. If `timeline.json` exists, its asset metadata and source fingerprint are
+refreshed as well; the timeline is revalidated before the replacement is saved.
+Stale proxies are removed when the source fingerprint changes. Relinking only
+accepts the original media type and extension, and preserves the replacement
+source file. The CLI stages and probes the replacement asynchronously; Ctrl+C
+cancels before commit or restores the prior asset, manifest, and timeline if
+the commit fails. JavaScript consumers can use
+`await relinkProjectAssetAsync(projectPath, assetId, sourcePath, { signal })`.
+Asset registration and relinking update timeline metadata. When a persistent
+timeline history sidecar exists, the Engine resets its snapshots automatically
+and preserves the configured history limit because asset metadata changes form
+a new undo baseline.
+
+Use `asset list` to inspect all registered media, including assets that are not
+yet referenced by a timeline. Video/audio records include container aliases
+and metadata for every video and audio stream. The command returns versioned
+manifest metadata as JSON without touching media files:
+
+```sh
+node src/cli.mjs asset list video-projects/my-edit
+```
+
+The JavaScript API exposes the same operation as
+`listProjectAssets(projectPath)`.
+
+Use `asset unregister` to remove unused media from the project manifest and
+timeline catalog. It refuses to unregister an asset referenced by any clip.
+The source and proxy files stay on disk, so this operation does not discard
+media; delete those files separately only when you have confirmed they are no
+longer needed. The API returns the removed asset metadata and confirms that the
+files were preserved:
+
+```sh
+node src/cli.mjs asset unregister video-projects/my-edit unused-intro
+```
+
+The JavaScript API exposes the same operation as
+`unregisterProjectAsset(projectPath, assetId)`.
+
+`asset proxy create` generates an H.264, video-only proxy for a registered
+video asset. The optional arguments set maximum dimension, CRF, and output
+frame rate (defaults: 960 and 28, with no frame-rate conversion); valid ranges
+are 160–3840 pixels, CRF 18–40, and frame rate 1–240 fps. A specified frame
+rate normalizes source timestamps to a CFR proxy, which can help browser
+previews of VFR media. Proxies preserve smaller source dimensions instead of
+upscaling and force a keyframe every second to make timeline seeking faster.
+Match the proxy frame rate to the project and enable proxy rendering. The
+Engine records the proxy profile, fingerprint, and media metadata
+in the asset manifest and reuses a matching current proxy. To use proxies for
+draft review, set
+`{ "useProxies": true }` in the timeline render options JSON. This switches
+video clips to the smallest current proxy and leaves audio clips on registered
+source media. `asset verify` checks proxy files too; a modified proxy is
+regenerated when the same proxy settings are requested again. Regular final
+renders continue using the original assets unless proxy use is explicitly
+requested. The CLI uses cancellable FFmpeg processing; Ctrl+C stops proxy
+generation and removes its staged output. JavaScript consumers can call
+`await createAssetProxyAsync(projectPath, assetId, { signal, ...options })`.
+Pass `onProgress(event)` to receive proxy preflight, FFmpeg encoding percentage,
+integrity validation, and publication events. The CLI reports proxy progress on
+stderr while keeping the final proxy record as JSON on stdout.
+
+`asset preview` creates cached thumbnails and/or an audio waveform for a
+registered asset. It returns source-relative thumbnail timestamps and paths,
+plus min/max waveform samples that preview clients can draw at any zoom level.
+Preview files live under `assets/previews/` and are keyed by the source hash and
+generation settings; changed source media cannot silently reuse stale previews.
+Pass an options JSON file to override `thumbnailIntervalSeconds` (default 2,
+0.25–60), `thumbnailMaxDimension` (default 320, 80–1280), or `waveformPoints`
+(default 2000, 32–20000). The JavaScript API is
+`await generateAssetPreview(projectPath, assetId, { signal, ...options })`;
+thumbnail extraction, waveform decoding, and media probing respond to the
+signal. Pass `onProgress(event)` to receive integrity hashing, media probing,
+thumbnail extraction, waveform decoding, and cache publication status. The CLI
+writes these updates to stderr and keeps preview JSON on stdout; Ctrl+C cancels
+active preview processes.
+
+Media-analysis providers use the same injected approach. Their findings are
+time-checked against the probed source and returned as suggestions for an AI or
+human editor to review; the Engine does not turn them into automatic cuts:
+
+For a local first-pass shot map, `detect-scenes` uses FFmpeg's scene-change
+score and returns review-required `scene-cut` findings in the same normalized
+analysis format. It accepts an optional JSON file with `threshold` (0.05–1,
+default 0.35), `minimumSpacingSeconds` (0–60, default 0.5), and
+`maximumFindings` (1–10000, default 2000). Raising the threshold finds only
+more pronounced visual changes. This detects visual differences; it does not
+identify semantic topics, camera quality, or whether a cut is editorially
+useful. The JavaScript API is `detectSceneChangesAsync(mediaPath, options)` and
+supports `AbortSignal` cancellation.
+
+```sh
+node src/cli.mjs detect-scenes path/to/source.mp4 edits/scene-candidates.json
+```
+
+Scene candidates can guide a provider or editing agent when selecting ranges
+for a rough cut, B-roll, or chapter markers. They do not create or apply edits
+by themselves.
+
+Generate a complete shot-review folder with a representative JPEG thumbnail for
+each detected shot, a contact sheet, and `scene-review.json` mapping shot
+indexes and time ranges to the images:
+
+```sh
+node src/cli.mjs scene-review path/to/source.mp4 video-projects/review/source-shots
+```
+
+The default pack is bounded to 300 shots and a 60-frame contact sheet. Use an
+options JSON file to adjust detection settings or set `maximumShots`,
+`thumbnailSize`, `contactSheetLimit`, and `columns`; the contact sheet is capped
+at 64 megapixels. The schema v2 pack includes the source SHA-256 identity. It is
+staged and published as a new directory; an existing output directory is never
+replaced.
+All findings remain review-required, and the thumbnails do not infer scene
+meaning. The API exposes `createSceneReviewPackAsync(mediaPath, outputDir, options)`
+with cancellation and progress callbacks; the CLI reports progress on stderr
+while writing the review manifest to stdout.
+
+An editing agent can turn explicitly selected review shots into a dry-run B-roll
+insertion plan. Register the same source media used to create the scene-review
+pack as a video asset, then provide only the shot, timeline position, and
+optional source trim selections:
+
+```json
+[
+  {
+    "shotIndex": 2,
+    "timelineStartSeconds": 8,
+    "sourceOffsetSeconds": 0.25,
+    "durationSeconds": 2,
+    "clipId": "market-broll-01"
+  }
+]
+```
+
+```sh
+node src/cli.mjs timeline plan-broll timeline.json scene-review.json broll-source video-broll placements.json edits/broll-plan.json
+```
+
+The command writes a `reviewRequired` plan with validated `add-clip` operations,
+a before/after preview, and SHA-256 identities for the timeline and source.
+It verifies the registered asset matches the media used by the scene-review
+pack. It does not change the timeline or choose semantically relevant shots.
+The selected source ranges must fit within their reviewed shot. Review the saved plan,
+then explicitly apply it through the undoable command:
+
+```sh
+node src/cli.mjs timeline apply-plan timeline.json edits/broll-plan.json
+```
+
+Application refuses if the timeline has changed since planning. The JavaScript
+APIs are `planSceneReviewPlacements(timeline, sceneReview, assetId, trackId,
+placements)` and `applyTimelineReviewPlan(timelinePath, plan)`.
+
+```js
+const { analysis } = await analyzeMediaWithProvider(mediaPath, {
+  id: 'scene-detector',
+  async analyze({ mediaPath, durationSeconds, media, options }) {
+    return detector.inspect(mediaPath, { durationSeconds, media, ...options });
+  },
+});
+```
+
+Each normalized finding has a stable result-local ID, kebab-case type, start
+time, optional end time, optional confidence, and optional description.
+Providers may attach a validated `remove-range` suggestion with source bounds
+and a reason. Convert explicit suggestions into a review-required EDL draft,
+then approve it only after review:
+
+```sh
+node src/cli.mjs analysis-to-edl edits/analysis.json edits/candidate-edl.json
+node src/cli.mjs approve-edl edits/candidate-edl.json edits/approved-edl.json
+```
+
+Candidate EDLs carry `reviewStatus: "needs-review"`; rendering, timeline
+construction, and transcript retiming reject them until the explicit approval
+command writes a separate approved file. Confidence filtering is optional via
+an options JSON file containing `minConfidence` from 0 to 1.
+
+For CLI workflows, pass a trusted JavaScript module that exports a provider as
+its default export (or as `mediaAnalysisProvider` / `provider`). The module
+receives normalized media metadata and optional provider settings; suggestions
+are written to a new JSON file and existing output is never overwritten:
+
+```sh
+node src/cli.mjs analyze path/to/source.mp4 path/to/provider.mjs edits/analysis.json provider-options.json
+```
+
+Keep provider credentials in the provider's own runtime configuration. The
+Engine validates the results and does not store provider credentials.
+
+The EDL is a JSON object with `schemaVersion`, `sourceDurationSeconds`, and
+`cuts` entries containing source-time `sourceStart`, `sourceEnd`, and `reason`.
+The `edit` command refuses to overwrite existing timeline, approved EDL,
+retimed transcript, or render artifacts. It stores the source SHA-256 and
+artifact paths in timeline lineage. To edit transcript words before rendering,
+apply corrections with `transcript correct` and provide the corrected file to
+`edit`. You can also build and render a generic timeline directly with the
+JavaScript API (`createProjectTimeline`, `timelineFromEdl`, `editTimeline`,
+`editTimelineBatch`, `editTimelineFile`, `undoTimelineFile`,
+`redoTimelineFile`, `detachAudioFromTimelineClip`, `createTimelineHistory`,
+`createCaptionTrack`, and `renderTimeline`).
+
+Use `timeline inspect` to give an editing agent a compact, read-only view of the
+project format, assets, ordered tracks, clip source and timeline ranges,
+transitions, and audio settings before it proposes an edit:
+
+```sh
+node src/cli.mjs timeline inspect timeline.json
+```
+
+The JavaScript API exports the same view through
+`inspectTimeline(timeline)`. It validates the timeline first and does not write
+or modify project files. Computed clip end times in the summary are rounded to
+six decimal places to avoid floating-point display noise.
+
+Generic edit operations can add/remove/reorder tracks and add/remove/duplicate clips, detach clip audio,
+move clips within and between compatible tracks, trim/slip/split clips,
+insert a synchronized gap or ripple-delete a time range across every track,
+apply crossfades or clip-edge transitions, and preserve timeline validation at
+each step. Gap insertion trims clips at the insertion point and shifts their
+remaining segments and later clips while keeping source ranges, keyframes,
+speed ramps, captions, and track synchronization aligned. Ripple deletion
+trims or splits clips that straddle the cut, retimes later clips, and shortens
+the project. Adding a clip or inserting a gap can extend project duration;
+ordinary removal leaves it unchanged so existing downstream timing is preserved.
+Cross-track moves preserve the clip id and all clip metadata, and require the
+source and destination tracks to have the same kind. To move a video clip to a
+different video layer, use `move-track` in an operation file:
+
+```json
+{
+  "type": "move-track",
+  "trackId": "video-main",
+  "clipId": "interview-shot",
+  "targetTrackId": "video-broll",
+  "timelineStart": 8
+}
+```
+
+For AI-proposed arbitrary time ranges, use `ripple-delete-range` with explicit
+project-time boundaries. It applies the same cut to every track, preserves the
+left/right clip segments, and retimes later clips, keyframes, audio automation,
+and markers together:
+
+```json
+{ "type": "ripple-delete-range", "startSeconds": 12.4, "endSeconds": 13.1 }
+```
+
+The JavaScript API exposes this as
+`rippleDeleteTimelineRange(timeline, startSeconds, endSeconds)`.
+
+Use `set-track-state` to show or hide video/overlay tracks, mute or solo audio
+tracks, lock either track kind, or adjust audio-track volume through the same
+reviewable operation workflow.
+Partial state updates preserve other settings, and `null` clears an override:
+
+```json
+{ "type": "set-track-state", "trackId": "music", "state": { "muted": true, "volume": 0.35 } }
+```
+
+Disable an individual clip without removing it from the timeline with
+`set-clip-state`. Re-enable it with `enabled: true`, or clear the override with
+`null`:
+
+```json
+{ "type": "set-clip-state", "trackId": "video-main", "clipId": "unused-take", "state": { "enabled": false } }
+```
+
+The JavaScript API exposes the same operation through
+`setTimelineClipState(timeline, trackId, clipId, state)`.
+
+Add a project-time marker for chapter points or review notes with `set-marker`.
+Markers are stored in the edit timeline and returned by `inspectTimeline`; they
+do not render into the video. Gap insertion moves markers at or after the
+insertion point, and ripple deletion removes markers inside the cut and shifts
+later markers with the retained edit:
+
+```json
+{
+  "type": "set-marker",
+  "marker": {
+    "id": "review-audio-mix",
+    "timeSeconds": 12.5,
+    "label": "Review music level",
+    "color": "#f59e0b"
+  }
+}
+```
+
+Use `remove-marker` with the marker id to delete it. The JavaScript API exposes
+these operations as `setTimelineMarker(timeline, marker)` and
+`removeTimelineMarker(timeline, markerId)`. Markers use stable kebab-case ids,
+non-empty labels of at most 200 characters, optional six-digit hex colors, and
+times within the project duration. OpenTimelineIO maps them to root-stack
+markers; other interchange adapters may not preserve or display them.
+
+To process every clip on a music track with the same chain, set its effects at
+track level:
+
+```json
+{
+  "type": "set-track-audio-effects",
+  "trackId": "music",
+  "audioEffects": [
+    { "type": "lowpass", "frequencyHz": 16000 },
+    { "type": "balance", "value": 0.15 }
+  ]
+}
+```
+
+Visual tracks accept `visible`; audio tracks accept `muted`, `solo`, `volume`, and
+project-time `volumeKeyframes` through `set-track-state`. Both track kinds accept
+`locked`. Lock or unlock it with a standalone operation:
+
+```json
+{ "type": "set-track-state", "trackId": "approved-footage", "state": { "locked": true } }
+```
+
+A locked track rejects clip edits and track-setting changes. Synchronized gap
+insertion and ripple deletion are refused when they would change locked track
+content. Unlock the track with `{"locked": false}` before editing it. Lock state
+is preserved in Engine OpenTimelineIO metadata; OTIO itself has no portable
+track-lock behavior.
+
+Use the dedicated
+`set-track-audio-effects` operation to replace or clear a track effect chain.
+Its JavaScript API is
+`setTimelineTrackAudioEffects(timeline, trackId, effects)`; pass `null` or an
+empty array to clear it. Clip effects run first; then a track with effects is
+mixed to one temporary stem and its chain runs across that full timeline.
+Clip/track gain, fades, and timing ducking are preserved.
+
+When one or more audio tracks have `solo: true`, draft and final timeline renders
+include only unmuted solo tracks. Clear the solo override with `null` to return
+to the full mix. Solo state is carried in Engine metadata during OpenTimelineIO
+round trips.
+
+Use `set-overlay` to reviewably change caption text, word timings, layout,
+styling, or composition reference after adding the overlay clip. The operation
+accepts validated overlay fields only, and `null` clears optional overrides:
+
+```json
+{
+  "type": "set-overlay",
+  "trackId": "captions",
+  "clipId": "caption-01",
+  "properties": { "text": "A clearer caption", "fontSize": 48, "textAlign": "center" }
+}
+```
+
+The JavaScript API is `setTimelineOverlay(timeline, trackId, clipId, properties)`.
+Use `preview-edit` to inspect caption and layout changes before writing them.
+
+Review the exact result before writing an edit. `preview-edit` prints the
+duration change and each added, removed, or updated track and clip as JSON; it
+does not write a timeline file:
+
+```sh
+node src/cli.mjs timeline preview-edit timeline.json edits/insert-gap.json
+```
+
+After reviewing the preview, apply the same operation plan to a new timeline
+file. For example, save this as `edits/insert-gap.json`:
+
+```json
+{
+  "type": "insert-gap",
+  "timelineStart": 12.5,
+  "durationSeconds": 2
+}
+```
+
+Then write the result to a new timeline file:
+
+```sh
+node src/cli.mjs timeline edit timeline.json edits/insert-gap.json timeline-edited.json
+```
+
+The operation file can also be a JSON array. The Engine applies each operation
+in order, validates each intermediate timeline, and only writes the final file
+if the entire batch succeeds:
+
+```json
+[
+  { "type": "move", "trackId": "video-main", "clipId": "intro", "timelineStart": 0.5 },
+  { "type": "transition", "trackId": "video-main", "clipId": "intro", "edge": "in", "transition": { "schemaVersion": 1, "type": "fade", "durationSeconds": 0.4 } }
+]
+```
+
+Single-operation files remain supported. Existing output files are never
+overwritten. The JavaScript API exposes the same behavior through
+`editTimelineBatch(timeline, operations)`. `previewTimelineEdit(timeline,
+operations)` returns the same validated change plan without modifying the input.
+
+Replace a clip's media source through a reviewable `replace-asset` operation.
+The clip keeps its timeline placement and visual/audio settings; provide new
+source bounds when the old range does not fit the replacement. The operation
+can also clear an incompatible playback rate or speed ramp with `null`, or
+select/clear an audio stream:
+
+```json
+{
+  "type": "replace-asset",
+  "trackId": "video-main",
+  "clipId": "b-roll-01",
+  "assetId": "b-roll-alternate",
+  "sourceIn": 2,
+  "sourceOut": 5,
+  "playbackRate": null,
+  "reverse": false,
+  "speedRamp": null
+}
+```
+
+Use `timeline preview-edit` first to inspect the resulting clip changes. The
+same operation is available as `replaceTimelineClipAsset` in the JavaScript API.
+
+Detach the selected video clip's source audio into a synchronized audio clip.
+This creates an audio track when the requested one does not exist and keeps
+the video clip's source range, timeline placement, and playback rate or speed
+ramp. Set `audioStreamIndex` to a zero-based ordinal to select a language or mic
+track from a multi-audio source; registered assets expose each stream's codec,
+channel layout, timing, language, and title. Edit the new audio clip
+independently to create an L-cut or J-cut:
+
+```json
+{
+  "type": "detach-audio",
+  "trackId": "video-main",
+  "clipId": "interview-shot",
+  "audioTrackId": "interview-audio",
+  "audioClipId": "interview-shot-audio",
+  "audioStreamIndex": 1
+}
+```
+
+For interactive workflows, wrap a timeline in bounded in-memory undo/redo
+history. Failed edits leave the history untouched, each returned timeline is an
+isolated snapshot, and applying a new edit after undo clears the redo branch:
+
+```js
+const history = createTimelineHistory(timeline, { limit: 100 });
+history.applyBatch([
+  { type: 'move', trackId: 'video-main', clipId: 'intro', timelineStart: 1 },
+  { type: 'transition', trackId: 'video-main', clipId: 'intro', edge: 'in', transition: { schemaVersion: 1, type: 'fade', durationSeconds: 0.4 } },
+]);
+const reviewed = history.undo();
+const restored = history.redo();
+```
+
+The history stores timeline snapshots in memory; save approved project files
+separately through the consumer's normal persistence flow. For CLI agents and
+other one-shot processes, persistent history operates directly on a timeline
+file and keeps a bounded hidden sidecar beside it:
+
+```sh
+node src/cli.mjs timeline preview-edit timeline.json edits/move-intro.json
+node src/cli.mjs timeline project-edit timeline.json edits/move-intro.json
+node src/cli.mjs timeline undo timeline.json
+node src/cli.mjs timeline redo timeline.json
+node src/cli.mjs timeline history timeline.json
+```
+
+The first edit creates `.timeline.json.history.json`; the default history limit
+is 20 snapshots. Pass a limit on the first `project-edit` call to choose a
+different bound. A failed or interrupted two-file update is recovered from its
+atomic history journal on the next command; a lock serializes concurrent CLI
+edits and stale locks from exited processes are cleared. If the timeline was edited outside
+that history, the CLI reports the mismatch; use
+`timeline history timeline.json reset [limit]` to begin a new history from the
+current timeline.
+
+For a crossfade between adjacent clips, apply a timeline edit before rendering:
+
+```js
+const transitioned = editTimeline(timeline, {
+  type: 'crossfade',
+  trackId: 'video-main',
+  clipId: 'intro',
+  incomingClipId: 'main',
+  durationSeconds: 0.35,
+});
+```
+
+Set `allowOverlap: true` on the track and place the incoming clip so it overlaps
+the outgoing clip by `durationSeconds`. The operation verifies that timing and
+configures opacity fades for video/text or volume fades for audio. Tracks still
+control compositing order.
+
+For reusable clip-edge transitions, assign a versioned fade or directional wipe
+to a video or overlay clip:
+
+```js
+const transitioned = editTimeline(timeline, {
+  type: 'transition',
+  trackId: 'video-main',
+  clipId: 'main',
+  edge: 'in',
+  transition: { schemaVersion: 1, type: 'wipe', direction: 'left', durationSeconds: 0.5 },
+});
+```
+
+Use `edge: 'out'` for the clip end, or `transition: null` to remove the edge
+transition. Wipes accept `left`, `right`, `up`, and `down`; both clip edges can
+have transitions when their durations do not overlap. Fade transitions cannot
+share opacity animation with that clip, and wipes cannot share a static mask.
+
+Video clips and text/composition overlays can define clip-local visual
+keyframes. `x`, `y`, `width`, and `height` are normalized to the canvas;
+`opacity` ranges from 0 to 1, and `rotationDegrees` rotates around the element
+center. Video clips can animate `objectPositionX` and `objectPositionY` from 0
+to 1 to reframe media inside its existing `object-fit` viewport, and `zoom`
+from 1× to 4× to scale the media inside a clipped, fixed-size viewport. Use
+object-position keyframes to pan the zoom focus without moving the clip's
+timeline bounds. Visual filter values include `brightness`, `contrast`, and `saturation`
+(0–5), `blurPixels` (0–100), and `hueDegrees` (-360–360). Each keyframe time is
+relative to its clip and the first keyframe must be at 0. Values interpolate to
+the next keyframe; `ease` is optional and uses an allowlisted GSAP ease. The
+last value holds through the clip end. Opacity keyframes cannot be combined
+with clip fade fields. Use an `eases` map for per-property easing when one
+keyframe changes multiple properties with different curve segments. Trim and
+split operations rebase these easing ranges to preserve motion continuity.
+An easing slice is represented as `{ type: 'range', name: 'power2.out',
+from: 0.5, to: 1 }`, where `from` and `to` select a normalized part of the
+allowlisted curve. The validator rejects unrecognized ease names and ranges.
+
+Video and overlay clips also accept validated static masks: `circle` with
+`centerX`, `centerY`, and `radius`; `ellipse` with `centerX`, `centerY`,
+`radiusX`, and `radiusY`; or `rect` with normalized `x`, `y`, `width`, and
+`height`. These are timeline data, not arbitrary CSS values. Animate a mask
+with the `maskProgress` keyframe property from 0 to 1; it scales the chosen
+shape from its center to its configured bounds. The first keyframe must include
+`maskProgress`, and the clip must define a static mask.
+
+Video and overlay clips may set an allowlisted CSS `blendMode` to composite
+against lower visual layers. Supported modes are `normal`, `multiply`,
+`screen`, `overlay`, `darken`, `lighten`, `color-dodge`, `color-burn`,
+`hard-light`, `soft-light`, `difference`, `exclusion`, `hue`, `saturation`,
+`color`, and `luminosity`. For example, `blendMode: 'screen'` can lighten a
+lower layer while preserving its dark areas. Blend modes are isolated to the
+project canvas and cannot be applied to audio clips.
+
+```js
+const clip = {
+  id: 'b-roll',
+  assetId: 'camera',
+  sourceIn: 0,
+  sourceOut: 4,
+  timelineStart: 2,
+  durationSeconds: 4,
+  keyframes: [
+    { time: 0, properties: { x: 0.5, y: 0.1, width: 0.4, height: 0.8, opacity: 0 } },
+    { time: 1, properties: { x: 0.3, opacity: 1 }, ease: 'power2.out' },
+    { time: 4, properties: { x: 0.1, rotationDegrees: -3 } },
+  ],
+};
+```
+
+Animated bounds must stay within the canvas. Keyframes are part of the
+schema-version-1 timeline object and use the same JavaScript renderer as other
+timeline operations. AI workflows can replace or clear clip keyframes with the
+reviewable `set-keyframes` timeline operation. It works in a batch and with
+`timeline preview-edit`, so proposed motion can be inspected before saving:
+
+```json
+{
+  "type": "set-keyframes",
+  "trackId": "video",
+  "clipId": "b-roll",
+  "keyframes": [
+    { "time": 0, "properties": { "x": 0.5, "width": 0.4 } },
+    { "time": 2, "properties": { "x": 0.2, "width": 0.6 }, "ease": "power2.out" }
+  ]
+}
+```
+
+Set `keyframes` to `null` to remove the animation. The JavaScript API exposes
+`setTimelineClipKeyframes(timeline, trackId, clipId, keyframes)`.
+
+Use `set-framing` to reviewably change a video's static fit or normalized
+viewport after adding it to the timeline. Partial updates preserve unspecified
+fields; set a field to `null` to restore its inherited/default value:
+
+```json
+{
+  "type": "set-framing",
+  "trackId": "video",
+  "clipId": "b-roll",
+  "framing": { "fit": "cover", "x": 0.1, "width": 0.8 }
+}
+```
+
+The JavaScript API exposes `setTimelineClipFraming(timeline, trackId, clipId,
+framing)`. Timeline validation checks the resulting crop and viewport bounds.
+
+Set a constant `playbackRate` from `0.1` to `5` on video or audio clips. The
+source range must equal `durationSeconds * playbackRate`. Rendering creates a
+temporary FFmpeg proxy for the selected source range (video is re-encoded;
+audio uses pitch-preserving `atempo`) and removes it afterward. Original assets
+and the saved timeline remain unchanged.
+
+Set `reverse: true` on a video or audio clip to play its selected source range
+backward. It can combine with a constant `playbackRate`, but not with
+`speedRamp`. Rendering creates a temporary reversed media proxy and removes it
+afterward. FFmpeg's reverse filters buffer the selected clip, so memory use
+grows with the clip's duration and resolution. Reverse playback is not represented by the
+OpenTimelineIO interchange profile. Detaching a reversed video clip copies the
+reverse setting to its audio clip. Trim and split preserve the reverse source
+direction. To change it as a reviewable edit, use the
+`set-reverse` timeline operation with the CLI or `setTimelineClipReverse` API:
+
+```json
+  { "type": "set-reverse", "trackId": "video", "clipId": "shot-1", "reverse": true }
+```
+
+The `doctor` command and `getEngineCapabilities()` report whether the FFmpeg
+`reverse` and `areverse` filters are available. Rendering checks the filter
+needed by each reversed track before it creates temporary media.
+
+For a smooth speed ramp, set source-relative `speedRamp` points instead of a
+constant `playbackRate`:
+
+```js
+import { speedRampDuration } from 'aivee';
+
+const speedRamp = [
+  { sourceOffset: 0, playbackRate: 1, ease: 'easeInOutCubic' },
+  { sourceOffset: 2, playbackRate: 2 },
+];
+const clip = {
+  sourceIn: 0,
+  sourceOut: 2,
+  durationSeconds: speedRampDuration(speedRamp),
+  speedRamp,
+};
+```
+
+The `ease` field on a point controls the outgoing segment. Supported curves are
+`linear`, `easeIn`, `easeOut`, `easeInOut`, `easeInCubic`, `easeOutCubic`, and
+`easeInOutCubic`; omitted easing defaults to `linear`. The renderer samples
+eased rate curves into bounded linear segments for video timestamp mapping and
+audio automation. The clip duration is `integral(ds / playbackRate(s))` over
+its source range; the first point starts at offset 0 and the last ends at
+`sourceOut - sourceIn`. Use the reviewable `set-speed` edit operation to set a
+constant rate, replace a speed ramp, or reset to normal speed. It recalculates
+clip duration and scales clip-local animation, fades, transitions, word timing,
+and volume automation to preserve their relative timing:
+
+```json
+{
+  "type": "set-speed",
+  "trackId": "video-main",
+  "clipId": "shot-1",
+  "speed": { "playbackRate": 1.5 }
+}
+```
+
+Pass `null` for `playbackRate` or `speedRamp` to reset to normal speed. The
+same operation is exposed as `setTimelineClipSpeed`.
+Rates must stay between 0.1× and 5×. Use the exported `speedRampDuration`
+helper to compute the required clip duration. The video proxy maps frame
+timestamps through the curve. Audio uses pitch-preserving FFmpeg `rubberband`
+commands sampled at up to 50 ms source intervals, then pads or trims to the
+clip's exact timeline duration. Audio speed ramps require an FFmpeg build with
+the `rubberband` filter; the renderer reports a clear error when it is missing.
+The `doctor` command reports whether the filter is available. Trim and split
+operations rebase speed curves and visual keyframes at the edit point.
+
+Audio tracks and clips accept `volume` from 0 to 1, and audio clips accept
+`fadeInSeconds` and `fadeOutSeconds`.
+
+Use `set-audio-state` to reviewably change an audio clip's static volume, fade
+durations, or selected source audio stream. Partial updates preserve unspecified
+fields; `null` restores the inherited/default value:
+
+```json
+{
+  "type": "set-audio-state",
+  "trackId": "narration",
+  "clipId": "voice-over",
+  "state": { "volume": 0.8, "fadeInSeconds": 0.2, "audioStreamIndex": 0 }
+}
+```
+
+The JavaScript API is
+`setTimelineClipAudioState(timeline, trackId, clipId, state)`. Timeline
+validation checks the selected stream and clip-bound fade durations.
+
+Video clips can select a zero-based video-stream ordinal with
+`videoStreamIndex`. Registered assets expose stream ordinals and their FFmpeg
+stream indexes in `videoStreams`. Use `set-video-state` to reviewably change or
+clear the selection; rendering creates a temporary clip proxy for the chosen
+stream and leaves the source media unchanged:
+
+```json
+{
+  "type": "set-video-state",
+  "trackId": "video-main",
+  "clipId": "interview-shot",
+  "state": { "videoStreamIndex": 1 }
+}
+```
+
+The JavaScript API is
+`setTimelineClipVideoState(timeline, trackId, clipId, state)`. The same
+selection can be supplied when replacing a clip asset with `videoStreamIndex`.
+
+For changing clip gain over time, use `volumeKeyframes`. Times are relative to
+the audio clip, begin at 0, and interpolate linearly between points. The last
+value holds through the clip end. Trim, split, gap insertion, and ripple delete
+preserve the curve. Use `set-volume-keyframes` or the
+`setTimelineClipVolumeKeyframes` API to reviewably replace the curve; pass
+`null` or an empty array to clear it.
+
+```json
+{
+  "type": "set-volume-keyframes",
+  "trackId": "narration",
+  "clipId": "voice-over",
+  "volumeKeyframes": [
+    { "time": 0, "volume": 1 },
+    { "time": 2.5, "volume": 0.35 },
+    { "time": 4, "volume": 1 }
+  ]
+}
+```
+
+Audio tracks can also define `volumeKeyframes` to automate the track fader over
+project time. These points start at time 0, use linear interpolation, and hold
+the last value. Clip and track automation multiply together with static track
+  and clip gain. `set-track-state` can replace the track curve; pass `null` to
+  clear it. Gap insertion and ripple deletion preserve its timing:
+
+```json
+{
+  "type": "set-track-state",
+  "trackId": "music",
+  "state": {
+    "volumeKeyframes": [
+      { "time": 0, "volume": 0.7 },
+      { "time": 5, "volume": 0.25 },
+      { "time": 12, "volume": 0.7 }
+    ]
+  }
+}
+```
+
+Audio clips can also define an ordered `audioEffects` array. The supported
+effects are `equalizer` (`frequencyHz`, `gainDB`, optional `q`), `highpass` or
+`lowpass` (`frequencyHz`, optional `order` 1–2), `compressor` (`thresholdDB`,
+`ratio`, optional attack/release and makeup gain), and `denoise`
+(`reductionDB`, 0.01–30). `balance` takes a `value` from `-1` (left) to `1`
+(right), with `0` centered. Effects are applied to a temporary clip proxy,
+leaving the registered source unchanged. Denoise requires the `afftdn` filter;
+stereo balance requires `stereotools`. `doctor` and `capabilities` report these
+and other audio filter availability. Render preflight checks all filters
+required by selected clip/track effects, sidechain, and mastering settings
+before creating temporary media.
+Audio tracks may define the same `audioEffects` array; the Engine mixes the
+track's clips to a temporary stem, then applies the track chain across that
+complete stem. Use `set-track-audio-effects` to replace or clear the track
+chain without editing the timeline file by hand.
+Use the reviewable `set-audio-effects` operation or the
+`setTimelineClipAudioEffects` API to apply or replace this ordered list. Pass
+`null` or an empty array to clear it.
+
+```json
+{
+  "audioEffects": [
+    { "type": "highpass", "frequencyHz": 80 },
+    { "type": "denoise", "reductionDB": 12 },
+    { "type": "compressor", "thresholdDB": -20, "ratio": 3 },
+    { "type": "balance", "value": -0.2 }
+  ]
+}
+```
+
+Keep the final `audioMastering` stage for whole-mix processing such as loudness,
+final equalization, limiting, and output channel layout.
+
+To duck a music track while narration clips are active, add this to the timeline:
+
+```js
+timeline.audioMix = {
+  // Clip-timing ducking remains available without signal analysis.
+  ducking: [{
+    sourceTrackId: 'narration',
+    targetTrackId: 'music',
+    attenuation: 0.22,
+    attackSeconds: 0.12,
+    releaseSeconds: 0.3,
+  }],
+  // Or compress the music from the actual narration signal.
+  sidechain: [{
+    sourceTrackId: 'narration',
+    targetTrackId: 'music',
+    thresholdDb: -24,
+    ratio: 4,
+    attackSeconds: 0.01,
+    releaseSeconds: 0.25,
+  }],
+};
+```
+
+`attenuation` is a multiplier on the target's current volume while source clips
+are active. This timing-based option compiles with track/clip gain and fades to
+one automation envelope. `sidechain` instead listens to the source track's
+rendered signal and applies FFmpeg sidechain compression to target clips. Its
+defaults are -24 dB threshold, 4:1 ratio, 10 ms attack, and 250 ms release.
+Threshold is limited to -60–0 dB, ratio to 1:1–20:1, attack to 0.01–2000 ms,
+and release to 0.01–9000 ms. The detector stem uses source track/clip gain and
+fades; output track/clip gain and fades remain applied by the timeline renderer.
+This is broadband compression, not speech recognition or phoneme-aware audio
+mixing. Final settings still need listening review on varied real material.
+Use the reviewable `set-audio-mix` edit operation or
+`setTimelineAudioMix(timeline, audioMix)` API to replace these rules; pass
+`null` to clear them.
+
+Optional final-mix loudness mastering is configured on the timeline:
+
+```js
+timeline.audioMastering = {
+  integratedLoudnessLUFS: -16,
+  truePeakDBTP: -1.5,
+  loudnessRangeLU: 11,
+  equalizer: [{ frequencyHz: 120, gainDB: 2, q: 1 }],
+  limiter: { limitDBFS: -1, attackMs: 5, releaseMs: 80 },
+  channelLayout: 'stereo',
+};
+```
+
+Defaults are -16 LUFS, -1.5 dBTP, and 11 LU. The renderer analyzes the final
+mix and uses two-pass FFmpeg `loudnorm` when the measurements are finite;
+unmeasurable non-silent audio falls back to single-pass dynamic normalization.
+Fully silent audio is re-encoded without loudness filtering because it has no
+measurable level to normalize. Before replacing the unmastered render, the
+encoded output is checked for duration, dimensions, and audio presence. GIF
+output cannot be mastered because GIF has
+no audio stream. Accepted ranges are -70 to -5 LUFS, -9 to 0 dBTP, and 1 to
+50 LU, respectively.
+Equalizer bands accept 20–20000 Hz, ±18 dB, and Q values from 0.1 to 10 (up to
+10 bands). The optional limiter accepts a -20 to 0 dBFS ceiling, 0.1–80 ms
+attack, and 10–1000 ms release. Equalization is applied before loudness analysis
+and normalization; the limiter runs at the end of the final mix chain. These
+controls need listening review against varied real material before mix presets
+can be recommended.
+`channelLayout` can request a mono or stereo final mix; the encoded channel count
+is checked before the mastered render replaces its input. Use the reviewable
+`set-audio-mastering` edit operation or
+`setTimelineAudioMastering(timeline, settings)` API to replace settings; pass
+`null` to clear mastering.
+
+Silence and repeated-word detection produce proposals only. Review and save the
+approved cuts in the versioned EDL format before applying them. Source media,
+transcripts, EDLs, and render outputs are kept separate; commands refuse to
+overwrite existing outputs.
+
+The CLI and JavaScript package exports are the engine interface. Editing agents,
+plugins, and creator-facing workflows can be built as separate consumers. See
+[`docs/architecture.md`](architecture.md) for contracts and runtime
+requirements, and [`docs/handoff.md`](handoff.md) for the full project
+context, validation state, and consolidated remaining-work checklist.
+
+## OpenTimelineIO interchange
+
+The optional OTIO bridge imports and exports standard external-media clips and
+gaps. Install the pinned Python adapter, then use a project timeline:
+
+```powershell
+python -m pip install -r requirements-otio.txt
+node src/cli.mjs timeline export-otio video-projects/my-edit timeline.json review.otio
+node src/cli.mjs timeline import-otio video-projects/my-edit edit.otio imported-timeline.json
+```
+
+The bridge uses the maintained OpenTimelineIO Python library; the Node.js API
+and other Engine features work without it. OTIO files reference media by path
+and do not embed media. The profile supports video/audio tracks, nested track
+stacks and nested compositions inside tracks flattened into ordered Engine
+tracks, cuts, gaps, root-stack markers, standard `SMPTE_Dissolve` transitions
+on import, track enabled state, and project duration including trailing gaps.
+Engine track lock and solo state are stored in the namespaced metadata; OTIO has
+no portable track-lock state. Imported dissolves become overlapping clips with
+video opacity fades or audio crossfades. Constant-rate retiming uses OTIO's
+`LinearTimeWarp`; imported clip duration is calculated from the source span and
+playback rate. Variable speed ramps and retimed crossfades remain unsupported.
+Import applies a trimmed track's source range to its clips and gaps; it rejects
+trims that partially cut transitions. Trimmed stacks are applied to direct tracks;
+nested or combined stack/track trims remain unsupported. Import also rejects
+custom transition types, other overlaps, third-party effects, nested-composition
+trims combined with parent-track trims, and remote media references. Clip enabled
+state is retained on import and export. Export converts explicitly faded two-clip overlaps into standard
+`SMPTE_Dissolve` transitions. Unmarked or chained overlaps are rejected rather
+than silently reinterpreted. Standalone fades, clip-edge transitions, clip
+settings, track-level audio effects and automation, and overlay tracks are
+retained in namespaced metadata for Engine round trips. Crossfade participants
+with additional Engine-only clip settings are rejected because splitting those
+clips would change the settings' timing or scope.
+Crossfade offsets and source ranges are derived from the overlapping Engine
+clips.
+Standard OTIO playback still represents only the interoperable subset; other
+editors may ignore or remove Engine metadata, and may not reproduce those
+settings when rendering.
+
+Run `npm run doctor` or `node src/cli.mjs capabilities` to check whether the
+selected Python environment has OpenTimelineIO and its `otio_json` adapter.
+Set `AIVE_OTIO_PYTHON` to the Python command for a separate environment when
+needed; the JavaScript capability API accepts the same override as `otioPython`.