framerudiments 0.1.0__tar.gz

framerudiments-0.1.0/AGENTS.md

@@ -0,0 +1,16 @@
+# FrameRudiments development
+
+Read README.md, docs/project-format.md and docs/extraction.md first. Preserve
+source audio/clock identity and separation of technical QA from perceptual
+approval. Use released DanceRudiments APIs and saved StemLab outputs; do not
+copy movement definitions or DSP. Keep creative scene decisions in adapters.
+
+Update README and relevant docs with feature changes. Add focused regression
+coverage, run ruff and pytest with FFmpeg/font integration enabled, build wheel
+and sdist, and smoke-test the installed wheel before a release. Keep credentials,
+private media, song text, local paths and campaign evidence out of distributions.
+Respect immutable tags, public deployment gates and explicit name ownership.
+Submit focused improvements to https://github.com/kieransimkin/FrameRudiments/pulls.
+Validate exact-head CI and immutable matching releases; do not rewrite tags or
+assets. GitHub and PyPI publication are separately verified states. Website:
+https://kieransimkin.co.uk/danceflow/.

framerudiments-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kieran Simkin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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.

framerudiments-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md LICENSE AGENTS.md
+recursive-include docs *.md
+recursive-include tests *.py

framerudiments-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: framerudiments
+Version: 0.1.0
+Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
+Author: Kieran Simkin
+License-Expression: MIT
+Project-URL: Homepage, https://kieransimkin.co.uk/danceflow/
+Project-URL: Repository, https://github.com/kieransimkin/FrameRudiments
+Project-URL: Issues, https://github.com/kieransimkin/FrameRudiments/issues
+Project-URL: Documentation, https://github.com/kieransimkin/FrameRudiments#readme
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow>=10
+Requires-Dist: dancerudiments<0.4,>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# FrameRudiments
+
+FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
+from one traceable timeline. It is the offline Python renderer in the
+[DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
+
+It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
+the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
+Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,
+scene layouts and creative decisions belong in project files or Python scene
+hooks. Historical render scripts and approved outputs remain preserved.
+
+## Install and run
+
+Python 3.11+ and FFmpeg with libx264/AAC are required. Install the package into
+its own virtual environment. Published packages use `python -m pip install framerudiments`;
+from a source checkout use `python -m pip install .`:
+
+```sh
+python -m pip install .
+framerudiments --version
+framerudiments demo demo --font /path/to/a/font.ttf
+framerudiments plan demo/project.json --output demo-plan.json
+framerudiments preflight demo/project.json --output preflight --ffmpeg /path/to/ffmpeg
+framerudiments render demo/project.json --output render --ffmpeg /path/to/ffmpeg
+```
+
+Use a new output directory each time. `--ffprobe` overrides FFmpeg's sibling
+ffprobe. Environment alternatives are `FRAMERUDIMENTS_FFMPEG` and
+`FRAMERUDIMENTS_FFPROBE`. Fonts are explicit hashed inputs; no platform-specific
+font or FFmpeg location is hardcoded into the engine. The synthetic demo creates
+its own tone, sprite, LRC, CUE and four-dimensional recording.
+
+## Capabilities
+
+* Portrait, landscape and square frame-addressed Pillow composition, at native
+  constant 60 fps by default. Other frame rates require a recorded reason.
+* Sample-addressed source excerpts and exact repetitions; no time-stretch,
+  resampling, normalization or remix. The master is never changed. Short
+  derivatives default to 120 ms quarter-sine endpoint fades; set
+  `audio.fade_seconds: 0` to preserve an approved raw seam. Visualisers and
+  Canvas-style projects default to no fades. AAC encoding is lossy.
+* One caption/cue ledger for actual raster transitions, JSON, SRT and ASS.
+  Retains signed frame error, same-frame ordering, explicit clears, carry-in
+  lyrics and repeat boundaries. Accepts UTF-8 LRC with offsets/multiple stamps
+  and CD CUE INDEX 01 at 75 subframes/s. Section labels never become lyrics.
+* Canonical lyric text comparison, exact input hashes, inert text, bounded text
+  wrapping and fit-or-fail behavior. Optional previous/current/next captions
+  and exact-text-associated lyric artwork (planes, tablets, signs, etc.).
+* Native DanceRudiments catalogue sampling at integer pips; optional explicit
+  interpolation of adjacent native samples for legacy compositor parity.
+  Preserves the distinction between 64 pips/beat and 16 DanceMoves ticks/beat.
+* Saved StemLab beat grids, accepted `stemlab.loops.v1` selections, explicitly
+  selected `stemlab.dancerudiments.candidates.v1` matches, and native
+  `dancerudiments.recording` files. No model execution or copied DSP.
+  Match-window extrapolation needs an explicit choice. N-dimensional
+  recordings retain their own source clock and never wrap outside capture.
+* Transparent sprites, atlas cycles in musical ticks, cue/time-gated layers,
+  position/rotation/scale mappings with selectable axes, same-pose directional
+  trails, masks, background contain/cover and N-dimensional signed bars.
+  Independent composite motion channels preserve separate bounce/sway/tilt.
+  All transformed sprite alpha extents are checked against declared bounds
+  on every frame. Custom scene drawing has its own review obligations.
+* The existing seeded paper-glider flight model and connected-alpha sprite
+  cleaner, plus a general frame-addressed lyric-art entrance/hold/exit helper.
+  The flight model is stylized animation; it does not simulate real aerodynamics
+  or establish musical synchronization by itself.
+* H.264/yuv420p + AAC MP4 with fast start, full decoding, exact decoded frame
+  count and every decoded timestamp checked for CFR. Audio length, sample
+  rate and channel count are checked against the source. Includes encoded QA
+  stills, a poster, phone preview, input/output hashes, commands and logs.
+
+## Project format
+
+Start from `framerudiments demo` and replace its synthetic assets. Every file
+reference has `path` and `sha256`; paths are relative to the project JSON unless
+absolute. See [docs/project-format.md](docs/project-format.md) for all fields and
+[docs/extraction.md](docs/extraction.md) for source mechanisms and boundaries.
+
+```python
+from framerudiments import Project, render
+
+project = Project.load("release/project.json")
+
+def scene(image, context):
+    # Existing custom drawing consumes frame, source_seconds, output_seconds,
+    # beat, lyric and cue. Return a frame-sized RGBA image.
+    return image
+
+render(project, "release/new-render", scene=scene, ffmpeg="/path/to/ffmpeg")
+```
+
+Pin any assets used by a custom scene with `project.ref({"path": ..., "sha256": ...})`
+before rendering. The hook is supplied by trusted Python code, never imported
+or executed from a project JSON. Do not reproduce clock, sampling, caption,
+encode or verification loops in release adapters.
+
+## Evidence and limits
+
+`plan` is preparation, `preflight` checks all composed frames without encoding,
+and `render` produces **technical-QA passed; creative and attended listening
+review pending**. No command uploads, schedules or publishes anything.
+Automatic checks cannot establish sung-word accuracy, pleasant motion, a
+musical loop seam, platform preview acceptance, rights or public eligibility.
+Caption boxes are composition constraints, not current official platform
+safe-zone verification. Review the exact encoded file and destination preview.
+
+Constant-BPM and saved variable-grid clocks record their authority/status;
+an estimate never becomes artist confirmation. Beat grids extrapolate from
+their first/last interval outside their covered extent; constrain projects to
+supported intervals where that is unsuitable. A ranked match does not prove
+whole-song alignment. Recording source/axis provenance is retained; the author
+must select the correct master/stem association. No live WordPress timing,
+sensor or plugin configuration is changed by offline rendering.
+
+All text in `captions.ass` is a portable timing sidecar with neutral styling;
+the raster compositor remains the authority for the approved layout.
+
+## Development
+
+```sh
+python -m pip install -e '.[dev]'
+ruff check .
+pytest
+python -m build
+```
+
+Set `FRAMERUDIMENTS_TEST_FONT` and `FRAMERUDIMENTS_FFMPEG` to run all integration
+tests. Without them, corresponding checks report skipped. Tests cover native
+sampling, non-looping recordings, input identity, lyric clears, excerpt/repeat
+boundaries, text/alpha overflow and actual encoded portrait/landscape/square
+outputs. Use synthetic fixtures; never put songs, personal data or private
+analysis outputs into the source distribution.
+
+## Source, contribution and releases
+
+[Canonical repository](https://github.com/kieransimkin/FrameRudiments) ·
+[Python package](https://pypi.org/project/framerudiments/) ·
+[Issues and improvements](https://github.com/kieransimkin/FrameRudiments/issues)
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine. Improvements
+belong in focused pull requests to the canonical repository, with current README,
+meaningful tests and reproducible synthetic examples.
+
+The GitHub Actions CI runs the complete render suite on Linux and Windows with
+Python 3.11 and 3.13. The release workflow validates the immutable `v<version>` tag,
+re-runs tests, builds/checks wheel and source distribution, performs a clean wheel
+render and publishes exact checksum-labelled assets. It refuses to overwrite
+an existing GitHub release. The optional PyPI job uses the `pypi` environment and
+a separately configured trusted publisher; no API token is stored in this project.
+A GitHub release and a PyPI listing are separately verified outcomes.

framerudiments-0.1.0/README.md

@@ -0,0 +1,151 @@
+# FrameRudiments
+
+FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
+from one traceable timeline. It is the offline Python renderer in the
+[DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
+
+It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
+the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
+Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,
+scene layouts and creative decisions belong in project files or Python scene
+hooks. Historical render scripts and approved outputs remain preserved.
+
+## Install and run
+
+Python 3.11+ and FFmpeg with libx264/AAC are required. Install the package into
+its own virtual environment. Published packages use `python -m pip install framerudiments`;
+from a source checkout use `python -m pip install .`:
+
+```sh
+python -m pip install .
+framerudiments --version
+framerudiments demo demo --font /path/to/a/font.ttf
+framerudiments plan demo/project.json --output demo-plan.json
+framerudiments preflight demo/project.json --output preflight --ffmpeg /path/to/ffmpeg
+framerudiments render demo/project.json --output render --ffmpeg /path/to/ffmpeg
+```
+
+Use a new output directory each time. `--ffprobe` overrides FFmpeg's sibling
+ffprobe. Environment alternatives are `FRAMERUDIMENTS_FFMPEG` and
+`FRAMERUDIMENTS_FFPROBE`. Fonts are explicit hashed inputs; no platform-specific
+font or FFmpeg location is hardcoded into the engine. The synthetic demo creates
+its own tone, sprite, LRC, CUE and four-dimensional recording.
+
+## Capabilities
+
+* Portrait, landscape and square frame-addressed Pillow composition, at native
+  constant 60 fps by default. Other frame rates require a recorded reason.
+* Sample-addressed source excerpts and exact repetitions; no time-stretch,
+  resampling, normalization or remix. The master is never changed. Short
+  derivatives default to 120 ms quarter-sine endpoint fades; set
+  `audio.fade_seconds: 0` to preserve an approved raw seam. Visualisers and
+  Canvas-style projects default to no fades. AAC encoding is lossy.
+* One caption/cue ledger for actual raster transitions, JSON, SRT and ASS.
+  Retains signed frame error, same-frame ordering, explicit clears, carry-in
+  lyrics and repeat boundaries. Accepts UTF-8 LRC with offsets/multiple stamps
+  and CD CUE INDEX 01 at 75 subframes/s. Section labels never become lyrics.
+* Canonical lyric text comparison, exact input hashes, inert text, bounded text
+  wrapping and fit-or-fail behavior. Optional previous/current/next captions
+  and exact-text-associated lyric artwork (planes, tablets, signs, etc.).
+* Native DanceRudiments catalogue sampling at integer pips; optional explicit
+  interpolation of adjacent native samples for legacy compositor parity.
+  Preserves the distinction between 64 pips/beat and 16 DanceMoves ticks/beat.
+* Saved StemLab beat grids, accepted `stemlab.loops.v1` selections, explicitly
+  selected `stemlab.dancerudiments.candidates.v1` matches, and native
+  `dancerudiments.recording` files. No model execution or copied DSP.
+  Match-window extrapolation needs an explicit choice. N-dimensional
+  recordings retain their own source clock and never wrap outside capture.
+* Transparent sprites, atlas cycles in musical ticks, cue/time-gated layers,
+  position/rotation/scale mappings with selectable axes, same-pose directional
+  trails, masks, background contain/cover and N-dimensional signed bars.
+  Independent composite motion channels preserve separate bounce/sway/tilt.
+  All transformed sprite alpha extents are checked against declared bounds
+  on every frame. Custom scene drawing has its own review obligations.
+* The existing seeded paper-glider flight model and connected-alpha sprite
+  cleaner, plus a general frame-addressed lyric-art entrance/hold/exit helper.
+  The flight model is stylized animation; it does not simulate real aerodynamics
+  or establish musical synchronization by itself.
+* H.264/yuv420p + AAC MP4 with fast start, full decoding, exact decoded frame
+  count and every decoded timestamp checked for CFR. Audio length, sample
+  rate and channel count are checked against the source. Includes encoded QA
+  stills, a poster, phone preview, input/output hashes, commands and logs.
+
+## Project format
+
+Start from `framerudiments demo` and replace its synthetic assets. Every file
+reference has `path` and `sha256`; paths are relative to the project JSON unless
+absolute. See [docs/project-format.md](docs/project-format.md) for all fields and
+[docs/extraction.md](docs/extraction.md) for source mechanisms and boundaries.
+
+```python
+from framerudiments import Project, render
+
+project = Project.load("release/project.json")
+
+def scene(image, context):
+    # Existing custom drawing consumes frame, source_seconds, output_seconds,
+    # beat, lyric and cue. Return a frame-sized RGBA image.
+    return image
+
+render(project, "release/new-render", scene=scene, ffmpeg="/path/to/ffmpeg")
+```
+
+Pin any assets used by a custom scene with `project.ref({"path": ..., "sha256": ...})`
+before rendering. The hook is supplied by trusted Python code, never imported
+or executed from a project JSON. Do not reproduce clock, sampling, caption,
+encode or verification loops in release adapters.
+
+## Evidence and limits
+
+`plan` is preparation, `preflight` checks all composed frames without encoding,
+and `render` produces **technical-QA passed; creative and attended listening
+review pending**. No command uploads, schedules or publishes anything.
+Automatic checks cannot establish sung-word accuracy, pleasant motion, a
+musical loop seam, platform preview acceptance, rights or public eligibility.
+Caption boxes are composition constraints, not current official platform
+safe-zone verification. Review the exact encoded file and destination preview.
+
+Constant-BPM and saved variable-grid clocks record their authority/status;
+an estimate never becomes artist confirmation. Beat grids extrapolate from
+their first/last interval outside their covered extent; constrain projects to
+supported intervals where that is unsuitable. A ranked match does not prove
+whole-song alignment. Recording source/axis provenance is retained; the author
+must select the correct master/stem association. No live WordPress timing,
+sensor or plugin configuration is changed by offline rendering.
+
+All text in `captions.ass` is a portable timing sidecar with neutral styling;
+the raster compositor remains the authority for the approved layout.
+
+## Development
+
+```sh
+python -m pip install -e '.[dev]'
+ruff check .
+pytest
+python -m build
+```
+
+Set `FRAMERUDIMENTS_TEST_FONT` and `FRAMERUDIMENTS_FFMPEG` to run all integration
+tests. Without them, corresponding checks report skipped. Tests cover native
+sampling, non-looping recordings, input identity, lyric clears, excerpt/repeat
+boundaries, text/alpha overflow and actual encoded portrait/landscape/square
+outputs. Use synthetic fixtures; never put songs, personal data or private
+analysis outputs into the source distribution.
+
+## Source, contribution and releases
+
+[Canonical repository](https://github.com/kieransimkin/FrameRudiments) ·
+[Python package](https://pypi.org/project/framerudiments/) ·
+[Issues and improvements](https://github.com/kieransimkin/FrameRudiments/issues)
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) before changing the engine. Improvements
+belong in focused pull requests to the canonical repository, with current README,
+meaningful tests and reproducible synthetic examples.
+
+The GitHub Actions CI runs the complete render suite on Linux and Windows with
+Python 3.11 and 3.13. The release workflow validates the immutable `v<version>` tag,
+re-runs tests, builds/checks wheel and source distribution, performs a clean wheel
+render and publishes exact checksum-labelled assets. It refuses to overwrite
+an existing GitHub release. The optional PyPI job uses the `pypi` environment and
+a separately configured trusted publisher; no API token is stored in this project.
+A GitHub release and a PyPI listing are separately verified outcomes.

framerudiments-0.1.0/docs/extraction.md

@@ -0,0 +1,28 @@
+# Extraction and ownership
+
+This package consolidates reusable render mechanisms. It does not copy private
+song assets or every historical campaign script into the distribution. Creative
+scene drawing remains release-owned and can use the shared Python scene hook.
+
+| Existing renderer family | Shared functionality now supplied by FrameRudiments |
+| --- | --- |
+| Gilt Trip Shorts/Canvas | Native table identity, source-time 64-pip sampling, layer placement, alpha bounds, lyric-frame ledger, endpoint fades, FFmpeg encode/probe/decode, poster/preview. |
+| Blame Putin Shorts/full visualiser | Direct native catalogue sampling, saved StemLab beat grid, explicit match source/window/phase, cue-gated layers, full-duration programmes, static caption plates. |
+| Clay Shorts/full film | Pinned exact source intervals and repeats, canonical LRC mapping, named native motions, no-fade option, text fit, layered transparent art, lyric tablets/signs, retained raw source provenance. |
+| Paper Dreams Shorts/full film | Sprite sheets, connected-alpha component cleaning, exact-text lyric artwork, masks, alpha manipulation, extracted seeded flight model, generalized lyric-art entrance/hold/exit and per-frame scene hook for fog/custom drawing. Narrative/asset decisions stay in its adapter. |
+| Silly Sausage Britain | Atlas cycles, body/sprite transforms, masks, same-pose directional trails, generated lyric artwork, bounded compositing. Specific dancers, gull routes and smoke artwork stay in its adapter. |
+| Free Danny Tommo / Patriotic Revolution | Reusable beat clock, sprite/lyric composition, pinned sources, transparent layering, rendered/encoded QA evidence. Protest/crown/identity assets stay private to their releases. |
+| Moderate or Good | Timed-caption concepts, separate structural cues, SRT/ASS export, full/short project modes and background composition; old estimated timings remain historical evidence. |
+
+The local migration inventory records original paths, hashes, imports and
+function names. It is private evidence outside the package. Original scripts
+are preserved; they are not silently redirected, deleted or asserted to have
+been regenerated. Approved existing films retain their original generators.
+New adaptations can remove their duplicated clock/caption/encoder loops and
+call the shared API while retaining scene drawing and provenance locally.
+
+StemLab owns analysis, accepted-loop evidence, beat grids, matching and recorded
+signals. DanceRudiments owns motion functions, schema validation and native
+recording playback. FrameRudiments owns offline timeline adaptation, composition,
+encoding and technical render QA. DanceMoves remains the live web runtime.
+Short Shifter remains outside DanceFlow.

framerudiments-0.1.0/docs/project-format.md

@@ -0,0 +1,70 @@
+# Project format v1
+
+The schema identifier is `framerudiments.project.v1`. Unknown fields are errors.
+All file references are `{ "path": "relative-or-absolute", "sha256": "64 hex digits" }`.
+Hash each final input, including the font; a changed file fails preparation and
+the inputs are checked again before and after a render.
+
+| Field | Meaning |
+| --- | --- |
+| `title`, `artist`, `notes` | Private project description; text appears only through `identity`. |
+| `purpose` | `short` (120 ms endpoint fades by default), `visualiser`, or `canvas` (no fades by default). |
+| `width`, `height`, `fps`, `fps_reason` | Even dimensions, fps defaults to 60; other rates need a reason. No platform compliance is inferred. |
+| `audio` | `source` file reference, verified `sample_rate`, start-inclusive `start_sample`, end-exclusive `end_sample`, optional positive integer `repeats` and `fade_seconds`. |
+| `clock` | `bpm` or `beat_grid` file reference; `authority`, `status` (`confirmed`, `estimated`, `synthetic`), optional `origin` in source seconds and `phase_status`. |
+| `font` | Pinned TTF/OTF file for authored text. |
+| `lyrics`, `cues` | Separate LRC references; `.cue` files are also supported for structural cues. |
+| `canonical_lyrics` | Optional pinned plain text whose performed nonempty lines must exactly match the LRC. Bracketed structural lines in this comparison file are excluded. |
+| `background` | `colour`, optional pinned `image` and `fit` (`cover` or `contain`). |
+| `captions` | `box` [left,top,right,bottom], `font_size`, optional `min_font_size`, `colour`, `panel`, `stroke`, `line_spacing`, `mode` (`current` or `neighbours`). |
+| `identity` | List of `{text, style}`; each style uses the same text-block fields as captions. |
+| `layers` | Ordered sprite/bar layers described below. |
+| `lyric_art` | `{items: [{text, asset}], placement: <sprite fields>, fallback: "text" or "error"}`. Exact text lookup preserves canonical lyric association. `error` requires every visible lyric to have an asset. |
+| `stemlab_loop` | `{file: <pinned loops report>, id: <accepted loop id>}`; imports native bounds/rate, verifies source SHA, rejects conflicting explicit audio values. Does not approve a seam. |
+
+Sprites use `id`, `asset`, `center` [x,y], `width` and optional `bounds`
+[left,top,right,bottom]. Optional `crop_alpha`, `opacity`, `motion`, `mapping`,
+`atlas`, `trail`, source-time `start_seconds`/`end_seconds` and `cue_labels`
+control their appearance. `mapping` amplitudes are `dx`, `dy`, `rotation`
+(degrees), `scale` (magnitude less than one); `x_axis`, `y_axis`, `rotation_axis`
+and `scale_axis` select index 0,1,2 of the motion projection. Defaults are
+0,1,2,2 respectively. Set `y_axis: 0` to map a one-dimensional bounce vertically.
+
+Atlas configuration is `{columns, rows, count, cycle_ticks, phase_beats?}`.
+The atlas must divide into exact cells. One beat is 16 ticks; cycle ticks are
+explicitly authored rather than silently quantised. Cycles use a continuous
+beat clock across repeated source excerpts. `trail` accepts `offset` [x,y],
+`opacity` and `radius`, with the expanded result included in bounds checks.
+
+Motion kinds:
+
+* `composite`: `channels` is a list of one-to-three `{motion, axis}` entries;
+  each output axis samples its own native motion route. Use this for independent
+  sway, bounce and tilt rather than conflating their periods or phases.
+* `named`: native `pattern`, optional `rate`, `phase_beats`, `origin_beat`.
+* `table`: pinned `file` containing an existing native sample export and
+  `pattern`. Requires 64-pip, version, binary-hash and exact period identity.
+* `match`: pinned StemLab report `file`, explicit zero-based `source_index`
+  and `match_index`, optional `source_offset_seconds` for a documented excerpt
+  report. Uses the selected pattern/phase and source-window origin. Extrapolation
+  requires `allow_outside_match: true`; it never implies approval.
+* `recording`: pinned native recording `file`, optional one-to-three named
+  `axes`. Its BPM, beat zero and negative start pip stay authoritative. Outside
+  capture `outside` is `error` by default, or explicitly `neutral`. Rate,
+  phase and interpolation overrides are rejected.
+
+`interpolate: true` on named/table/match routes explicitly blends adjacent
+integer native samples for old compositor parity. Default sampling is native
+integer-pip. Named/table `repeat_clock` is `continuous` by default; `source`
+replays the source phase each cycle. Recorded and matched motion always use
+absolute source time.
+
+A layer with `type: "bars"`, `bounds` and a recording motion displays every
+dimension on a signed -1..+1 scale, including Fourier buckets. It does not
+extract frequencies or generate envelopes: StemLab supplies that evidence.
+
+The Python `scene(image, FrameContext)` hook supports release-owned custom
+flight physics, fog, backgrounds and choreography. Pure/random-access hooks
+are easiest to test; a stateful simulation must advance by encoded frame in
+a deterministic order and own its collision/occlusion QA. Custom drawing is
+not automatically covered by sprite bounds. All external assets must be pinned.

framerudiments-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "framerudiments"
+version = "0.1.0"
+description = "Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence."
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+authors = [{name = "Kieran Simkin"}]
+dependencies = ["Pillow>=10", "dancerudiments>=0.3.0,<0.4"]
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "build>=1.2", "ruff>=0.9", "twine>=6"]
+
+[project.urls]
+Homepage = "https://kieransimkin.co.uk/danceflow/"
+Repository = "https://github.com/kieransimkin/FrameRudiments"
+Issues = "https://github.com/kieransimkin/FrameRudiments/issues"
+Documentation = "https://github.com/kieransimkin/FrameRudiments#readme"
+
+[project.scripts]
+framerudiments = "framerudiments.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+
+[tool.ruff]
+line-length = 110
+
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]

framerudiments-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

framerudiments-0.1.0/src/framerudiments/__init__.py

@@ -0,0 +1,7 @@
+"""Offline frame composition on a traceable musical clock."""
+__version__ = "0.1.0"
+
+from .project import Project
+from .render import render, preflight
+
+__all__ = ["Project", "render", "preflight", "__version__"]

framerudiments-0.1.0/src/framerudiments/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

framerudiments-0.1.0/src/framerudiments/atlas.py

@@ -0,0 +1,44 @@
+"""Connected alpha-component cleaning extracted from the sprite preparation tools."""
+from collections import deque
+from PIL import Image
+
+def components(alpha: Image.Image, threshold: int = 18) -> list[list[tuple[int, int]]]:
+    width, height = alpha.size
+    pixels = alpha.load()
+    seen: set[tuple[int, int]] = set()
+    result: list[list[tuple[int, int]]] = []
+    for y in range(height):
+        for x in range(width):
+            if (x, y) in seen or pixels[x, y] < threshold:
+                continue
+            queue = deque([(x, y)])
+            seen.add((x, y))
+            group: list[tuple[int, int]] = []
+            while queue:
+                px, py = queue.popleft()
+                group.append((px, py))
+                for ny in range(max(0, py - 1), min(height, py + 2)):
+                    for nx in range(max(0, px - 1), min(width, px + 2)):
+                        if (nx, ny) not in seen and pixels[nx, ny] >= threshold:
+                            seen.add((nx, ny))
+                            queue.append((nx, ny))
+            result.append(group)
+    return sorted(result, key=len, reverse=True)
+
+def isolate_one_object(cell: Image.Image) -> tuple[Image.Image, int, int]:
+    rgba = cell.convert("RGBA")
+    groups = components(rgba.getchannel("A"))
+    if not groups:
+        raise ValueError("atlas cell contains no opaque object")
+    keep = set(groups[0])
+    removed = sum(len(group) for group in groups[1:])
+    src = rgba.load()
+    for y in range(rgba.height):
+        for x in range(rgba.width):
+            if (x, y) not in keep:
+                r, g, b, _ = src[x, y]
+                src[x, y] = (r, g, b, 0)
+    post = [group for group in components(rgba.getchannel("A")) if len(group) >= 8]
+    if len(post) != 1:
+        raise ValueError(f"cleaned cell has {len(post)} meaningful objects")
+    return rgba, len(groups), removed

framerudiments-0.1.0/src/framerudiments/choreography.py

@@ -0,0 +1,30 @@
+"""Frame-addressed entrance/hold/exit mechanics extracted from lyric-plane rendering."""
+from .timeline import half_up
+from .io import number, integer
+
+
+def lyric_placements(events, frame, *, fps, bpm, transition_ticks=8, width=1920, centre=960,
+                     margin=650, programme_frames):
+    """Enter by onset, hold to explicit end_frame, then leave; no copied song BPM."""
+    fps = integer(fps, "fps", minimum=1)
+    bpm = number(bpm, "bpm", minimum=.00001)
+    transition = max(1, half_up(number(transition_ticks, "transition ticks", minimum=0) * 3.75 / bpm * fps))
+    for index, event in enumerate(events):
+        onset = event["frame"]
+        if "end_frame" not in event:
+            raise ValueError("Lyric-art choreography requires explicit end_frame")
+        following = event["end_frame"]
+        if following < onset:
+            raise ValueError("Lyric-art end precedes onset")
+        enter, end = max(0, onset - transition), min(programme_frames, following + transition)
+        if not enter <= frame < end:
+            continue
+        if frame < onset:
+            u = 1 - (1 - (frame - enter) / max(1, onset - enter)) ** 3
+            x, phase = -margin + (centre + margin) * u, "enter"
+        elif frame < following:
+            x, phase = centre, "hold"
+        else:
+            u = 1 - (1 - min(1, (frame - following) / transition)) ** 3
+            x, phase = centre + (width + margin - centre) * u, "exit"
+        yield index, round(x), phase