pymotion-studio 1.0.1__tar.gz

pymotion_studio-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+env:
+  SYSTEM_DEPS: ffmpeg libcairo2-dev pkg-config libfreetype6-dev libharfbuzz-dev fonts-liberation
+
+jobs:
+  lint:
+    name: Lint & Type Check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y $SYSTEM_DEPS
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Ruff format check
+        run: ruff format --check pymotion/ tests/
+      - name: Ruff lint
+        run: ruff check pymotion/ tests/
+      - name: Mypy strict
+        run: mypy --strict pymotion/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y $SYSTEM_DEPS
+      - name: Install Python dependencies
+        run: pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest --cov=pymotion --cov-report=xml --cov-fail-under=80 -v
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml
+
+  security:
+    name: Security Audit
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y $SYSTEM_DEPS
+      - name: Install dependencies
+        run: |
+          pip install pip-audit
+          pip install -e .
+      - name: pip-audit
+        run: pip-audit

pymotion_studio-1.0.1/.github/workflows/publish.yml

@@ -0,0 +1,44 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  build:
+    name: Build Distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/pymotion-studio
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

pymotion_studio-1.0.1/.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Extract changelog for this version
+        id: changelog
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          # Extract section between this version header and the next
+          awk "/^## \[${TAG}\]/{found=1; next} /^## \[/{if(found) exit} found{print}" CHANGELOG.md > release_notes.md
+          echo "Release notes:"
+          cat release_notes.md
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release_notes.md
+          generate_release_notes: false

pymotion_studio-1.0.1/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+eggs/
+*.whl
+
+# Virtual environments
+.env
+.venv/
+venv/
+ENV/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# Type checking
+.mypy_cache/
+
+# Linting
+.ruff_cache/
+
+# Testing
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+*.cover
+.pytest_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Build artifacts / rendered output
+*.mp4
+*.mov
+*.webm
+*.gif
+*.avi
+test_output.*
+
+# Docs build
+site/
+
+# Example output (generated by running examples)
+examples/output/
+
+# Internal project documents (not part of the distributed package)
+PYMOTION_STATE.md
+PyMotion_PRD.md
+PyMotion_Framework_Paper.docx

pymotion_studio-1.0.1/CHANGELOG.md

@@ -0,0 +1,142 @@
+# 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

pymotion_studio-1.0.1/Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.12-slim
+
+# System dependencies for Cairo, FreeType, and FFmpeg
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends \
+        ffmpeg \
+        libcairo2-dev \
+        pkg-config \
+        libfreetype6-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy project files and install
+COPY . .
+RUN pip install --no-cache-dir -e .
+
+ENTRYPOINT ["pymotion"]

pymotion_studio-1.0.1/LICENSE

@@ -0,0 +1,95 @@
+PyMotion Source Available License
+Version 1.0, March 2026
+
+Copyright (c) 2026 Ohswedd. All rights reserved.
+
+1. DEFINITIONS
+
+   "Software" means the PyMotion library source code, documentation, and
+   associated files in this repository.
+
+   "You" means any individual or legal entity exercising permissions granted
+   by this License.
+
+   "Derivative Work" means any work that is based on or incorporates the
+   Software, including modifications, translations, adaptations, or
+   extensions of the Software's source code.
+
+   "Application" means any software product, service, or system that uses
+   the Software as a dependency, library, or component — but is not itself
+   a distribution of the Software.
+
+2. PERMITTED USES
+
+   Subject to the conditions below, You are granted a non-exclusive,
+   worldwide, royalty-free right to:
+
+   a) USE the Software in any project, including commercial Applications.
+      You may import, call, and depend on the Software in products you
+      build and sell.
+
+   b) FORK and MODIFY the Software for your own internal use, including
+      bug fixes, performance improvements, and feature additions.
+
+   c) CONTRIBUTE modifications back to the original repository via pull
+      requests or patches, under this same License.
+
+   d) STUDY the Software's source code for educational, research, or
+      reference purposes.
+
+3. RESTRICTIONS
+
+   You may NOT:
+
+   a) REDISTRIBUTE the Software, in whole or in substantial part, as a
+      standalone library, package, framework, or product — whether in
+      original or modified form, and whether for free or for a fee.
+
+   b) PUBLISH, UPLOAD, or DISTRIBUTE the Software (or a Derivative Work
+      of the Software) to any package registry, marketplace, app store,
+      or distribution channel as a library or framework.
+
+   c) SELL, LICENSE, SUBLICENSE, or otherwise commercially exploit the
+      Software itself as a product. This includes offering the Software
+      as a paid library, a SaaS wrapper around its core functionality, or
+      a rebranded/white-labeled distribution.
+
+   d) REMOVE or ALTER this license notice, copyright notice, or
+      attribution from any copy of the Software.
+
+4. CONTRIBUTIONS
+
+   By submitting a contribution (pull request, patch, issue, or other
+   material) to the official repository, You grant the copyright holder a
+   perpetual, worldwide, royalty-free, irrevocable license to use,
+   reproduce, modify, distribute, and sublicense your contribution as part
+   of the Software under this License or any future license version.
+
+5. CLARIFICATIONS
+
+   - Using PyMotion as a dependency in your commercial application (e.g.,
+     importing it in a video rendering service you sell) is PERMITTED.
+   - Forking the repository to fix a bug for your own project is PERMITTED.
+   - Publishing a modified version of PyMotion to PyPI, npm, or any
+     registry under any name is NOT PERMITTED.
+   - Copying substantial portions of the Software into another library
+     that serves the same purpose is NOT PERMITTED.
+   - Referencing small code snippets (< 50 lines) for educational
+     purposes with attribution is PERMITTED.
+
+6. NO WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+   OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+   IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES
+   OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+   ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+   OTHER DEALINGS IN THE SOFTWARE.
+
+7. TERMINATION
+
+   This License and the rights granted hereunder will terminate
+   automatically if You fail to comply with any of its terms. Upon
+   termination, You must cease all use and destroy all copies of the
+   Software in your possession.

pymotion_studio-1.0.1/Makefile

@@ -0,0 +1,19 @@
+.PHONY: lint test render clean format
+
+lint: format
+	ruff check pymotion/ tests/
+	mypy --strict pymotion/
+
+format:
+	ruff format pymotion/ tests/
+
+test:
+	pytest -v
+
+render:
+	python examples/01_real_estate_tour.py
+
+clean:
+	rm -rf __pycache__ .mypy_cache .ruff_cache htmlcov dist build *.egg-info .pytest_cache .coverage
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type f -name "*.pyc" -delete 2>/dev/null || true