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

# Changelog

## 0.4.14 - 2026-08-17

- Resolved the configured CinemachineBrain from camera tracks on descendant
  PlayableDirectors, including Cinemachine 3 `OutputCamera` setups, so
  orchestration Timelines can import AI results without duplicating camera
  tracks on the parent Timeline.
- Made AI preview cloning inactive from construction and disconnected cloned
  authored Cinemachine tracks and virtual cameras before playback. This
  prevents the authored Motion Timeline from competing with the generated
  Shot tracks while preserving the original scene hierarchy. This is an
  Editor-only hotfix; the bundled Windows worker remains 0.1.9.

## 0.4.13 - 2026-08-16

- Enforced radial distance bounds on the actual float32 camera coordinates,
  preventing oblique wide-shot plateaus from drifting a few micrometres past
  their authored safety annulus during publication.
- Made a final distance postcondition failure reject only that camera
  candidate while preserving fail-closed handling for real generator
  invariants. Rebuilt the self-contained Windows worker as 0.1.9.

## 0.4.12 - 2026-08-16

- Made packaged catalog freshness checks portable across Windows Git
  checkouts: an exact raw hash remains authoritative, while a byte-for-byte
  equivalent CRLF checkout is accepted only when LF normalization reproduces
  the indexed hash. Content changes and Git LFS pointer files still fail
  closed.
- Extended `CWCameraWorker doctor` to validate the packaged training index
  against its catalog, and pinned the release catalog and training index to LF
  line endings. Rebuilt the self-contained Windows worker as 0.1.8.

## 0.4.11 - 2026-08-10

- Integrated the verified YAMO dataset refresh without replacing the packaged
  production reference library or its default models. Dataset revisions now
  retain distinct runtime identities, provenance, and subject-targeting
  evidence instead of colliding with their base recordings.
- Added fail-closed audio-aligned frame-mask handling across trajectory,
  sequence, cut-ranker, and cut-reference consumers. Incomplete shots and
  censored audio tails are excluded rather than silently becoming training or
  authored-cut supervision.
- Hardened exact-audio cut references so independently aligned sources cannot
  be unioned into spurious double cuts, and expanded transition-only candidate
  search only when the normal safe pool cannot make both neighbouring edits.
  A bounded all-fail transition search now stops generation instead of
  publishing a known-bad edge.
- Rebuilt the self-contained Windows worker as 0.1.7 from the checkpointed
  source with the pinned Python 3.12.13 build environment. The bundled
  RuntimeData~ library remains the established production baseline; research
  candidate models and indexes are deliberately not bundled by default.

## 0.4.10 - 2026-08-09

- Replaced the loose first-passing angular limiter with an authored-target
  minimum-jerk selector. The Arisa regression output keeps all 69 music-shaped
  cuts while angular jerk P90 falls from about 852 to 235 deg/s^3 and P99 from
  about 4,455 to 912 deg/s^3.
- Made final float32 quaternion tracking authoritative, removed shot-entry
  pre-echo, added a C2 semantic-focus dead zone, and recorded explicit angular
  and dynamics fallback shot indices.
- Hardened translation rewrites and the final radial clamp so a repair cannot
  hide or introduce a local acceleration/jerk seam. Intentional dolly and orbit
  motion remains available.
- Baked position and quaternion animation as audited not-a-knot C2 curves
  instead of piecewise-linear or C1-only curves. The importer verifies C2 seams,
  240/480 Hz motion, quaternion continuity, and the post-Unity clip curves, with
  adaptive key refinement and fail-closed dense C2 fallback.
- Resolved the active package through `FileUtil.GetPhysicalPath` so serialized
  paths to an older `Library/PackageCache` revision can no longer keep running a
  stale worker after a package update. Valid explicit external paths are kept.
- Rebuilt the self-contained Windows worker as 0.1.6 with Python 3.12.13. The
  clean 647-file build passes `doctor`; camera, time, and shot outputs are
  byte-identical to source generation for the 12,269-frame regression input.

## 0.4.9 - 2026-08-09

- Restored the authored same-audio cut prior for production generation inputs
  without admitting the target camera trajectory into the planner or template
  library. The Arisa regression song now recovers its music-shaped 69-shot
  cadence, while a silent-tail fallback cut is removed.
- Replaced performer-screen-motion penalties with stabilized residual framing
  diagnostics so expressive dance motion no longer suppresses orbit, drift,
  lead-room, or authored camera movement. Hard person, distance, step, aim, and
  dynamics gates remain fail-closed.
- Calibrated front-facing safety once over the full performance. Choreography
  turns can keep a stable stage-front camera without rewarding side or rear
  placement, while true 180-degree rear candidates remain rejected.
- Added a versioned selection-safety contract for selected-shot regeneration,
  verified exact-audio reference hashes across bundled and project data roots,
  and deterministically deduplicated identical packaged reference copies.
- Added a final-world post-clamp kinematic repair and hard audit. Distance
  clamping can no longer reintroduce an unbraked reversal after the YAMO
  deceleration/acceleration pass; all 69 regression shots pass the final
  post-clamp contract and Shot 66 has zero remaining abrupt reversal events.
- Rebuilt the self-contained Windows worker as 0.1.5 with Python 3.12.13 in a
  disposable, exact-pinned environment with one-thread scientific-library
  limits, artifact size/file-count guards, and a distribution provenance
  manifest. The clean worker contains 647 files (267,608,825 bytes), passes
  `doctor`, and is byte-identical to source generation for camera, time, and
  shot outputs.

## 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.6

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

## 0.4.5

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

## 0.4.4

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

## 0.4.3

- Added a self-contained `RuntimeData~` reference bundle containing 263
  prepared songs.
- Made the packaged worker auto-discover the bundle; raw source audio and a
  separate CW-AI checkout are no longer required for generation.
- Kept generation caches project-local and writable.

## 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.