# Changelog

All notable changes to PyMotion are documented here.

## [1.0.1] — 2026-03-10

### Fixed
- **Critical: compositor alpha cache memory aliasing** — `_alpha_cache` in `compositor.py`
  used numpy memory pointers (`ctypes.data`) as cache keys. When numpy reused memory
  addresses for new frame allocations, the cache returned stale alpha info from previous
  frames, causing the compositor to randomly skip text and clip layers (visible as
  flickering/disappearing text in rendered videos). Fixed by clearing the cache at the
  start of each `composite_layers()` call.
- **Text animation reveal-mask architecture** — Rewrote Typewriter, WordByWord, and
  LetterByLetter presets to use a cached full-text render with a horizontal alpha reveal
  mask. Already-revealed pixels are now bit-for-bit identical across frames. CountUp and
  CountDown use quintic ease-out with frame-stepping (`step_frames=3`) for smooth
  deceleration.

### Changed
- **H.264 encoding quality** — CRF 18 → 10, preset `faster` → `medium` for all H.264
  presets. Added `no-dct-decimate` and `no-fast-pskip` x264 params to eliminate temporal
  text shimmer. Added Lanczos chroma scaling (`-sws_flags lanczos+accurate_rnd+full_chroma_int`)
  for better colored text quality during RGB → YUV420p conversion.
- **H.265 encoding quality** — CRF 22 → 16, preset `faster` → `medium`.
- **Instagram/TikTok presets** — Added `-tune animation` for better text/graphics quality.
- **FreeType text renderer** — Replaced block-character fallback with proper FreeType
  glyph rendering in `_render_text_simple`. Added glyph cache and character position
  measurement for reveal-mask animations.

### Improved
- **Examples rewritten** — All 5 example scripts (`01_real_estate_tour` through
  `05_educational_explainer`) rewritten as complete, production-ready runnable demos
  showcasing real-world niches (real estate, tech review, fitness, restaurant, education).
  Each uses multiple PyMotion features: ImageClip, TextClip, ShapeClip, GradientClip,
  animated text, particles, blend modes, and multi-track composition.
- **Stock assets** — Added `download_assets.py` script and 19 stock image/audio assets
  for the example scripts.

## [1.0.0] — 2026-03-09

### Added
- Complete PRD §8.2 public API: all symbols importable from `import pymotion`
- `Silence` helper for creating silent audio placeholders
- `animate()` shorthand for two-keyframe animations
- `Align` enum for text/element alignment (13 values)
- Audio effects: `Reverb`, `Delay`, `PitchShift`, `NoiseReduction`, `LowPassFilter`, `HighPassFilter`
- 3D exports: `Scene3DClip`, `Scene3D`, `Camera`, `PointLight`, `DirectionalLight`, `SpotLight`, `AmbientLight`, `HDRIEnvironment`, `PBRMaterial`
- Particle exports: `ParticleSystem`, `Emitter`, `Sparkles`, `Confetti`, `Fire`, `Smoke`, `Rain`, `Stars`
- `ScrambleText` alias for `Scramble` animated text
- 37 new unit tests for v1.0 API surface

### Changed
- Version bumped to 1.0.0 (stable release)
- `__init__.py` docstring updated to "v1.0"

## [0.9.0-rc] — 2026-03-09

### Added
- `PyMotionConfig` global configuration (network access, cache size, file limits)
- ACES, Reinhard, and Filmic tone mapping operators
- `pymotion doctor` CLI command for checking system dependencies
- Variable font full axis support (ital, opsz, custom axes)
- Jupyter integration: `export_frame_inline()` and `preview_widget()`
- MkDocs documentation site with API reference and 5 guides
- 10 example scripts
- Dockerfile for containerized usage
- README with install, quickstart, feature matrix
- Performance regression test infrastructure

### Changed
- Asset cache size now configurable via `PyMotionConfig.cache_max_bytes`
- Color pipeline supports tone mapping parameter

## [0.4.0-beta] — 2026-03-09

### Added
- All 39 built-in transitions (19 new: ZoomBlur, Glitch, FilmBurn, etc.)
- Complete visual effects: MotionBlur, FilmGrain, Sharpen, ChromaticAberration, Glow, Bloom, LensFlare
- Color effects: Brightness, Contrast, Saturation, HSL, ColorBalance, Curves, LUT, SplitToning, BleachBypass
- Distortion effects: WaveWarp, Ripple, Twirl, PerspectiveWarp, Fisheye
- Light effects: LensFlare, GodRays, NeonGlow, LightLeak
- Particle presets: Stars, Dust, Explosion, Bubbles (9 total)
- 9 animated text presets (Typewriter, WordByWord, etc.)
- Variable font support (weight, width, slant axes)
- Google Fonts download with httpx and domain allowlist
- Volume keyframe automation and pan automation
- Waveform-to-keyframe converter
- Template ABC with field validation
- Frame sequence export (PNG/EXR)
- All 15 export presets
- Frame cache for static layers
- All 8 blend modes (Multiply, Screen, Overlay, etc.)
- CLI benchmark, validate, new commands
- pip-audit in CI

## [0.3.0-beta] — 2026-03-09

### Added
- 3D rendering backend (ModernGL headless, PBR shaders, OBJ/GLTF loading)
- SSAO, Bloom, Depth of Field post-FX
- ACES/Filmic/Reinhard tone mapping (3D backend)
- Audio DSP effects (EQ, Compressor, Limiter via pedalboard)
- Beat detection, onset detection, waveform extraction (librosa)
- Sidechain compression
- Particle system with vectorized NumPy updates
- 5 particle presets (Sparkles, Confetti, Fire, Smoke, Rain)
- Color pipeline with .cube LUT support and trilinear interpolation
- Color grading (lift/gamma/gain/saturation)
- Hot-reload preview server (asyncio + aiohttp + WebSocket)
- Parallel frame rendering (multiprocessing)

## [0.2.0-alpha] — 2026-03-09

### Added
- FontLoader with system font discovery and LRU cache
- GlyphRenderer with FreeType and HarfBuzz integration
- TextClip with multiline word-wrap, alignment, stroke, shadow
- VideoClip (FFmpeg decode, trim, loop, speed, reverse)
- GradientClip (linear, radial, conic)
- Complete easing library (30+ functions, spring, cubic bezier, steps)
- Color interpolation via OKLCH
- 20 transitions (Fade, CrossDissolve, Slide, Push, Cover, Reveal, Zoom)
- AudioMixer with add, set_volume, render
- AudioClip with trim, fade, volume, loop
- 8 export presets
- CLI preview command (basic)

## [0.1.0-alpha] — 2026-03-09

### Added
- Core architecture: Composition, Track, Clip base class
- ColorClip, ImageClip, ShapeClip
- Keyframe animation system with interpolation
- 2D rendering backend (Cairo)
- Compositor with alpha blending
- FFmpeg encoder with subprocess (shell=False)
- GaussianBlur, Vignette effects
- Security validators (path, color, asset magic, text sanitize)
- CLI render and export-frame commands
- Asset loader with LRU cache
- structlog-based logging
