streamingle-unity-utilities/CameraAI~/CHANGELOG.md

# Changelog

## 0.4.8 - 2026-08-09

- Replaced the unstable frame-local aim controller with a causal, feed-forward
  angular-velocity path. Static targets now settle without a left/right limit
  cycle, legal 45/80-degree-per-second pans keep their entry velocity, and
  abrupt changes are bounded to 90 deg/s, 360 deg/s^2, and 7,200 deg/s^3.
- Added C2 position resampling, speed-adaptive C2 distance transitions, and a
  final distance/step audit after every trajectory transform. The final
  candidate gate now fails closed on missing data and checks translation jerk,
  screen-space p99 and one-frame impulses, and the actual post-clamp step.
- Calibrated the new dynamics policy against 1,381 runtime-eligible authored
  shots. The 600 m/s^3 translation maximum applies only to final generated
  candidates; expressive authored wide/dolly templates remain available for
  retargeting and soft ranking.
- Replaced Unity's piecewise-linear reduced position curves with velocity-aware
  C1 Hermite curves. Every reduced shot is audited at source times and
  midpoints for position error, local speed/acceleration/jerk regressions, and
  meaningful-motion retention; unsafe reductions automatically fall back to
  exact position keys for that shot only.
- Rebuilt the self-contained Windows worker as 0.1.4 with the trajectory module
  and build-identity snapshot included. The frozen worker doctor and 196-test
  build suite pass without requiring Python on the artist machine.
- On the 12,269-frame Arisa regression input, all 56 shots passed visibility,
  facing, aim, distance, step, screen-dynamics, and cut-transition checks.
  Worst translation jerk improved from 641.61 to 247.81 m/s^3 and worst
  angular jerk from 30,294.84 to 7,146.35 deg/s^3; uncached generation improved
  from about 124 seconds to 107 seconds.
- Unity compiled with zero Camera AI errors and the package EditMode suite
  passed 121/121. The Balanced importer retained simplified C1 curves for 41
  shots and safely selected exact position keys for the 15 shots whose reduced
  curves exceeded the local motion or 5 mm error contract.

## 0.4.7 - 2026-08-09

- Fixed the incomplete 6D-to-quaternion conversion that replaced every
  non-positive-trace rotation with a fixed 180-degree roll. This had rejected
  almost all authored front-camera templates and biased generation toward the
  actor's back.
- Added torso-derived front-facing safety to candidate selection, including
  median alignment, severe-rear frame ratio, and longest consecutive rear run.
- Made missing or non-finite front-facing audit data fail closed and improved
  all-candidates-rejected diagnostics with per-gate counts.
- Invalidated both preparation and candidate caches because corrected template
  rotations affect both stages.
- Rebuilt self-contained Windows worker 0.1.3 with pinned, verified runtime
  dependencies. The focused worker suite passes 148 tests.
- On the 12,269-frame Arisa regression input, front-safety failures improved
  from 49/56 shots to 0/56; severe rear-facing frames fell from 72.64% to
  0.18%, with a maximum per-shot run of 15 frames.

## 0.4.2 - 2026-08-03

- Fixed Unity assembly exclusion caused by duplicate legacy/package script GUIDs.
- Added YAMO-calibrated, angle-aware camera translation kinematics: concentrated
  direction changes slow before the turn and accelerate afterward, while smooth
  arcs and naturally eased motion remain untouched.
- Applied the kinematic pass exactly once per shot: Orbit reversals are measured
  in subject-relative space and other motion families in final world space.
- Made the braking window C2-continuous at its outer seams, removed cumulative-
  minimum speed kinks, and rejected any rewrite that introduces an acceleration
  or jerk regression instead of chasing newly-created seam events.
- Added rendered end-to-start transition scoring against the actually selected
  adjacent cameras, including both neighbours during selected-shot regeneration.
- Hard-rejected only perceptible near-duplicate jump cuts and unbridged extreme
  axis crossings; screen jumps and opposing motion remain soft ranking signals.
- Preserved the braking envelope around 40-degree-or-greater direction changes
  when editable Unity animation curves are simplified.
- Bumped the packaged worker to 0.1.2 and invalidated stale candidate caches for
  the new transition and trajectory policies.

## 0.4.1 - 2026-08-03

- Added the UXML/USS camera-generation workflow with a compact narrow-dock
  layout, full preflight readiness, result-only refinement/save stages, and a
  compact status footer.
- Fixed stale Unity-project folders being mistaken for a complete CW-AI data
  library; the window now validates the training index and cut model and
  automatically repairs the path to a complete sibling library.
- Prepared the package for the Streamingle Utilities Git distribution with the
  frozen Windows x64 `CWCameraWorker` folder under `Tools~`; artist machines no
  longer need a separate Python installation.
- Moved generated preparation and candidate caches out of the reference-data
  library and into the Unity project's writable `Library/CWAI` directory. An
  optional `CWAI_CACHE_ROOT` environment variable can override that location.

## 0.4.0 - 2026-08-02

- Replaced the Unity-native generation backends with the packaged
  `CWCameraWorker.exe` high-quality pipeline.
- Added `generate`, `prepare-cache`, `version --json`, and `doctor` CLI
  contracts with structured progress events and cooperative cancellation.
- Split generation-time data preparation from training-only dependencies; the
  verified Windows onedir worker is 316.54 MiB and requires no separate
  Python installation on artist workstations.
- Kept full-Timeline and selected-shot generation, per-camera AnimationClips,
  curve simplification, provenance validation, and cut-correction capture in
  the Unity Editor workflow.
- Removed the portable native runtime, exporter, generator implementation, and
  their dedicated tests. Existing generated results and parity reports remain
  importable historical artifacts.

## 0.3.5 - 2026-08-02

- Added the Unity-native Portable HQ v1 path: authored trajectory retargeting,
  global cut dynamic programming, random-forest sequence-beam planning, and
  multi-candidate safety/quality selection now run as one deterministic
  generation pipeline.
- Materialized `unity_native_portable_hq_v1_arisa_final_pass1` as a 60-shot,
  12,269-frame, 60 FPS Timeline. It contains 60 independent cameras,
  Animators, Animation Tracks, and AnimationClips, with zero runtime
  LookAt/Tracking bindings and zero template fallbacks.
- Preserved hard cuts with zero ease and an intentional 1 microsecond boundary
  guard. The final run completed in 17.701 seconds; the isolated EditMode suite
  passed 161/161.
- Verified byte-identical output for the same Seed. A different Seed changed
  the selected authored template in 35% of shots and materially changed 32.8%
  of frames. Real beat/mel features and the deduplicated weighted duration
  prior remain explicit parity gaps.
- Added the experimental `작업자 카메라 기반 (Unity 내장 · 실험)` backend.
  It loads a portable JSON/float32 runtime bundle containing 1,381 authored
  camera templates and retargets them entirely inside Unity without requiring
  Python at generation time.
- Added a content-addressed, hash-validated runtime-bundle exporter and Unity
  loader. The original preparation cache is trusted only during explicit
  export; the published runtime bundle contains no pickle or executable
  serialization.
- Verified the initial Unity smoke run on the 12,269-frame input: 51 shots,
  51 authored-template shots, zero template fallbacks, and 51 independent
  camera Animators. At that checkpoint the path did not yet include the
  high-quality cut planner, candidate retarget/re-score, or complete
  composition pass; Portable HQ v1 above supersedes that limitation.
- Added an explicit Unity cut-correction snapshot workflow. It compares the
  provenance-bound generated `shots.json` with edited hard-cut clip starts and
  records ordered `keep/move/add/delete` operations without modifying or saving
  the Scene or Timeline asset.
- Added causal three-shot cut context (duration, music/motion energy, beat
  proximity), schema-v2 closed-loop ranker training, deterministic bounded
  history-beam planning, v1 artifact rejection, and complete context trace
  provenance. The v2 model passes its no-model non-regression gate but does not
  yet replace the legacy cut path.
- Added the 60 FPS data-driven cut planner: broad music/motion candidates,
  duplicate-aware authored duration prior, exact-audio soft prior, portable
  listwise ranker, and deterministic global DAG optimization with trace output.
- Added high-quality full-generation cut-rhythm controls
  (Auto/Slow/Normal/Fast), while selected-shot regeneration continues to lock
  every existing cut.
- Added source-audio SHA-256 export so the generator can reuse approved timing
  evidence for the same recording without copying camera trajectories.
- Added a shape-preserving relative-trajectory velocity limiter. The final
  67-shot Arisa composite reduced within-shot position spikes over
  `0.15m/frame` from `12` to `0` (`0.17551m` max to `0.11991m`) while preserving
  visibility, cut boundaries, every non-selected shot, and baked-aim quality.
- Verified the final `12,269`-frame/67-shot/60 FPS preview in Unity with
  compile `0/0`, related EditMode `65/65`, and no new Console errors after
  Timeline import.
- Added true high-quality selected-shot generation with
  `--only-shot-index`/`--base-generation`, skipping full-sequence planning and
  preserving every non-selected camera frame, shot row, cut, and Unity clip.
- Added full-compatible materialized composites with base hashes and selected
  span provenance, plus a separate Seed-independent per-shot candidate cache.
- Advanced the next base and Seed only after successful Timeline import, and
  rejected incompatible Native/stale bases before launching Python.
- Added selected-shot ETA/cache reporting and regression coverage for paired
  CLI arguments, fail-closed base validation, exact preservation, and A -> B
  sequential regeneration; independent finite/coverage/person/aim/spike gates
  pass on the final Arisa composites.
- Hardened base loading with exact JSON integer/numeric contracts, pre-read
  payload byte-size checks, and direct non-reparse payload paths. Only
  `selected_shot_directives.json` is accepted as an output sidecar.
- Added best-effort transactional directory publication with validated staging,
  single-orphan-backup recovery, and fail-closed handling for ambiguous or
  malformed recovery state.
- Preserved the legacy selection string while adding authoritative
  `materializedShotSeedLineage` and an identical-base-hash reproducibility scope
  for mixed-Seed composites.
- Kept the archived Arisa `2.058s/1.293s` selected-shot benchmark and recorded a
  separate latest-user-base `2.489s/1.498s` result with `20/20` invariants.
  Final-source hit revalidation was `1.430752s` total (`0.0006751s` candidate
  retarget). Python is `215/215` with py_compile/Ruff passing; Unity EditMode is
  `59/59`, importer validation accepted `12,269` frames/52 shots/60 FPS, and
  compilation reported `0/0`.

## 0.3.4 - 2026-08-01

- Made Hybrid Seed deterministically select from camera candidates that pass
  person-safety checks and are visually distinct after final composition.
- Kept the same Seed reproducible and made adjacent Seeds select different
  candidates whenever a shot has at least two safe, distinct candidates.
- Limited variation candidates to a bounded score delta from the best safe
  camera and preserved the full legacy safety-rescue search when needed.
- Decoupled the Seed-selected output from the deterministic sequence context,
  preventing later shots from converging back to the same camera.
- Preserved explicit `static` direction and safety constraints; a shot may
  remain unchanged when only one safe, distinct candidate exists.
- Clarified in the generator UI that reapplying an existing result does not
  generate a new candidate and therefore does not use Seed.
- Distinguished full-result Seed state from a single regenerated camera, and
  no longer reports an applied Seed when Timeline import fails.

## 0.3.3 - 2026-08-01

- Added live generation stages, elapsed time, and a backend-specific ETA range
  that learns from completed timelines while keeping cache preparation separate.
- Bound every generated Cinemachine camera to its own `Animator`, Animation
  Track, and `.anim` asset so offsets and curves can be edited per camera.
- Initialized every per-camera Track Offset from its first generated pose so
  finite clips preserve world height instead of collapsing toward the floor.
- Added Timeline clip, animation asset, and Hierarchy camera selection for
  regenerating exactly one generated shot while preserving all other shots.
- Prevented automatically directed opening shots from becoming static unless
  the user explicitly requests a static shot or zero motion intensity.
- Made preview scope identifiers stable across script recompiles and Editor
  reloads so selected-camera regeneration keeps resolving the same preview.
- Removed each scoped preview asset folder atomically to prevent orphaned clips
  and duplicate-suffixed Timeline assets after repeated preview rebuilds.

## 0.3.2 - 2026-07-31

- Replaced the development-first generator layout with a Timeline-select and
  one-click generation workflow.
- Hid repository paths, Python, dataset IDs, seeds, caches, and manual import
  controls under an advanced foldout.
- Added localized optional direction controls and result-only per-camera
  regeneration/final-save actions.
- Added a short Korean menu path while retaining the legacy menu entry.
- Improved multi-song one-click selection by matching the chosen source
  Timeline to the freshly exported song manifest.
- Added a camera-free generation-input export for Timelines containing only
  character motion and audio, including frame-aligned RMS/onset features.
- Existing Cinemachine tracks are explicitly ignored during generation-input
  export; the simple workflow no longer exposes a “dataset song” selector.
- Allowed Hybrid generation targets outside the training index while keeping
  the indexed worker-camera reference library split- and leakage-guarded.

## 0.3.1 - 2026-07-31

- Fixed multi-song Hybrid selection by distinguishing 16-hex song IDs from names.
- Added explicit source `PlayableDirector` scoping for preview import, removal, and regeneration.
- Made Final scene copies own independent Timeline and animation assets.
- Made Native safety validation fail closed for missing/non-finite joints.
- Rebased non-zero source Timeline time samples while preserving provenance.
- Added complete Native seed, global direction, and directives provenance metadata.

## 0.3.0 - 2026-07-31

- Added Python-free `Native Fast` camera generation inside the Unity Editor.
- Added learned `Python Hybrid Quality` generation controls and per-shot JSON directions.
- Stabilized camera bodies with shot-fixed stage anchors and low-frequency follow.
- Added fail-closed character-envelope framing checks and safe distance fallback.
- Added per-camera animation clips and selected-shot regeneration with GUID preservation.
- Added Exact, Balanced, and Editable error-bounded curve simplification presets.
- Added a content-addressed Hybrid preparation-cache workflow shared across
  candidate seeds.
## 0.4.3

- Added a self-contained `RuntimeData~` reference bundle (263 prepared songs).
- The packaged worker auto-discovers the bundle; raw CW-AI source audio and a separate checkout are no longer required for generation.
- Generation caches remain project-local and writable.
## 0.4.4

- Automatically prefers bundled `RuntimeData~`, including Unity Git PackageCache installs, over stale serialized external roots.
## 0.4.5

- Rebuilt the frozen worker so portable prepared-template rotation conversion is included in the executable.
## 0.4.6

- Added a soft front-facing preference so safe candidates do not systematically place the actor's back toward the camera.
- Bumped candidate cache logic version to invalidate stale orientation candidates.