> built 2026-10-14 05:06 UTC from 5219317 (main) · an 0.1.239. Details: build_info.json # index.html.md # an AI-driven structured animation in Python. The user is the **director**; an AI agent (Claude Opus 4.7) is the **assistant orchestrator**; existing animation libraries (a custom 2D-cutout runtime, Manim, Remotion) are the **executors**. ```bash pip install an ``` Renamed from `anima` (PyPI conflict). Repo: [https://github.com/thorwhalen/an](https://github.com/thorwhalen/an). --- ## What works today ```bash an check # diagnose backend system deps an init my-scene # create a fresh project # edit scene.md ... an validate my-scene # schema + semantic validation an render my-scene # → output/main.mp4 (offline defaults) an render my-scene --tts elevenlabs --lipsync whisper # real speech, word-aligned visemes an render my-scene --parallel auto # per-shot threads (~N× speedup on N-shot scenes) an render my-scene --step-hz 15 # tweens "on twos" (15 pose updates/s at 30 fps); camera stays smooth an preview my-scene # live in-browser preview; reloads on edit an iterate my-scene "make Maya laugh longer and warmer" # free-text → IR patch → invalidate caches an render my-scene # re-renders only the affected shot # Character authoring (Phase 11a) an character new maya --seed maya-warm # generate a DiceBear-backed character an character new bob --offline # offline-only: deterministic geometric fallback an character mouths maya # regenerate the 9-shape mouth set + its viseme@happy / viseme@sad variants an character add-gaze maya # give an older character the sclera/pupil/lid eye stack (new ones have it) an character validate maya # check parts, mouth set, pivots an character silhouette maya --other bob # silhouette test (IoU score) an character preview maya --open-browser # HTML viewer cycling all 9 visemes # Synthetic impact clips with exact ground truth (for scoring sub-frame timing) an impacts clip out/ --kind air --fps 30 --exposure 0.5 --jitter-sd 0.012 an impacts clip-set out/set --fps 24,30,60 # objects x kinds x fps x shutter, + index.json ``` The defaults run without any API keys: offline TTS produces silent audio of the right length, offline lip-sync deterministically generates viseme tracks. To get real audible speech, set `ELEVEN_API_KEY` and pass `--tts elevenlabs`. For word-aligned mouth shapes, `pip install faster-whisper` and pass `--lipsync whisper`. For free-text editing via `an iterate`, set `ANTHROPIC_API_KEY`. --- ## A 30-second tour A project is a small directory: ```default my-scene/ ├── scene.md # human Markdown — what you and the agent edit ├── ir/scene.json # Pydantic-validated SSOT (auto-synced) ├── assets/ # characters, props, environments, voices, styles ├── artifacts/ # audio, viseme tracks, per-shot mp4s (content-hash cached) ├── output/ # final mp4s └── .an/ # decisions log + agent memory ``` Authoring happens in `scene.md`: ```markdown # Park Bench ```yaml meta title: Park Bench duration: 12 fps: 24 resolution: { width: 640, height: 360 } ``` ## Shot s1 (cutout) ```yaml shot duration: 6 camera: { move: push_in } ``` ```yaml entities - { kind: environment, id: park_bg, store: environments, ref: park } - { kind: character, id: charlie, store: characters, ref: charlie-v1 } - { kind: character, id: maya, store: characters, ref: maya-v1 } ``` ```dialogue charlie [thinking]: Did you ever wonder why we always meet here? maya [amused]: Because the pigeons trust us. ``` ``` `an render` produces an mp4 with two visually-distinct characters (per-id palette: skin/clothing/hair), animated mouths over the dialogue lines, eye-blinks every ~4 seconds, brows, lids and mouth form driven by each line’s `[emotion]` (the face solver), a sky/grass park background, and a slow camera push-in. --- ## A 3-minute tour `an` separates a scene into three layers: 1. **Narrative** — `scene.md`. Markdown with structured fenced blocks: `yaml meta`, `yaml shot`, `yaml entities`, `yaml actions`, `dialogue`. What you and the agent edit. 2. **Scene Graph** — `ir/scene.json`. Pydantic-validated, renderer-agnostic. The single source of truth. Diffable. Pipeline stages (audio synthesis, lip-sync) write into the JSON; `an sync` keeps it consistent with the Markdown using mtime-newer-wins. 3. **Render Code** — generated per-backend (cutout JSON for the JS runtime, Manim Python, Remotion TSX). Disposable; never edited by hand. ### Composition Authoring is fluent in Python and flattens to a canonical timeline: ```python from an import sequence, parallel, tween, delay, flatten action = sequence( tween("charlie/torso", "rotation", to=10.0, duration=1.0), delay(0.5), tween("charlie/torso", "rotation", to=0.0, duration=1.0), ) flat = flatten(action) # [FlatAction(start=0.0, end=1.0, ...), FlatAction(start=1.5, end=2.5, ...)] ``` The same shape is also writable in markdown via a `yaml actions` block: ```yaml - { kind: tween, target: charlie/torso, property: rotation, to: 10.0, duration: 1.0 } - { kind: tween, target: charlie/torso, property: rotation, to: 0.0, duration: 1.0, start: 1.5 } ``` ### Persistence — the project mall Everything long-lived (assets, artifacts, decisions, scene state) goes through a `dol`-backed `MutableMapping` mall: ```python from an import build_project_mall mall = build_project_mall("my-scene", ensure=True) mall["voices"]["maya-warm"] = {"provider": "elevenlabs", "voice_id": "..."} mall["scenes"]["main"] # returns a SceneIR ``` ### End-to-end orchestration ```python from an.orchestrate import orchestrate report = orchestrate("my-scene") # report.success: bool # report.output_path: Path # report.validation: ValidationReport # report.verifications: list[VerificationReport] from each verifier ``` The default verifier chain runs `LayoutLintVerifier` (pre + post) and `MediaQualityVerifier` (post). Pass your own list to swap in `VisionLMVerifier` (Claude vision QA) or `HumanInTheLoopVerifier` (interactive approval). ### Free-text iteration (the spec’s signature loop) ```python from an.orchestrate import iterate result = iterate("my-scene", "Make Maya's response a bit longer and more affectionate") # result.summary: "Extended Maya's reply..." # result.patches: [Patch(op='set', path='timeline/1/dialogue/0/text', value=...), ...] # result.affected_shots: ['s2'] # result.success / .error / .new_scene / .validation ``` The patches are validated against the schema and persisted; affected shots’ cached mp4s are invalidated so the next `an render` regenerates only those. --- ## Architecture | Subsystem | Implementation | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **Renderer Protocol** | `an.adapters.Renderer` — Cutout (real), Manim (real if installed), Remotion (skeleton), Whiteboard (stub) | | **Cutout backend** | `an.adapters.cutout.compile_shot` → `CutoutSceneJSON` → PixiJS v7 in headless Chromium → ffmpeg mux | | **Character rig** | Ellipse head + per-id palette (skin/clothing/hair) + eyebrows and eyelids driven by the compile-time face solver (`expression` actions, ten presets, the dialogue `[emotion]` sugar; `viseme@
` mouth-set variants) + eyes as a sclera/pupil/lid stack (the pupils follow `gaze_x`/`gaze_y` and make seeded ambient saccades; blinks compiled as channels — an eyelid swap where the rig has closed-eye art, a squash otherwise; `an character add-gaze` gives an older rig the stack) + bezier-curved mouth (9 viseme shapes) | | **TTS Protocol** | `OfflineTTS` (silent placeholder), `ElevenLabsTTS` (real, needs `ELEVEN_API_KEY`) | | **Lip-sync Protocol** | `OfflineLipSync` (char-distribution), `WhisperLipSync` (word-aligned via faster-whisper), `RhubarbLipSync` (phoneme-aligned), `WordTimingsLipSync` (driven by an injected `WordTimingProvider` — skip transcription entirely when the caller already has authoritative word timings) | | **Verifier Protocol** | `LayoutLintVerifier`, `MediaQualityVerifier`, `VisionLMVerifier` (Claude vision), `HumanInTheLoopVerifier` | | **Persistence** | dol-backed `MutableMapping`s organized into `build_project_mall(...)` | | **CLI** | `typer` dispatch over `an.tools._dispatch_funcs` (init / validate / sync / check / render / iterate / bench) plus the `an character ...` and `an impacts ...` namespaces | | **Iterate loop** | `an.iterate` — Anthropic Opus 4.7 + adaptive thinking + structured JSON patches + path-based mutation + cache invalidation | For a deeper as-built reference (module-by-module map, control flows, key invariants, content-hash caching strategy), see [`misc/docs/architecture_as_built.md`](). The research reports next to it cover the design space the system was built against — they are not current state, and `wave1_verification.md` is (verified fact, with the URLs each licence was read at). ### Injecting word timings (no whisper redundancy) When the caller already has authoritative word-level alignment data (e.g. from a separate lyric-alignment pipeline), `an` can skip its own transcription pass entirely: ```python from an.audio import StaticWordTimings, WordTimingsLipSync from an.orchestrate import orchestrate timings = [("hello", 0.5, 1.0), ("world", 1.2, 1.8), ...] lipsync = WordTimingsLipSync(StaticWordTimings(timings, label="my-aligner")) orchestrate("my-scene", lipsync=lipsync) ``` `orchestrate(..., tts=, lipsync=, parallel=)` accepts either provider name strings or instances. Plug in any `WordTimingProvider` (structural protocol with `name: str` and `words_for(audio, transcript=)` returning `(text, start, end)` tuples). `muvid` uses this hook to feed `lacing` alignment-store timings straight into the cutout pipeline. ### Synthetic impact clips (`cutan.impacts`) Structured animations of a stick or a ball striking a surface — or striking *the air*, a stroke that turns with nothing to hit — on a known tempo grid, filmed by a camera whose frame rate, shutter and capture jitter you choose. Each clip ships a sidecar that keeps three times apart, which is what makes it useful for scoring estimators that try to recover an impact *between* two frames: the **intended** grid time, the **executed** impact time (grid plus humanisation, in continuous seconds — never snapped to a frame), and **what the frames show** (each frame’s exposure interval and sample instants, per-frame keypoints, and which frames bracket each impact). ```python from cutan.impacts import ImpactClipSpec, write_impact_clip, write_impact_set spec = ImpactClipSpec( object="stick", kind="air", # or "ball" / "surface" tempo=[(0, 90), (16, 120)], beats=16, # an accelerando; or a single bpm pattern=(1, 0.5, 0.8, 0.5), # per-step stroke height, 0 = rest jitter_sd=0.012, jitter_rho=0.3, # human timing, seconds (default 8 ms; 0 = metronome) fps=30, exposure=0.5, timestamp_jitter_sd=0.002, # the camera ) clip_dir = write_impact_clip( spec, "~/clips" ) # clip.mp4, truth.json, keypoints.ndjson, trajectory.csv, scene.json write_impact_clip( spec, "~/clips", render=False ) # truth + keypoints only: no browser needed write_impact_set("~/clips/set") # 24 clips sharing one performance ``` The clips are ordinary `an` scenes (two props, one tween per stroke segment), and the ground truth is read back from the same compiled document the renderer draws — `write_impact_clip` refuses to write a sidecar whose keypoints disagree with the analytic motion at any captured instant, or whose document is not the one the renderer staged. With an open shutter, a frame’s keypoints are the average over its exposure (what the blurred frame shows), with the mid-exposure position recorded beside them. The `truth.json` schema is documented in `cutan/impacts/truth.py`. The camera model is `an.frame_clock.FrameClock`, which reaches the renderer through `RenderContext.frame_samples`: several instants averaged per frame are an open shutter, instants off the `i / fps` grid are capture jitter, and a render without it is byte-identical to before. --- ## What’s not in v0.1 - 3D animation, generative video, interactive output, SaaS hosting, music/sound-effect generation, in-house GUI, or editing of pre-existing video footage. `an` synthesizes; it does not cut. - The Manim backend works for placeholder title cards but isn’t doing real shot-to-Manim translation; Remotion + whiteboard are skeleton implementations that respond correctly to `can_render` but can’t produce video yet. - Lip-sync for face-baked characters. Characters whose descriptor declares `face_overlay: false` (DiceBear avatars, or any hand-declared baked face) carry their face inside the head SVG, so the compiler suppresses both the overlay mouth and the viseme channel — they speak without moving their mouths. Hand-rigged characters lip-sync normally; see `examples/promote_demo/`. - Multi-scene projects — `"main"` is the only scene key supported today. SVG character art *has* shipped — descriptors drive real sprites through `svg_sprite` visuals, not the placeholder geometry an earlier version of this list described. --- ## Reference - [`misc/docs/architecture_as_built.md`]() — module map, control flows, invariants, caching strategy. - [`misc/docs/`]() — the design-space research reports, plus [`wave1_verification.md`](), which is *verified current fact* rather than design space: licences with the URLs they were read at, and the silent-discard inventory. - [`misc/CHANGELOG.md`]() — phase-by-phase what shipped when. - [`.claude/skills/`]() — the skills the agent uses to drive the package (`an` to use it, `an-spec` to interview a director, `an-dev` to work on it, plus `an-dev-licensing` and `an-dev-runtime-assets` for the two things that fail silently). - [`examples/`]() — the canonical demo scenes. `single_character/` is the smallest thing that renders; `character_gallery/build.py` goes end to end from character creation.

This documentation as a single file: an.md (Markdown, for agents).

# _autosummary/an.adapters.cutout.cache_key.html.md # an.adapters.cutout.cache_key Moved to [`an.stage.cache_key`](_autosummary/an.stage.cache_key.html.md#module-an.stage.cache_key) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.canvas_capture.html.md # an.adapters.cutout.canvas_capture Moved to [`an.stage.canvas_capture`](_autosummary/an.stage.canvas_capture.html.md#module-an.stage.canvas_capture) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.channel.html.md # an.adapters.cutout.channel Channel evaluation — moved to [`an.timing.channel`](_autosummary/an.timing.channel.html.md#module-an.timing.channel) (the timing kernel). This path keeps working for every existing caller; new code imports from `an.timing`. \*\*This module’s names are the executable spec of `runtime.js`’s `evaluateChannel``** (with the default ``kind=None`: by value type), pinned by `tests/test_cutout_channel_parity.py`. ```pycon >>> ch = Channel("a", "x", [Keyframe(0.0, 0.0), Keyframe(1.0, 10.0)]) >>> evaluate(ch, 0.5) 5.0 ``` ### Functions | [`evaluate`](_autosummary/an.adapters.cutout.channel.html.md#an.adapters.cutout.channel.evaluate)(channel, t, \*[, kind]) | Evaluate `channel` at time `t` (see the module docstring for `kind`). | |-------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`check_channel`](_autosummary/an.adapters.cutout.channel.html.md#an.adapters.cutout.channel.check_channel)(channel, kind) | Why `channel`'s keyframe values do not fit `kind` (empty if they do). | ### Classes | [`Channel`](_autosummary/an.adapters.cutout.channel.html.md#an.adapters.cutout.channel.Channel)(target, property[, keyframes]) | Sorted keyframes for one property of one target. | |-------------------------------------------------------------------------------------------|---------------------------------------------------------| | [`Keyframe`](_autosummary/an.adapters.cutout.channel.html.md#an.adapters.cutout.channel.Keyframe)(time, value[, easing]) | One keyframe: time, value, optional per-segment easing. | ### *class* an.adapters.cutout.channel.Channel(target, property, keyframes=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Sorted keyframes for one property of one target. Construction validates that `keyframes` is non-empty and sorted. ### *class* an.adapters.cutout.channel.Keyframe(time, value, easing=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One keyframe: time, value, optional per-segment easing. The easing on a keyframe describes the curve **leaving** that keyframe toward the next one. The last keyframe’s easing is therefore unused. ### an.adapters.cutout.channel.check_channel(channel, kind) Why `channel`’s keyframe values do not fit `kind` (empty if they do). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.adapters.cutout.channel.evaluate(channel, t, , kind=None) Evaluate `channel` at time `t` (see the module docstring for `kind`). * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) # _autosummary/an.adapters.cutout.clip.html.md # an.adapters.cutout.clip Clips, loop modes and poses — moved to [`an.timing.clip`](_autosummary/an.timing.clip.html.md#module-an.timing.clip) (the timing kernel). This path keeps working for every existing caller; new code imports from `an.timing`. ```pycon >>> from an.adapters.cutout.channel import Channel, Keyframe >>> ch = Channel("a", "x", [Keyframe(0.0, 0.0), Keyframe(1.0, 10.0)]) >>> clip = Clip("walk", duration=1.0, channels=[ch], loop_mode=LoopMode.LOOP) >>> evaluate(clip, 1.25)[("a", "x")] # loop wraps 2.5 ``` ### Functions | [`evaluate`](_autosummary/an.adapters.cutout.clip.html.md#an.adapters.cutout.clip.evaluate)(clip, t, \*[, kind_of]) | Evaluate `clip` at time `t`, returning a `Pose`. | |-------------------------------------------------------------------------------------|------------------------------------------------------------------------| | [`merge_poses`](_autosummary/an.adapters.cutout.clip.html.md#an.adapters.cutout.clip.merge_poses)(\*poses) | Merge multiple poses with **override semantics** (later wins per key). | ### Classes | [`Clip`](_autosummary/an.adapters.cutout.clip.html.md#an.adapters.cutout.clip.Clip)(name, duration[, channels, loop_mode]) | Named animation: a duration + a bundle of channels. | |------------------------------------------------------------------------------------------------|-------------------------------------------------------| | [`LoopMode`](_autosummary/an.adapters.cutout.clip.html.md#an.adapters.cutout.clip.LoopMode)(\*values) | How a clip behaves past its natural duration. | ### *class* an.adapters.cutout.clip.Clip(name, duration, channels=, loop_mode=LoopMode.ONCE) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Named animation: a duration + a bundle of channels. ### *class* an.adapters.cutout.clip.LoopMode(\*values) Bases: [`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Enum`](https://docs.python.org/3/library/enum.html#enum.Enum) How a clip behaves past its natural duration. ### an.adapters.cutout.clip.evaluate(clip, t, , kind_of=None) Evaluate `clip` at time `t`, returning a `Pose`. `kind_of` declares each channel’s field kind; `None` interpolates by value type, as `runtime.js` does (see [`an.timing.channel`](_autosummary/an.timing.channel.html.md#module-an.timing.channel)). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.adapters.cutout.clip.merge_poses(\*poses) Merge multiple poses with **override semantics** (later wins per key). Used by the timeline to combine concurrent clips on the same target. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> merge_poses({("a", "x"): 1.0}, {("a", "x"): 2.0, ("a", "y"): 3.0}) {('a', 'x'): 2.0, ('a', 'y'): 3.0} ``` # _autosummary/an.adapters.cutout.compile.html.md # an.adapters.cutout.compile Moved to [`an.stage.compile`](_autosummary/an.stage.compile.html.md#module-an.stage.compile) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.easing.html.md # an.adapters.cutout.easing Moved to [`an.stage.easing`](_autosummary/an.stage.easing.html.md#module-an.stage.easing) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.fidelity.html.md # an.adapters.cutout.fidelity Moved to [`an.stage.fidelity`](_autosummary/an.stage.fidelity.html.md#module-an.stage.fidelity) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.html.md # an.adapters.cutout The cut-out backend’s old package: the stage moved to [`an.stage`](_autosummary/an.stage.html.md#module-an.stage) (an#247). The render path is `an.stage.compile` -> `an.stage.serialize` -> `an.stage.render` (the stage engine, driven by the core frame stage) -> `runtime.js`. Every module that moved keeps a LIVE alias here (`an.adapters.cutout.render` is `an.stage.render` for reading and for rebinding, `an._shims.alias_module()`). `coarticulate` and `gaze` moved to `cutan` (an#225; live aliases with a warning). What stays here is the timing re-exports (`channel`, `clip`, `timeline`). The names this package used to export are resolved LAZILY, on first access: importing `an.adapters.cutout.coarticulate` from the stage’s compiler must not load the stage back through this `__init__`. ```pycon >>> from an.adapters.cutout import CutoutRenderer, compile_shot >>> CutoutRenderer().name 'cutout' ``` ### Functions | [`compile_shot`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.compile_shot)(shot[, mall, fps, width, ...]) | Compile a single cutout-style `Shot` to its JS-runtime JSON form. | |------------------------------------------------------------------------------------------------|---------------------------------------------------------------------| ### Classes | [`CutoutRenderer`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.CutoutRenderer)([engine, name, ...]) | The stage renderer: the stage engine through the core frame stage. | |----------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | [`CutoutSceneJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.CutoutSceneJSON)(\*\*data) | Top-level cutout scene JSON — the JS runtime's input contract. | | [`NodeJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.NodeJSON)(\*\*data) | One node in the scene tree. | | [`VisualJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.VisualJSON)(\*\*data) | Drawable content attached to a node. | | [`AnimationClipJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.AnimationClipJSON)(\*\*data) | A named, reusable animation clip. | | [`ChannelJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.ChannelJSON)(\*\*data) | One animated property of one target. | | [`KeyframeJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.KeyframeJSON)(\*\*data) | Single keyframe in an animation channel. | | [`TimelineJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.TimelineJSON)(\*\*data) | Top-level timeline: total duration + tracks. | | [`TrackJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.TrackJSON)(\*\*data) | A sequence of placed clips with optional target-prefix metadata. | | [`PlacedClipJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.PlacedClipJSON)(\*\*data) | An animation placed on a track at a specific time. | | [`AssetsJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.AssetsJSON)(\*\*data) | Map of asset id → AssetJSON, split by kind. | | [`AssetJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.AssetJSON)(\*\*data) | A single asset (texture / audio file). | | [`AssetResolutionJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.AssetResolutionJSON)(\*\*data) | How one scene entity's store reference actually resolved at compile time. | ### Exceptions | [`CutoutRenderError`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.CutoutRenderError) | Raised when a cutout render fails. | |----------------------------------------------------------------------|--------------------------------------| ### *class* an.adapters.cutout.AnimationClipJSON(\*\*data) Bases: `_JSONModel` A named, reusable animation clip. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.AssetJSON(\*\*data) Bases: `_JSONModel` A single asset (texture / audio file). #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.AssetResolutionJSON(\*\*data) Bases: `_JSONModel` How one scene entity’s store reference actually resolved at compile time. The IR declares every drawable entity as `store` + `ref`. What the compiler *builds* from that pair is not recoverable from the scene tree afterwards: a character whose descriptor is missing and a character that never had one produce byte-identical procedural rigs. That ambiguity is an#33 — three CI runners once agreed perfectly about a picture that was not the picture, and the agreement read as a clean positive result. So the compiler records what it did, per entity, in the artifact the browser actually loads. `fallback` is the load-bearing bit: True means the declared ref supplied nothing and a stand-in was drawn in its place. ```pycon >>> AssetResolutionJSON( ... id="maya", kind="character", store="characters", ref="maya-v1", ... resolved="descriptor", fallback=False, ... ).fallback False ``` #### detail *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* One human sentence saying why, when `fallback` is True. #### fallback *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* True when the declared ref supplied nothing and a stand-in was drawn. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### resolved *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* “descriptor” | “parts” | “placeholder”. Environments: “store” | “preset” | “default”. * **Type:** What was built. Characters ### *class* an.adapters.cutout.AssetsJSON(\*\*data) Bases: `_JSONModel` Map of asset id → AssetJSON, split by kind. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.ChannelJSON(\*\*data) Bases: `_JSONModel` One animated property of one target. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *exception* an.adapters.cutout.CutoutRenderError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) Raised when a cutout render fails. Carries actionable detail. ### *class* an.adapters.cutout.CutoutRenderer(engine=, name='cutout', supported_renderers=('cutout', 'stage'), error=, capture_options=, paint_orders=('container', 'global')) Bases: [`FrameStageRenderer`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.FrameStageRenderer) The stage renderer: the stage engine through the core frame stage. It claims both renderer names (ADR 0001 decision 9): `stage`, the engine’s own, and `cutout`, the persisted name every existing scene carries. Its registry name stays `cutout` – persisted too (the shot cache keys on it) – and `StageRenderer` is the same class. ```pycon >>> r = CutoutRenderer() >>> r.name 'cutout' >>> r.supported_renderers ('cutout', 'stage') ``` #### error alias of [`CutoutRenderError`](_autosummary/an.stage.render.html.md#an.stage.render.CutoutRenderError) #### paint_orders *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('container', 'global')* one container’s items sorted (`applyPaintOrder`) and one list across containers (`applyGlobalPaint`). Read as the `engine.paint_order` capability. * **Type:** The paint orders the stage runtime honours (an#430) #### supported_renderers *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('cutout', 'stage')* The `Shot.renderer` values this renderer claims (the ONE place it names them). ### *class* an.adapters.cutout.CutoutSceneJSON(\*\*data) Bases: `_JSONModel` Top-level cutout scene JSON — the JS runtime’s input contract. Versioned so the runtime can refuse incompatible inputs. #### asset_resolution *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[AssetResolutionJSON](_autosummary/an.stage.serialize.html.md#an.stage.serialize.AssetResolutionJSON)]* One entry per drawable entity, in scene order — see [`AssetResolutionJSON`](_autosummary/an.adapters.cutout.html.md#an.adapters.cutout.AssetResolutionJSON). Inert to the runtime; read by the bench harness and the golden-corpus bless to assert WHICH render path ran. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### overlay *: [NodeJSON](_autosummary/an.stage.serialize.html.md#an.stage.serialize.NodeJSON) | [None](https://docs.python.org/3/builtins/constants.html#None)* a second top-level container the runtime centres on the canvas and never indexes, so no channel — the camera’s `root.pivot`/`root.scale` included — can reach it. Its children are indexed by their own paths exactly like `scene`’s, so an overlay title’s words tween like anything else. `None` when the shot has no overlay, and then omitted from the serialized document. * **Type:** The camera-immune layer (an#155) ### *class* an.adapters.cutout.KeyframeJSON(\*\*data) Bases: `_JSONModel` Single keyframe in an animation channel. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.NodeJSON(\*\*data) Bases: `_JSONModel` One node in the scene tree. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### paint_order *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The order its descendants’ visuals are PAINTED in, when it is not the tree’s (an#430): node paths relative to this node, back to front. Set on a rig’s entity node whose nested chain interleaves with an unrelated part (an upper arm 1, a cord 2, a forearm 3); the runtime keeps each visual in its transform tree and paints it from this list. #### scope *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* as the children of the node named `scope` in the same parent (`""`: as the parent’s own children). `None` = under this node’s own path, the rule before an#343. An environment’s foreground container carries `scope=`, so every plane is `/` wherever the environment is cut. [`an.stage.tree`](_autosummary/an.stage.tree.html.md#module-an.stage.tree) is the Python statement of the rule. * **Type:** Where this node’s CHILDREN are indexed (an#343) #### z_index *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* This node’s place among its siblings when its parent sorts them (an#403): a nested chain whose declared draw order is not the tree’s (a far arm behind the torso it nests under). `None` = insertion order. ### *class* an.adapters.cutout.PlacedClipJSON(\*\*data) Bases: `_JSONModel` An animation placed on a track at a specific time. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.TimelineJSON(\*\*data) Bases: `_JSONModel` Top-level timeline: total duration + tracks. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.TrackJSON(\*\*data) Bases: `_JSONModel` A sequence of placed clips with optional target-prefix metadata. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.adapters.cutout.VisualJSON(\*\*data) Bases: `_JSONModel` Drawable content attached to a node. `kind="svg_sprite"` is the Phase 11b path: the runtime instantiates a `PIXI.Sprite` from a pre-loaded SVG texture identified by `asset_id`. `asset_sets` carries this node’s swap vocabulary — `{set_name: {KEY: asset_id}}`, the compiler’s per-slot **projection** of the descriptor’s `asset_sets` onto the slot this visual draws (an#87). A channel whose property names one of these sets swaps the sprite’s texture by key; `viseme` is just the conventional set name lip-sync uses. Same field name as `CharacterDescriptor.asset_sets` on purpose: one vocabulary, two layers (descriptor = declared, wire = resolved to texture aliases). Replaces the mouth-only `viseme_assets`. `width`/`height` are the box the art is fitted **into**, not the size it is forced to. Under `fit="contain"` the art keeps its own aspect ratio and may leave slack on one axis; that slack is the correct rendering, not a bug. #### asset_geometry *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [float](https://docs.python.org/3/builtins/functions.html#float)]] | [None](https://docs.python.org/3/builtins/constants.html#None)* Per-texture geometry for a swap key drawn differently from the built one (an#211): `{asset_id: {"width", "height", "anchor_x", "anchor_y", "x", "y"}}` — the box the key is fitted into, its anchor, and its offset from the node (scene pixels). A swap used to carry the texture only, so every key drew in the DEFAULT attachment’s box: a closed mouth on a thin canvas squashed every open mouth to a fraction of a pixel. Only keys whose geometry differs are listed; `None` = every key shares it. #### blend *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['add', 'multiply'] | [None](https://docs.python.org/3/builtins/constants.html#None)* `"add"` for a glow, `"multiply"` for the paper grain. PixiJS 7 does both in the blend equation — no filter, no render texture. `None` = normal. * **Type:** The engine’s native blend mode for this visual (an#163) #### fit *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['stretch', 'contain']* How the art is fitted to `width`/`height`. `"contain"` scales uniformly so the art keeps the shape it was drawn with — the invariant of an#74. `"stretch"` sizes each axis independently, which is what every sprite did before that issue and what distorted `arm_l` by 3.929x on the repo’s own art. Additive with a `"stretch"` default so no stored scene changes meaning; the compiler emits `"contain"` for every sprite it builds. #### kind *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* One of `BUILTIN_VISUAL_KINDS`, or a kind a genre’s runtime script registers (`window.anRegisterVisual`, an#247). A string on the wire, as it always was; the open set is what lets `cutan` ship the mouth and eye. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### path *: [PathJSON](_autosummary/an.stage.serialize.html.md#an.stage.serialize.PathJSON) | [None](https://docs.python.org/3/builtins/constants.html#None)* The stroke for `kind="path"` (an#160); `None` on every other visual. #### underlays *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[UnderlayJSON](_autosummary/an.stage.serialize.html.md#an.stage.serialize.UnderlayJSON)] | [None](https://docs.python.org/3/builtins/constants.html#None)* Copies drawn behind this visual, back to front (an#163) — the outline and the paper-gap shadow. Only `rect`, `ellipse` and `svg_sprite` take them; the runtime refuses any other kind. #### z_index *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* The visual’s place among its node’s children when the node sorts them (an#403): a part drawn over the chain nested under it. ### an.adapters.cutout.compile_shot(shot, mall=None, , fps=30, width=1920, height=1080, background='#ffffff', strict_assets=False, step_hz=None, expression_provider=None, style_pack=None, default_easing=None) Compile a single cutout-style `Shot` to its JS-runtime JSON form. `default_easing` (an#166) is the scene’s `meta.default_easing`: the curve of every authored tween that names none (tween > this > the built-in `"ease_in_out"`, [`resolved_easing()`](_autosummary/an.ir.schema.html.md#an.ir.schema.TweenAction.resolved_easing)). `None` leaves the document byte-identical to before the knob existed. `expression_provider` (an#98) is the seam that turns authored `expression` leaves and dialogue `[emotion]` sugar into per-axis curves for the face solver; `None` is the genre’s default provider. `step_hz` (an#89) resamples every authored **tween** onto a SHOT-wide pose grid of that many updates per second (multiples of `1/step_hz` on this shot’s clock, shared by every tween in the shot; the grid restarts at a cut), each keyframe step-eased, so the character holds each pose for the frames between grid points — “on twos” at half the frame rate, “on threes” at a third. It is sample-and-hold of the eased curve at the grid instants, not a retiming into holds and fast transitions. `None` (default) leaves tweens smooth and the compiled document byte-identical to before the knob existed; anything else must satisfy `0 < step_hz <= fps` — checked HERE as well as by `an validate`, because a render never runs validate and a non-positive rate used to spin `step_times` forever (an#89 review). Exempt by construction, because they are separate emission sites rather than string-sniffed: the camera (`_add_camera_clips` — a stepped character under a translating camera slides in screen space, which is why the practice keeps cameras on ones), compiled blinks, `play` clips, and swap channels (already stepped by format). The value is stamped into `meta.step_hz` — only when set — so a serialized scene declares its timing policy without moving the contract hash of one that has none. `strict_assets` turns a stand-in asset — the placeholder rig drawn for a character whose descriptor is missing, or the default backdrop drawn for an unknown environment ref — from a warning into a `CutoutCompileError`. Off by default so an asset-less project still renders; on for anything that measures pixels, where a stand-in is a wrong answer wearing a right one’s clothes (an#33). * **Return type:** [`CutoutSceneJSON`](_autosummary/an.stage.serialize.html.md#an.stage.serialize.CutoutSceneJSON) ### Modules | [`cache_key`](_autosummary/an.adapters.cutout.cache_key.html.md#module-an.adapters.cutout.cache_key) | Moved to [`an.stage.cache_key`](_autosummary/an.stage.cache_key.html.md#module-an.stage.cache_key) (an#247); this path is a LIVE alias of it. | |----------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`canvas_capture`](_autosummary/an.adapters.cutout.canvas_capture.html.md#module-an.adapters.cutout.canvas_capture) | Moved to [`an.stage.canvas_capture`](_autosummary/an.stage.canvas_capture.html.md#module-an.stage.canvas_capture) (an#247); this path is a LIVE alias of it. | | [`channel`](_autosummary/an.adapters.cutout.channel.html.md#module-an.adapters.cutout.channel) | Channel evaluation — moved to [`an.timing.channel`](_autosummary/an.timing.channel.html.md#module-an.timing.channel) (the timing kernel). | | [`clip`](_autosummary/an.adapters.cutout.clip.html.md#module-an.adapters.cutout.clip) | Clips, loop modes and poses — moved to [`an.timing.clip`](_autosummary/an.timing.clip.html.md#module-an.timing.clip) (the timing kernel). | | [`compile`](_autosummary/an.adapters.cutout.compile.html.md#module-an.adapters.cutout.compile) | Moved to [`an.stage.compile`](_autosummary/an.stage.compile.html.md#module-an.stage.compile) (an#247); this path is a LIVE alias of it. | | [`easing`](_autosummary/an.adapters.cutout.easing.html.md#module-an.adapters.cutout.easing) | Moved to [`an.stage.easing`](_autosummary/an.stage.easing.html.md#module-an.stage.easing) (an#247); this path is a LIVE alias of it. | | [`fidelity`](_autosummary/an.adapters.cutout.fidelity.html.md#module-an.adapters.cutout.fidelity) | Moved to [`an.stage.fidelity`](_autosummary/an.stage.fidelity.html.md#module-an.stage.fidelity) (an#247); this path is a LIVE alias of it. | | [`path`](_autosummary/an.adapters.cutout.path.html.md#module-an.adapters.cutout.path) | Moved to [`an.stage.path_geometry`](_autosummary/an.stage.path_geometry.html.md#module-an.stage.path_geometry) (an#247); this path is a LIVE alias of it. | | [`render`](_autosummary/an.adapters.cutout.render.html.md#module-an.adapters.cutout.render) | Moved to [`an.stage.render`](_autosummary/an.stage.render.html.md#module-an.stage.render) (an#247); this path is a LIVE alias of it. | | [`runtime_files`](_autosummary/an.adapters.cutout.runtime_files.html.md#module-an.adapters.cutout.runtime_files) | Moved to [`an.stage.runtime_files`](_autosummary/an.stage.runtime_files.html.md#module-an.stage.runtime_files) (an#247); this path is a LIVE alias of it. | | [`serialize`](_autosummary/an.adapters.cutout.serialize.html.md#module-an.adapters.cutout.serialize) | Moved to [`an.stage.serialize`](_autosummary/an.stage.serialize.html.md#module-an.stage.serialize) (an#247); this path is a LIVE alias of it. | | [`shutter`](_autosummary/an.adapters.cutout.shutter.html.md#module-an.adapters.cutout.shutter) | Moved to [`an.media.shutter`](_autosummary/an.media.shutter.html.md#module-an.media.shutter) (an#247); this path is a LIVE alias of it. | | [`supersample`](_autosummary/an.adapters.cutout.supersample.html.md#module-an.adapters.cutout.supersample) | Moved to [`an.media.supersample`](_autosummary/an.media.supersample.html.md#module-an.media.supersample) (an#247); this path is a LIVE alias of it. | | [`surface`](_autosummary/an.adapters.cutout.surface.html.md#module-an.adapters.cutout.surface) | Moved to [`an.stage.surface`](_autosummary/an.stage.surface.html.md#module-an.stage.surface) (an#247); this path is a LIVE alias of it. | | [`text`](_autosummary/an.adapters.cutout.text.html.md#module-an.adapters.cutout.text) | Moved to [`an.stage.text_layout`](_autosummary/an.stage.text_layout.html.md#module-an.stage.text_layout) (an#247); this path is a LIVE alias of it. | | [`timeline`](_autosummary/an.adapters.cutout.timeline.html.md#module-an.adapters.cutout.timeline) | Moved to [`an.stage.timeline`](_autosummary/an.stage.timeline.html.md#module-an.stage.timeline) (an#247); this path is a LIVE alias of it. | # _autosummary/an.adapters.cutout.path.html.md # an.adapters.cutout.path Moved to [`an.stage.path_geometry`](_autosummary/an.stage.path_geometry.html.md#module-an.stage.path_geometry) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.render.html.md # an.adapters.cutout.render Moved to [`an.stage.render`](_autosummary/an.stage.render.html.md#module-an.stage.render) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.runtime_files.html.md # an.adapters.cutout.runtime_files Moved to [`an.stage.runtime_files`](_autosummary/an.stage.runtime_files.html.md#module-an.stage.runtime_files) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.serialize.html.md # an.adapters.cutout.serialize Moved to [`an.stage.serialize`](_autosummary/an.stage.serialize.html.md#module-an.stage.serialize) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.shutter.html.md # an.adapters.cutout.shutter Moved to [`an.media.shutter`](_autosummary/an.media.shutter.html.md#module-an.media.shutter) (an#247); this path is a LIVE alias of it. The resolve is engine-independent, so it lives in the core’s media package. Every name of the new module is reachable here, and rebinding one here rebinds it there (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.supersample.html.md # an.adapters.cutout.supersample Moved to [`an.media.supersample`](_autosummary/an.media.supersample.html.md#module-an.media.supersample) (an#247); this path is a LIVE alias of it. The resolve is engine-independent, so it lives in the core’s media package. Every name of the new module is reachable here, and rebinding one here rebinds it there (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.surface.html.md # an.adapters.cutout.surface Moved to [`an.stage.surface`](_autosummary/an.stage.surface.html.md#module-an.stage.surface) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.text.html.md # an.adapters.cutout.text Moved to [`an.stage.text_layout`](_autosummary/an.stage.text_layout.html.md#module-an.stage.text_layout) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.adapters.cutout.timeline.html.md # an.adapters.cutout.timeline Moved to [`an.stage.timeline`](_autosummary/an.stage.timeline.html.md#module-an.stage.timeline) (an#247); this path is a LIVE alias of it. The compiled document’s evaluation entry point and its screen space are the stage’s (ADR 0001 decision 5). Every name of the new module is reachable here, and rebinding one here rebinds it there (`an._shims.alias_module()`). # _autosummary/an.adapters.html.md # an.adapters Renderer adapters — facades over backends (the stage, Manim, Remotion, whiteboard). The Renderer Protocol and registry live in `_base`. The core’s own optional backends are imported here so they self-register on package import. The stage (`an.stage`, the cut-out renderer) sits behind the import firewall, so it is named by MODULE and imported the first time the registry is asked anything (an#247). Backends with missing system deps still register but their `render()` raises a clear error; `can_render(shot)` continues to work for routing decisions. ### Functions | [`register_renderer`](_autosummary/an.adapters.html.md#an.adapters.register_renderer)(renderer) | Register a renderer in the default registry. | |---------------------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`get_renderer`](_autosummary/an.adapters.html.md#an.adapters.get_renderer)(name) | Look up a renderer by name in the default registry. | | [`list_renderers`](_autosummary/an.adapters.html.md#an.adapters.list_renderers)() | Names of all renderers registered in the default registry. | | [`register_lazy_renderer`](_autosummary/an.adapters.html.md#an.adapters.register_lazy_renderer)(name, module) | Name the module whose import registers renderer `name` (default registry). | ### Classes | [`Renderer`](_autosummary/an.adapters.html.md#an.adapters.Renderer)(\*args, \*\*kwargs) | Backend renderer interface. | |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`RendererRegistry`](_autosummary/an.adapters.html.md#an.adapters.RendererRegistry)(\*[, entry_point_group]) | Name-keyed registry of renderers. | | [`RenderContext`](_autosummary/an.adapters.html.md#an.adapters.RenderContext)(mall, work_dir[, fps, ...]) | Everything a renderer needs that isn't on the Shot itself. | | [`RenderResult`](_autosummary/an.adapters.html.md#an.adapters.RenderResult)(mp4_path, duration[, ...]) | Outcome of a single shot render. | | [`ManimRenderer`](_autosummary/an.adapters.html.md#an.adapters.ManimRenderer)(\*[, render_check, source_resolver]) | Manim Community Edition, through `manimkit`: an opaque-source shot renderer. | | [`RemotionRenderer`](_autosummary/an.adapters.html.md#an.adapters.RemotionRenderer)() | Remotion-based renderer (skeleton). | | [`WhiteboardRenderer`](_autosummary/an.adapters.html.md#an.adapters.WhiteboardRenderer)() | Whiteboard-style renderer (stub). | ### *class* an.adapters.ManimRenderer(, render_check=None, source_resolver=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Manim Community Edition, through `manimkit`: an opaque-source shot renderer. Implements [`Renderer`](_autosummary/an.adapters.html.md#an.adapters.Renderer) and `ClockOwningRenderer`. Seams: `render_check` (default `manimkit.render_check()`, imported on first use) and `source_resolver` (default: the project’s `sources` store, `store_source_resolver()`). The shot cache keys a shot through the REGISTERED instance’s resolver; a subclass registers its own keyer (`register_shot_keyer(name, manim_shot_inputs, renderer_type=Sub)`). #### measure_duration(shot, ctx, , render=True, force=False) Manim’s length of this shot’s scene, from the `measurements` store, or rendered now (and stored) when there is none — or when `force`. * **Return type:** `DurationMeasurement` | [`None`](https://docs.python.org/3/builtins/constants.html#None) #### probe_frames(shot, ctx, times) The film’s frames of `shot` at each of `times`, from its STORED picture (an#347). Manim owns its clock and renders a whole scene at once, so `an probe` never runs it: the picture a render stored is conformed exactly as [`render()`](_autosummary/an.adapters.html.md#an.adapters.ManimRenderer.render) conforms it, and the frames showing at `times` are read out. With no stored picture it refuses, naming the render that stores one. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)] #### render(shot, ctx) Render `shot` for exactly `shot.duration` (`an.render` settles it to the measured length, or longer to hold for its narration). * **Return type:** [`RenderResult`](_autosummary/an.adapters.html.md#an.adapters.RenderResult) #### stored_reads(key, ctx) The read trace stored with picture `key` (`None`: none stored, or not recorded). Reads stores only; never renders. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### *class* an.adapters.RemotionRenderer Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Remotion-based renderer (skeleton). ### *class* an.adapters.RenderContext(mall, work_dir, fps=30, resolution=(1920, 1080), strict_assets=False, supersample=1, pix_fmt=None, step_hz=None, style_pack=None, default_easing=None, frame_samples=None, capture=None, extra=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Everything a renderer needs that isn’t on the Shot itself. `mall` carries the project’s stores so the renderer can resolve assets by reference. `work_dir` is a scratch space; the renderer must clean up after itself or treat it as ephemeral. #### capture *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* `"screenshot"` (a Playwright element screenshot per instant) or `"canvas"` (the runtime reads its own canvas in-page, in batches). `None` is the renderer’s module default, read at call time — `"canvas"` since an#192, after the equivalence gate held on the whole corpus on both lanes. The two paths write frames whose DECODED pixels are equal, so this is a throughput knob and never a picture knob; a `RenderContext` field for `supersample`’s reason, and recorded in per-shot provenance. * **Type:** How frames leave the browser #### default_easing *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* the curve of every authored tween that names none. `None` = the built-in `"ease_in_out"`, and a compiled document byte-identical to before the field existed; set, it changes keyframes, so the contract hash moves with it — as it should. * **Type:** The scene’s `meta.default_easing` (an#166) #### fps *: [int](https://docs.python.org/3/builtins/functions.html#int) | [float](https://docs.python.org/3/builtins/functions.html#float)* Frames per second of the delivered video. May be non-integer — a camera’s 29.97 — and the capture loop and the mux honour it exactly. The COMPILER aligns its frame-sampled curves (gaze saccades, co-articulation, descriptor plays, face curves) to the nearest integer grid instead, because the compiled document’s `meta.fps` is an integer; tweens and every other keyframe are exact at any rate. #### frame_samples *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), ...], ...] | [None](https://docs.python.org/3/builtins/constants.html#None)* Per output frame, the scene instants to render and average into it — `None` is one instant at `i / fps`, the path every render took before this field existed, byte for byte. Several instants per frame are an open shutter (motion blur); instants off the `i / fps` grid are capture jitter. Built by [`an.frame_clock.FrameClock`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock), which is also what the impact harness writes into its ground truth, so the render and the record of when each frame was taken come from one object. A `RenderContext` field for `supersample`’s reason: it changes how frames are CAPTURED, not what the scene is, so it must not move the compiled document. Its length must equal the render’s frame count. #### pix_fmt *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The delivered encode’s pixel format, or `None` for the module default. **The one first-order quality lever in the encoder**: 4:2:0 -> 4:4:4 cuts the edge-band error 11.35 -> 3.79, where mathematically lossless 4:2:0 only reaches 10.15. Losslessness buys 8%; dropping chroma subsampling buys 66%. `None` rather than the literal, so the bench’s `pix_fmt` lever — which rebinds the module default — still reaches an unset render. The default stays 4:2:0 for a PRODUCT reason and not an encoder one: High 4:4:4 Predictive is refused by many hardware decoders, browsers and platforms. #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Scene-level stepped-timing policy for authored tweens (an#89); a shot’s own `step_hz` overrides it. `None` = smooth. Reaches the compiled document’s `meta.step_hz` (only when set) and per-shot provenance. The one deliberate exception to the rule two fields up (“a field on the compiled scene document moves `scene_contract_sha256`”): unlike `supersample`, this knob CHANGES the compiled document — the resampled keyframes are the contract — so the hash moves whenever it is set no matter where the knob lives, and a document that carries its own timing policy is the honest one. Omit-when-unset keeps the unset case free. #### strict_assets *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* Refuse to draw a stand-in for a declared asset that the stores do not supply. Off by default so an asset-less project still renders; on for anything that measures pixels, where a stand-in is a different picture that looks like a successful render (an#33). #### style_pack *: [StylePack](_autosummary/an.styles.html.md#an.styles.StylePack) | [None](https://docs.python.org/3/builtins/constants.html#None)* The `StylePack` this render is drawn under, already resolved from the scene’s `meta.style_pack` (an#112). Resolved ONCE per render rather than per shot: a pack is art direction for a project, and a scene whose shots disagreed about it would be two scenes. #### supersample *: [int](https://docs.python.org/3/builtins/functions.html#int)* Render at this many times the declared resolution and resolve back with an exact block mean. **1 means off, and off is free** — Chromium’s own PNG bytes reach disk untouched. A `RenderContext` field, and that placement is load-bearing rather than convenient. Simulated against a real committed ledger row: as a `render_kwargs` entry it becomes a `COMMON_ENV_PATHS` key and \*\*all 96 metrics are refused\*\*; as a field on the compiled scene document it moves `scene_contract_sha256` and **every scene becomes incomparable**; here, only `runtime_sha256` moves, which is deliberately not a comparability key — so 30 render-side entries still compare. It needs no `SCHEMA_VERSION` migration, and it MUST reach per-shot provenance, because a row that does not record it cannot be read back later. ### *class* an.adapters.RenderResult(mp4_path, duration, frame_manifest=, log='', provenance=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Outcome of a single shot render. ### *class* an.adapters.Renderer(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Backend renderer interface. Implementations should be cheap to construct and stateless across renders; state belongs in the `RenderContext` or the project mall. #### can_render(shot) Return True if this renderer can render `shot`. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) #### render(shot, ctx) Render a single shot to mp4. Idempotent given identical inputs. * **Return type:** [`RenderResult`](_autosummary/an.adapters.html.md#an.adapters.RenderResult) #### supported_renderers *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* The `Shot.renderer` values this backend claims. It is the ONE place an adapter names them: `can_render` derives from it rather than comparing to its own literal, so an adapter cannot advertise one renderer and accept another. an#106 renamed this from `supported_styles`; the rename is a break for an out-of-tree adapter because `Renderer` is `@runtime_checkable` and 3.12 checks data members, so `isinstance(old_adapter, Renderer)` is now False. ### *class* an.adapters.RendererRegistry(, entry_point_group=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Name-keyed registry of renderers. A module-level instance is exposed via `register_renderer` / `get_renderer` / `list_renderers`; callers needing isolation (tests, multi-tenant servers) can construct their own. **Backends outside the core register LAZILY** (an#247): a renderer that lives behind the import firewall – the stage, a genre’s, a third-party engine – is named here by the MODULE that registers it ([`register_lazy()`](_autosummary/an.adapters.html.md#an.adapters.RendererRegistry.register_lazy), or the `an.renderers` entry point group), and that module is imported the first time the registry is asked anything. So importing the core loads no backend, and every lookup still finds it. #### find_for(shot) Return the first registered renderer that `can_render(shot)`. `None` when none can; a `RendererLoadError` when none can AND a backend failed to import, since that backend may have been the one. * **Return type:** [`Renderer`](_autosummary/an.adapters.html.md#an.adapters.Renderer) | [`None`](https://docs.python.org/3/builtins/constants.html#None) #### get(name) The renderer registered as `name`, else the one that claims it (`get("stage")` is the stage renderer, registered as `cutout`). * **Return type:** [`Renderer`](_autosummary/an.adapters.html.md#an.adapters.Renderer) #### register_lazy(name, module) Declare that importing `module` registers the renderer `name`. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### *class* an.adapters.WhiteboardRenderer Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Whiteboard-style renderer (stub). ### an.adapters.get_renderer(name) Look up a renderer by name in the default registry. * **Return type:** [`Renderer`](_autosummary/an.adapters.html.md#an.adapters.Renderer) ### an.adapters.list_renderers() Names of all renderers registered in the default registry. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.adapters.register_lazy_renderer(name, module) Name the module whose import registers renderer `name` (default registry). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.adapters.register_renderer(renderer) Register a renderer in the default registry. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### Modules | [`cutout`](_autosummary/an.adapters.cutout.html.md#module-an.adapters.cutout) | The cut-out backend's old package: the stage moved to [`an.stage`](_autosummary/an.stage.html.md#module-an.stage) (an#247). | |-------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------| | [`manim_adapter`](_autosummary/an.adapters.manim_adapter.html.md#module-an.adapters.manim_adapter) | ManimRenderer — a whole-shot renderer for opaque Manim scene files (an#279). | | [`remotion_adapter`](_autosummary/an.adapters.remotion_adapter.html.md#module-an.adapters.remotion_adapter) | RemotionRenderer — invoke `npx remotion render` against a generated TSX project. | | [`whiteboard`](_autosummary/an.adapters.whiteboard.html.md#module-an.adapters.whiteboard) | WhiteboardRenderer — stub for hand-drawn / chalkboard-style animation. | # _autosummary/an.adapters.manim_adapter.html.md # an.adapters.manim_adapter ManimRenderer — a whole-shot renderer for opaque Manim scene files (an#279). A Manim shot names a Python scene file and a `Scene` class in it; `an` runs that file as it is and treats the result like any other rendered shot: ```yaml ## Shot chart (manim) ```yaml shot options: {source: bar_chart, scene: BarChartStory} ``` ``` `options.source` is a key of the project’s `sources` store (`assets/sources/bar_chart.py`); `options.scene` the class (optional when the file defines exactly one). The shot has NO IR inside it — it is (a)-level opaque source on the structured ↔ semantic spectrum — and gets everything around it from the core: narration (a dialogue line with an off-screen speaker, muxed under the picture), captions in the sidecar, sound cues, transitions, film assembly, the shot cache. **The files a scene reads.** The render runs in a staged copy of the WHOLE `sources` folder (`assets/sources/` and everything under it), so a scene imports a sibling module or loads `ImageMobject("bars/logo.png")` by a path relative to its own file, and every one of those bytes is in both keys below. A file read from OUTSIDE that folder — a literal absolute path, or one computed (`Path.home() / "data.csv"`, an environment variable, a helper) — is RECORDED as the render runs (manimkit’s `record_reads`: an audit hook in the render’s child process, an#291) and stored with the measurement as a trace (`read_trace()`): each file’s digest, `absent` for one looked for and missing, and each listed folder’s names. A stored picture is reused only while its trace still holds (`stale_reads()`), and the shot key has a `reads` part, so editing such a file re-renders the picture and the shot, and leaving it alone reuses both. A literal outside path is still a finding at its line: the cache sees it now, but another machine will not have it. **Manim owns its clock** (core study §4.2): only the file’s own `play` and `wait` calls decide how long it runs. The renderer implements `measure_duration` (`ClockOwningRenderer`); the measurement is derived data, kept in the `measurements` store under the **picture key** — what decides Manim’s own output and length: the bytes of the sources folder, the entry file, the scene, the Manim and manimkit versions, the quality preset and, only for a file that uses LaTeX, whether TeX is available. Never the film’s fps or size, the encode, or this module’s code: those change how the picture is CONFORMED, not what Manim draws. The core applies it in memory ([`an.measurements`](_autosummary/an.measurements.html.md#module-an.measurements)); the author’s scene is never rewritten. **The picture is cached apart from the shot.** Manim’s raw video is stored by its own sha256 (`pictures` store), named by the measurement record under the picture key, so a change that is not to the picture — narration, the film’s fps, the background pad, an `an` upgrade — re-conforms and re-muxes without running Manim. The shot key ([`manim_shot_inputs()`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.manim_shot_inputs)) is the picture key’s inputs plus the conform and encode knobs, the muxed audio and the render path’s code; the machine is the separate environment part ([`manim_environment()`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.manim_environment)). **Findings** — manimkit’s layout warnings, lint and errors, a file read the cache cannot see, a preset whose frame rate the film’s does not divide — are [`Finding`](_autosummary/an.verify.html.md#an.verify.Finding) s located by `file:line` (`Finding.location`), stored with the measurement (so a reused shot still reports them) and routed by the core to `an render`’s warnings, `render_reports/.json`, `orchestrate` and `an validate`. **Capabilities** (ADR 0002, environment subject): `env.manim` (`manim` and `manimkit` importable) is required — absent, [`ManimNotInstalledError`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimNotInstalledError) with the install command. `env.latex` is required only by a file that uses LaTeX; absent, the scene renders in manimkit’s `no_latex` mode, so a LaTeX use fails AT ITS LINE with the remedy instead of deep inside a TeX run. ```pycon >>> spec = ManimShotSpec.from_options({"source": "chart", "scene": "Chart"}) >>> spec.source, spec.scene, spec.quality ('chart', 'Chart', None) >>> choose_quality(fps=30, resolution=(1280, 720)) 'm' ``` ### Module Attributes | [`DEFAULT_SOURCE_STORE`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.DEFAULT_SOURCE_STORE) | The project store a shot's `options.source` is a key of. | |-------------------------------------------------------------------------|--------------------------------------------------------------------| | [`CONTACT_SHEET_STORE`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.CONTACT_SHEET_STORE) | Derived, content-keyed stores (see the module docstring). | | [`QUALITY_PRESETS`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.QUALITY_PRESETS) | Manim Community Edition's presets (`-ql` … `-qk`), smallest first. | ### Functions | [`choose_quality`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.choose_quality)(\*, fps, resolution) | The smallest Manim preset that is at least as tall and as fast as the film. | |----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------| | [`manim_environment`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.manim_environment)() | The Manim render's machine: Manim's stack, ffmpeg, LaTeX, fonts, the ISA. | | [`manim_shot_inputs`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.manim_shot_inputs)(shot, ctx) | The Manim renderer's [`ShotKeyer`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyer). | | [`store_source_resolver`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.store_source_resolver)([store]) | The default resolver: `options.source` is a key of the mall's `store`. | ### Classes | [`ManimQuality`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimQuality)(letter, width, height, fps) | One of Manim's quality presets: its letter, pixel size and frame rate. | |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`ManimRenderer`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimRenderer)(\*[, render_check, source_resolver]) | Manim Community Edition, through `manimkit`: an opaque-source shot renderer. | | [`ManimShotSpec`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimShotSpec)(source[, scene, quality, ...]) | What a Manim shot's `options` say, checked. | | [`SourceFile`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.SourceFile)(key, entry, closure, display) | A scene file and its closure, as a resolver read them. | ### Exceptions | [`ManimNotInstalledError`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimNotInstalledError) | `manim` / `manimkit` are not importable (`env.manim` is absent). | |---------------------------------------------------------------------------|--------------------------------------------------------------------| | [`ManimRenderError`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimRenderError) | A Manim shot could not be rendered. | ### an.adapters.manim_adapter.CONTACT_SHEET_STORE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'contact_sheets'* Derived, content-keyed stores (see the module docstring). ### an.adapters.manim_adapter.DEFAULT_SOURCE_STORE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'sources'* The project store a shot’s `options.source` is a key of. ### *exception* an.adapters.manim_adapter.ManimNotInstalledError Bases: [`ManimRenderError`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimRenderError), [`ImportError`](https://docs.python.org/3/builtins/exceptions.html#ImportError) `manim` / `manimkit` are not importable (`env.manim` is absent). ### *class* an.adapters.manim_adapter.ManimQuality(letter, width, height, fps) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One of Manim’s quality presets: its letter, pixel size and frame rate. ### *exception* an.adapters.manim_adapter.ManimRenderError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A Manim shot could not be rendered. Carries the [file:line](file:line) and the fix. ### *class* an.adapters.manim_adapter.ManimRenderer(, render_check=None, source_resolver=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Manim Community Edition, through `manimkit`: an opaque-source shot renderer. Implements [`Renderer`](_autosummary/an.adapters.html.md#an.adapters.Renderer) and `ClockOwningRenderer`. Seams: `render_check` (default `manimkit.render_check()`, imported on first use) and `source_resolver` (default: the project’s `sources` store, [`store_source_resolver()`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.store_source_resolver)). The shot cache keys a shot through the REGISTERED instance’s resolver; a subclass registers its own keyer (`register_shot_keyer(name, manim_shot_inputs, renderer_type=Sub)`). #### measure_duration(shot, ctx, , render=True, force=False) Manim’s length of this shot’s scene, from the `measurements` store, or rendered now (and stored) when there is none — or when `force`. * **Return type:** `DurationMeasurement` | [`None`](https://docs.python.org/3/builtins/constants.html#None) #### probe_frames(shot, ctx, times) The film’s frames of `shot` at each of `times`, from its STORED picture (an#347). Manim owns its clock and renders a whole scene at once, so `an probe` never runs it: the picture a render stored is conformed exactly as [`render()`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimRenderer.render) conforms it, and the frames showing at `times` are read out. With no stored picture it refuses, naming the render that stores one. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)] #### render(shot, ctx) Render `shot` for exactly `shot.duration` (`an.render` settles it to the measured length, or longer to hold for its narration). * **Return type:** [`RenderResult`](_autosummary/an.adapters.html.md#an.adapters.RenderResult) #### stored_reads(key, ctx) The read trace stored with picture `key` (`None`: none stored, or not recorded). Reads stores only; never renders. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### *class* an.adapters.manim_adapter.ManimShotSpec(source, scene=None, quality=None, background='#000000', timeout=600.0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a Manim shot’s `options` say, checked. ```pycon >>> ManimShotSpec.from_options({"source": "s", "quality": "z"}) Traceback (most recent call last): ... an.adapters.manim_adapter.ManimRenderError: options.quality must be one of ['l', 'm', 'h', 'p', 'k'] (Manim's presets), got 'z' ``` ### an.adapters.manim_adapter.QUALITY_PRESETS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [ManimQuality](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimQuality)]* *= {'h': ManimQuality(letter='h', width=1920, height=1080, fps=60), 'k': ManimQuality(letter='k', width=3840, height=2160, fps=60), 'l': ManimQuality(letter='l', width=854, height=480, fps=15), 'm': ManimQuality(letter='m', width=1280, height=720, fps=30), 'p': ManimQuality(letter='p', width=2560, height=1440, fps=60)}* Manim Community Edition’s presets (`-ql` … `-qk`), smallest first. ### *class* an.adapters.manim_adapter.SourceFile(key, entry, closure, display) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A scene file and its closure, as a resolver read them. `closure` is every file the render stages into its working directory — `{relative path: bytes}`, the entry file included as `entry` — and `digest` covers all of it, so a sibling module or an image the scene loads relatively is in the keys. `display` is how a finding names the entry (`assets/sources/chart.py`; never an absolute path). ### an.adapters.manim_adapter.choose_quality(, fps, resolution) The smallest Manim preset that is at least as tall and as fast as the film. The picture is then resampled and scaled to exactly the film’s rate and size, so a smaller preset would be upscaled (blur) or frame-doubled (judder). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> choose_quality(fps=15, resolution=(640, 360)), choose_quality(fps=30, resolution=(1920, 1080)) ('l', 'h') >>> choose_quality(fps=120, resolution=(8000, 4000)) # nothing is enough: the largest 'k' ``` ### an.adapters.manim_adapter.manim_environment() The Manim render’s machine: Manim’s stack, ffmpeg, LaTeX, fonts, the ISA. Python package versions (Manim draws with Cairo and Pango through pycairo and ManimPango, and writes with PyAV), the full `ffmpeg -version` banner (the conform and the encode), the LaTeX and dvisvgm builds (a formula’s glyphs), the installed font set, and the ISA and OS family. Never a path. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.adapters.manim_adapter.manim_shot_inputs(shot, ctx) The Manim renderer’s [`ShotKeyer`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyer). Named parts: `source` (every file of the sources folder the render stages), `manim` (the picture’s other inputs: entry, scene, Manim and manimkit versions, quality, LaTeX mode — `picture_inputs()`), `knobs` (fps, size, background and the encode: pixel format, x264 argv, scale filter, faststart), `audio` (the dialogue muxed under it and the frame count it is cut to — a held narration moves it), `code` (`render_code_digest()`) and `reads` (what the files the picture’s render read outside the sources folder hold NOW — `current_reads_digest()` of the trace stored with the picture; an#291). Raises what the render would for a bad shot. * **Return type:** [`ShotKeyInputs`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyInputs) ### an.adapters.manim_adapter.store_source_resolver(store='sources') The default resolver: `options.source` is a key of the mall’s `store`. * **Return type:** [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`ManimShotSpec`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.ManimShotSpec), [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]], [`SourceFile`](_autosummary/an.adapters.manim_adapter.html.md#an.adapters.manim_adapter.SourceFile)] ```pycon >>> resolve = store_source_resolver() >>> resolve(ManimShotSpec("chart"), {"sources": {"chart": b"x = 1"}}).data b'x = 1' ``` # _autosummary/an.adapters.remotion_adapter.html.md # an.adapters.remotion_adapter RemotionRenderer — invoke `npx remotion render` against a generated TSX project. Phase 6 skeleton. The full implementation needs a templated Remotion node project (package.json + Composition.tsx + Root.tsx) and per-shot TSX generation. For now the renderer raises a clear error when invoked, documenting what’s needed. ### Classes | [`RemotionRenderer`](_autosummary/an.adapters.remotion_adapter.html.md#an.adapters.remotion_adapter.RemotionRenderer)() | Remotion-based renderer (skeleton). | |-----------------------------------------------------------------------|---------------------------------------| ### Exceptions | [`RemotionRenderError`](_autosummary/an.adapters.remotion_adapter.html.md#an.adapters.remotion_adapter.RemotionRenderError) | Raised when a Remotion render fails. | |------------------------------------------------------------------------|----------------------------------------| ### *exception* an.adapters.remotion_adapter.RemotionRenderError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) Raised when a Remotion render fails. ### *class* an.adapters.remotion_adapter.RemotionRenderer Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Remotion-based renderer (skeleton). # _autosummary/an.adapters.whiteboard.html.md # an.adapters.whiteboard WhiteboardRenderer — stub for hand-drawn / chalkboard-style animation. Phase 6 ships the registry entry only. The real implementation will likely be a thin wrapper around the cutout backend with hand-drawn-styled assets (rough strokes, paper texture), or a Manim subclass with a chalkboard theme. A spike during v0.1 picks the direction. ### Classes | [`WhiteboardRenderer`](_autosummary/an.adapters.whiteboard.html.md#an.adapters.whiteboard.WhiteboardRenderer)() | Whiteboard-style renderer (stub). | |-------------------------------------------------------------------------|-------------------------------------| ### Exceptions | [`WhiteboardRenderError`](_autosummary/an.adapters.whiteboard.html.md#an.adapters.whiteboard.WhiteboardRenderError) | Raised by the whiteboard stub. | |--------------------------------------------------------------------------|----------------------------------| ### *exception* an.adapters.whiteboard.WhiteboardRenderError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) Raised by the whiteboard stub. ### *class* an.adapters.whiteboard.WhiteboardRenderer Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Whiteboard-style renderer (stub). # _autosummary/an.assemble.html.md # an.assemble Film assembly: rendered shots → one film, with transitions and a sound layer. Every shot renders in isolation (`an.render`); this module decides how the shots meet and what is heard over them. It runs only when a scene asks for it — a non-`cut` [`Transition`](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) or any [`SoundCue`](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue) — so a scene with neither takes the old `_ffmpeg_concat` path, byte for byte ([`needs_assembly()`](_autosummary/an.assemble.html.md#an.assemble.needs_assembly)). **Where each part happens, and why there.** - *Picture*: transitions are composed in the FRAME STAGE, on the per-shot PNGs, in exact integer arithmetic, and encoded by the same `an.media.mp4.mux_frames` every shot uses. Composing in ffmpeg (`xfade`) would decode already-encoded shots and re-encode them — a second generation of x264 loss on every frame of the film, not just the transition — and would retire the render pipeline’s “ffmpeg never touches a frame” clause. - *The picture is a stream-copy concat of SEGMENTS* (an#260), each encoded once from PNGs: a shot no transition touches is its own mp4’s video stream, copied; a shot a transition touches contributes the encoded span between its windows (its *body*) plus the PNGs inside them; each run of composed frames is encoded on its own. So a reused shot needs its mp4 (and, at a transition, its body and window PNGs, a few dozen frames) — never every frame it has ([`shot_windows()`](_autosummary/an.assemble.html.md#an.assemble.shot_windows), [`ShotParts`](_autosummary/an.assemble.html.md#an.assemble.ShotParts)). The film’s frame `i` is at `i / fps` and decodes to exactly what its segment decodes to (measured, an#260; [`MIN_SEGMENT_FRAMES`](_autosummary/an.assemble.html.md#an.assemble.MIN_SEGMENT_FRAMES) is why no segment is shorter than three). - *Sound*: the film’s audio is rebuilt from SOURCES — every dialogue line’s cached WAV and every cue’s asset, placed in film time — in one ffmpeg mix, then muxed onto the picture with `-c:v copy`. Mixing onto the shots’ already-encoded AAC would be a second audio generation for the dialogue. **The timeline is frame-exact.** Shot `i` occupies `frame_count(duration, fps)` frames (the renderer’s own rule) starting at film frame `FilmTimeline.starts` `[i]`; audio is placed at `start / fps` plus its shot-local time, so a line stays on the frames it was lip-synced to whatever the transitions do. ```pycon >>> from an.ir.schema import Shot, Transition >>> tl = film_timeline( ... [Shot(id="a", duration=2.0), ... Shot(id="b", duration=2.0, transition=Transition(kind="dissolve", duration=0.5))], ... fps=10, ... ) >>> tl.starts, tl.total_frames # b starts 5 frames early: the film is 0.5 s shorter ((0, 15), 35) ``` ### Module Attributes | [`MIN_SEGMENT_FRAMES`](_autosummary/an.assemble.html.md#an.assemble.MIN_SEGMENT_FRAMES) | The fewest frames a segment of a MULTI-segment picture may have. | |-----------------------------------------------------------------------|--------------------------------------------------------------------| ### Functions | [`assemble_film`](_autosummary/an.assemble.html.md#an.assemble.assemble_film)(scene, shot_results, output, ...) | Assemble rendered shots into `output`: the picture as a concat of segments (transitions composed in), then the mix. | |-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`duck_gain`](_autosummary/an.assemble.html.md#an.assemble.duck_gain)(t, spans, \*, duck_db, attack, release) | The linear gain a ducked cue plays at, at film time `t` — the spec the ffmpeg expressions (`_duck_expressions()`) are written from. | | [`film_duration`](_autosummary/an.assemble.html.md#an.assemble.film_duration)(scene, \*[, fps]) | Seconds the delivered film runs: the shots' durations, minus each dissolve's overlap. | | [`film_timeline`](_autosummary/an.assemble.html.md#an.assemble.film_timeline)(shots, \*, fps[, closing]) | Lay `shots` end to end, overlapping each dissolve, the last fading out by `closing` (the film's closing fade, an#389). | | [`needs_assembly`](_autosummary/an.assemble.html.md#an.assemble.needs_assembly)(scene, \*[, fps]) | True when the scene asks for anything beyond hard cuts and shot audio. | | [`picture_segments`](_autosummary/an.assemble.html.md#an.assemble.picture_segments)(timeline, windows) | The film's picture as segments, in film order. | | [`shot_parts`](_autosummary/an.assemble.html.md#an.assemble.shot_parts)(frames, window, \*, fps, work_dir) | A rendered shot's [`ShotParts`](_autosummary/an.assemble.html.md#an.assemble.ShotParts) for `window`, from its frames. | | [`shot_windows`](_autosummary/an.assemble.html.md#an.assemble.shot_windows)(timeline, \*[, min_segment_frames]) | Each shot's [`ShotWindow`](_autosummary/an.assemble.html.md#an.assemble.ShotWindow): the frames its transitions touch, widened until every segment of the picture has `min_segment_frames`. | | [`transition_problems`](_autosummary/an.assemble.html.md#an.assemble.transition_problems)(shots, fps, \*[, closing]) | Every reason these shots' transitions cannot be assembled, as `(shot index, message)`. | | [`write_film_frames`](_autosummary/an.assemble.html.md#an.assemble.write_film_frames)(timeline, frame_of, out_dir, \*) | Every frame of the film as a PNG, in `out_dir` — what the delivered picture shows, frame for frame, BEFORE it is encoded. | ### Classes | [`FilmTimeline`](_autosummary/an.assemble.html.md#an.assemble.FilmTimeline)(fps, frames, starts, ...[, ...]) | Where each shot's frames land in the film, and what blends them. | |--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`Segment`](_autosummary/an.assemble.html.md#an.assemble.Segment)(kind, shot, start, stop) | One independently encoded run of the film's picture, film frames `[start, stop)`: a whole shot's own stream (`"shot"`), a shot's encoded body (`"body"`), or a run of PNGs composed here (`"frames"`). | | [`ShotParts`](_autosummary/an.assemble.html.md#an.assemble.ShotParts)(window, frames[, body]) | What a film takes from a shot its transitions touch: the PNGs inside its [`ShotWindow`](_autosummary/an.assemble.html.md#an.assemble.ShotWindow) (`frames`: shot-local index -> path) and its body, encoded once (`body`; `None` when the window covers the shot). | | [`ShotWindow`](_autosummary/an.assemble.html.md#an.assemble.ShotWindow)(frames[, head, tail]) | Which of one shot's `frames` its film needs as PNGs: the first `head` and the last `tail`. | ### Exceptions | [`AssemblyError`](_autosummary/an.assemble.html.md#an.assemble.AssemblyError) | The shots cannot be assembled as the scene asks. | |------------------------------------------------------------------|----------------------------------------------------| ### *exception* an.assemble.AssemblyError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The shots cannot be assembled as the scene asks. Carries the fix. ### *class* an.assemble.FilmTimeline(fps, frames, starts, dissolve_in, fade_in, fade_out, fade_in_color, fade_out_color, total_frames, closing=False, wipe_in=()) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Where each shot’s frames land in the film, and what blends them. `dissolve_in[i]` — frames shot `i` overlaps the previous shot by. `fade_in[i]` — frames at shot `i`’s head that fade up from a colour. `fade_out[i]` — frames at shot `i`’s tail that fade to a colour (the NEXT shot’s fade colour, or the film’s closing fade’s on the last shot). `closing` — the last shot’s `fade_out` is the film’s closing fade (`Meta.closing_transition`, an#389), so its final frame IS the colour: no next shot reaches it instead. #### end_seconds(i) Film time just after shot `i`’s last frame. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) #### start_seconds(i) Film time of shot `i`’s first frame. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) #### wipe_in *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None), ...]* *= ()* Per shot, the direction its incoming overlap WIPES in (an#390); `None` for a dissolve (or no overlap). ### an.assemble.MIN_SEGMENT_FRAMES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 3* The fewest frames a segment of a MULTI-segment picture may have. Measured on ffmpeg 9.0.1 / libx264 with the pinned argv (an#260): a stream of three or more frames carries a two-frame B-pyramid decode delay (its first DTS is two frames before its first PTS) whatever its content, and a stream of one or two frames carries none. The concat demuxer offsets every file alike, so a delay-free segment between two delayed ones leaves the DTS going backwards; the muxer patches that with one-tick packets, and a constant-rate decode of the film then shows a frame twice. [`shot_windows()`](_autosummary/an.assemble.html.md#an.assemble.shot_windows) widens every short run instead, so each segment of a multi-segment picture has the delay. ### *class* an.assemble.Segment(kind, shot, start, stop) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One independently encoded run of the film’s picture, film frames `[start, stop)`: a whole shot’s own stream (`"shot"`), a shot’s encoded body (`"body"`), or a run of PNGs composed here (`"frames"`). ### *class* an.assemble.ShotParts(window, frames, body=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a film takes from a shot its transitions touch: the PNGs inside its [`ShotWindow`](_autosummary/an.assemble.html.md#an.assemble.ShotWindow) (`frames`: shot-local index -> path) and its body, encoded once (`body`; `None` when the window covers the shot). ### *class* an.assemble.ShotWindow(frames, head=0, tail=0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Which of one shot’s `frames` its film needs as PNGs: the first `head` and the last `tail`. Between them is the shot’s *body*, which the film takes as one encoded span. A shot with an empty window (`whole`) is taken as its own mp4’s video stream, so it needs no frame at all. ```pycon >>> w = ShotWindow(frames=10, head=0, tail=4) >>> w.whole, w.body, w.png_indices (False, (0, 6), (6, 7, 8, 9)) ``` #### *property* body *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), [int](https://docs.python.org/3/builtins/functions.html#int)]* the shot-local frames taken as one encoded span. * **Type:** `(first, stop)` #### *property* png_indices *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), ...]* The shot-local frames the film needs as PNGs. ### an.assemble.assemble_film(scene, shot_results, output, , fps, mall, work_dir, pix_fmt=None, parts=None) Assemble rendered shots into `output`: the picture as a concat of segments (transitions composed in), then the mix. `shot_results` are the renderers’ `RenderResult`s, in timeline order. A shot no transition touches contributes its mp4 alone. A shot one touches needs its :class:`ShotParts` for its [`shot_windows()`](_autosummary/an.assemble.html.md#an.assemble.shot_windows) window: pass them in `parts` (a reused shot’s come from the shot cache), or the shot’s `frame_manifest` must hold its frames, from which they are built. **Why not one mux of every frame**, as before an#260: the picture depended on every frame of every shot, so a film with a dissolve or a music bed could reuse no shot without caching all of its PNGs — hundreds of MB per 1080p shot. The segment concat puts frame `i` at `i / fps` exactly as the one mux did (measured, an#260), and each frame decodes to exactly what its own segment decodes to. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.assemble.duck_gain(t, spans, , duck_db, attack, release) The linear gain a ducked cue plays at, at film time `t` — the spec the ffmpeg expressions (`_duck_expressions()`) are written from. Full level away from dialogue; `duck_db` down while a line plays; a linear ramp over `attack` seconds BEFORE each line (so its first syllable is already clear) and `release` seconds after. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> spans = [(1.0, 2.0)] >>> [round(duck_gain(t, spans, duck_db=-20, attack=0.5, release=0.5), 3) ... for t in (0.0, 0.75, 1.5, 2.25, 3.0)] [1.0, 0.55, 0.1, 0.55, 1.0] ``` ### an.assemble.film_duration(scene, , fps=None) Seconds the delivered film runs: the shots’ durations, minus each dissolve’s overlap. Exactly `sum(durations)` for a scene without one, so every existing document’s arithmetic is unchanged. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> from an.ir.schema import SceneIR, Shot, Transition >>> film_duration(SceneIR(timeline=[Shot(id="a", duration=2.0), ... Shot(id="b", duration=2.0, transition=Transition(kind="dissolve", duration=0.5))])) 3.5 ``` ### an.assemble.film_timeline(shots, , fps, closing=None) Lay `shots` end to end, overlapping each dissolve, the last fading out by `closing` (the film’s closing fade, an#389). Raises [`AssemblyError`](_autosummary/an.assemble.html.md#an.assemble.AssemblyError) on any [`transition_problems()`](_autosummary/an.assemble.html.md#an.assemble.transition_problems). * **Return type:** [`FilmTimeline`](_autosummary/an.assemble.html.md#an.assemble.FilmTimeline) ### an.assemble.needs_assembly(scene, , fps=None) True when the scene asks for anything beyond hard cuts and shot audio. Decided on FRAMES at the render’s rate (`fps`, default the scene’s): a transition that rounds to zero frames asks for nothing, and must not cost a scene its byte-identical concat. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> from an.ir.schema import Meta, SceneIR, Shot, Transition >>> needs_assembly(SceneIR(timeline=[Shot(id="a"), Shot(id="b")])) False >>> needs_assembly(SceneIR(timeline=[ ... Shot(id="a"), Shot(id="b", transition=Transition(kind="fade", duration=0.0))])) False ``` ### an.assemble.picture_segments(timeline, windows) The film’s picture as segments, in film order. A film frame is part of a shot’s body when exactly one shot shows it and that frame is outside the shot’s window; every other frame (a blend, a fade, or a frame a window was widened over) is composed from PNGs. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Segment`](_autosummary/an.assemble.html.md#an.assemble.Segment)] ```pycon >>> from an.ir.schema import Shot, Transition >>> tl = film_timeline([Shot(id="a", duration=1.0), Shot(id="b", duration=1.0, ... transition=Transition(kind="dissolve", duration=0.4))], fps=10) >>> [(s.kind, s.shot, s.start, s.stop) for s in picture_segments(tl, shot_windows(tl))] [('body', 0, 0, 6), ('frames', None, 6, 10), ('body', 1, 10, 16)] ``` ### an.assemble.shot_parts(frames, window, , fps, work_dir, pix_fmt=None) A rendered shot’s [`ShotParts`](_autosummary/an.assemble.html.md#an.assemble.ShotParts) for `window`, from its frames. The body is encoded by `an.media.mp4.mux_frames` — the shot mux’s own encoder and argv — from the body’s PNGs, renumbered from zero in `work_dir`. The window’s PNGs are referenced where they are. * **Return type:** [`ShotParts`](_autosummary/an.assemble.html.md#an.assemble.ShotParts) ### an.assemble.shot_windows(timeline, , min_segment_frames=3) Each shot’s [`ShotWindow`](_autosummary/an.assemble.html.md#an.assemble.ShotWindow): the frames its transitions touch, widened until every segment of the picture has `min_segment_frames`. A pure function of the timeline, so the render loop, the shot cache and the garbage collector all agree on what a shot’s film needs from it. A picture of one segment has no minimum (there is nothing to concatenate). * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`ShotWindow`](_autosummary/an.assemble.html.md#an.assemble.ShotWindow), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> from an.ir.schema import Shot, Transition >>> d = Transition(kind="dissolve", duration=0.1) # one frame at 10 fps >>> tl = film_timeline([Shot(id="a", duration=1.0), Shot(id="b", duration=1.0, ... transition=d)], fps=10) >>> [(w.head, w.tail) for w in shot_windows(tl)] # the 1-frame run, widened to 3 [(0, 1), (3, 0)] ``` ### an.assemble.transition_problems(shots, fps, , closing=None) Every reason these shots’ transitions cannot be assembled, as `(shot index, message)`. The ONE list `an validate` reports and [`film_timeline()`](_autosummary/an.assemble.html.md#an.assemble.film_timeline) raises on, so the two cannot disagree. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> from an.ir.schema import Shot, Transition >>> transition_problems([Shot(id="a", transition=Transition(kind="dissolve"))], fps=30) [(0, "shot 'a' is the first shot, so a dissolve has nothing to dissolve from; use a fade (from a colour) or a cut")] ``` ### an.assemble.write_film_frames(timeline, frame_of, out_dir, , pattern=None) Every frame of the film as a PNG, in `out_dir` — what the delivered picture shows, frame for frame, BEFORE it is encoded. The film itself is a concat of segments (an#260) and never holds this sequence on disk; a measurement that needs the composed picture — the bench’s reference for an assembled scene (an#279) — builds it here, with the same per-frame composition (`_compose_frame()`) the segments use. `frame_of(i, j)` is the PNG of frame `j` of shot `i`. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)] # _autosummary/an.audio.cli.html.md # an.audio.cli `an voices ...` — browse a TTS provider’s voices from the shell (an#209). Thin string-typed wrappers dispatched by typer the way `an character ...` is; the business logic is [`browse_voices()`](_autosummary/an.audio.cli.html.md#an.audio.cli.browse_voices), a plain function over the provider factories. > an voices list –provider elevenlabs > an voices list –provider elevenlabs –search british > an voices list –provider mac_say > an voices rescore “He did not ask” # re-choose a line’s take from its cached takes > an voices reroll “He did not ask” # synthesize new takes for it (billed) The `voice_id` column is what a `voices`-store document’s `voice_id` takes. `rescore` and `reroll` are the only ways a recorded best-of-N take is replaced ([`an.audio.pipeline.retake_lines()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.retake_lines)); the next `an render` does the choosing, and prints what it will bill first. ### Functions | [`browse_voices`](_autosummary/an.audio.cli.html.md#an.audio.cli.browse_voices)([provider, search, make]) | The voices `provider` exposes, optionally filtered by `search`. | |--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`format_voices`](_autosummary/an.audio.cli.html.md#an.audio.cli.format_voices)(voices) | One line per voice: `voice_id name (labels)`. | | [`retake`](_autosummary/an.audio.cli.html.md#an.audio.cli.retake)(project, line, \*[, rescore, tts, make]) | Release the recorded takes of the lines of `project` containing `line`. | ### an.audio.cli.browse_voices(provider='elevenlabs', \*, search=None, make=) The voices `provider` exposes, optionally filtered by `search`. A provider whose `list_voices` takes `search` (ElevenLabs) filters on its server; for the others the filter is a case-insensitive substring over the name, id and labels. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`VoiceMeta`](_autosummary/an.audio.tts.html.md#an.audio.tts.VoiceMeta)] ```pycon >>> from an.audio.tts import VoiceMeta >>> class Fake: ... name = "fake" ... def list_voices(self): ... return [VoiceMeta("v1", "Ada", "fake"), VoiceMeta("v2", "Bob", "fake")] >>> [v.name for v in browse_voices("fake", search="ad", make=lambda _: Fake())] ['Ada'] ``` ### an.audio.cli.format_voices(voices) One line per voice: `voice_id name (labels)`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> from an.audio.tts import VoiceMeta >>> print(format_voices([VoiceMeta("abc", "Ada", "x", extra={"labels": {"accent": "british"}})])) abc Ada (accent=british) ``` ### an.audio.cli.retake(project, line, \*, rescore=False, tts='elevenlabs', make=) Release the recorded takes of the lines of `project` containing `line`. The plain-function core of `an voices rescore` / `an voices reroll`: see [`an.audio.pipeline.retake_lines()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.retake_lines). `tts` must be the provider the line is rendered with (its takes are keyed by it). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) # _autosummary/an.audio.effects.html.md # an.audio.effects Voice effects: a deterministic transform applied to a synthesized line (an#163). A voice document in the `voices` store may declare `effects`. Three exist: - `pitch_semitones` (an#163) — South Park raises its voices to sound like fourth graders; duration-preserving. - `tempo` (an#265) — a pitch-preserving speed ratio (`1.1` is 10% faster). `eleven_v3` ignores `voice_settings.speed` and no audio tag moves its rate, so a narrator that must run at 5.8 syllables/s, or an expressive voice that must be slowed to a serene pace, is re-timed here. Unlike the pitch effect it CHANGES the line’s duration. - `trim_silence` (an#254) — cut the silence before the first word and after the last, keeping a little of each (`true`, or `{threshold_db, keep_lead_s, keep_tail_s}`). A real voice pads a line: `eleven_v3` returned 1.6 s for “Hi!” — 0.4 s of breath before the word and 0.65 s of room tone after it — so the line started late and the next one ran past its shot. It CHANGES the line’s duration too, and it is OPT-IN: a voice that values its breaths (a style that keeps a performance’s natural artifacts) declares nothing, or a lower threshold, and keeps them. A raised voice or a fast narrator is a property of the *character*, not of the TTS provider, so it lives beside the voice the line already resolves through rather than in the IR. ```pycon >>> normalize_effects({"pitch_semitones": 4}) {'pitch_semitones': 4.0, 'chain_version': 2} >>> normalize_effects({"pitch_semitones": 0}) == normalize_effects({"tempo": 1}) == normalize_effects(None) == {} True >>> normalize_effects({"tempo": 1.1, "pitch_semitones": -2}) {'pitch_semitones': -2.0, 'tempo': 1.1, 'chain_version': 2} >>> round(_pitch_filter(12), 3) 0.5 >>> filter_chain({"tempo": 1.25}) 'aresample=44100,apad=pad_dur=0.25,atempo=1.250000000' >>> normalize_effects({"trim_silence": True})["trim_silence"] {'keep_lead_s': 0.1, 'keep_tail_s': 0.2, 'threshold_db': -20.0, 'version': 1} >>> normalize_effects({"trim_silence": False}) == {} True >>> normalize_effects({"reverb": 1}) Traceback (most recent call last): ... an.audio.effects.VoiceEffectError: unknown voice effect(s) ['reverb']; known: ['pitch_semitones', 'tempo', 'trim_silence'] ``` Design, in the order the pipeline uses it: - **The transform runs after synthesis and before alignment.** Lip-sync reads the audio the viewer hears. The pitch chain keeps the duration, so word timings computed on raw and on shifted audio agree to a frame; a `tempo` does not, which is why the shifted bytes are what is aligned, the line’s `duration` is read from them, and the viseme key derives from the effect-keyed audio key — visemes, word timings and captions all follow the audio the viewer hears. - **The cache keys on the effect.** `effects_key` is empty for no effect, and `an.audio.pipeline` adds it to the audio key only when it is non-empty, so a project that declares none keeps every key it ever had. - **Stock ffmpeg only.** The chain is `aresample → asetrate → aresample → atempo`: the sample rate is relabelled by the pitch ratio (pitch and speed both move) and `atempo` removes the speed change; a `tempo` multiplies into that same `atempo` factor (`aresample → atempo` alone when there is no pitch). A factor outside `atempo`’s clean `[0.5, 2]` is split into stages, each inside it; the pitch-only chain is one stage, character for character what it was before `tempo` existed. `rubberband` is a better shifter but is a build option, and its output would differ between machines — which a content-hash cache cannot tolerate. The output is bit-exact WAV (no encoder tag, no metadata), so two runs produce identical bytes. - **The trim runs last, in Python**, on the WAV the chain wrote (or on the synthesized audio, decoded by ffmpeg only when it is not 16-bit PCM WAV — ElevenLabs sends MP3): the level of each [`TRIM_WINDOW_S`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_WINDOW_S) window is compared with the line’s loudest, so a quiet voice and a loud one are cut alike, and the kept padding is in the seconds the viewer hears. Its parameters, resolved (defaults included) with [`TRIM_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_VERSION), are what the key holds, so a changed default re-trims instead of replaying. What it cut is RECORDED in the WAV it writes — a standard `LIST`/`INFO` comment after the samples, which every reader skips — and [`trim_record()`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_record) reads it back: the record travels with the bytes it describes and is collected with them. A line with nothing above the threshold (the offline voice’s silence) is left whole. ### Module Attributes | [`PITCH_SEMITONES_LIMIT`](_autosummary/an.audio.effects.html.md#an.audio.effects.PITCH_SEMITONES_LIMIT) | Effects a voice document may declare, with the range each accepts. | |--------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`TEMPO_LIMITS`](_autosummary/an.audio.effects.html.md#an.audio.effects.TEMPO_LIMITS) | half to double speed. | | [`ATEMPO_STAGE_LIMITS`](_autosummary/an.audio.effects.html.md#an.audio.effects.ATEMPO_STAGE_LIMITS) | One `atempo` stage's clean range; a factor beyond it is chained in stages. | | [`EFFECT_SAMPLE_RATE`](_autosummary/an.audio.effects.html.md#an.audio.effects.EFFECT_SAMPLE_RATE) | The sample rate the chain runs at (and the shifted WAV is written at). | | [`TRIM_SILENCE`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_SILENCE) | The effect that cuts a line's leading and trailing silence (an#254). | | [`DFLT_TRIM_THRESHOLD_DB`](_autosummary/an.audio.effects.html.md#an.audio.effects.DFLT_TRIM_THRESHOLD_DB) | `trim_silence`'s defaults. | | [`DFLT_TRIM_KEEP_LEAD_S`](_autosummary/an.audio.effects.html.md#an.audio.effects.DFLT_TRIM_KEEP_LEAD_S) | more than the lip-sync anticipation lead (2/24 s), so the mouth can open before the sound. | | [`DFLT_TRIM_KEEP_TAIL_S`](_autosummary/an.audio.effects.html.md#an.audio.effects.DFLT_TRIM_KEEP_TAIL_S) | a word's release and decay. | | [`TRIM_THRESHOLD_LIMITS`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_THRESHOLD_LIMITS) | `threshold_db` bounds (relative to the line's loudest window). | | [`TRIM_KEEP_LIMITS`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_KEEP_LIMITS) | `keep_lead_s` / `keep_tail_s` bounds, seconds. | | [`TRIM_WINDOW_S`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_WINDOW_S) | a change to it (or to anything else that moves a trimmed line's bytes) is a [`TRIM_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_VERSION) bump — a test pins the trim's output to the version (an#309). | | [`TRIM_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_VERSION) | Bumped whenever a trimmed line's bytes would change (algorithm, window, record tag, rounding); part of every trimmed line's key. | | [`CHAIN_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.CHAIN_VERSION) | The version of the ffmpeg chain every effected line passes (pitch, tempo, and the decode of a non-WAV line before its trim): its filters, rate ([`EFFECT_SAMPLE_RATE`](_autosummary/an.audio.effects.html.md#an.audio.effects.EFFECT_SAMPLE_RATE)), `atempo` stages and flags (an#309). | | [`TEMPO_PAD_S`](_autosummary/an.audio.effects.html.md#an.audio.effects.TEMPO_PAD_S) | Seconds of silence appended before the `atempo` stages, so their window never eats the line's tail (it dropped 20-40 ms of every short padded clip, an#350); the output is then cut to the exact length the tempo gives. | | [`TRIM_RECORD_TAG`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_RECORD_TAG) | The prefix of the `LIST`/`INFO` comment a trimmed WAV carries. | ### Functions | [`apply_voice_effects`](_autosummary/an.audio.effects.html.md#an.audio.effects.apply_voice_effects)(audio, effects) | `audio` (any container ffmpeg sniffs) with `effects` applied, as WAV bytes. | |--------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`atempo_stages`](_autosummary/an.audio.effects.html.md#an.audio.effects.atempo_stages)(factor, \*[, limits]) | `factor` as a product of `atempo` stages, each inside `limits`. | | [`decode_chain`](_autosummary/an.audio.effects.html.md#an.audio.effects.decode_chain)() | The chain that decodes a non-WAV line (MP3, from ElevenLabs) before its trim (part of [`CHAIN_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.CHAIN_VERSION)). | | [`ffmpeg_argv`](_autosummary/an.audio.effects.html.md#an.audio.effects.ffmpeg_argv)(chain, out_path, \*[, source_path]) | The argv that runs `chain` over audio on stdin into a bit-exact 16-bit PCM WAV at `out_path` (part of [`CHAIN_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.CHAIN_VERSION)). | | [`filter_chain`](_autosummary/an.audio.effects.html.md#an.audio.effects.filter_chain)(effects) | The ffmpeg `-af` chain for normalised `effects` (`""` for none). | | [`normalize_effects`](_autosummary/an.audio.effects.html.md#an.audio.effects.normalize_effects)(raw) | The canonical effects dict for a voice's `effects` value. | | [`speech_end`](_autosummary/an.audio.effects.html.md#an.audio.effects.speech_end)(audio, \*[, threshold_db, window_s]) | Seconds into `audio` at which its audible speech ends (an#397); `None` when silent or unreadable. | | [`trim_record`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_record)(wav) | What `trim_silence` cut from `wav` (`lead_s`, `tail_s`, `source_s`), read from the comment it wrote; `None` for audio it did not write. | | [`trim_silence`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_silence)(wav, \*[, threshold_db, ...]) | `wav` (16-bit PCM) cut to its speech, plus `keep_lead_s` before it and `keep_tail_s` after it, and the cut recorded in the WAV it returns. | | [`voice_effects`](_autosummary/an.audio.effects.html.md#an.audio.effects.voice_effects)(mall, voice_id) | The normalised effects declared by `mall["voices"][voice_id]`, or `{}`. | ### Classes | [`SilenceTrim`](_autosummary/an.audio.effects.html.md#an.audio.effects.SilenceTrim)(audio, lead_s, tail_s, source_s) | What [`trim_silence()`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_silence) produced: the trimmed WAV, and what it cut. | |-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| ### Exceptions | [`VoiceEffectError`](_autosummary/an.audio.effects.html.md#an.audio.effects.VoiceEffectError) | A voice declares an effect that is unknown, malformed or out of range. | |---------------------------------------------------------------------|--------------------------------------------------------------------------| ### an.audio.effects.ATEMPO_STAGE_LIMITS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= (0.5, 2.0)* One `atempo` stage’s clean range; a factor beyond it is chained in stages. ### an.audio.effects.CHAIN_VERSION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* The version of the ffmpeg chain every effected line passes (pitch, tempo, and the decode of a non-WAV line before its trim): its filters, rate ([`EFFECT_SAMPLE_RATE`](_autosummary/an.audio.effects.html.md#an.audio.effects.EFFECT_SAMPLE_RATE)), `atempo` stages and flags (an#309). Keyed only once it is not the first, so introducing it moved no key; bump it with any change to [`filter_chain()`](_autosummary/an.audio.effects.html.md#an.audio.effects.filter_chain), [`ffmpeg_argv()`](_autosummary/an.audio.effects.html.md#an.audio.effects.ffmpeg_argv) or their constants — a test pins them to the version. Moving the key re-processes each line from its raw take, which is cached: nothing is billed. 2 (an#350): silence padded before the `atempo` stages and the output cut to exactly `input / tempo` — `atempo` dropped the last 20-40 ms. ### an.audio.effects.DFLT_TRIM_KEEP_LEAD_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.1* more than the lip-sync anticipation lead (2/24 s), so the mouth can open before the sound. * **Type:** Kept before the first window above the threshold ### an.audio.effects.DFLT_TRIM_KEEP_TAIL_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.2* a word’s release and decay. * **Type:** Kept after the last window above it ### an.audio.effects.DFLT_TRIM_THRESHOLD_DB *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= -20.0* `trim_silence`’s defaults. A window is “speech” when its RMS level is within `threshold_db` of the line’s loudest window. Measured on two eleven_v3 lines (an#254): the breath before “Hi!” peaks 25 dB under the word and its room tone 35-40 dB under, while each word’s own edges stay within 20 dB — so -20 cuts the breath and the tail and keeps the word. Lower it (-45) to keep breaths. ### an.audio.effects.EFFECT_SAMPLE_RATE *= 44100* The sample rate the chain runs at (and the shifted WAV is written at). ### an.audio.effects.PITCH_SEMITONES_LIMIT *= 12.0* Effects a voice document may declare, with the range each accepts. ### *class* an.audio.effects.SilenceTrim(audio, lead_s, tail_s, source_s) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What [`trim_silence()`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_silence) produced: the trimmed WAV, and what it cut. #### lead_s *: [float](https://docs.python.org/3/builtins/functions.html#float)* Seconds cut before the kept audio, and after it. #### record() The record the trimmed WAV carries ([`trim_record()`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_record)). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float)] #### source_s *: [float](https://docs.python.org/3/builtins/functions.html#float)* The length of the audio before the trim, seconds. ### an.audio.effects.TEMPO_LIMITS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= (0.5, 2.0)* half to double speed. Outside it speech stops being speech. * **Type:** `tempo` bounds ### an.audio.effects.TEMPO_PAD_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.25* Seconds of silence appended before the `atempo` stages, so their window never eats the line’s tail (it dropped 20-40 ms of every short padded clip, an#350); the output is then cut to the exact length the tempo gives. Enough for the slowest stage of [`TEMPO_LIMITS`](_autosummary/an.audio.effects.html.md#an.audio.effects.TEMPO_LIMITS) at every pitch. ### an.audio.effects.TRIM_KEEP_LIMITS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= (0.0, 2.0)* `keep_lead_s` / `keep_tail_s` bounds, seconds. ### an.audio.effects.TRIM_RECORD_TAG *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'an:trim_silence '* The prefix of the `LIST`/`INFO` comment a trimmed WAV carries. ### an.audio.effects.TRIM_SILENCE *= 'trim_silence'* The effect that cuts a line’s leading and trailing silence (an#254). ### an.audio.effects.TRIM_THRESHOLD_LIMITS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= (-80.0, -3.0)* `threshold_db` bounds (relative to the line’s loudest window). ### an.audio.effects.TRIM_VERSION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 1* Bumped whenever a trimmed line’s bytes would change (algorithm, window, record tag, rounding); part of every trimmed line’s key. ### an.audio.effects.TRIM_WINDOW_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.02* a change to it (or to anything else that moves a trimmed line’s bytes) is a [`TRIM_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.TRIM_VERSION) bump — a test pins the trim’s output to the version (an#309). * **Type:** The level-measuring window, seconds. Not keyed itself ### *exception* an.audio.effects.VoiceEffectError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A voice declares an effect that is unknown, malformed or out of range. ### an.audio.effects.apply_voice_effects(audio, effects) `audio` (any container ffmpeg sniffs) with `effects` applied, as WAV bytes. Returns the input unchanged for no effects. Raises `VoiceEffectError` when ffmpeg is missing or fails — never returns unprocessed audio for a voice that asked for an effect. `trim_silence` alone on a 16-bit PCM WAV needs no ffmpeg ([`trim_silence()`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_silence)). * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) ### an.audio.effects.atempo_stages(factor, , limits=(0.5, 2.0)) `factor` as a product of `atempo` stages, each inside `limits`. One stage when `factor` already fits (the pitch-only chain, always). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`float`](https://docs.python.org/3/builtins/functions.html#float)] ```pycon >>> atempo_stages(1.5) [1.5] >>> atempo_stages(3.0) [2.0, 1.5] >>> atempo_stages(0.3) [0.5, 0.6] ``` ### an.audio.effects.decode_chain() The chain that decodes a non-WAV line (MP3, from ElevenLabs) before its trim (part of [`CHAIN_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.CHAIN_VERSION)). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.effects.ffmpeg_argv(chain, out_path, , source_path=None) The argv that runs `chain` over audio on stdin into a bit-exact 16-bit PCM WAV at `out_path` (part of [`CHAIN_VERSION`](_autosummary/an.audio.effects.html.md#an.audio.effects.CHAIN_VERSION)). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] source_path: also write the input, decoded ([`decode_chain()`](_autosummary/an.audio.effects.html.md#an.audio.effects.decode_chain)) and : untouched, there — in the same run, so its length is known whatever container came in (an#350: a tempo chain’s output is cut to it) ```pycon >>> ffmpeg_argv("aresample=44100", "o.wav")[-3:] ['-c:a', 'pcm_s16le', 'o.wav'] >>> ffmpeg_argv("atempo=2", "o.wav", source_path="s.wav")[-1] 's.wav' ``` ### an.audio.effects.filter_chain(effects) The ffmpeg `-af` chain for normalised `effects` (`""` for none). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.effects.normalize_effects(raw) The canonical effects dict for a voice’s `effects` value. Omit-when-unset: `None`, `{}` and a zero-valued effect all normalise to `{}`, which the pipeline treats as “no effect” (and keys nothing on). Unknown keys raise — an effect that silently does nothing is worse than none. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.audio.effects.speech_end(audio, , threshold_db=-20.0, window_s=0.02) Seconds into `audio` at which its audible speech ends (an#397); `None` when silent or unreadable. The end of the last `window_s` window whose RMS level is within `threshold_db` of the loudest window’s — [`trim_silence()`](_autosummary/an.audio.effects.html.md#an.audio.effects.trim_silence)’s rule, so a take’s own trailing silence (a provider pads ~0.3 s) is not counted. A 16-bit PCM WAV is read directly; any other container is decoded with ffmpeg when it is installed. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> import array, io, wave >>> rate = 8000 >>> samples = array.array("h", [9000, -9000] * (rate // 4) + [0] * rate) # 0.5 s, then 1 s silent >>> buf = io.BytesIO() >>> with wave.open(buf, "wb") as w: ... w.setnchannels(1); w.setsampwidth(2); w.setframerate(rate); w.writeframes(samples.tobytes()) >>> round(speech_end(buf.getvalue()), 2) 0.5 ``` ### an.audio.effects.trim_record(wav) What `trim_silence` cut from `wav` (`lead_s`, `tail_s`, `source_s`), read from the comment it wrote; `None` for audio it did not write. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float)] | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.effects.trim_silence(wav, , threshold_db=-20.0, keep_lead_s=0.1, keep_tail_s=0.2, window_s=0.02) `wav` (16-bit PCM) cut to its speech, plus `keep_lead_s` before it and `keep_tail_s` after it, and the cut recorded in the WAV it returns. Speech is every `window_s` window whose RMS level is within `threshold_db` of the loudest window’s; only the edges move, never a pause between words. A clip with no sound at all is returned whole (with the record of a zero cut), and a pad is never longer than the silence it keeps. * **Return type:** [`SilenceTrim`](_autosummary/an.audio.effects.html.md#an.audio.effects.SilenceTrim) ```pycon >>> import array, io, math, wave >>> rate = 8000 >>> tone = [int(9000 * math.sin(i / 3)) for i in range(rate // 2)] >>> samples = array.array("h", [0] * rate + tone + [0] * rate) # 1 s, 0.5 s, 1 s >>> buf = io.BytesIO() >>> with wave.open(buf, "wb") as w: ... w.setnchannels(1); w.setsampwidth(2); w.setframerate(rate) ... w.writeframes(samples.tobytes()) >>> cut = trim_silence(buf.getvalue(), keep_lead_s=0.1, keep_tail_s=0.2) >>> round(cut.lead_s, 2), round(cut.tail_s, 2), round(cut.source_s, 2) (0.9, 0.8, 2.5) >>> trim_record(cut.audio) == cut.record() True >>> with wave.open(io.BytesIO(cut.audio)) as w: ... round(w.getnframes() / w.getframerate(), 2) 0.8 ``` ### an.audio.effects.voice_effects(mall, voice_id) The normalised effects declared by `mall["voices"][voice_id]`, or `{}`. A voice that is not in the store (the offline default, a raw provider voice id) has no effects; so does a store that does not exist. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] # _autosummary/an.audio.elevenlabs_tts.html.md # an.audio.elevenlabs_tts ElevenLabsTTS — real speech via the ElevenLabs API. Requires ELEVEN_API_KEY. Lazily imports the elevenlabs SDK so the rest of `an` works without it. If you want real speech, `pip install elevenlabs` and set `ELEVEN_API_KEY` (or `ELEVENLABS_API_KEY`) in your environment. **Expressive voices (an#209).** A voice document in the `voices` store may declare, beside `voice_id`, the `model_id` it speaks with, its `voice_settings` and a sampling `seed`; a dialogue line’s `[emotion]` and `{direction}` reach a model that takes inline audio tags (`eleven_v3`, `eleven_v4` and their variants) as `[excited] Hi!`. [`ElevenLabsTTS.synthesis_options()`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.ElevenLabsTTS.synthesis_options) turns those into the keyword arguments [`ElevenLabsTTS.synthesize()`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.ElevenLabsTTS.synthesize) takes — the audio pipeline keys its cache on exactly that dict, and a voice declaring none of them yields `{}`, so no existing cache key moves. ```pycon >>> tts = ElevenLabsTTS(api_key="unused") >>> tts.synthesis_options({}) {} >>> tts.synthesis_options({"model_id": "eleven_v3"}, emotion="happy", direction=["sighs"]) {'model_id': 'eleven_v3', 'audio_tags': ['happy', 'sighs']} >>> tts.synthesis_options({"voice_settings": {"stability": 0.3, "speed": 1.1}}) {'voice_settings': {'speed': 1.1, 'stability': 0.3}} >>> tagged_text("Hi!", ["excited"]) '[excited] Hi!' ``` ### Module Attributes | [`AUDIO_TAG_MODEL_PREFIXES`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.AUDIO_TAG_MODEL_PREFIXES) | Model ids that read inline audio tags (`[excited]`, `[sighs]`). | |-----------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| | [`VOICE_SETTINGS_RANGES`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.VOICE_SETTINGS_RANGES) | The `voice_settings` keys the API takes, with the range each accepts (`None` = a boolean). | ### Functions | [`normalize_voice_settings`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.normalize_voice_settings)(raw) | The canonical `voice_settings` dict — only what was declared, key-sorted. | |---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | [`tagged_text`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.tagged_text)(text, tags) | `text` with each tag prefixed as `[tag]` — what an audio-tag model reads. | | [`takes_audio_tags`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.takes_audio_tags)(model_id, \*[, prefixes]) | Whether `model_id` reads inline audio tags. | ### Classes | [`ElevenLabsTTS`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.ElevenLabsTTS)(\*[, api_key, model_id, ...]) | ElevenLabs-backed TTSProvider. | |------------------------------------------------------------------------------------------------|----------------------------------| ### Exceptions | [`ElevenLabsUnavailableError`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.ElevenLabsUnavailableError) | A request cannot be sent: no API key is configured. | |-------------------------------------------------------------------------------|-------------------------------------------------------------------| | [`ElevenLabsVoiceError`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.ElevenLabsVoiceError) | A voice document declares ElevenLabs settings that are malformed. | ### an.audio.elevenlabs_tts.AUDIO_TAG_MODEL_PREFIXES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('eleven_v3', 'eleven_v4')* Model ids that read inline audio tags (`[excited]`, `[sighs]`). Matched as prefixes, so `eleven_v3_conversational` and `eleven_v4_turbo` count. Every other model would speak the brackets, so it never receives a tag. ### *class* an.audio.elevenlabs_tts.ElevenLabsTTS(, api_key=None, model_id='eleven_turbo_v2_5', output_format='mp3_44100_128', audio_tag_model_prefixes=('eleven_v3', 'eleven_v4'), client_factory=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) ElevenLabs-backed TTSProvider. Constructor takes an optional api_key (falls back to `ELEVEN_API_KEY` / `ELEVENLABS_API_KEY`). Implements the `TTSProvider` protocol, plus the optional `synthesis_options` hook the audio pipeline reads (an#209). #### billed *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* what may never run in memory). * **Type:** Every request is charged (an#311 #### billed_characters(text, , audio_tags=None, \*\*\_options) Characters one request bills: the text as sent, audio tags included. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> ElevenLabsTTS(api_key="unused").billed_characters("Hi!", audio_tags=["excited"]) 13 ``` #### check_available() Raise [`ElevenLabsUnavailableError`](_autosummary/an.audio.elevenlabs_tts.html.md#an.audio.elevenlabs_tts.ElevenLabsUnavailableError) when a request could not be sent (no API key) — what the audio pipeline asks before the first request of a render, so nothing is half-synthesized (an#305). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) #### client_factory `api_key -> client`; tests inject a fake so nothing reaches the API. #### list_voices(, search=None) The account’s voices (its own plus the ones it saved), newest API. `search` filters by name, description and labels on the server. An absent key or SDK yields `[]`; a key that is present and a call that fails RAISES — an empty listing must mean “no voices”, not “it broke”. * **Return type:** [`Iterable`](https://docs.python.org/3/library/typing.html#typing.Iterable)[[`VoiceMeta`](_autosummary/an.audio.tts.html.md#an.audio.tts.VoiceMeta)] #### synthesis_options(voice, , emotion=None, direction=None) The `synthesize` keyword arguments a voice document and a line imply. Only what is declared appears (`{}` for a plain voice), so the audio cache key — which includes this dict when it is non-empty — is unchanged for every voice that declares nothing new. `audio_tags` are the line’s `[emotion]` (unless `neutral`) then its `direction` cues, and only on a model that reads tags; elsewhere a direction is dropped with a warning and the emotion stays a face-only cue, as before. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] #### synthesize(text, voice_id=None, , model_id=None, voice_settings=None, seed=None, audio_tags=None, \*\*kw) Speak `text`. The clip’s `transcript` is `text` WITHOUT the tags, so alignment and captions never read a cue. * **Return type:** [`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip) #### take_options(options, take) The request for candidate `take` of a best-of-N line ([`an.audio.takes`](_autosummary/an.audio.takes.html.md#module-an.audio.takes)). A declared `seed` is offset by the take, so a model that does honour it (every model but `eleven_v3`, measured) still returns different takes; without a seed the request is unchanged and the model’s own sampling varies the take. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> ElevenLabsTTS(api_key="unused").take_options({"seed": 11}, 2) {'seed': 13} ``` ### *exception* an.audio.elevenlabs_tts.ElevenLabsUnavailableError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A request cannot be sent: no API key is configured. ### *exception* an.audio.elevenlabs_tts.ElevenLabsVoiceError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A voice document declares ElevenLabs settings that are malformed. ### an.audio.elevenlabs_tts.VOICE_SETTINGS_RANGES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)] | [None](https://docs.python.org/3/builtins/constants.html#None)]* *= {'similarity_boost': (0.0, 1.0), 'speed': (0.7, 1.2), 'stability': (0.0, 1.0), 'style': (0.0, 1.0), 'use_speaker_boost': None}* The `voice_settings` keys the API takes, with the range each accepts (`None` = a boolean). `speed` is the API’s documented 0.7–1.2. ### an.audio.elevenlabs_tts.normalize_voice_settings(raw) The canonical `voice_settings` dict — only what was declared, key-sorted. Omit-when-unset: `None` and `{}` give `{}`. Unknown keys and values out of range raise, so a typo cannot silently fall back to the account default. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> normalize_voice_settings({"style": 1, "stability": 0.25}) {'stability': 0.25, 'style': 1.0} >>> normalize_voice_settings({"stabilty": 0.5}) Traceback (most recent call last): ... an.audio.elevenlabs_tts.ElevenLabsVoiceError: unknown voice_settings key(s) ['stabilty']; known: ['similarity_boost', 'speed', 'stability', 'style', 'use_speaker_boost'] ``` ### an.audio.elevenlabs_tts.tagged_text(text, tags) `text` with each tag prefixed as `[tag]` — what an audio-tag model reads. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.elevenlabs_tts.takes_audio_tags(model_id, , prefixes=('eleven_v3', 'eleven_v4')) Whether `model_id` reads inline audio tags. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> takes_audio_tags("eleven_v3"), takes_audio_tags("eleven_turbo_v2_5") (True, False) ``` # _autosummary/an.audio.html.md # an.audio Audio pipeline — TTS and lip-sync providers + orchestration. Phase 3 ships: - Protocols: `TTSProvider`, `LipSyncProvider` (Phase 1). - Default offline provider: `OfflineTTS` (silent WAV). The lip-sync providers (`OfflineLipSync` deterministic char-to-viseme, `RhubarbLipSync`, `WhisperLipSync`) moved to `cutan` with the cut-out genre (an#225); the old names still resolve from here, with a warning. - Real providers: `ElevenLabsTTS` (needs `ELEVEN_API_KEY`). - Orchestration: `produce_audio_for_dialogue` / `produce_audio_for_scene` walk a SceneIR, synthesize, persist to mall, stamp viseme tracks back onto the IR. The defaults are intentionally offline so the entire `an` pipeline works without external services. ### Functions | [`word_timings_to_visemes`](_autosummary/an.audio.html.md#an.audio.word_timings_to_visemes)(words, \*, ...[, ...]) | Distribute viseme keyframes across word boundaries. | |----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`default_tts`](_autosummary/an.audio.html.md#an.audio.default_tts)() | The default TTS provider: `OfflineTTS`. | | [`default_lipsync`](_autosummary/an.audio.html.md#an.audio.default_lipsync)() | The default lip-sync provider: the loaded genre's `offline` one (the deterministic char-to-viseme provider of `cutan`), else [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync). | | [`produce_audio_for_dialogue`](_autosummary/an.audio.html.md#an.audio.produce_audio_for_dialogue)(dialogue[, mall, ...]) | Synthesize audio + visemes for one dialogue line. | | [`produce_audio_for_scene`](_autosummary/an.audio.html.md#an.audio.produce_audio_for_scene)(scene[, mall, tts, ...]) | Walk every dialogue line, synthesize, and stamp viseme tracks back. | | [`make_tts`](_autosummary/an.audio.html.md#an.audio.make_tts)(name) | Instantiate a TTS provider by name. | | [`make_lipsync`](_autosummary/an.audio.html.md#an.audio.make_lipsync)(name, \*[, language]) | Instantiate a LipSync provider by name. | | [`known_tts_names`](_autosummary/an.audio.html.md#an.audio.known_tts_names)() | Return the registered TTS provider names. | | [`known_lipsync_names`](_autosummary/an.audio.html.md#an.audio.known_lipsync_names)() | Return the registered LipSync provider names. | ### Classes | [`TTSProvider`](_autosummary/an.audio.html.md#an.audio.TTSProvider)(\*args, \*\*kwargs) | Text-to-speech provider. | |----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | [`AudioClip`](_autosummary/an.audio.html.md#an.audio.AudioClip)([path, bytes_, duration, ...]) | A rendered audio clip, on disk or in memory. | | [`VoiceMeta`](_autosummary/an.audio.html.md#an.audio.VoiceMeta)(voice_id, name, provider[, ...]) | Metadata for a TTS voice as exposed by a provider. | | [`LipSyncProvider`](_autosummary/an.audio.html.md#an.audio.LipSyncProvider)(\*args, \*\*kwargs) | Audio + transcript → aligned viseme track. | | [`Viseme`](_autosummary/an.audio.html.md#an.audio.Viseme)(time, code[, intensity]) | A single mouth-shape keyframe. | | [`VisemeTrack`](_autosummary/an.audio.html.md#an.audio.VisemeTrack)([visemes, convention, duration, ...]) | Aligned viseme sequence produced by a LipSyncProvider. | | [`WordTimingProvider`](_autosummary/an.audio.html.md#an.audio.WordTimingProvider)(\*args, \*\*kwargs) | Audio → `[(word, start_s, end_s), ...]`. | | [`NullLipSync`](_autosummary/an.audio.html.md#an.audio.NullLipSync)() | The lip-sync provider of a core without a genre: no mouth shapes at all. | | [`OfflineTTS`](_autosummary/an.audio.html.md#an.audio.OfflineTTS)(\*[, sample_rate, channels, ...]) | Default TTS provider: silent WAV of length proportional to text. | | [`ElevenLabsTTS`](_autosummary/an.audio.html.md#an.audio.ElevenLabsTTS)(\*[, api_key, model_id, ...]) | ElevenLabs-backed TTSProvider. | | [`MacSayTTS`](_autosummary/an.audio.html.md#an.audio.MacSayTTS)(\*[, default_voice_id, ...]) | macOS `say`-backed TTSProvider. | ### *class* an.audio.AudioClip(path=None, bytes_=None, duration=0.0, sample_rate=44100, channels=1, voice_id=None, transcript=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A rendered audio clip, on disk or in memory. ### *class* an.audio.ElevenLabsTTS(, api_key=None, model_id='eleven_turbo_v2_5', output_format='mp3_44100_128', audio_tag_model_prefixes=('eleven_v3', 'eleven_v4'), client_factory=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) ElevenLabs-backed TTSProvider. Constructor takes an optional api_key (falls back to `ELEVEN_API_KEY` / `ELEVENLABS_API_KEY`). Implements the `TTSProvider` protocol, plus the optional `synthesis_options` hook the audio pipeline reads (an#209). #### billed *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* what may never run in memory). * **Type:** Every request is charged (an#311 #### billed_characters(text, , audio_tags=None, \*\*\_options) Characters one request bills: the text as sent, audio tags included. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> ElevenLabsTTS(api_key="unused").billed_characters("Hi!", audio_tags=["excited"]) 13 ``` #### check_available() Raise `ElevenLabsUnavailableError` when a request could not be sent (no API key) — what the audio pipeline asks before the first request of a render, so nothing is half-synthesized (an#305). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) #### client_factory `api_key -> client`; tests inject a fake so nothing reaches the API. #### list_voices(, search=None) The account’s voices (its own plus the ones it saved), newest API. `search` filters by name, description and labels on the server. An absent key or SDK yields `[]`; a key that is present and a call that fails RAISES — an empty listing must mean “no voices”, not “it broke”. * **Return type:** [`Iterable`](https://docs.python.org/3/library/typing.html#typing.Iterable)[[`VoiceMeta`](_autosummary/an.audio.tts.html.md#an.audio.tts.VoiceMeta)] #### synthesis_options(voice, , emotion=None, direction=None) The `synthesize` keyword arguments a voice document and a line imply. Only what is declared appears (`{}` for a plain voice), so the audio cache key — which includes this dict when it is non-empty — is unchanged for every voice that declares nothing new. `audio_tags` are the line’s `[emotion]` (unless `neutral`) then its `direction` cues, and only on a model that reads tags; elsewhere a direction is dropped with a warning and the emotion stays a face-only cue, as before. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] #### synthesize(text, voice_id=None, , model_id=None, voice_settings=None, seed=None, audio_tags=None, \*\*kw) Speak `text`. The clip’s `transcript` is `text` WITHOUT the tags, so alignment and captions never read a cue. * **Return type:** [`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip) #### take_options(options, take) The request for candidate `take` of a best-of-N line ([`an.audio.takes`](_autosummary/an.audio.takes.html.md#module-an.audio.takes)). A declared `seed` is offset by the take, so a model that does honour it (every model but `eleven_v3`, measured) still returns different takes; without a seed the request is unchanged and the model’s own sampling varies the take. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> ElevenLabsTTS(api_key="unused").take_options({"seed": 11}, 2) {'seed': 13} ``` ### *class* an.audio.LipSyncProvider(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Audio + transcript → aligned viseme track. A provider that fills `VisemeTrack.words` also declares `emits_word_timings = True` (a plain class attribute, absent means False). The audio pipeline reads it to decide whether a line whose `word_timings` are missing needs re-alignment — without the flag, a provider that cannot supply words would re-align every line forever. #### align(audio, transcript) Produce a viseme track for `audio` given its `transcript`. * **Return type:** [`VisemeTrack`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.VisemeTrack) ### *class* an.audio.MacSayTTS(, default_voice_id='Samantha', sample_rate=22050, rate_wpm=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) macOS `say`-backed TTSProvider. Implements the `TTSProvider` protocol. Audible, deterministic, and fully offline — uses Apple’s voice synthesis bundled with the OS. #### billed *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* an#311). * **Type:** Costs nothing per request (stated, never inferred #### repeatable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* The same request gives the same audio, so best-of-N takes never apply ([`an.audio.takes.voice_takes()`](_autosummary/an.audio.takes.html.md#an.audio.takes.voice_takes)) and nothing is billed. ### *class* an.audio.NullLipSync Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The lip-sync provider of a core without a genre: no mouth shapes at all. A genre that animates mouths (`cutan`) registers real providers (`offline`, `rhubarb`, `whisper`); without one, a line’s audio is still synthesized and the track it gets is empty – nothing draws a mouth anyway. ```pycon >>> NullLipSync().align(AudioClip(bytes_=b"", duration=0.5), "hi").duration 0.5 ``` #### repeatable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* a reader of the cache keys may run it in memory (an#311). * **Type:** The same request gives the same track, and nothing is billed ### *class* an.audio.OfflineTTS(, sample_rate=22050, channels=1, seconds_per_char=0.06) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Default TTS provider: silent WAV of length proportional to text. Implements the `TTSProvider` protocol. #### billed *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* an#311). * **Type:** Costs nothing per request (stated, never inferred #### repeatable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* The same request gives the same audio, so best-of-N takes never apply ([`an.audio.takes.voice_takes()`](_autosummary/an.audio.takes.html.md#an.audio.takes.voice_takes)) and nothing is billed. #### silent *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* a line it speaks for a voice written for a real provider is a stand-in the render says so loudly (an#305). * **Type:** Its audio is silence ### *class* an.audio.TTSProvider(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Text-to-speech provider. #### list_voices() Return all voices the provider exposes. * **Return type:** [`Iterable`](https://docs.python.org/3/library/typing.html#typing.Iterable)[[`VoiceMeta`](_autosummary/an.audio.tts.html.md#an.audio.tts.VoiceMeta)] #### synthesize(text, voice_id, \*\*kw) Render `text` in `voice_id`’s voice. Returns an AudioClip. * **Return type:** [`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip) ### *class* an.audio.Viseme(time, code, intensity=1.0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A single mouth-shape keyframe. ### *class* an.audio.VisemeTrack(visemes=, convention='rhubarb', duration=0.0, words=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Aligned viseme sequence produced by a LipSyncProvider. `words` carries the word timings the provider aligned from, when it had any (whisper, `WordTimingsLipSync`); `None` for providers that never see words (offline, Rhubarb — whose JSON is mouth cues only). Retained since an#96 rather than discarded after the viseme conversion: captions (Wave 8) and any consumer that wants to know *which word* a mouth shape belongs to read them from the IR. ### *class* an.audio.VoiceMeta(voice_id, name, provider, language='en', gender=None, extra=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Metadata for a TTS voice as exposed by a provider. ### *class* an.audio.WordTimingProvider(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Audio → `[(word, start_s, end_s), ...]`. Implementations may run a transcriber (Whisper / Scribe) or look up pre-computed timings (`muvid`’s lacing store). Returned tuples are expected to be in ascending start-time order; gaps between words are fine and represent silence the lipsync provider should rest through. #### words_for(audio, , transcript='') Return the word timings for `audio`. * **Return type:** [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)]] ### an.audio.default_lipsync() The default lip-sync provider: the loaded genre’s `offline` one (the deterministic char-to-viseme provider of `cutan`), else [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync). * **Return type:** [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider) ```pycon >>> default_lipsync().name in {"offline", "none"} True ``` ### an.audio.default_tts() The default TTS provider: `OfflineTTS`. * **Return type:** [`TTSProvider`](_autosummary/an.audio.tts.html.md#an.audio.tts.TTSProvider) ### an.audio.known_lipsync_names() Return the registered LipSync provider names. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.audio.known_tts_names() Return the registered TTS provider names. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.audio.make_lipsync(name, , language='en') Instantiate a LipSync provider by name. `language` (BCP-47) reaches providers that select behaviour by language — Rhubarb’s recognizer today; a future aligner’s weight allowlist. The default name (`"offline"`) resolves to [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync) when no loaded genre provides it, so voicing a line needs no genre; any other name that nothing provides is an error that says how to get it. * **Return type:** [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider) ```pycon >>> make_lipsync("offline").name in {"offline", "none"} True ``` ### an.audio.make_tts(name) Instantiate a TTS provider by name. Raises `ValueError` for unknown names with a list of known options. * **Return type:** [`TTSProvider`](_autosummary/an.audio.tts.html.md#an.audio.tts.TTSProvider) ### an.audio.produce_audio_for_dialogue(dialogue, mall=None, \*, tts=None, lipsync=None, effects=None, voice_id=None, takes=, take_scorer=) Synthesize audio + visemes for one dialogue line. Side effects: when `mall` is provided, persists the WAV to `mall["audio"]` keyed by the content-hash of the dialogue, and persists the viseme JSON to `mall["visemes"]` similarly. Cache-friendly: a second call with identical inputs returns the cached versions. `effects` (default: what the line’s voice declares in `mall["voices"]`) is applied to the synthesized audio BEFORE alignment, so the visemes are computed on the audio the viewer hears. The raw synthesis stays cached under its own key, so changing an effect never re-pays the TTS. `tts` (default: the provider the voice document declares, else offline — `tts_chooser()`) is an override when given. `voice_id` (default: the line’s `voice_ref`, else `"default"`) is the `voices`-store key; [`produce_audio_for_scene()`](_autosummary/an.audio.html.md#an.audio.produce_audio_for_scene) passes the one [`an.audio.voices.line_voice_id()`](_autosummary/an.audio.voices.html.md#an.audio.voices.line_voice_id) resolves, so a character’s bound voice reaches here (an#194). The provider is handed the voice document’s own voice id when it names one. What the provider’s optional `synthesis_options` hook derives from the voice document and the line (ElevenLabs: `model_id`, `voice_settings`, `seed`, and the `[emotion]`/`direction` audio tags — an#209) is passed to `synthesize` and keyed; the text handed to alignment is always the bare `dialogue.text`, never the tagged one. `takes` (default: what the voice declares for this line — see [`an.audio.takes`](_autosummary/an.audio.takes.html.md#module-an.audio.takes); `None` forces one take) synthesizes several takes, scores each with `take_scorer(spec)` on the audio the viewer hears, keeps the best and records the choice in `mall["takes"]`. A recorded choice is restored from the record and never re-rolled; a recorded take whose audio is gone raises [`TakeLostError`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeLostError) before any request. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip), [`VisemeTrack`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.VisemeTrack)] ### an.audio.produce_audio_for_scene(scene, mall=None, \*, tts=None, lipsync=None, take_scorer=, announce=, overruns=True, strict=False, tts_factory=None) Walk every dialogue line, synthesize, and stamp viseme tracks back. Mutates the `scene` in place AND returns it (for chaining). Stamps `Dialogue.duration`, `Dialogue.viseme_track`, and `Dialogue.audio_ref` (mall[“audio”] key) so the renderer can find the audio later. Lines with an existing viseme_track AND audio_ref are not re-synthesized (idempotent). `Dialogue.start` is DERIVED on every pass, synthesized or not, by `Dialogue.planned_start()`: the line’s `at` if set, else the previous line’s end plus its `pause` (an#187). So editing a pause re-times the shot without touching the audio, and every consumer of `start` — the mux, the visemes, captions, ducking — follows. A `start` on a line that was never synthesized is an authored start from before `at` existed, and is kept as the line’s `at`. Every line’s request is resolved BEFORE anything is synthesized, so a malformed voice (an effect, a `takes`), a corrupt takes record or a recorded take whose audio is gone fails before a credit is spent; and `announce` (default: a line on stderr; `None` for silence) is told, before the first request, what best-of-N takes will bill (requests and the provider’s characters) and which recorded takes were chosen by an older scorer version than the current one (they are kept). After synthesis, a line that ends past its shot’s end (`dialogue_overruns()`) is announced too — or, with `announce=None`, a `DialogueOverrunWarning` — unless `overruns=False`: `an render` passes that, because it reports every post-synthesis finding together in its summary (an#254). **Who speaks each line** (an#305, `tts_chooser()`): with `tts` not given (`None`, `""` or `VOICE_TTS`), the line’s voice document’s `provider`, built by `tts_factory` (default [`an.audio.providers.make_tts()`](_autosummary/an.audio.providers.html.md#an.audio.providers.make_tts)), else offline; a `tts` given speaks every line. A line spoken by another provider than its voice declares is a `VoiceStandInWarning` — the silent offline voice says so — and, with `strict`, a `VoiceStandInError` before any request. A provider with requests to send is asked `check_available()` first (ElevenLabs: is there a key?), and what a provider that bills per character will bill is announced before the first request — whatever chose the provider; a cached line is never billed and never counted. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ### an.audio.word_timings_to_visemes(words, , total_duration, char_to_viseme, rest_viseme='X', min_gap_for_rest=0.2) Distribute viseme keyframes across word boundaries. Used by `WhisperLipSync` and `WordTimingsLipSync`. The algorithm: per word, walk its characters in order, look up each character’s viseme code, dedupe consecutive identical codes, and space the resulting keyframes evenly across the word’s `[start, end]` interval. In gaps wider than `min_gap_for_rest` — between two words, or after the last one before `total_duration` — insert a single rest keyframe just after the previous word ended. Times are clamped to `[0, total_duration]` since some transcribers occasionally round the last word’s end past the audio’s actual length. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Viseme`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.Viseme)] ### Modules | [`cli`](_autosummary/an.audio.cli.html.md#module-an.audio.cli) | `an voices ...` — browse a TTS provider's voices from the shell (an#209). | |------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | [`effects`](_autosummary/an.audio.effects.html.md#module-an.audio.effects) | Voice effects: a deterministic transform applied to a synthesized line (an#163). | | [`elevenlabs_tts`](_autosummary/an.audio.elevenlabs_tts.html.md#module-an.audio.elevenlabs_tts) | ElevenLabsTTS — real speech via the ElevenLabs API. | | [`lipsync`](_autosummary/an.audio.lipsync.html.md#module-an.audio.lipsync) | Lip-sync provider protocol + viseme dataclasses. | | [`loudness`](_autosummary/an.audio.loudness.html.md#module-an.audio.loudness) | Voice loudness: one integrated loudness for every voice of a film (an#315). | | [`mac_say_tts`](_autosummary/an.audio.mac_say_tts.html.md#module-an.audio.mac_say_tts) | MacSayTTS — audible offline speech via macOS's built-in `say` command. | | [`offline_tts`](_autosummary/an.audio.offline_tts.html.md#module-an.audio.offline_tts) | OfflineTTS — produces silent audio of plausible duration. | | [`pipeline`](_autosummary/an.audio.pipeline.html.md#module-an.audio.pipeline) | Audio pipeline orchestration: dialogue → audio → visemes → IR mutation. | | [`providers`](_autosummary/an.audio.providers.html.md#module-an.audio.providers) | Provider factory: name → concrete TTS/LipSync provider instance. | | [`takes`](_autosummary/an.audio.takes.html.md#module-an.audio.takes) | Best-of-N takes: re-roll a line, score every take, keep the best, record the choice. | | [`tts`](_autosummary/an.audio.tts.html.md#module-an.audio.tts) | TTS provider protocol + supporting dataclasses. | | [`voices`](_autosummary/an.audio.voices.html.md#module-an.audio.voices) | Which voice speaks a dialogue line: the character → voice binding (an#194). | # _autosummary/an.audio.lipsync.html.md # an.audio.lipsync Lip-sync provider protocol + viseme dataclasses. Viseme conventions are renderer-agnostic in the IR; concrete providers in later phases (Rhubarb, Azure, MFA) emit their own letter/number encodings, which the cutout adapter then maps to mouth-slot attachments. Two protocols live here: - [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider) — the head-to-toe pipeline (“audio + transcript → visemes”). Owns its own transcription if it needs one. Most cutout callers go through this. - [`WordTimingProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.WordTimingProvider) — the narrower “audio → word timings” contract. Lets external callers (e.g. `muvid`, with its own lyric alignment store) skip a redundant transcription pass and feed timings directly into `WordTimingsLipSync`. ### Module Attributes | [`WordTiming`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.WordTiming) | One word's slice in time. | |---------------------------------------------------------------|-----------------------------| ### Functions | [`word_timings_to_visemes`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.word_timings_to_visemes)(words, \*, ...[, ...]) | Distribute viseme keyframes across word boundaries. | |---------------------------------------------------------------------------------------------------|-------------------------------------------------------| ### Classes | [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider)(\*args, \*\*kwargs) | Audio + transcript → aligned viseme track. | |----------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------| | [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync)() | The lip-sync provider of a core without a genre: no mouth shapes at all. | | [`Viseme`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.Viseme)(time, code[, intensity]) | A single mouth-shape keyframe. | | [`VisemeTrack`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.VisemeTrack)([visemes, convention, duration, ...]) | Aligned viseme sequence produced by a LipSyncProvider. | | [`WordTimingProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.WordTimingProvider)(\*args, \*\*kwargs) | Audio → `[(word, start_s, end_s), ...]`. | ### *class* an.audio.lipsync.LipSyncProvider(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Audio + transcript → aligned viseme track. A provider that fills `VisemeTrack.words` also declares `emits_word_timings = True` (a plain class attribute, absent means False). The audio pipeline reads it to decide whether a line whose `word_timings` are missing needs re-alignment — without the flag, a provider that cannot supply words would re-align every line forever. #### align(audio, transcript) Produce a viseme track for `audio` given its `transcript`. * **Return type:** [`VisemeTrack`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.VisemeTrack) ### *class* an.audio.lipsync.NullLipSync Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The lip-sync provider of a core without a genre: no mouth shapes at all. A genre that animates mouths (`cutan`) registers real providers (`offline`, `rhubarb`, `whisper`); without one, a line’s audio is still synthesized and the track it gets is empty – nothing draws a mouth anyway. ```pycon >>> NullLipSync().align(AudioClip(bytes_=b"", duration=0.5), "hi").duration 0.5 ``` #### repeatable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* a reader of the cache keys may run it in memory (an#311). * **Type:** The same request gives the same track, and nothing is billed ### *class* an.audio.lipsync.Viseme(time, code, intensity=1.0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A single mouth-shape keyframe. ### *class* an.audio.lipsync.VisemeTrack(visemes=, convention='rhubarb', duration=0.0, words=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Aligned viseme sequence produced by a LipSyncProvider. `words` carries the word timings the provider aligned from, when it had any (whisper, `WordTimingsLipSync`); `None` for providers that never see words (offline, Rhubarb — whose JSON is mouth cues only). Retained since an#96 rather than discarded after the viseme conversion: captions (Wave 8) and any consumer that wants to know *which word* a mouth shape belongs to read them from the IR. ### an.audio.lipsync.WordTiming One word’s slice in time. Tuple form keeps providers cheap. alias of [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)] ### *class* an.audio.lipsync.WordTimingProvider(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Audio → `[(word, start_s, end_s), ...]`. Implementations may run a transcriber (Whisper / Scribe) or look up pre-computed timings (`muvid`’s lacing store). Returned tuples are expected to be in ascending start-time order; gaps between words are fine and represent silence the lipsync provider should rest through. #### words_for(audio, , transcript='') Return the word timings for `audio`. * **Return type:** [`Sequence`](https://docs.python.org/3/library/typing.html#typing.Sequence)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)]] ### an.audio.lipsync.word_timings_to_visemes(words, , total_duration, char_to_viseme, rest_viseme='X', min_gap_for_rest=0.2) Distribute viseme keyframes across word boundaries. Used by `WhisperLipSync` and `WordTimingsLipSync`. The algorithm: per word, walk its characters in order, look up each character’s viseme code, dedupe consecutive identical codes, and space the resulting keyframes evenly across the word’s `[start, end]` interval. In gaps wider than `min_gap_for_rest` — between two words, or after the last one before `total_duration` — insert a single rest keyframe just after the previous word ended. Times are clamped to `[0, total_duration]` since some transcribers occasionally round the last word’s end past the audio’s actual length. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Viseme`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.Viseme)] # _autosummary/an.audio.loudness.html.md # an.audio.loudness Voice loudness: one integrated loudness for every voice of a film (an#315). TTS providers deliver voices at very different levels — measured on a four-voice ElevenLabs episode: -16.4, -35.5, -28.4 and -23.4 LUFS, a 19 dB spread that left one character barely audible. `meta.voice_loudness` ([`VoiceLoudness`](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness)) asks for one level for all of them: - each voice’s integrated loudness (EBU R128 / ITU-R BS.1770, measured by ffmpeg’s `ebur128` over ALL of that voice’s lines in the film, back to back: a 0.6 s line has a single 400 ms gating block, and a voice’s own dynamics between lines — a whisper, a shout — are kept); - ONE gain per voice, `target - measured` plus the voice document’s `loudness_offset_db`, rounded to [`GAIN_STEP_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.GAIN_STEP_DB), then a lookahead peak limiter at `peak_db` ([`limit_peaks()`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.limit_peaks): a sample never passes the ceiling, and the gain eases into and out of a peak rather than clipping); - the result is DERIVED audio, content-keyed in the `audio` store by (the line’s audio, the gain, the ceiling, [`LEVEL_VERSION`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.LEVEL_VERSION)) — never a re-synthesis, never billed — and the line is stamped with it, so the per-shot mux, the film mix and every cache key follow it. The gain changes no timing: lip-sync, word timings and durations are the source line’s. A voice whose lines are silence (the offline provider) is left as it is. A voice whose lines are all short is measured looped ([`MIN_MEASURE_S`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MIN_MEASURE_S)). The gain is capped at [`MAX_GAIN_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MAX_GAIN_DB), and a voice that ends more than [`MISS_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MISS_WARNING_DB) from its target (capped, or held down by its peaks) is warned about. `peak_db` is a SAMPLE-peak ceiling: an AAC encode can still overshoot it between samples by a fraction of a dB, so keep a margin. The gain and the source are stamped on each line (`Dialogue.leveled`): a render whose voice is unchanged reuses them without decoding or measuring anything, and a re-measure that moves the gain by less than a step keeps the previous gain (hysteresis), so one new line rarely re-renders a voice’s other shots. Without a target, [`loudness_report()`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.loudness_report) measures the voices and [`voice_loudness_spread()`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.voice_loudness_spread) says when they differ by more than [`SPREAD_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SPREAD_WARNING_DB) — the render warns, naming each voice’s level. ```pycon >>> float(limit_peaks(__import__("numpy").array([[0.0], [2.0], [0.0]]), ceiling=1.0).max()) 1.0 ``` ### Module Attributes | [`LEVEL_VERSION`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.LEVEL_VERSION) | Bumped whenever a leveled line's bytes would change for the same inputs (the limiter, its window, the encoding); part of every leveled line's key. | |--------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`GAIN_STEP_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.GAIN_STEP_DB) | A voice's gain is rounded to this, so a new line that moves its voice's loudness by less than half of it re-renders nothing else (half a dB is below what a listener hears between two lines; the measurement itself is to 0.1 LU). | | [`SILENCE_LUFS`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SILENCE_LUFS) | never leveled. | | [`SPREAD_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SPREAD_WARNING_DB) | Voices further apart than this, with no target set, are warned about. | | [`LIMITER_WINDOW_S`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.LIMITER_WINDOW_S) | the gain eases into a peak and back out over this much on each side, so nothing below ~20 Hz is modulated within a cycle (a 5 ms release distorted anything under 100 Hz, an#315 review). | | [`MAX_GAIN_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MAX_GAIN_DB) | The largest gain leveling gives a voice; beyond it the voice is mostly noise (room tone measured at -62 LUFS asked for +46 dB). | | [`OFFSET_LIMITS_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.OFFSET_LIMITS_DB) | `loudness_offset_db` bounds on a voice document. | | [`MIN_MEASURE_S`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MIN_MEASURE_S) | EBU R128 gates in 400 ms blocks, and a voice of only short lines would read as silence. | | [`MISS_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MISS_WARNING_DB) | A leveled voice that ends further than this from its target (the limiter held its peaks, or the gain was capped) is warned about. | ### Functions | [`integrated_loudness`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.integrated_loudness)(pcm) | EBU R128 integrated loudness (LUFS) of `pcm`, by ffmpeg's `ebur128` (`-inf` for silence). | |----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`level_voices`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.level_voices)(scene, mall, spec) | Level every voice of `scene` to `spec` ([`VoiceLoudness`](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness)): each line is stamped with its leveled audio (made once per source bytes, gain and ceiling, in the `audio` store) and `Dialogue.leveled`. | | [`leveled_audio`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.leveled_audio)(audio, \*, gain_db, peak_db) | `audio` at `gain_db`, its peaks held at `peak_db` dBFS, as a 16-bit PCM WAV of exactly the length of the decoded source (an MP3 source is stored decoded, as the mux would decode it). | | [`leveled_key`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.leveled_key)(source, \*, gain_db, peak_db) | The content key of a leveled line: the sha256 of its source audio's BYTES (not the request that made them: a take re-synthesised under the same request is other audio, an#315 review), the gain, the ceiling, the rate a non-WAV source is decoded at, and [`LEVEL_VERSION`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.LEVEL_VERSION). | | [`limit_peaks`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.limit_peaks)(samples, \*, ceiling[, window]) | `samples` with no sample above `ceiling` (absolute, full scale 1.0). | | [`loudness_report`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.loudness_report)(scene, mall) | Every voice's integrated loudness over its lines, as heard now (a leveled line's leveled audio). | | [`voice_loudness_spread`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.voice_loudness_spread)(levels) | What to say when the audible voices differ by more than [`SPREAD_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SPREAD_WARNING_DB); `None` otherwise. | | [`voiced_lines`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.voiced_lines)(scene, mall) | `{voice id: [line, ...]}` for every line with audio in the store. | | [`voiced_sources`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.voiced_sources)(scene, mall) | [`voiced_lines()`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.voiced_lines), by each line's SOURCE audio (a leveled line's own). | ### Classes | [`VoiceLevel`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.VoiceLevel)(voice, lufs[, gain_db, lines]) | One voice's measured loudness, and the gain leveling gives it. | |----------------------------------------------------------------------------------------------|------------------------------------------------------------------| ### Exceptions | [`VoiceLoudnessError`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.VoiceLoudnessError) | The voices cannot be measured or leveled (no ffmpeg, an unreadable line). | |-----------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------| | [`VoiceLoudnessWarning`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.VoiceLoudnessWarning) | The film's voices differ in loudness by more than [`SPREAD_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SPREAD_WARNING_DB). | ### an.audio.loudness.GAIN_STEP_DB *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.5* A voice’s gain is rounded to this, so a new line that moves its voice’s loudness by less than half of it re-renders nothing else (half a dB is below what a listener hears between two lines; the measurement itself is to 0.1 LU). ### an.audio.loudness.LEVEL_VERSION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 1* Bumped whenever a leveled line’s bytes would change for the same inputs (the limiter, its window, the encoding); part of every leveled line’s key. A test pins the leveled output to it. ### an.audio.loudness.LIMITER_WINDOW_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.05* the gain eases into a peak and back out over this much on each side, so nothing below ~20 Hz is modulated within a cycle (a 5 ms release distorted anything under 100 Hz, an#315 review). * **Type:** The limiter’s lookahead and release, seconds ### an.audio.loudness.MAX_GAIN_DB *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 24.0* The largest gain leveling gives a voice; beyond it the voice is mostly noise (room tone measured at -62 LUFS asked for +46 dB). Capped, and warned. ### an.audio.loudness.MIN_MEASURE_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 1.0* EBU R128 gates in 400 ms blocks, and a voice of only short lines would read as silence. * **Type:** A voice shorter than this is measured looped to this length ### an.audio.loudness.MISS_WARNING_DB *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 1.0* A leveled voice that ends further than this from its target (the limiter held its peaks, or the gain was capped) is warned about. ### an.audio.loudness.OFFSET_LIMITS_DB *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= (-12.0, 12.0)* `loudness_offset_db` bounds on a voice document. ### an.audio.loudness.SILENCE_LUFS *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= -70.0* never leveled. * **Type:** Below this a voice is silence (BS.1770’s absolute gate) ### an.audio.loudness.SPREAD_WARNING_DB *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 6.0* Voices further apart than this, with no target set, are warned about. ### *class* an.audio.loudness.VoiceLevel(voice, lufs, gain_db=0.0, lines=0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One voice’s measured loudness, and the gain leveling gives it. ### *exception* an.audio.loudness.VoiceLoudnessError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The voices cannot be measured or leveled (no ffmpeg, an unreadable line). ### *exception* an.audio.loudness.VoiceLoudnessWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) The film’s voices differ in loudness by more than [`SPREAD_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SPREAD_WARNING_DB). ### an.audio.loudness.integrated_loudness(pcm) EBU R128 integrated loudness (LUFS) of `pcm`, by ffmpeg’s `ebur128` (`-inf` for silence). * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ### an.audio.loudness.level_voices(scene, mall, spec) Level every voice of `scene` to `spec` ([`VoiceLoudness`](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness)): each line is stamped with its leveled audio (made once per source bytes, gain and ceiling, in the `audio` store) and `Dialogue.leveled`. Returns each voice’s level; warns ([`VoiceLoudnessWarning`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.VoiceLoudnessWarning)) about a voice it had to cap or could not bring within [`MISS_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.MISS_WARNING_DB). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`VoiceLevel`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.VoiceLevel)] ### an.audio.loudness.leveled_audio(audio, , gain_db, peak_db) `audio` at `gain_db`, its peaks held at `peak_db` dBFS, as a 16-bit PCM WAV of exactly the length of the decoded source (an MP3 source is stored decoded, as the mux would decode it). * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) ### an.audio.loudness.leveled_key(source, , gain_db, peak_db) The content key of a leveled line: the sha256 of its source audio’s BYTES (not the request that made them: a take re-synthesised under the same request is other audio, an#315 review), the gain, the ceiling, the rate a non-WAV source is decoded at, and [`LEVEL_VERSION`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.LEVEL_VERSION). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> leveled_key(b"a", gain_db=1.0, peak_db=-1.5) != leveled_key(b"a", gain_db=1.1, peak_db=-1.5) True ``` ### an.audio.loudness.limit_peaks(samples, , ceiling, window=1) `samples` with no sample above `ceiling` (absolute, full scale 1.0). The gain each sample needs (`ceiling / |x|`, at most 1) is spread over `window` samples on both sides — a sliding minimum over `2 * window + 1`, then a moving average over `window` — so it eases into and out of a peak. Every sample’s gain is at most what that sample needs, so the ceiling holds exactly; nothing moves in time. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.audio.loudness.loudness_report(scene, mall) Every voice’s integrated loudness over its lines, as heard now (a leveled line’s leveled audio). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`VoiceLevel`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.VoiceLevel)] ### an.audio.loudness.voice_loudness_spread(levels) What to say when the audible voices differ by more than [`SPREAD_WARNING_DB`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.SPREAD_WARNING_DB); `None` otherwise. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.loudness.voiced_lines(scene, mall) `{voice id: [line, ...]}` for every line with audio in the store. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.audio.loudness.voiced_sources(scene, mall) [`voiced_lines()`](_autosummary/an.audio.loudness.html.md#an.audio.loudness.voiced_lines), by each line’s SOURCE audio (a leveled line’s own). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] # _autosummary/an.audio.mac_say_tts.html.md # an.audio.mac_say_tts MacSayTTS — audible offline speech via macOS’s built-in `say` command. Free, local, no API keys, no Python deps. macOS-only. The `say` binary ships with every macOS install since at least 10.4. Voices are listed by `say -v '?'` and can be passed as `voice_id`; common defaults: `"Samantha"`, `"Daniel"`, `"Karen"`, `"Alex"`. Output is 16-bit little-endian PCM WAV at 22050 Hz so the rest of the audio pipeline (which prefers WAV) can read frames + duration directly. ```pycon >>> tts = MacSayTTS() >>> tts.name 'mac_say' ``` ### Classes | [`MacSayTTS`](_autosummary/an.audio.mac_say_tts.html.md#an.audio.mac_say_tts.MacSayTTS)(\*[, default_voice_id, ...]) | macOS `say`-backed TTSProvider. | |-------------------------------------------------------------------------------------------|-----------------------------------| ### Exceptions | [`MacSayTTSError`](_autosummary/an.audio.mac_say_tts.html.md#an.audio.mac_say_tts.MacSayTTSError) | Raised when the `say` subprocess fails. | |-------------------------------------------------------------------|-------------------------------------------| ### *class* an.audio.mac_say_tts.MacSayTTS(, default_voice_id='Samantha', sample_rate=22050, rate_wpm=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) macOS `say`-backed TTSProvider. Implements the `TTSProvider` protocol. Audible, deterministic, and fully offline — uses Apple’s voice synthesis bundled with the OS. #### billed *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* an#311). * **Type:** Costs nothing per request (stated, never inferred #### repeatable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* The same request gives the same audio, so best-of-N takes never apply ([`an.audio.takes.voice_takes()`](_autosummary/an.audio.takes.html.md#an.audio.takes.voice_takes)) and nothing is billed. ### *exception* an.audio.mac_say_tts.MacSayTTSError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) Raised when the `say` subprocess fails. # _autosummary/an.audio.offline_tts.html.md # an.audio.offline_tts OfflineTTS — produces silent audio of plausible duration. No network, no keys. This is the **default** TTS provider for `an`. It’s honest about being silent (it doesn’t pretend to speak), but it produces a real WAV file with the right duration so the rest of the pipeline (lip-sync, rendering, mp4 muxing) runs end-to-end without any API setup. Use `ElevenLabsTTS` for real speech once you’ve set `ELEVEN_API_KEY`. ```pycon >>> tts = OfflineTTS() >>> clip = tts.synthesize("Hello, world!", voice_id="default") >>> clip.duration > 0.0 True >>> clip.transcript 'Hello, world!' ``` ### Functions | [`estimate_speech_duration`](_autosummary/an.audio.offline_tts.html.md#an.audio.offline_tts.estimate_speech_duration)(text, \*[, ...]) | Seconds the offline voice takes to say `text` — a leading pad plus a per-character rate over the non-space characters, clamped. | |----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| ### Classes | [`OfflineTTS`](_autosummary/an.audio.offline_tts.html.md#an.audio.offline_tts.OfflineTTS)(\*[, sample_rate, channels, ...]) | Default TTS provider: silent WAV of length proportional to text. | |-------------------------------------------------------------------------------------------------|--------------------------------------------------------------------| ### *class* an.audio.offline_tts.OfflineTTS(, sample_rate=22050, channels=1, seconds_per_char=0.06) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Default TTS provider: silent WAV of length proportional to text. Implements the `TTSProvider` protocol. #### billed *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* an#311). * **Type:** Costs nothing per request (stated, never inferred #### repeatable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* The same request gives the same audio, so best-of-N takes never apply ([`an.audio.takes.voice_takes()`](_autosummary/an.audio.takes.html.md#an.audio.takes.voice_takes)) and nothing is billed. #### silent *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* a line it speaks for a voice written for a real provider is a stand-in the render says so loudly (an#305). * **Type:** Its audio is silence ### an.audio.offline_tts.estimate_speech_duration(text, , seconds_per_char=0.06) Seconds the offline voice takes to say `text` — a leading pad plus a per-character rate over the non-space characters, clamped. It is exactly what an offline render gives a line (before a voice’s `tempo`, which `an validate` divides it by), so `an validate` uses it to warn about a shot too short for its dialogue BEFORE anything is synthesized. A real voice is usually a little slower, so for one this is an under-estimate: a line it says overruns will overrun. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> round(estimate_speech_duration("It only takes exact change."), 3) 1.43 ``` # _autosummary/an.audio.pipeline.html.md # an.audio.pipeline Audio pipeline orchestration: dialogue → audio → visemes → IR mutation. Phase 3 wires the pieces together. `produce_audio_for_scene` walks every `Dialogue` in the scene, synthesizes its audio + viseme track via the configured providers, persists artifacts to `mall["audio"]` / `mall["visemes"]`, and stamps the resulting `VisemeTrack` and timing back onto the `Dialogue` line so renderers can find it. **Who speaks a line** (an#305): with no `tts` given, each line’s voice document decides — its `provider` ([`an.audio.voices.declared_provider()`](_autosummary/an.audio.voices.html.md#an.audio.voices.declared_provider)) — and a voice that names none is spoken by the offline provider (silent WAV; lip-sync defaults to deterministic offline visemes), so a project that declares no provider runs without API keys or external binaries, exactly as before. A `tts` given is an override for every line; a line spoken by another provider than its voice declares is a [`VoiceStandInWarning`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VoiceStandInWarning) (an error under `strict`). See [`tts_chooser()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.tts_chooser). ```pycon >>> from an.audio.pipeline import default_tts, default_lipsync >>> default_tts().name 'offline' ``` ### Module Attributes | [`VOICE_TTS`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VOICE_TTS) | The `tts` that means "each line's voice document names its provider" — the default of a render (an#305). | |------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------| | [`DEFAULT_TTS_NAME`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.DEFAULT_TTS_NAME) | Who speaks a line whose voice declares no provider, when no `tts` overrides it. | | [`TakeScorerFactory`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.TakeScorerFactory) | `(TakesSpec) -> TakeScorer` — the seam that turns a takes spec into its scorer. | | [`OVERRUN_TOLERANCE_S`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.OVERRUN_TOLERANCE_S) | a frame at 60 fps (the same as `an validate`'s). | | [`AUDIO_OUTPUT_STORES`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.AUDIO_OUTPUT_STORES) | The stores the audio pipeline writes what it makes to. | | [`REROLL_ONLY_HINT`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.REROLL_ONLY_HINT) | only a new roll (new keys) replaces it. | | [`LEGACY_DURATION_TOLERANCE_S`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.LEGACY_DURATION_TOLERANCE_S) | How far a legacy sidecar's duration may sit from its audio's and still be the same take: a frame at 60 fps. | ### Functions | [`audio_key`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.audio_key)(text, voice_id, tts_name[, ...]) | Content key of a line's audio: text, voice, provider, and — only when the voice declares them — its effects, the provider voice it names (an#194), the provider's synthesis options (model, settings, seed, audio tags — an#209). | |----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`default_lipsync`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.default_lipsync)() | The default lip-sync provider: the loaded genre's `offline` one (the deterministic char-to-viseme provider of `cutan`), else [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync). | | [`default_tts`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.default_tts)() | The default TTS provider: `OfflineTTS`. | | [`dialogue_overruns`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.dialogue_overruns)(scene, \*[, tolerance_s, mall]) | One message per synthesized line that ends past its shot's end. | | [`free_and_repeatable`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.free_and_repeatable)(provider) | Whether `provider` may be run where nothing may be spent or written (an#311): it DECLARES `repeatable = True` (the same request gives the same bytes: `offline`, `mac_say`) and `billed = False` — stated, never inferred from a missing method — and has no `billed_characters` hook. | | [`in_memory_audio_mall`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.in_memory_audio_mall)(mall) | `mall` with its audio and visemes stores behind [`InMemoryOverlay`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.InMemoryOverlay) s — hand it to [`stamp_from_stores()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.stamp_from_stores) (`free_in_memory=True`) and then to whatever keys the stamped scene (an#311). | | [`is_voice_tts`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.is_voice_tts)(tts) | Whether `tts` means "each voice's own provider": `None`, `""` or [`VOICE_TTS`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VOICE_TTS). | | [`produce_audio_for_dialogue`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.produce_audio_for_dialogue)(dialogue[, mall, ...]) | Synthesize audio + visemes for one dialogue line. | | [`produce_audio_for_scene`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.produce_audio_for_scene)(scene[, mall, tts, ...]) | Walk every dialogue line, synthesize, and stamp viseme tracks back. | | [`retake_lines`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.retake_lines)(scene, mall, match, \*, tts[, ...]) | Mark the recorded takes of the lines whose text contains `match` to be chosen again on the next render; one message per matching line. | | [`retime_dialogue`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.retime_dialogue)(scene, \*[, timed_shots_only]) | Stamp every synthesized line's `start` from its `pause` / `at`. | | [`stamp_from_stores`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.stamp_from_stores)(scene, mall, \*[, tts, ...]) | Stamp `scene`'s dialogue exactly as [`produce_audio_for_scene()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.produce_audio_for_scene) would with these providers — `tts` as it takes it: `None` for each voice's own (an#305) — from the content-keyed `audio` and `visemes` stores only. | | [`synthesis_options`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.synthesis_options)(tts, line, mall, voice_id) | The provider-specific `synthesize` kwargs for `line` in `voice_id`. | | [`takes_cost_message`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.takes_cost_message)(lines, tts, audio_store) | What synthesizing `lines` with `tts` will bill, when any of them takes best-of-N or `tts` bills per character (an#305: a voice that names a paid provider is spoken by it with no flag, so its cost is said first); else `""`. | | [`tts_chooser`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.tts_chooser)(tts, mall, \*[, make]) | `voice_id -> provider`: who speaks a line in that voice (an#305). | | [`viseme_key`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.viseme_key)(audio_key_, lipsync_name, transcript) | Content key of a line's viseme track (a function of the audio HEARD). | | [`voice_stand_ins`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.voice_stand_ins)(lines, mall, \*, overridden) | One message per voice whose lines are spoken by another provider than its document declares; `lines` is `(voice_id, provider)` per line, and `overridden` says whether a `tts` was given for every line. | ### Classes | [`InMemoryOverlay`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.InMemoryOverlay)(store) | A store view that reads through and keeps every write IN MEMORY: what a reader of a render's cache keys stamps free audio into (an#311), so the keys it computes next see that audio while the store itself is untouched. | |---------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ### Exceptions | [`AudioNotCachedError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.AudioNotCachedError) | A line's audio (or its visemes) is not in the content-keyed stores, so stamping it would need a synthesis this caller does not allow. | |-------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | [`AudioPipelineError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.AudioPipelineError) | The scene declares audio the pipeline cannot produce. | | [`DialogueOverrunWarning`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.DialogueOverrunWarning) | A synthesized line runs past its shot's end, so its tail is cut. | | [`TakeDigestWarning`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.TakeDigestWarning) | The audio restored for a line's recorded take is not the audio the record names. | | [`VoiceStandInError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VoiceStandInError) | Under `strict`: a line would be spoken by another provider than its voice declares. | | [`VoiceStandInWarning`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VoiceStandInWarning) | A line is spoken by another provider than its voice document declares — an override for every line, or a provider `an` has no TTS for (an#305). | ### an.audio.pipeline.AUDIO_OUTPUT_STORES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('audio', 'visemes')* The stores the audio pipeline writes what it makes to. ### *exception* an.audio.pipeline.AudioNotCachedError Bases: [`AudioPipelineError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.AudioPipelineError) A line’s audio (or its visemes) is not in the content-keyed stores, so stamping it would need a synthesis this caller does not allow. ### *exception* an.audio.pipeline.AudioPipelineError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The scene declares audio the pipeline cannot produce. Carries detail. ### an.audio.pipeline.DEFAULT_TTS_NAME *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'offline'* Who speaks a line whose voice declares no provider, when no `tts` overrides it. ### *exception* an.audio.pipeline.DialogueOverrunWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) A synthesized line runs past its shot’s end, so its tail is cut. ### *class* an.audio.pipeline.InMemoryOverlay(store) Bases: [`MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping) A store view that reads through and keeps every write IN MEMORY: what a reader of a render’s cache keys stamps free audio into (an#311), so the keys it computes next see that audio while the store itself is untouched. Deleting is refused. ### an.audio.pipeline.LEGACY_DURATION_TOLERANCE_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.016666666666666666* How far a legacy sidecar’s duration may sit from its audio’s and still be the same take: a frame at 60 fps. ### an.audio.pipeline.OVERRUN_TOLERANCE_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.016666666666666666* a frame at 60 fps (the same as `an validate`’s). * **Type:** Slack before a line counts as running past its shot ### an.audio.pipeline.REROLL_ONLY_HINT *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'Re-roll it with \`an voices reroll \` (new takes under new keys, billed; the render prints the cost first)'* only a new roll (new keys) replaces it. * **Type:** The remedy when a recorded take is gone ### *exception* an.audio.pipeline.TakeDigestWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) The audio restored for a line’s recorded take is not the audio the record names. ### an.audio.pipeline.TakeScorerFactory `(TakesSpec) -> TakeScorer` — the seam that turns a takes spec into its scorer. alias of [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`TakesSpec`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesSpec)], [`TakeScorer`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScorer)] ### an.audio.pipeline.VOICE_TTS *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'voice'* The `tts` that means “each line’s voice document names its provider” — the default of a render (an#305). `None` and `""` mean the same. ### *exception* an.audio.pipeline.VoiceStandInError Bases: [`AudioPipelineError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.AudioPipelineError) Under `strict`: a line would be spoken by another provider than its voice declares. Raised before any request. ### *exception* an.audio.pipeline.VoiceStandInWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) A line is spoken by another provider than its voice document declares — an override for every line, or a provider `an` has no TTS for (an#305). ### an.audio.pipeline.audio_key(text, voice_id, tts_name, effects=None, , provider_voice=None, options=None, takes=None, take=None, roll=None) Content key of a line’s audio: text, voice, provider, and — only when the voice declares them — its effects, the provider voice it names (an#194), the provider’s synthesis options (model, settings, seed, audio tags — an#209). With none of them, the payload is exactly the pre-effects one, so every key a project already has is unchanged. `take` (1, 2, … — never 0) and `roll` (1, 2, … after `an voices reroll`) key one candidate take of a best-of-N line; take 0 of roll 0 is the single-take request and keeps its key. `takes` ([`an.audio.takes.takes_choice_part()`](_autosummary/an.audio.takes.html.md#an.audio.takes.takes_choice_part)) keys the CHOICE among a line’s takes — the record in `mall["takes"]`, not an audio blob. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> audio_key("hi", "default", "offline") == audio_key( ... "hi", "default", "offline", {}, provider_voice=None, options={}, ... takes=None, take=0, roll=0) True ``` ### an.audio.pipeline.default_lipsync() The default lip-sync provider: the loaded genre’s `offline` one (the deterministic char-to-viseme provider of `cutan`), else [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync). * **Return type:** [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider) ```pycon >>> default_lipsync().name in {"offline", "none"} True ``` ### an.audio.pipeline.default_tts() The default TTS provider: `OfflineTTS`. * **Return type:** [`TTSProvider`](_autosummary/an.audio.tts.html.md#an.audio.tts.TTSProvider) ### an.audio.pipeline.dialogue_overruns(scene, , tolerance_s=0.016666666666666666, mall=None) One message per synthesized line that ends past its shot’s end. `an validate` warns before synthesis from an estimate; this is the exact check AFTER it — a voice’s `tempo` (or a real voice’s own pace, or the silence it pads a line with) can make a line longer than estimated, and the render cuts the shot’s audio at the shot’s end, so the tail would otherwise be lost silently. It is `an validate`’s own check ([`an.ir.validate.shot_dialogue_overruns()`](_autosummary/an.ir.validate.html.md#an.ir.validate.shot_dialogue_overruns)), over the synthesized lines; `mall` lets its fix name the voice’s `trim_silence`. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> from an.ir.schema import Dialogue, SceneIR, Shot >>> shot = Shot(id="s", duration=1.0, dialogue=[ ... Dialogue(speaker="a", text="hi", start=0.2, duration=1.3, audio_ref="k")]) >>> dialogue_overruns(SceneIR(timeline=[shot]))[0][:46] "shot 's': line 0 (a) ends at 1.30s as synthesi" ``` ### an.audio.pipeline.free_and_repeatable(provider) Whether `provider` may be run where nothing may be spent or written (an#311): it DECLARES `repeatable = True` (the same request gives the same bytes: `offline`, `mac_say`) and `billed = False` — stated, never inferred from a missing method — and has no `billed_characters` hook. Re-running it reproduces exactly what a render stored; anything else would give new bytes, so new keys, or cost money. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> from an.audio.offline_tts import OfflineTTS >>> free_and_repeatable(OfflineTTS()), free_and_repeatable(object()) (True, False) ``` ### an.audio.pipeline.in_memory_audio_mall(mall) `mall` with its audio and visemes stores behind [`InMemoryOverlay`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.InMemoryOverlay) s — hand it to [`stamp_from_stores()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.stamp_from_stores) (`free_in_memory=True`) and then to whatever keys the stamped scene (an#311). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.audio.pipeline.is_voice_tts(tts) Whether `tts` means “each voice’s own provider”: `None`, `""` or [`VOICE_TTS`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VOICE_TTS). * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> [is_voice_tts(t) for t in (None, "", "voice", " Voice ", "offline")] [True, True, True, True, False] ``` ### an.audio.pipeline.produce_audio_for_dialogue(dialogue, mall=None, \*, tts=None, lipsync=None, effects=None, voice_id=None, takes=, take_scorer=) Synthesize audio + visemes for one dialogue line. Side effects: when `mall` is provided, persists the WAV to `mall["audio"]` keyed by the content-hash of the dialogue, and persists the viseme JSON to `mall["visemes"]` similarly. Cache-friendly: a second call with identical inputs returns the cached versions. `effects` (default: what the line’s voice declares in `mall["voices"]`) is applied to the synthesized audio BEFORE alignment, so the visemes are computed on the audio the viewer hears. The raw synthesis stays cached under its own key, so changing an effect never re-pays the TTS. `tts` (default: the provider the voice document declares, else offline — [`tts_chooser()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.tts_chooser)) is an override when given. `voice_id` (default: the line’s `voice_ref`, else `"default"`) is the `voices`-store key; [`produce_audio_for_scene()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.produce_audio_for_scene) passes the one [`an.audio.voices.line_voice_id()`](_autosummary/an.audio.voices.html.md#an.audio.voices.line_voice_id) resolves, so a character’s bound voice reaches here (an#194). The provider is handed the voice document’s own voice id when it names one. What the provider’s optional `synthesis_options` hook derives from the voice document and the line (ElevenLabs: `model_id`, `voice_settings`, `seed`, and the `[emotion]`/`direction` audio tags — an#209) is passed to `synthesize` and keyed; the text handed to alignment is always the bare `dialogue.text`, never the tagged one. `takes` (default: what the voice declares for this line — see [`an.audio.takes`](_autosummary/an.audio.takes.html.md#module-an.audio.takes); `None` forces one take) synthesizes several takes, scores each with `take_scorer(spec)` on the audio the viewer hears, keeps the best and records the choice in `mall["takes"]`. A recorded choice is restored from the record and never re-rolled; a recorded take whose audio is gone raises [`TakeLostError`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeLostError) before any request. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip), [`VisemeTrack`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.VisemeTrack)] ### an.audio.pipeline.produce_audio_for_scene(scene, mall=None, \*, tts=None, lipsync=None, take_scorer=, announce=, overruns=True, strict=False, tts_factory=None) Walk every dialogue line, synthesize, and stamp viseme tracks back. Mutates the `scene` in place AND returns it (for chaining). Stamps `Dialogue.duration`, `Dialogue.viseme_track`, and `Dialogue.audio_ref` (mall[“audio”] key) so the renderer can find the audio later. Lines with an existing viseme_track AND audio_ref are not re-synthesized (idempotent). `Dialogue.start` is DERIVED on every pass, synthesized or not, by `Dialogue.planned_start()`: the line’s `at` if set, else the previous line’s end plus its `pause` (an#187). So editing a pause re-times the shot without touching the audio, and every consumer of `start` — the mux, the visemes, captions, ducking — follows. A `start` on a line that was never synthesized is an authored start from before `at` existed, and is kept as the line’s `at`. Every line’s request is resolved BEFORE anything is synthesized, so a malformed voice (an effect, a `takes`), a corrupt takes record or a recorded take whose audio is gone fails before a credit is spent; and `announce` (default: a line on stderr; `None` for silence) is told, before the first request, what best-of-N takes will bill (requests and the provider’s characters) and which recorded takes were chosen by an older scorer version than the current one (they are kept). After synthesis, a line that ends past its shot’s end ([`dialogue_overruns()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.dialogue_overruns)) is announced too — or, with `announce=None`, a `DialogueOverrunWarning` — unless `overruns=False`: `an render` passes that, because it reports every post-synthesis finding together in its summary (an#254). **Who speaks each line** (an#305, [`tts_chooser()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.tts_chooser)): with `tts` not given (`None`, `""` or [`VOICE_TTS`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VOICE_TTS)), the line’s voice document’s `provider`, built by `tts_factory` (default [`an.audio.providers.make_tts()`](_autosummary/an.audio.providers.html.md#an.audio.providers.make_tts)), else offline; a `tts` given speaks every line. A line spoken by another provider than its voice declares is a [`VoiceStandInWarning`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VoiceStandInWarning) — the silent offline voice says so — and, with `strict`, a [`VoiceStandInError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VoiceStandInError) before any request. A provider with requests to send is asked `check_available()` first (ElevenLabs: is there a key?), and what a provider that bills per character will bill is announced before the first request — whatever chose the provider; a cached line is never billed and never counted. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ### an.audio.pipeline.retake_lines(scene, mall, match, \*, tts, rescore=False, take_scorer=) Mark the recorded takes of the lines whose text contains `match` to be chosen again on the next render; one message per matching line. `rescore=True` re-chooses among the takes already synthesized (with the current scorer; nothing billed while they are cached); otherwise a new roll of takes is synthesized (billed — the render prints the cost first). Either way the replaced choice is kept in the record’s `history`, and the new take has its own key, so its visemes and word timings are aligned afresh. This is the only way a recorded take is replaced (ADR 0003). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.audio.pipeline.retime_dialogue(scene, , timed_shots_only=False) Stamp every synthesized line’s `start` from its `pause` / `at`. Pure — synthesizes nothing, reads no store — and idempotent. The audio pipeline ends with it, and every path that skips the pipeline (`render` with `auto_audio=False`, `an preview`) runs it too, so a pause edited after synthesis is never played at the stale stamp (an#187). A shot is re-timed up to its first line with no `duration` (never synthesized: nothing after it has a known start). Mutates in place and returns `scene`. `timed_shots_only=True` — what the paths that skip synthesis pass — leaves a shot whose lines carry no `pause`/`at` exactly as stamped: a hand-built scene may stamp `start` itself (a test, a fixture), and without the pipeline there is no authority to say that stamp is stale. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ```pycon >>> from an.ir.schema import Dialogue, SceneIR, Shot >>> shot = Shot(id="s", dialogue=[ ... Dialogue(speaker="a", text="hi", start=0.0, duration=0.5, audio_ref="k1"), ... Dialogue(speaker="b", text="bye", start=0.5, duration=0.4, audio_ref="k2", ... pause=1.5)]) >>> [d.start for d in retime_dialogue(SceneIR(timeline=[shot])).timeline[0].dialogue] [0.0, 2.0] ``` ### an.audio.pipeline.stamp_from_stores(scene, mall, , tts=None, lipsync, tts_factory=None, free_in_memory=False) Stamp `scene`’s dialogue exactly as [`produce_audio_for_scene()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.produce_audio_for_scene) would with these providers — `tts` as it takes it: `None` for each voice’s own (an#305) — from the content-keyed `audio` and `visemes` stores only. Synthesises, aligns, writes and announces nothing; a line the stores cannot answer raises [`AudioNotCachedError`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.AudioNotCachedError). `free_in_memory` (an#311): a line the stores cannot answer whose provider is free and repeatable ([`free_and_repeatable()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.free_and_repeatable): offline speech) is synthesised and aligned for real — it reproduces the bytes a render stored — into the mall’s [`InMemoryOverlay`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.InMemoryOverlay) s, which [`in_memory_audio_mall()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.in_memory_audio_mall) puts in front of the audio and visemes stores (required: nothing is ever written to a store). Billed or non-repeatable providers still raise. Still nothing is announced. What a reader of the render’s cache keys needs (an#274): a `scene.md` edit drops every stamp on re-sync, and the next render re-stamps the same audio from the stores, so the keys a render WILL use are these, not the unstamped IR’s. Mutates `scene` in place and returns it. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ### an.audio.pipeline.synthesis_options(tts, line, mall, voice_id) The provider-specific `synthesize` kwargs for `line` in `voice_id`. `{}` for a provider without a `synthesis_options` hook (offline, mac_say) and for a voice written for another provider — which is what keeps their cache keys where they were. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.audio.pipeline.takes_cost_message(lines, tts, audio_store) What synthesizing `lines` with `tts` will bill, when any of them takes best-of-N or `tts` bills per character (an#305: a voice that names a paid provider is spoken by it with no flag, so its cost is said first); else `""`. Counts only the requests not already in `audio_store` (a cached take is free; a recorded take is restored, never billed), and the provider’s billed characters per request (its `billed_characters(text, **options)` hook — ElevenLabs counts the audio tags too). A provider without the hook bills no characters, and the message says so. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.pipeline.tts_chooser(tts, mall, , make=None) `voice_id -> provider`: who speaks a line in that voice (an#305). A `tts` given (a provider, or a name `make` builds) speaks every line — an override. Otherwise (`None`, `""`, [`VOICE_TTS`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.VOICE_TTS)) the voice document’s `provider` decides, and a voice that declares none — or one `make` has no provider for ([`voice_stand_ins()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.voice_stand_ins) reports it) — is spoken by [`DEFAULT_TTS_NAME`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.DEFAULT_TTS_NAME). One instance per provider name. `make` defaults to [`an.audio.providers.make_tts()`](_autosummary/an.audio.providers.html.md#an.audio.providers.make_tts). * **Return type:** [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)], [`TTSProvider`](_autosummary/an.audio.tts.html.md#an.audio.tts.TTSProvider)] ```pycon >>> mall = {"voices": {"bob": {"provider": "mac_say"}, "ann": {}}} >>> choose = tts_chooser(None, mall) >>> choose("bob").name, choose("ann").name, choose("nobody").name ('mac_say', 'offline', 'offline') >>> tts_chooser("offline", mall)("bob").name 'offline' ``` ### an.audio.pipeline.viseme_key(audio_key_, lipsync_name, transcript) Content key of a line’s viseme track (a function of the audio HEARD). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.pipeline.voice_stand_ins(lines, mall, , overridden) One message per voice whose lines are spoken by another provider than its document declares; `lines` is `(voice_id, provider)` per line, and `overridden` says whether a `tts` was given for every line. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> from an.audio.offline_tts import OfflineTTS >>> mall = {"voices": {"bob": {"provider": "elevenlabs"}}} >>> print(voice_stand_ins([("bob", OfflineTTS())] * 2, mall, overridden=True)[0]) voice 'bob' declares provider 'elevenlabs', but its 2 line(s) are spoken by 'offline' — SILENT audio — because `tts` overrides every voice. Drop `--tts` to let each voice speak with its own provider. >>> voice_stand_ins([("bob", OfflineTTS())], {}, overridden=True) [] ``` # _autosummary/an.audio.providers.html.md # an.audio.providers Provider factory: name → concrete TTS/LipSync provider instance. Used by the CLI and orchestrator to map `--tts elevenlabs` (and similar) strings into instantiated providers without callers having to import the specific classes. ```pycon >>> from an.audio.providers import make_tts, make_lipsync >>> make_tts("offline").name 'offline' >>> make_lipsync("none").name 'none' ``` ### Module Attributes | [`DEFAULT_LANGUAGE`](_autosummary/an.audio.providers.html.md#an.audio.providers.DEFAULT_LANGUAGE) | The language a provider aligns for when the caller says nothing. | |---------------------------------------------------------------------|----------------------------------------------------------------------| | [`LIPSYNC_FACTORIES`](_autosummary/an.audio.providers.html.md#an.audio.providers.LIPSYNC_FACTORIES) | The lip-sync providers the core itself offers. | | [`DFLT_LIPSYNC`](_autosummary/an.audio.providers.html.md#an.audio.providers.DFLT_LIPSYNC) | The provider `default_lipsync()` prefers when a genre registered it. | ### Functions | [`known_lipsync_names`](_autosummary/an.audio.providers.html.md#an.audio.providers.known_lipsync_names)() | Return the registered LipSync provider names. | |-------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`known_tts_names`](_autosummary/an.audio.providers.html.md#an.audio.providers.known_tts_names)() | Return the registered TTS provider names. | | [`lipsync_factories`](_autosummary/an.audio.providers.html.md#an.audio.providers.lipsync_factories)() | Every lip-sync factory by name: the core's, then the loaded genres' services. | | [`make_lipsync`](_autosummary/an.audio.providers.html.md#an.audio.providers.make_lipsync)(name, \*[, language]) | Instantiate a LipSync provider by name. | | [`make_tts`](_autosummary/an.audio.providers.html.md#an.audio.providers.make_tts)(name) | Instantiate a TTS provider by name. | ### an.audio.providers.DEFAULT_LANGUAGE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'en'* The language a provider aligns for when the caller says nothing. Only Rhubarb reads it today (its recognizer follows the language, an#96). ### an.audio.providers.DFLT_LIPSYNC *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'offline'* The provider `default_lipsync()` prefers when a genre registered it. ### an.audio.providers.LIPSYNC_FACTORIES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[...], [LipSyncProvider](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider)]]* *= {'none': >}* The lip-sync providers the core itself offers. A genre adds its own through the `lipsync.` service (`cutan`: `offline`, `rhubarb`, `whisper`); see [`lipsync_factories()`](_autosummary/an.audio.providers.html.md#an.audio.providers.lipsync_factories). ### an.audio.providers.known_lipsync_names() Return the registered LipSync provider names. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.audio.providers.known_tts_names() Return the registered TTS provider names. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.audio.providers.lipsync_factories() Every lip-sync factory by name: the core’s, then the loaded genres’ services. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Callable`](https://docs.python.org/3/library/typing.html#typing.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider)]] ### an.audio.providers.make_lipsync(name, , language='en') Instantiate a LipSync provider by name. `language` (BCP-47) reaches providers that select behaviour by language — Rhubarb’s recognizer today; a future aligner’s weight allowlist. The default name (`"offline"`) resolves to [`NullLipSync`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.NullLipSync) when no loaded genre provides it, so voicing a line needs no genre; any other name that nothing provides is an error that says how to get it. * **Return type:** [`LipSyncProvider`](_autosummary/an.audio.lipsync.html.md#an.audio.lipsync.LipSyncProvider) ```pycon >>> make_lipsync("offline").name in {"offline", "none"} True ``` ### an.audio.providers.make_tts(name) Instantiate a TTS provider by name. Raises `ValueError` for unknown names with a list of known options. * **Return type:** [`TTSProvider`](_autosummary/an.audio.tts.html.md#an.audio.tts.TTSProvider) # _autosummary/an.audio.takes.html.md # an.audio.takes Best-of-N takes: re-roll a line, score every take, keep the best, record the choice. An expressive TTS model does not repeat itself: `eleven_v3` returned three different files for three byte-identical requests (same text, voice, settings and seed), and the spread between two takes of one line was larger than the effect of any voice setting. So the way to land a delivery on its measured targets is to synthesize a few takes and keep the one that measures closest. A voice document opts in with `takes`: ```default {"voice_id": "...", "model_id": "eleven_v3", "takes": {"n": 3, # takes per line (1 = off) "targets": {"articulation_rate_sps": [5.2, 6.3], ...}, "cues": {"deadpan": {"n": 4, "targets": {...}}}}} ``` - `n` — takes per line; `1` (the default) is today’s single take, byte for byte. A bare integer (`takes: 3`) is `{"n": 3}`. - `targets` — `[low, high]` prosody targets ([`an.verify.prosody.METRICS`](_autosummary/an.verify.prosody.html.md#an.verify.prosody.METRICS)) the default scorer measures each take against. A style’s targets are named by role in its spec; [`style_voice_role()`](_autosummary/an.audio.takes.html.md#an.audio.takes.style_voice_role) resolves those names into values when the style is applied, so the voice document holds numbers, never names. - `reference_hz` — the voice’s neutral median pitch, for a `register_st` target. - `cues` — per-line opt-in: a line whose `{direction}` carries one of these cues uses that entry’s `n` / `targets` / `reference_hz` over the voice’s (the first matching cue, in the line’s order, wins). So a narrator can re-roll only its `{deadpan}` punchlines, scored as punchlines. - `scorer` — the scorer’s name (default `prosody`); the scorer itself is a seam ([`TakeScorer`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScorer), the pipeline’s `take_scorer=`). How the pipeline uses it ([`an.audio.pipeline`](_autosummary/an.audio.pipeline.html.md#module-an.audio.pipeline)): 1. **Every take has its own content key.** Take `0` of roll `0` is the request a single take makes, under the same key — turning takes on for a line already synthesized reuses that take and pays for `n - 1` more. Take `i` adds `take: i` (and a re-roll adds `roll: r`) to its key, and a provider may vary its request per take (ElevenLabs offsets a declared `seed` by `i`). The audio a line KEEPS is the chosen take’s own heard key (its effects applied), so a different take is a different `audio_ref`, and its visemes, word timings and captions follow it. 2. Each take is scored on the audio the viewer hears (the voice’s effects applied, so a `tempo` counts toward the rate); the lowest score wins, ties to the lower take index. 3. **The record is the resolution** (ADR 0003 decision 3). The choice is written to `mall["takes"]` under the line’s *choice key* — the line’s request, `n`, the scorer’s name and its configuration (its targets), but NOT its version — with the chosen take, the sha256 of what it sounds like, every take’s keys, digests and scores, and the scorer that chose. Every render reads it first: - the chosen take is restored from the record (its heard audio, else its raw audio with the effects re-applied) and never re-billed; - a hand edit of `chosen` wins: that take is restored, the record says `superseded_by: hand` and the decision is logged; - a chosen take whose audio is gone is a [`TakeLostError`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeLostError) raised before any request — `an voices reroll` is the explicit way to re-roll; - a record made by an older scorer version is KEPT, and the render reports it — `an voices rescore` re-chooses explicitly, from the cached takes. Changing `n`, the targets, the scorer or the voice’s effects is a new choice key, chosen from the takes already cached where it can. ```pycon >>> spec = takes_spec({"n": 3, "targets": {"f0_sd_st": [2, 4]}}) >>> spec.n, spec.scorer, dict(spec.targets) (3, 'prosody', {'f0_sd_st': [2.0, 4.0]}) >>> takes_spec(None) is None and takes_spec(1) is None True >>> doc = {"n": 1, "cues": {"deadpan": {"n": 4, "targets": {"final_drop_st": [-3.6, -1.7]}}}} >>> takes_spec(doc, direction=["deadpan"]).n, takes_spec(doc, direction=["excited"]) (4, None) >>> takes_spec({"n": 3}) Traceback (most recent call last): ... an.audio.takes.VoiceTakesError: takes: n=3 with the prosody scorer needs `targets` ([low, high] per metric) to choose by >>> choose_take([TakeScore((0.5, 1.0)), TakeScore((0.0, 2.0)), TakeScore((0.0, 2.0))]) 1 ``` ### Module Attributes | [`TAKES_KEY`](_autosummary/an.audio.takes.html.md#an.audio.takes.TAKES_KEY) | The key, in a voice document, declaring best-of-N takes. | |----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`TAKES_STORE`](_autosummary/an.audio.takes.html.md#an.audio.takes.TAKES_STORE) | The name of the store the choices are recorded in. | | [`DEFAULT_SCORER`](_autosummary/an.audio.takes.html.md#an.audio.takes.DEFAULT_SCORER) | The scorer a `takes` declaration uses when it names none. | | [`MAX_TAKES`](_autosummary/an.audio.takes.html.md#an.audio.takes.MAX_TAKES) | each one is a billed request. | | [`TAKES_RECORD_VERSION`](_autosummary/an.audio.takes.html.md#an.audio.takes.TAKES_RECORD_VERSION) | The shape of a record in `mall["takes"]`; raised when a field changes meaning. | | [`PROSODY_SCORER_VERSION`](_autosummary/an.audio.takes.html.md#an.audio.takes.PROSODY_SCORER_VERSION) | The prosody scorer's own version (its distance and tie-break); the estimator's version ([`an.verify.prosody.ESTIMATOR_VERSION`](_autosummary/an.verify.prosody.html.md#an.verify.prosody.ESTIMATOR_VERSION)) is joined to it. | | [`PROSODY_SCORER_AGREES_OFF_SHORT`](_autosummary/an.audio.takes.html.md#an.audio.takes.PROSODY_SCORER_AGREES_OFF_SHORT) | The prosody scorer versions whose choice the current one agrees with on a line that is NOT short ([`ProsodyTakeScorer.agrees_with()`](_autosummary/an.audio.takes.html.md#an.audio.takes.ProsodyTakeScorer.agrees_with)): version 2 changed short lines only, so a longer line's recorded pick is no "older scorer" to report. | | [`SHORT_LINE_SYLLABLES`](_autosummary/an.audio.takes.html.md#an.audio.takes.SHORT_LINE_SYLLABLES) | A line with fewer syllables than this ([`an.verify.prosody.count_syllables()`](_autosummary/an.verify.prosody.html.md#an.verify.prosody.count_syllables)) is SHORT: too short to show pauses or a rate (an#404, end-user test finding 8). | | [`SHORT_LINE_INAPPLICABLE`](_autosummary/an.audio.takes.html.md#an.audio.takes.SHORT_LINE_INAPPLICABLE) | The targets a short line cannot show — they need several words — and is not scored on (recorded as `not_applicable` in the take's detail). | | [`SCORING_SAMPLE_RATE`](_autosummary/an.audio.takes.html.md#an.audio.takes.SCORING_SAMPLE_RATE) | The sample rate takes are decoded at for scoring — the one the targets were measured at. | | [`REROLL_HINT`](_autosummary/an.audio.takes.html.md#an.audio.takes.REROLL_HINT) | What to run when a recorded take must be replaced (named in every error). | | [`SCORERS`](_autosummary/an.audio.takes.html.md#an.audio.takes.SCORERS) | `TakesSpec -> TakeScorer`. | ### Functions | [`audio_digest`](_autosummary/an.audio.takes.html.md#an.audio.takes.audio_digest)(audio) | The sha256 a takes record names a take's audio by. | |----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`choose_take`](_autosummary/an.audio.takes.html.md#an.audio.takes.choose_take)(scores) | The index of the best take: the lowest score, ties to the lower index. | | [`decode_for_scoring`](_autosummary/an.audio.takes.html.md#an.audio.takes.decode_for_scoring)(audio, \*[, sr]) | `audio` as mono float samples at `sr` Hz, decoded by ffmpeg — the decoder the targets were measured with, and the only one, so the same bytes score the same on every machine. | | [`is_short_line`](_autosummary/an.audio.takes.html.md#an.audio.takes.is_short_line)(text) | Whether `text` is too short to show pauses or a rate (an#404). | | [`make_take_scorer`](_autosummary/an.audio.takes.html.md#an.audio.takes.make_take_scorer)(spec) | The scorer `spec` names, from [`SCORERS`](_autosummary/an.audio.takes.html.md#an.audio.takes.SCORERS) (the pipeline's default `take_scorer`). | | [`normalize_takes`](_autosummary/an.audio.takes.html.md#an.audio.takes.normalize_takes)(raw) | The canonical `takes` declaration of a voice document (`{}` for none). | | [`read_takes_record`](_autosummary/an.audio.takes.html.md#an.audio.takes.read_takes_record)(store, key) | The takes record under `key` in `store` (`mall["takes"]`), or `None`. | | [`require_ffmpeg`](_autosummary/an.audio.takes.html.md#an.audio.takes.require_ffmpeg)() | Raise [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) with the install hint when ffmpeg is not on PATH. | | [`scorer_identity`](_autosummary/an.audio.takes.html.md#an.audio.takes.scorer_identity)(scorer) | The scorer as a record names it: name, version and configuration. | | [`style_voice_role`](_autosummary/an.audio.takes.html.md#an.audio.takes.style_voice_role)(spec, role) | The partial voice document a style casts `role` as, with target NAMES resolved. | | [`takes_choice_part`](_autosummary/an.audio.takes.html.md#an.audio.takes.takes_choice_part)(scorer, n) | What identifies a CHOICE among `n` takes: the scorer's name and its configuration, never its version — a new scorer version keeps the takes it chose, and says so ([`REROLL_HINT`](_autosummary/an.audio.takes.html.md#an.audio.takes.REROLL_HINT)). | | [`takes_spec`](_autosummary/an.audio.takes.html.md#an.audio.takes.takes_spec)(raw, \*[, direction]) | The takes a line with `direction` gets from a voice's `takes`, or `None` for one take. | | [`voice_takes`](_autosummary/an.audio.takes.html.md#an.audio.takes.voice_takes)(mall, voice_id, \*[, direction, ...]) | The takes `mall["voices"][voice_id]` declares for a line with `direction`. | | [`write_takes_record`](_autosummary/an.audio.takes.html.md#an.audio.takes.write_takes_record)(store, key, record) | Write `record` under `key` (stable, indented JSON); no store, no record. | ### Classes | [`ProsodyTakeScorer`](_autosummary/an.audio.takes.html.md#an.audio.takes.ProsodyTakeScorer)(targets, \*[, reference_hz, sr]) | Scores a take by how far its prosody sits from `[low, high]` targets. | |-------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`TakeScore`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScore)(value[, detail]) | A take's score — compared as a tuple, lower is better — and what it measured. | | [`TakeScorer`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScorer)(\*args, \*\*kwargs) | Scores one take of a line. | | [`TakesSpec`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesSpec)(n[, scorer, targets, reference_hz]) | The takes ONE line gets: how many, and what chooses between them. | ### Exceptions | [`TakeLostError`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeLostError) | A line's recorded take is gone from the audio store and cannot be restored. | |-------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`TakesRecordError`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesRecordError) | A `mall["takes"]` record cannot be read as a takes record. | | [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) | A voice's `takes` declaration is malformed, or cannot be scored. | ### an.audio.takes.DEFAULT_SCORER *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'prosody'* The scorer a `takes` declaration uses when it names none. ### an.audio.takes.MAX_TAKES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 10* each one is a billed request. * **Type:** More takes than this per line is refused ### an.audio.takes.PROSODY_SCORER_AGREES_OFF_SHORT *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'1'})* The prosody scorer versions whose choice the current one agrees with on a line that is NOT short ([`ProsodyTakeScorer.agrees_with()`](_autosummary/an.audio.takes.html.md#an.audio.takes.ProsodyTakeScorer.agrees_with)): version 2 changed short lines only, so a longer line’s recorded pick is no “older scorer” to report. ### an.audio.takes.PROSODY_SCORER_VERSION *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '2'* The prosody scorer’s own version (its distance and tie-break); the estimator’s version ([`an.verify.prosody.ESTIMATOR_VERSION`](_autosummary/an.verify.prosody.html.md#an.verify.prosody.ESTIMATOR_VERSION)) is joined to it. 2 (an#404): a short line is scored only on the targets it can show. ### *class* an.audio.takes.ProsodyTakeScorer(targets, , reference_hz=None, sr=16000) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Scores a take by how far its prosody sits from `[low, high]` targets. The score is [`an.verify.prosody.target_distance()`](_autosummary/an.verify.prosody.html.md#an.verify.prosody.target_distance): the summed distance outside the ranges, then the summed distance from their midpoints (the tie-break between takes all on target), in units of each range’s width. A SHORT line (fewer than [`SHORT_LINE_SYLLABLES`](_autosummary/an.audio.takes.html.md#an.audio.takes.SHORT_LINE_SYLLABLES) syllables) is scored only on the targets it can show: the pause and rate targets ([`SHORT_LINE_INAPPLICABLE`](_autosummary/an.audio.takes.html.md#an.audio.takes.SHORT_LINE_INAPPLICABLE)) are left out and recorded as `not_applicable` (an#404). Otherwise a one-word line’s choice measured its shortness, every target it cannot measure costing a range-width. That changed version 1’s choices for short lines only; a pick already recorded keeps its take and its keys (the choice key never holds the version), and a longer line’s pick is not reported as made by an older scorer ([`agrees_with()`](_autosummary/an.audio.takes.html.md#an.audio.takes.ProsodyTakeScorer.agrees_with)). #### SCORE_MEANS *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= "score = [outside, off_centre], lower is better; the take with the smallest pair is kept. outside: for each target in scorer.config.targets, how far the measured value sits outside its [low, high] range, in widths of that range (0 inside; a value this take cannot measure, listed in \`unmeasured\`, counts 1). off_centre: each value's distance from its range's middle, in the same units (the tie-break). \`measured\` holds the values, \`misses\` the targets missed. A line under 4 syllables is not scored on the targets it cannot show (pauses and rates), listed in \`not_applicable\`."* What a take’s `score` pair means, written into each takes record (an#397). #### agrees_with(version, text) Whether a choice recorded by scorer `version` is the one this scorer would make for `text`: the same version, or an older one that scored a line like this one the same way (version 1, on a line that is not short). * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> s = ProsodyTakeScorer({"f0_sd_st": [2, 4]}) >>> old = s.version.replace("2+", "1+", 1) >>> s.agrees_with(old, "He did not do the job."), s.agrees_with(old, "Hi!") (True, False) ``` #### applicable(text) The targets `text` is scored on: all of them, or for a short line those it can show (an#404). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Sequence`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Sequence)[[`float`](https://docs.python.org/3/builtins/functions.html#float)]] ```pycon >>> s = ProsodyTakeScorer({"f0_sd_st": [2, 4], "pause_share": [0.1, 0.2]}) >>> sorted(s.applicable("Hi!")), sorted(s.applicable("He did not do the job.")) (['f0_sd_st'], ['f0_sd_st', 'pause_share']) ``` #### check_available() Raise before any request when this scorer could not score (no ffmpeg). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.takes.REROLL_HINT *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 're-roll it explicitly with \`an voices reroll \` (new takes, billed) or, while every take of its roll is still cached, re-choose among them with \`an voices rescore \`'* What to run when a recorded take must be replaced (named in every error). ### an.audio.takes.SCORERS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[TakesSpec](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesSpec)], [TakeScorer](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScorer)]]* *= {'prosody': >}* `TakesSpec -> TakeScorer`. * **Type:** Scorer factories by name ### an.audio.takes.SCORING_SAMPLE_RATE *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 16000* The sample rate takes are decoded at for scoring — the one the targets were measured at. ### an.audio.takes.SHORT_LINE_INAPPLICABLE *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'articulation_rate_sps', 'pause_median_s', 'pause_p90_s', 'pause_share', 'pauses_per_min', 'speech_rate_sps'})* The targets a short line cannot show — they need several words — and is not scored on (recorded as `not_applicable` in the take’s detail). ### an.audio.takes.SHORT_LINE_SYLLABLES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 4* A line with fewer syllables than this ([`an.verify.prosody.count_syllables()`](_autosummary/an.verify.prosody.html.md#an.verify.prosody.count_syllables)) is SHORT: too short to show pauses or a rate (an#404, end-user test finding 8). ### an.audio.takes.TAKES_KEY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'takes'* The key, in a voice document, declaring best-of-N takes. ### an.audio.takes.TAKES_RECORD_VERSION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 1* The shape of a record in `mall["takes"]`; raised when a field changes meaning. ### an.audio.takes.TAKES_STORE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'takes'* The name of the store the choices are recorded in. ### *exception* an.audio.takes.TakeLostError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A line’s recorded take is gone from the audio store and cannot be restored. Raised before any request: re-rolling an approved take is never implicit. ### *class* an.audio.takes.TakeScore(value, detail=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A take’s score — compared as a tuple, lower is better — and what it measured. ### *class* an.audio.takes.TakeScorer(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Scores one take of a line. Deterministic: the same bytes score the same. `name`, `version` and `config` enter the line’s audio key, so a scorer that would choose differently must differ in one of them. #### score(audio, text) Score `audio` (any container ffmpeg reads; WAV without it) speaking `text`. * **Return type:** [`TakeScore`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScore) ### *exception* an.audio.takes.TakesRecordError Bases: [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) A `mall["takes"]` record cannot be read as a takes record. ### *class* an.audio.takes.TakesSpec(n, scorer='prosody', targets=, reference_hz=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The takes ONE line gets: how many, and what chooses between them. ### *exception* an.audio.takes.VoiceTakesError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A voice’s `takes` declaration is malformed, or cannot be scored. ### an.audio.takes.audio_digest(audio) The sha256 a takes record names a take’s audio by. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.takes.choose_take(scores) The index of the best take: the lowest score, ties to the lower index. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ### an.audio.takes.decode_for_scoring(audio, , sr=16000) `audio` as mono float samples at `sr` Hz, decoded by ffmpeg — the decoder the targets were measured with, and the only one, so the same bytes score the same on every machine. Raises [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) without ffmpeg. ### an.audio.takes.is_short_line(text) Whether `text` is too short to show pauses or a rate (an#404). * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> is_short_line("Hi!"), is_short_line("[deadpan] No."), is_short_line("He did not do the job.") (True, True, False) ``` ### an.audio.takes.make_take_scorer(spec) The scorer `spec` names, from [`SCORERS`](_autosummary/an.audio.takes.html.md#an.audio.takes.SCORERS) (the pipeline’s default `take_scorer`). * **Return type:** [`TakeScorer`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakeScorer) ### an.audio.takes.normalize_takes(raw) The canonical `takes` declaration of a voice document (`{}` for none). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> normalize_takes(3) {'n': 3} >>> normalize_takes({"cues": {"deadpan": 4}}) {'cues': {'deadpan': {'n': 4}}} ``` ### an.audio.takes.read_takes_record(store, key) The takes record under `key` in `store` (`mall["takes"]`), or `None`. Raises [`TakesRecordError`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesRecordError) — naming the record and the remedy — for one that is not JSON, not a mapping, or whose `chosen` names no take. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> read_takes_record({}, "k") is None True >>> read_takes_record({"k": b'{"chosen": 0, "takes": [{"take": 0}]}'}, "k")["chosen"] 0 >>> read_takes_record({"k": b"[1, 2]"}, "k") Traceback (most recent call last): ... an.audio.takes.TakesRecordError: the takes record 'k' is not a takes record (a JSON object with `chosen` and `takes`): ... ``` ### an.audio.takes.require_ffmpeg() Raise [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) with the install hint when ffmpeg is not on PATH. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.takes.scorer_identity(scorer) The scorer as a record names it: name, version and configuration. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.audio.takes.style_voice_role(spec, role) The partial voice document a style casts `role` as, with target NAMES resolved. A style spec (`cutan.style_spec(name)`) declares `live.voice.roles.` and may name a delivery’s targets by its key in `prosody_targets` (`takes: {n: 3, targets: narrator}`). This returns a copy whose `takes` (and each cue’s) hold the target VALUES, ready to merge beside a `voice_id`: `{**style_voice_role(spec, "narrator"), "voice_id": ...}`. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> spec = {"live": {"voice": {"roles": {"narrator": {"model_id": "eleven_v3", ... "takes": {"n": 2, "targets": "narrator", "cues": {"deadpan": {"targets": "punchline"}}}}}}}, ... "prosody_targets": {"narrator": {"f0_sd_st": [3.9, 5.2]}, "punchline": {"f0_sd_st": [2.2, 3.4]}}} >>> role = style_voice_role(spec, "narrator") >>> role["takes"]["targets"], role["takes"]["cues"]["deadpan"]["targets"] ({'f0_sd_st': [3.9, 5.2]}, {'f0_sd_st': [2.2, 3.4]}) ``` ### an.audio.takes.takes_choice_part(scorer, n) What identifies a CHOICE among `n` takes: the scorer’s name and its configuration, never its version — a new scorer version keeps the takes it chose, and says so ([`REROLL_HINT`](_autosummary/an.audio.takes.html.md#an.audio.takes.REROLL_HINT)). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.audio.takes.takes_spec(raw, , direction=None) The takes a line with `direction` gets from a voice’s `takes`, or `None` for one take. Raises [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) for a malformed declaration, and for more than one take with nothing to choose by. * **Return type:** [`TakesSpec`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesSpec) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.takes.voice_takes(mall, voice_id, , direction=None, tts_name=None, repeatable=False) The takes `mall["voices"][voice_id]` declares for a line with `direction`. `None` (one take) for a voice not in the store, one declaring nothing, one written for another provider than `tts_name`, and any voice spoken by a `repeatable` provider (`offline`, `mac_say`: the same request gives the same audio, so a second take is the first one again). A malformed declaration raises [`VoiceTakesError`](_autosummary/an.audio.takes.html.md#an.audio.takes.VoiceTakesError) in every case. * **Return type:** [`TakesSpec`](_autosummary/an.audio.takes.html.md#an.audio.takes.TakesSpec) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.takes.write_takes_record(store, key, record) Write `record` under `key` (stable, indented JSON); no store, no record. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) # _autosummary/an.audio.tts.html.md # an.audio.tts TTS provider protocol + supporting dataclasses. ### Classes | [`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip)([path, bytes_, duration, ...]) | A rendered audio clip, on disk or in memory. | |---------------------------------------------------------------------------------------------|----------------------------------------------------| | [`TTSProvider`](_autosummary/an.audio.tts.html.md#an.audio.tts.TTSProvider)(\*args, \*\*kwargs) | Text-to-speech provider. | | [`VoiceMeta`](_autosummary/an.audio.tts.html.md#an.audio.tts.VoiceMeta)(voice_id, name, provider[, ...]) | Metadata for a TTS voice as exposed by a provider. | ### *class* an.audio.tts.AudioClip(path=None, bytes_=None, duration=0.0, sample_rate=44100, channels=1, voice_id=None, transcript=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A rendered audio clip, on disk or in memory. ### *class* an.audio.tts.TTSProvider(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) Text-to-speech provider. #### list_voices() Return all voices the provider exposes. * **Return type:** [`Iterable`](https://docs.python.org/3/library/typing.html#typing.Iterable)[[`VoiceMeta`](_autosummary/an.audio.tts.html.md#an.audio.tts.VoiceMeta)] #### synthesize(text, voice_id, \*\*kw) Render `text` in `voice_id`’s voice. Returns an AudioClip. * **Return type:** [`AudioClip`](_autosummary/an.audio.tts.html.md#an.audio.tts.AudioClip) ### *class* an.audio.tts.VoiceMeta(voice_id, name, provider, language='en', gender=None, extra=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Metadata for a TTS voice as exposed by a provider. # _autosummary/an.audio.voices.html.md # an.audio.voices Which voice speaks a dialogue line: the character → voice binding (an#194). A line resolves its voice — a key of the project’s `voices` store — in this order, first hit wins: 1. the line’s own `voice_ref` (set from Python or `ir/scene.json`); 2. the speaking character’s `voice_ref`: the shot entity whose `id` is the line’s `speaker`, read from its descriptor in the `characters` store with the entity’s `overrides` merged over it (so `overrides: {voice_ref: x}` on the entity re-voices it for one shot); 3. [`DEFAULT_VOICE`](_autosummary/an.audio.voices.html.md#an.audio.voices.DEFAULT_VOICE). A voice document may name the TTS provider’s own voice with `voice_id` (a `say -v` name for `mac_say`, a voice id for ElevenLabs); the provider is handed that, and otherwise the store key itself. A document that declares `provider` scopes its provider-specific keys (`voice_id`, and the `model_id` / `voice_settings` / `seed` ElevenLabs reads — an#209) to that provider: rendered with another one, the line is handed `"default"`, so an ElevenLabs-voiced project previews with `mac_say` or `offline` instead of failing on a foreign voice id. Nothing declared anywhere resolves every line to `"default"` handed to the provider as `"default"` — exactly what the pipeline did before this module, so no cache key moves. The document’s `provider` also DECIDES who speaks the line when the render names no provider (an#305): [`declared_provider()`](_autosummary/an.audio.voices.html.md#an.audio.voices.declared_provider) reads it, and [`an.audio.pipeline.tts_chooser()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.tts_chooser) turns it into the provider — so a voice written for ElevenLabs is spoken by ElevenLabs by a plain `an render`, and `--tts` is an override for every line. ```pycon >>> from an.ir.schema import AssetRef, Dialogue, Shot >>> shot = Shot(id="s", entities=[ ... AssetRef(kind="character", id="carl", store="characters", ref="carl"), ... AssetRef(kind="character", id="ned", store="characters", ref="ned", ... overrides={"voice_ref": "ned_sad"})]) >>> mall = {"characters": {"carl": {"voice_ref": "carl_kid"}, "ned": {"voice_ref": "ned_kid"}}, ... "voices": {"carl_kid": {"voice_id": "Junior"}}} >>> [line_voice_id(Dialogue(speaker=s, text="hi"), shot, mall) for s in ("carl", "ned", "narrator")] ['carl_kid', 'ned_sad', 'default'] >>> line_voice_id(Dialogue(speaker="carl", text="hi", voice_ref="own"), shot, mall) 'own' >>> provider_voice(mall, "carl_kid"), provider_voice(mall, "default") ('Junior', None) >>> mall["voices"]["bob"] = {"provider": "elevenlabs", "voice_id": "abc123"} >>> provider_voice(mall, "bob", tts_name="elevenlabs"), provider_voice(mall, "bob", tts_name="mac_say") ('abc123', 'default') >>> declared_provider(mall, "bob"), declared_provider(mall, "carl_kid") ('elevenlabs', None) ``` ### Module Attributes | [`DEFAULT_VOICE`](_autosummary/an.audio.voices.html.md#an.audio.voices.DEFAULT_VOICE) | The voice a line gets when neither it nor its speaker names one. | |----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | [`PROVIDER_VOICE_KEY`](_autosummary/an.audio.voices.html.md#an.audio.voices.PROVIDER_VOICE_KEY) | The key, in a voice document, naming the TTS provider's own voice. | | [`PROVIDER_KEY`](_autosummary/an.audio.voices.html.md#an.audio.voices.PROVIDER_KEY) | The key, in a voice document, naming the TTS provider it is written for. | | [`CHARACTER_VOICE_KEY`](_autosummary/an.audio.voices.html.md#an.audio.voices.CHARACTER_VOICE_KEY) | The key, in a character descriptor (or an entity's `overrides`), naming the character's voice in the `voices` store. | ### Functions | [`declared_provider`](_autosummary/an.audio.voices.html.md#an.audio.voices.declared_provider)(mall, voice_id) | The TTS provider `mall["voices"][voice_id]` is written for, lower-cased, or `None` when the voice declares none (or has no document). | |-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------| | [`line_voice_id`](_autosummary/an.audio.voices.html.md#an.audio.voices.line_voice_id)(line, shot, mall, \*[, default]) | The `voices`-store key `line` is spoken with (see the module doc). | | [`provider_voice`](_autosummary/an.audio.voices.html.md#an.audio.voices.provider_voice)(mall, voice_id, \*[, tts_name]) | The provider voice `mall["voices"][voice_id]` names, or `None`. | | [`speaker_voice_ref`](_autosummary/an.audio.voices.html.md#an.audio.voices.speaker_voice_ref)(speaker, shot, mall) | The voice the speaking character is bound to in `shot`, or `None`. | | [`voice_applies`](_autosummary/an.audio.voices.html.md#an.audio.voices.voice_applies)(doc, tts_name) | Whether `doc`'s provider-specific keys apply under the TTS `tts_name`. | | [`voice_document`](_autosummary/an.audio.voices.html.md#an.audio.voices.voice_document)(mall, voice_id) | `mall["voices"][voice_id]` when it is a mapping, else `{}`. | ### an.audio.voices.CHARACTER_VOICE_KEY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'voice_ref'* The key, in a character descriptor (or an entity’s `overrides`), naming the character’s voice in the `voices` store. ### an.audio.voices.DEFAULT_VOICE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'default'* The voice a line gets when neither it nor its speaker names one. ### an.audio.voices.PROVIDER_KEY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'provider'* The key, in a voice document, naming the TTS provider it is written for. ### an.audio.voices.PROVIDER_VOICE_KEY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'voice_id'* The key, in a voice document, naming the TTS provider’s own voice. ### an.audio.voices.declared_provider(mall, voice_id) The TTS provider `mall["voices"][voice_id]` is written for, lower-cased, or `None` when the voice declares none (or has no document). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> declared_provider({"voices": {"v": {"provider": " ElevenLabs "}}}, "v") 'elevenlabs' >>> declared_provider({"voices": {"v": {"provider": ""}}}, "v") is None True ``` ### an.audio.voices.line_voice_id(line, shot, mall, , default='default') The `voices`-store key `line` is spoken with (see the module doc). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.audio.voices.provider_voice(mall, voice_id, , tts_name=None) The provider voice `mall["voices"][voice_id]` names, or `None`. `None` means “hand the provider `voice_id` itself” — a voice that is not in the store, a document without `voice_id`, or one whose `voice_id` is its own key (which changes nothing, so it must not move a cache key). Given `tts_name`, a document written for ANOTHER provider gives [`DEFAULT_VOICE`](_autosummary/an.audio.voices.html.md#an.audio.voices.DEFAULT_VOICE) — never a foreign voice id (an#209). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.voices.speaker_voice_ref(speaker, shot, mall) The voice the speaking character is bound to in `shot`, or `None`. `None` when no character entity of the shot has the speaker’s id (an off-screen narrator), or when neither its descriptor nor its `overrides` name a voice. A store that is absent, or that does not hold the ref, still lets the entity’s `overrides` speak. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.audio.voices.voice_applies(doc, tts_name) Whether `doc`’s provider-specific keys apply under the TTS `tts_name`. True when the document names no `provider`, or names this one (case ignored), or when the caller does not say which provider is speaking. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> voice_applies({}, "offline"), voice_applies({"provider": "ElevenLabs"}, "elevenlabs") (True, True) >>> voice_applies({"provider": "elevenlabs"}, "offline") False ``` ### an.audio.voices.voice_document(mall, voice_id) `mall["voices"][voice_id]` when it is a mapping, else `{}`. * **Return type:** [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping) # _autosummary/an.base.html.md # an.base Core types, constants, and re-exports for an. This module is the *type vocabulary* shared across the package: schema versions, default render parameters, easing presets, type aliases for paths and time. Heavy data classes (the Pydantic IR models, the Renderer/Verifier protocols) live in their own subpackages and are re-exported from `an` itself. Keep this module small and dependency-light. Everything here should import in a fraction of a second so the CLI is snappy. ### Module Attributes | [`SCHEMA_VERSION`](_autosummary/an.base.html.md#an.base.SCHEMA_VERSION) | Current Scene IR schema version. | |-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`COMPATIBLE_VERSION`](_autosummary/an.base.html.md#an.base.COMPATIBLE_VERSION) | Minimum Scene IR version this code can still read without migration. | | [`DEFAULT_SUPERSAMPLE`](_autosummary/an.base.html.md#an.base.DEFAULT_SUPERSAMPLE) | Render at this many times the declared resolution, then resolve back with an exact block mean. | | [`MP4_FASTSTART_ARGS`](_autosummary/an.base.html.md#an.base.MP4_FASTSTART_ARGS) | Put the mp4's `moov` atom in front of `mdat`, so a player can start before the file has finished downloading. | | [`BT709_SCALE_FILTER`](_autosummary/an.base.html.md#an.base.BT709_SCALE_FILTER) | The RGB->YUV conversion `an` performs, stated EXPLICITLY rather than left to the encoder flags to imply. | | [`EASING_PRESETS`](_autosummary/an.base.html.md#an.base.EASING_PRESETS) | Named easing presets. | | [`COLOUR_PROPERTY`](_autosummary/an.base.html.md#an.base.COLOUR_PROPERTY) | The property names the cutout runtime animates NUMERICALLY. | | [`PLANE_REST_VALUES`](_autosummary/an.base.html.md#an.base.PLANE_REST_VALUES) | a node targeted with any of them is drawn on a plane tilted away from the camera (`rotation_x`, radians, positive = the top recedes; `perspective`, the eye's distance in frame heights; `plane_fade_start`/`plane_fade_end`, the far fade, scene px up the plane from the hinge, off while the end is `<= 0`). | | [`TRIM_PROPERTIES`](_autosummary/an.base.html.md#an.base.TRIM_PROPERTIES) | The path-only properties inside `TRANSFORM_PROPERTIES` (an#160; the name predates `dash_offset`, an#161): trim and the dash phase. | | [`SWAP_SET_NAME_FORBIDDEN_SUBSTRINGS`](_autosummary/an.base.html.md#an.base.SWAP_SET_NAME_FORBIDDEN_SUBSTRINGS) | `/` would read as a path segment and `::` is the runtime's pose-key separator. | | [`AUTHORABLE_PROPERTIES`](_autosummary/an.base.html.md#an.base.AUTHORABLE_PROPERTIES) | a compiled transform channel, or the authored colour spelling the compiler expands. | | [`PathStr`](_autosummary/an.base.html.md#an.base.PathStr) | Slash-delimited node path, e.g. `"charlie/head/mouth"`. | | [`Seconds`](_autosummary/an.base.html.md#an.base.Seconds) | Time in seconds. | | [`EasingSpec`](_autosummary/an.base.html.md#an.base.EasingSpec) | Either an easing preset name or a 4-tuple cubic-Bézier control [cx1,cy1,cx2,cy2]. | | [`RendererName`](_autosummary/an.base.html.md#an.base.RendererName) | Which renderer draws a shot. | | [`SUPPORTED_RENDERERS`](_autosummary/an.base.html.md#an.base.SUPPORTED_RENDERERS) | The same vocabulary as [`RendererName`](_autosummary/an.base.html.md#an.base.RendererName), as a runtime tuple — DERIVED from it, because a hand-typed second copy is a second SSOT that drifts on the day a renderer is added and nothing fails. | | [`TRANSITION_KINDS`](_autosummary/an.base.html.md#an.base.TRANSITION_KINDS) | The transition kinds a shot may be entered by. | | [`WIPE_DIRECTIONS`](_autosummary/an.base.html.md#an.base.WIPE_DIRECTIONS) | The ways a `wipe`'s edge can travel across the frame (an#390). | | [`DEFAULT_TRANSITION_DURATION`](_autosummary/an.base.html.md#an.base.DEFAULT_TRANSITION_DURATION) | half a second is a conventional editor's default, short enough not to eat a line of dialogue and long enough to read as deliberate. | | [`DEFAULT_TRANSITION_COLOR`](_autosummary/an.base.html.md#an.base.DEFAULT_TRANSITION_COLOR) | The colour a `fade` passes through when it names none. | | [`FILM_AUDIO_SAMPLE_RATE`](_autosummary/an.base.html.md#an.base.FILM_AUDIO_SAMPLE_RATE) | The film mix's sample rate and channel count. | | [`DEFAULT_DUCK_DB`](_autosummary/an.base.html.md#an.base.DEFAULT_DUCK_DB) | how far a ducked cue drops under dialogue, and how fast it gets there and comes back. | ### Functions | [`swap_set_name_problem`](_autosummary/an.base.html.md#an.base.swap_set_name_problem)(name) | Why `name` cannot be a swap-set name, or `None` if it can. | |--------------------------------------------------------------------------------|--------------------------------------------------------------| ### an.base.AUTHORABLE_PROPERTIES *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'alpha', 'dash_offset', 'perspective', 'pivot_x', 'pivot_y', 'plane_fade_end', 'plane_fade_start', 'rotation', 'rotation_rad', 'rotation_x', 'scale_x', 'scale_y', 'skew_x', 'skew_y', 'tint', 'tint_b', 'tint_g', 'tint_r', 'trim_end', 'trim_start', 'x', 'y'})* a compiled transform channel, or the authored colour spelling the compiler expands. Validate checks against this, and the compiler’s rest table against `TRANSFORM_PROPERTIES` — the difference between the two sets is exactly `tint`, and a test pins that rather than trusting it. * **Type:** What a set/tween may name ### an.base.BT709_SCALE_FILTER *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'scale=out_range=tv:out_color_matrix=bt709'* The RGB->YUV conversion `an` performs, stated EXPLICITLY rather than left to the encoder flags to imply. an#34 pinned `-colorspace bt709` and measured that it does not merely *tag* the file: it sets the matrix of the auto-inserted conversion, so the encoded planes themselves change. That measurement was made on ffmpeg 8/9 and \*\*is not a universal ffmpeg fact\*\* (an#148). Measured on the product’s own `_ffmpeg_mux` with flat known-colour frames, decoded as raw `yuv420p` (planes verbatim, no conversion on read), against the analytic limited-range values: build | pure red decodes to Y | BT.601 says | BT.709 says |
``` |---| ``` — ``` |---| ``` —| | ffmpeg 9.0.1 | 63 | 81.5 | 62.6 | | ffmpeg 6.1.6 | 81 | 81.5 | 62.6 | Over five colours and all three planes, the worst disagreement is 0.44 from BT.709 and 28.45 from BT.601 on ffmpeg 9 – and 0.48 from BT.601 against 27.63 from BT.709 on ffmpeg 6.1.6, which is the CI runner’s apt build. Both files are *tagged* `color_space=bt709 color_primaries=bt709 color_transfer=bt709 color_range=tv`. So on 6.1 an#34’s re-baseline was metadata only: `an` shipped BT.601 planes wearing a BT.709 label, and a conforming player undoes a conversion that was never applied. This filter removes the build-dependence by naming the conversion instead of inferring it. It is BYTE-IDENTICAL to today’s output on ffmpeg 9.0.1 (measured: same mp4 sha256 on real corpus frames), so it re-baselines nothing where the flags already worked, and it moves ffmpeg 6.1.6’s output onto the same conversion (its residual against an analytic BT.709 reference drops from luma mean 0.788 to 0.205 – ffmpeg 9’s own number to three decimals). \*\*The committed ledger rows were captured on ffmpeg 8.1, which is not on this machine, so the byte-identity above was not re-measured there.\*\* That those rows are equally unaffected rests on an#34’s own measurement — that on 8.x `-colorspace bt709` already set the auto-inserted conversion, so this filter names what that build was doing anyway. It is a sound inference from a recorded measurement, not a second observation; treat it as such if an 8.x build ever contradicts a row. Here, and not beside one of the ffmpeg calls, for the same reason `MP4_FASTSTART_ARGS` is: **three commands must agree on it**, and they are in two packages. The delivered mux (`_ffmpeg_mux`), the bench’s lossless reference leg and the bench’s PNG decode leg all perform this conversion, and the lossless leg’s entire contract is “these ARE the planes libx264 received”. Pin one and not the others and every encode-side metric silently measures a colour-space disagreement instead of encoder damage – the failure `an/bench/imageio.py`’s module docstring records CI catching once already. ### an.base.COLOUR_PROPERTY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'tint'* The property names the cutout runtime animates NUMERICALLY. Any other property on a set/tween names a swap SET declared by the target entity’s descriptor (an#87). This is the SSOT the three consumers share so the IR validator, the character validator and the compiler cannot drift: the compiler derives its rest-value table from `TransformJSON` and a test asserts that derivation equals this set. Lives here because `an.base` is the one module all three layers may import. The colour multiply as an AUTHOR spells it. Not in `TRANSFORM_PROPERTIES` because nothing downstream of the compiler ever sees it — `_expand_tint_actions` rewrites each leaf into the three numeric components before the swap-set dispatch, which would otherwise read it as an asset-set name (an#62). ### an.base.COMPATIBLE_VERSION *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '0.3.0'* Minimum Scene IR version this code can still read without migration. ### an.base.DEFAULT_DUCK_DB *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= -12.0* how far a ducked cue drops under dialogue, and how fast it gets there and comes back. The ramps are linear in gain. * **Type:** Ducking defaults ### an.base.DEFAULT_SUPERSAMPLE *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 1* Render at this many times the declared resolution, then resolve back with an exact block mean. **1 is off, and off is free**: the un-supersampled path keeps Chromium’s own PNG bytes and pays nothing. Here rather than in `an.adapters.cutout.supersample`, where the rest of the mechanism lives, because `an/adapters/_base.py` needs it for `RenderContext`’s default and importing the cutout package from there is a real cycle (`_base` -> `cutout` -> `render` -> `_base`), not a hypothetical one. `an/base.py` imports nothing from `an`. The default stays 1 deliberately. Supersampling ships OPT-IN with its A/B committed (an#58, discussion #52), per the standing rule that a default chosen by taste ships opt-in and the flip is its own one-line change. ### an.base.DEFAULT_TRANSITION_COLOR *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '#000000'* The colour a `fade` passes through when it names none. ### an.base.DEFAULT_TRANSITION_DURATION *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.5* half a second is a conventional editor’s default, short enough not to eat a line of dialogue and long enough to read as deliberate. * **Type:** Seconds, when a `fade` or `dissolve` names no duration ### an.base.EASING_PRESETS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('linear', 'ease', 'ease_in', 'ease_out', 'ease_in_out', 'step')* Named easing presets. Renderers should accept these and the cubic-Bézier 4-tuple form `[cx1, cy1, cx2, cy2]`. They are `an`’s LEGACY family ([`an.timing.easing`](_autosummary/an.timing.easing.html.md#module-an.timing.easing)): `ease` and `ease_in_out` are the quadratic ease-in-out, not CSS `ease`; the CSS curves are the hyphenated names (`ease-in-out`, `cubic-bezier(...)`) of the `css` family. ### an.base.EasingSpec *: [TypeAlias](https://docs.python.org/3/library/typing.html#typing.TypeAlias)* *= str | tuple[float, float, float, float] | list[float]* Either an easing preset name or a 4-tuple cubic-Bézier control [cx1,cy1,cx2,cy2]. ### an.base.FILM_AUDIO_SAMPLE_RATE *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 44100* The film mix’s sample rate and channel count. The SAME values the per-shot audio mux (`an.stage.render._ffmpeg_add_audio`) writes, so a film assembled from sources and one concatenated from shot mp4s carry the same audio format. ### an.base.MP4_FASTSTART_ARGS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('-movflags', '+faststart')* Put the mp4’s `moov` atom in front of `mdat`, so a player can start before the file has finished downloading. Here, and not beside one of the ffmpeg calls, because \*\*three separate commands build the one file a user receives\*\* – the frame mux (`_ffmpeg_mux`), the audio mux (`_ffmpeg_add_audio`) and the concat (`_ffmpeg_concat`) – and each of the last two re-lays the container with `-c copy`, which writes `moov` LAST. The flag was on the first of those alone, which reads as done and delivers nothing: it applied only to `silent.mp4`, a per-shot intermediate that is never handed to anyone. Measured on a local example render (these mp4s are gitignored build products; `git ls-files` tracks exactly one, and it is moov-last too): `.an/render_work/shot_s1/silent.mp4` is `ftyp moov free mdat`, while the per-shot mp4, `artifacts/shots/*.mp4` and `output/main.mp4` are all `ftyp free mdat moov`. Single-shot and multi-shot alike; an#57’s “single-shot ones keep it” is wrong, because the `shutil.copy` branch copies a file that already lost it. Deliberately NOT part of `DETERMINISTIC_X264_ARGS`. That tuple is an `ENCODE_ENV_PATHS` comparability key (an/bench/compare.py:98), and this flag moves no number the panel reads: with `-c copy` it is a container rewrite, not a re-encode. Verified on ffmpeg 8.1 – elementary-stream sha256 identical, video/audio packet totals identical, file size identical, decoded YUV sha256 identical, wall time unchanged. ### an.base.PLANE_REST_VALUES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= {'perspective': 1.0, 'plane_fade_end': 0.0, 'plane_fade_start': 0.0, 'rotation_x': 0.0}* a node targeted with any of them is drawn on a plane tilted away from the camera (`rotation_x`, radians, positive = the top recedes; `perspective`, the eye’s distance in frame heights; `plane_fade_start`/`plane_fade_end`, the far fade, scene px up the plane from the hinge, off while the end is `<= 0`). See `runtime.js` “Planes” and `an.stage.timeline.Transform2D`. Their rest values — the untilted plane, the eye one frame height away, no far fade — the one table the compiler’s rest table, the Python projection (`an.stage.timeline`) and `runtime.js`’s `PLANE_PROPERTIES` (pinned by a test) agree on. * **Type:** The plane properties inside `TRANSFORM_PROPERTIES` (an#314) ### an.base.PathStr Slash-delimited node path, e.g. `"charlie/head/mouth"`. The example matters: an unknown target now RAISES rather than being skipped, and the long-standing `"charlie/torso/left_arm"` illustration names a node no rig actually builds — the cutout rigs are flat, so arms are siblings of the torso, not children of it. ### an.base.RendererName Which renderer draws a shot. The orchestrator uses this to pick an adapter. alias of [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)[‘cutout’, ‘stage’, ‘manim’, ‘motion_graphics’, ‘whiteboard’] ### an.base.SCHEMA_VERSION *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '0.3.0'* Current Scene IR schema version. Bump on additive changes; on breaking changes, also bump COMPATIBLE_VERSION and add a migration in `ir.migrate`. 0.2.0 renamed `Shot.style` -> `Shot.renderer` and `Meta.default_style` -> `Meta.default_renderer`, and retired `AssetRef(kind="style")` (an#106). 0.3.0 removed `Camera.position` / `.target` / `.focal_length`, which described a 3D camera this package never had, and gave `Camera` a `keys` list so it can translate (an#109). ### an.base.SUPPORTED_RENDERERS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('cutout', 'stage', 'manim', 'motion_graphics', 'whiteboard')* The same vocabulary as [`RendererName`](_autosummary/an.base.html.md#an.base.RendererName), as a runtime tuple — DERIVED from it, because a hand-typed second copy is a second SSOT that drifts on the day a renderer is added and nothing fails. ### an.base.SWAP_SET_NAME_FORBIDDEN_SUBSTRINGS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('/', '::')* `/` would read as a path segment and `::` is the runtime’s pose-key separator. * **Type:** Characters within which a swap-set name is not addressable ### an.base.Seconds Time in seconds. Floats at the IR boundary; rational time is used internally only inside the audio pipeline where drift matters. ### an.base.TRANSITION_KINDS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('cut', 'fade', 'dissolve', 'wipe')* The transition kinds a shot may be entered by. `cut` is the default and what every document written before transitions existed means. ### an.base.TRIM_PROPERTIES *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'dash_offset', 'trim_end', 'trim_start'})* The path-only properties inside `TRANSFORM_PROPERTIES` (an#160; the name predates `dash_offset`, an#161): trim and the dash phase. A node that draws no path refuses all of them. ### an.base.WIPE_DIRECTIONS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('left', 'right', 'up', 'down')* The ways a `wipe`’s edge can travel across the frame (an#390). ### an.base.swap_set_name_problem(name) Why `name` cannot be a swap-set name, or `None` if it can. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> swap_set_name_problem("hands") is None True >>> swap_set_name_problem("alpha") "'alpha' is a transform property; the runtime's static switch would shadow the set" >>> swap_set_name_problem("a::b") "'a::b' contains '::', which is reserved" ``` # _autosummary/an.bench.capture.html.md # an.bench.capture Render one corpus fixture into a throwaway copy, and hand back its artifacts. Two things this module exists to get right, both of which produce plausible numbers when got wrong: **Render into a copy.** The render path mutates the project directory — scene mtimes, the decisions log, `.an/render_work` — so rendering in place makes the git sha in the ledger filename a lie about the tree that produced the row. **Do not inherit a stale render.** `shutil.copytree` of a developer’s checkout would carry `.an/render_work` and `output/` across, `frames/` is never cleared, and ffmpeg’s image2 demuxer reads the contiguous `frame_%06d.png` run from 0 — so a longer previous render is silently appended to this one. Every encode-side metric pairs source frame *i* with decoded frame *i*, so that appends garbage to one leg and shifts nothing on the other. `artifacts/` is deliberately kept *except for one subdirectory*: it holds the audio cache, whose warm/cold state is recorded rather than destroyed — but `artifacts/shots` is `mall["shots"]`, the previous render’s per-shot mp4s, and this module’s whole promise is that nothing of a previous render crosses. It is gitignored, so it does not reproduce on a clean checkout: a per-developer landmine, in the module whose docstring says the opposite. ### Functions | [`capture_fixture`](_autosummary/an.bench.capture.html.md#an.bench.capture.capture_fixture)(name, fixture, \*, repo_root) | Render `fixture` in a throwaway copy and return its artifacts. | |--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`cleanup`](_autosummary/an.bench.capture.html.md#an.bench.capture.cleanup)(capture) | Remove a capture's throwaway tree. | | [`dirty_paths`](_autosummary/an.bench.capture.html.md#an.bench.capture.dirty_paths)(repo_root) | `git status --porcelain` lines, so a capture can prove it touched nothing. | | [`distinct_png_sizes`](_autosummary/an.bench.capture.html.md#an.bench.capture.distinct_png_sizes)(frames_dir) | Every distinct `(width, height)` among a shot's frame PNGs, sorted. | | [`expected_frame_count`](_autosummary/an.bench.capture.html.md#an.bench.capture.expected_frame_count)(duration, fps) | The renderer's own frame-count expression, reused rather than restated. | ### Classes | [`SceneCapture`](_autosummary/an.bench.capture.html.md#an.bench.capture.SceneCapture)(name, source, prepared, ...[, ...]) | One fixture's whole render. | |-----------------------------------------------------------------------------------------------------|--------------------------------| | [`ShotCapture`](_autosummary/an.bench.capture.html.md#an.bench.capture.ShotCapture)(shot_id, frames_dir, scene_json, ...) | One rendered shot's artifacts. | ### Exceptions | [`GitStatusUnavailable`](_autosummary/an.bench.capture.html.md#an.bench.capture.GitStatusUnavailable) | `git status` did not answer, so "the tree is clean" is not known. | |-------------------------------------------------------------------------|---------------------------------------------------------------------| ### *exception* an.bench.capture.GitStatusUnavailable Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) `git status` did not answer, so “the tree is clean” is not known. Separated from an empty result on purpose. `git status` failing prints nothing to stdout, so `check=False` turned every failure into “no dirty paths” — indistinguishable from a clean tree, and *silently* so. Measured: a concurrent `git` in a linked worktree of this repo takes `index.lock`, `git status` exits nonzero with empty stdout, and `test_a_capture_leaves_the_repository_untouched` fails with `[] != [...]` — an assertion about the capture, pointing at nothing, in a run that has been green fifty times. A check that could not run is not evidence that nothing is wrong. ### *class* an.bench.capture.SceneCapture(name, source, prepared, project_dir, mp4, shots, resolution, fps, duration, n_declared_entity_refs, visual_kinds, asset_resolution, audio_cache, wall_seconds, determinism=, capture='', film=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One fixture’s whole render. #### capture *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* How the frames left the browser (`"screenshot"` / `"canvas"`), resolved the way the render resolves it. The decoded pixels are the same either way, so no metric moves — but `wall_seconds` does, several-fold, and a timing row is only readable beside the path that produced it (an#192 flipped the default). #### film *: [ShotCapture](_autosummary/an.bench.capture.html.md#an.bench.capture.ShotCapture) | [None](https://docs.python.org/3/builtins/constants.html#None)* An ASSEMBLED scene’s composed frames (transitions, a sound layer — `an.assemble`), as one segment: what the delivered mp4 shows. `None` for a scene that is the concatenation of its shots, which is every scene before an#279’s core corpus. When set, every metric, the golden frames and the frame count read IT — pairing the shots’ frames against a film whose dissolves overlap them would measure the overlap, not the encoder. #### *property* frame_segments *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[ShotCapture](_autosummary/an.bench.capture.html.md#an.bench.capture.ShotCapture)]* The frame sequence(s) the delivered mp4 shows, in order. ### *class* an.bench.capture.ShotCapture(shot_id, frames_dir, scene_json, runtime_dir, frame_count, duration=0.0, frame_sizes=()) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One rendered shot’s artifacts. #### duration *: [float](https://docs.python.org/3/builtins/functions.html#float)* The shot’s declared duration, from the IR rather than from the staged scene, so the expected frame count is derived from the same number the renderer used. #### frame_sizes *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), [int](https://docs.python.org/3/builtins/functions.html#int)], ...]* The distinct pixel sizes actually on disk, from each PNG’s IHDR. The independent half of a pair whose other half — `SceneCapture.resolution` — comes from the staged scene’s `meta` and never from a file. Empty only when the shot wrote no frames. ### an.bench.capture.capture_fixture(name, fixture, , repo_root, keep_render=None) Render `fixture` in a throwaway copy and return its artifacts. The copy lives until the caller is done with it — the metrics read the frames — so this is a context-free function that leaves the tree in place and hands back the path. `captured()` is the scoped form. * **Return type:** [`SceneCapture`](_autosummary/an.bench.capture.html.md#an.bench.capture.SceneCapture) ### an.bench.capture.cleanup(capture) Remove a capture’s throwaway tree. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.bench.capture.dirty_paths(repo_root) `git status --porcelain` lines, so a capture can prove it touched nothing. Raises [`GitStatusUnavailable`](_autosummary/an.bench.capture.html.md#an.bench.capture.GitStatusUnavailable) when git does not answer, rather than reporting a clean tree it never observed. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.capture.distinct_png_sizes(frames_dir) Every distinct `(width, height)` among a shot’s frame PNGs, sorted. Read from each file’s IHDR — 24 bytes per frame — so reading all of them costs nothing and catches what sampling one would miss: a sequence whose size changes partway through, which is what a half-applied supersample produces. **Recorded here, enforced elsewhere.** Rendering a fixture at a size the scene does not declare is a legitimate thing to do — `misc/bench/wave3_ab.py` patches `runtime.js` to `resolution: k, autoDensity: false` and drives [`capture_fixture()`](_autosummary/an.bench.capture.html.md#an.bench.capture.capture_fixture) directly to measure the supersample — so this module reports what it saw and [`an.bench.run`](_autosummary/an.bench.run.html.md#module-an.bench.run) is where the *bench’s* invariant is asserted. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`int`](https://docs.python.org/3/builtins/functions.html#int)], [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.bench.capture.expected_frame_count(duration, fps) The renderer’s own frame-count expression, reused rather than restated. `max(1, int(round(duration * fps)))` — and Python 3’s `round` is banker’s rounding, so `math.ceil` or `int(x + 0.5)` silently disagrees on every half-frame duration. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> expected_frame_count(2.5, 24) 60 >>> expected_frame_count(0.0, 24) 1 ``` # _autosummary/an.bench.compare.html.md # an.bench.compare `an bench --compare`: read two ledger rows, and **refuse when they are not comparable**. Refusing is the feature. Two rows measured on different scenes, at different resolutions, or on different x264 builds are not “one better and one worse” — every number in them is **uninterpretable** relative to the other, and a number reported across incomparable rows is worse than no number at all. Three things here that are easy to get wrong in a way that still produces a plausible verdict: **A single per-metric sign mis-reports one of the two mutations.** The sharpness family moves in *opposite* directions for AA-off and high-CRF, so the direction is read per metric *and per mutation*, from the `under_mutation` block the row already carries. Where the optimum is interior (`edge_transition_width` — under 1 is a staircase, 3+ is soft) there is no “better” direction at all, and the comparison says `changed`, never `regression`. Inventing a band there would be the silently-widened threshold this whole wave exists to prevent. **The two sides have opposite comparison rules, and both are measured.** Render-side rows compare across any machine: zero differing pixels across arm64 macOS, x86-64 Linux and arm64 Linux, across two SwiftShader JIT backends — \*at a pinned Chromium build\*, which is why the browser build is itself a render-side comparability key. Encode-side rows are **machine-scoped**: same ISA and x264 build is byte-identical, a different ISA moves the decoded stream a little, and a different x264 build moves it by two orders of magnitude. A band wide enough to absorb that would swallow `flat_field_deviation`’s entire crf18->23 signal (0.0003 -> 0.0005), so the answer is to refuse, not to widen. **There is no tolerance, and none is needed.** Every comparison is exact. Measured: two consecutive `an bench` runs on the same machine produce **bit-identical** numbers for every metric on all six scenes, and identical `source_pixels_sha256` — the render is pinned and the encode is pinned, so a delta of exactly zero is the normal case and any nonzero delta is a real change. An epsilon here would only hide small real movements. **A direction must survive the metric’s own knobs** (an#140). The two hard-threshold counters (`flat_field_deviation`, `encode_flicker_on_held_pixels`) carry their count at every cell of a small grid of their own free parameters, and a movement whose direction some cells contradict is reported `unstable` — neither counted toward a family nor `contrary`. Measured: under 4:2:0 -> 4:4:4, `graded_field`’s flat-field count read +84.2% at tol 6 and -81.6% at tol 8, and the panel had no way to say so. That is not a tolerance band: every cell is still compared exactly; what changes is whether the answer is a direction at all. A fourth, quieter one: **a metric’s own declaration is a comparability key**. If `family` or `optimum` changed between the two rows, the metric means something different in each and the comparison is refused for that metric alone — which is why every row carries its full `metric_declarations` block rather than referencing the registry that happened to be installed. ### Module Attributes | [`SUPPORTED_SCHEMA_VERSIONS`](_autosummary/an.bench.compare.html.md#an.bench.compare.SUPPORTED_SCHEMA_VERSIONS) | Row schema versions this comparer understands. | |------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`SCENE_KEYS`](_autosummary/an.bench.compare.html.md#an.bench.compare.SCENE_KEYS) | Scene-provenance fields that must match for ANY metric to be comparable. | | [`MASK_PARAM_PATHS`](_autosummary/an.bench.compare.html.md#an.bench.compare.MASK_PARAM_PATHS) | Mask **parameters**, addressed by path into the scene's `masks` block. | | [`RENDER_ENV_PATHS`](_autosummary/an.bench.compare.html.md#an.bench.compare.RENDER_ENV_PATHS) | Row-provenance paths that must match for a **render-side** metric. | | [`ENCODE_ENV_PATHS`](_autosummary/an.bench.compare.html.md#an.bench.compare.ENCODE_ENV_PATHS) | Row-provenance paths that must match for an **encode-side** metric. | | [`COMMON_ENV_PATHS`](_autosummary/an.bench.compare.html.md#an.bench.compare.COMMON_ENV_PATHS) | Row-provenance paths that must match for **either** side. | | [`DECLARATION_KEYS`](_autosummary/an.bench.compare.html.md#an.bench.compare.DECLARATION_KEYS) | Per-metric declaration fields that must agree, or the metric means something different in each row. | | [`REQUIRED_FAMILIES`](_autosummary/an.bench.compare.html.md#an.bench.compare.REQUIRED_FAMILIES) | How many distinct causal families must move as declared for a mutation to count as caught. | | [`CROSS_CHECKED_FIELDS`](_autosummary/an.bench.compare.html.md#an.bench.compare.CROSS_CHECKED_FIELDS) | Every field a row stores TWICE — inline on the metric and in `metric_declarations` — except `under_mutation`, whose nested shape gets `_prediction_disagreements` instead. | | [`SCORING_FIELDS`](_autosummary/an.bench.compare.html.md#an.bench.compare.SCORING_FIELDS) | The fields of a per-mutation prediction that the verdict actually reads. | ### Functions | [`compare`](_autosummary/an.bench.compare.html.md#an.bench.compare.compare)(before, after, \*[, mutation]) | Compare two ledger rows. | |----------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | [`direction_of`](_autosummary/an.bench.compare.html.md#an.bench.compare.direction_of)(before, after) | `increase` / `decrease` / `no_change` — exactly, with no tolerance. | | [`format_comparison`](_autosummary/an.bench.compare.html.md#an.bench.compare.format_comparison)(report) | The human-readable digest. | | [`latest_rows`](_autosummary/an.bench.compare.html.md#an.bench.compare.latest_rows)(\*[, root, count]) | | | [`load_row`](_autosummary/an.bench.compare.html.md#an.bench.compare.load_row)(path) | Read one ledger row from disk. | | [`readable_sweep`](_autosummary/an.bench.compare.html.md#an.bench.compare.readable_sweep)(sweep) | `sweep` if every cell is a possible `[counted, of]` pair, else `None`. | | [`sweep_verdict`](_autosummary/an.bench.compare.html.md#an.bench.compare.sweep_verdict)(before, after, \*[, shipped]) | Does a threshold counter's direction survive its own parameter grid? | ### Exceptions | [`ComparisonError`](_autosummary/an.bench.compare.html.md#an.bench.compare.ComparisonError) | The comparer was handed something it cannot read at all. | |--------------------------------------------------------------------|------------------------------------------------------------| ### an.bench.compare.COMMON_ENV_PATHS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], ...]* *= (('render_kwargs',),)* Row-provenance paths that must match for **either** side. ### an.bench.compare.CROSS_CHECKED_FIELDS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('family', 'side', 'comparison_scope', 'reference')* Every field a row stores TWICE — inline on the metric and in `metric_declarations` — except `under_mutation`, whose nested shape gets `_prediction_disagreements` instead. Both copies are written from one registry at one moment, so a disagreement means the row was edited, and `compare` reads the INLINE one. Three defects of this exact class were found in one review pass, each on a field that had been left out: `family` (moved a witness between families and took `criterion_met_on` from three scenes to five), `under_mutation` (flipped `contrary` to `as_declared`), and `comparison_scope` (compared an encode-side metric across a different ISA). The list is therefore checked for COMPLETENESS by a test rather than maintained by hand — see `tests/test_bench_compare.py::test_every_doubly_stored_field_is_cross_checked`. ### *exception* an.bench.compare.ComparisonError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) The comparer was handed something it cannot read at all. ### an.bench.compare.DECLARATION_KEYS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('family', 'side', 'optimum', 'unit')* Per-metric declaration fields that must agree, or the metric means something different in each row. `optimum` decides which way “better” points and `family` decides what an#41’s criterion counts. ### an.bench.compare.ENCODE_ENV_PATHS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], ...]* *= (('environment', 'encode_side', 'isa'), ('environment', 'encode_side', 'x264_sei'), ('environment', 'encode_side', 'x264_argv'), ('environment', 'encode_side', 'pix_fmt'), ('environment', 'encode_side', 'scale_filter'), ('encode_command_source',), ('decode_commands',))* Row-provenance paths that must match for an **encode-side** metric. ### an.bench.compare.MASK_PARAM_PATHS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], ...]* *= (('masks', 'edge', 'operator'), ('masks', 'edge', 'threshold'), ('masks', 'flat', 'operator'), ('masks', 'flat', 'dilate_k'), ('masks', 'held', 'operator'), ('masks', 'ring', 'operator'), ('masks', 'render_edge', 'operator'), ('masks', 'render_edge', 'threshold'))* Mask **parameters**, addressed by path into the scene’s `masks` block. The counts and fractions beside them are measurements and are excluded. ### an.bench.compare.RENDER_ENV_PATHS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], ...]* *= (('environment', 'render_side', 'chromium_build'), ('environment', 'render_side', 'playwright'), ('environment', 'render_side', 'launch_argv'))* Row-provenance paths that must match for a **render-side** metric. The Chromium build is here and not merely informational: the cross-arch verdict measured ISA- and OS-invariance *at a pinned build*, and an#38’s golden path keys on the build for the same reason. One bump has been measured to move zero pixels (1187 -> 1223), so this refusal is precautionary rather than a known break — and a deliberate re-bless is the intended response. ### an.bench.compare.REQUIRED_FAMILIES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 3* How many distinct causal families must move as declared for a mutation to count as caught. an#41’s criterion, restated from the research: “>=3 metrics from >=3 distinct causal families, evaluated per mutation, with a per-metric per-mutation sign declared in advance”. ### an.bench.compare.SCENE_KEYS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('scene_contract_sha256', 'resolution', 'fps', 'n_frames', 'shot_order', 'palette_hex', 'tolerances')* Scene-provenance fields that must match for ANY metric to be comparable. Deliberately not the whole provenance block: that also carries per-run *measurements* (mask pixel counts, `wall_seconds`, the golden diagnostics), which change exactly when the render changes — i.e. when the two rows are most worth comparing. ### an.bench.compare.SCORING_FIELDS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('expect', 'counts', 'gate', 'state')* The fields of a per-mutation prediction that the verdict actually reads. `reason` is prose and is deliberately NOT here — the declarations block carries it and the inline block drops it, so requiring it would refuse every real row. ### an.bench.compare.SUPPORTED_SCHEMA_VERSIONS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), ...]* *= (1,)* Row schema versions this comparer understands. A row it cannot read is refused rather than guessed at — the whole point of the version field. ### an.bench.compare.compare(before, after, , mutation=None) Compare two ledger rows. Returns a report; raises only on an unreadable row. `mutation` selects the question. With one, the report answers an#41’s: did the declared witnesses move in the declared direction, and did at least three distinct causal families do so. Without one, it answers “is the second row worse”, which only the one-sided metrics can answer at all. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.compare.direction_of(before, after) `increase` / `decrease` / `no_change` — exactly, with no tolerance. Two consecutive runs on one machine are bit-identical, so zero is the normal delta and any nonzero one is real. Booleans compare as booleans: a tripwire that went `True -> False` has not “decreased”. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> direction_of(1.0, 1.0) 'no_change' >>> direction_of(True, False) 'decrease' ``` ### an.bench.compare.format_comparison(report) The human-readable digest. Refusals first, because they are the verdict. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.compare.latest_rows(, root=None, count=2) * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)] The most recent committed ledger rows, newest last — \*\*by ``` ` ``` generated_at\`\*\*. Not by filename. Filenames are `-[-dirty].json`, so a filename sort orders same-day rows by *sha hex*. On a Wave 3 PR the re-baseline and the after-run are plausibly the same day, and when the after-commit’s sha sorts lower a bare `an bench-compare` silently swaps before and after and reports every improvement as a regression. A row whose `generated_at` cannot be read sorts **before** every dated one, so it is dropped as soon as two dated rows exist: a corrupt or pre-schema file must never become the `after` row a verdict is drawn from. The filename stays the tiebreak, which is what keeps a directory whose rows all lack the key ordered by date. `-dirty` rows are excluded: a row measured against uncommitted edits describes no commit, and comparing one is comparing against nothing nameable. `an bench --out` still lets a caller point at one explicitly. ### an.bench.compare.load_row(path) Read one ledger row from disk. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.compare.readable_sweep(sweep) `sweep` if every cell is a possible `[counted, of]` pair, else `None`. Possible means integers (a bool is not a count), `of > 0` and `0 <= counted <= of` — a cell no measurement could have produced is an edited row, and reading it would let the edit choose the verdict. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> readable_sweep({"t=1": [3, 10]}) {'t=1': [3, 10]} >>> readable_sweep({"t=1": [11, 10]}) is None True >>> readable_sweep({"t=1": [True, 10]}) is None True ``` ### an.bench.compare.sweep_verdict(before, after, , shipped=None) Does a threshold counter’s direction survive its own parameter grid? an#140. `flat_field_deviation` counts pixels past a hard threshold over a mask eroded by a second free parameter, and a row carries its count at every cell of a declared grid of both (`sweep`: `{cell: [counted, of]}`). This reads the direction at every cell the two rows SHARE. When some cells rise and others fall, the shipped value’s direction is a property of where the threshold happened to be set, not of the change under test — measured, a 4:2:0 -> 4:4:4 change moved `graded_field` +84.2% at tol 6 and -81.6% at tol 8 — and `state` is `unstable`. `no_change` cells contradict nothing. Exact, like everything else here: fractions are compared by cross-multiplying the integer counts, never as rounded floats. Shared cells rather than identical grids: a dilation whose mask is empty in one row is omitted from that row, and discarding the other fourteen cells for it would let the verdict count unchecked. `unknown` only when a side has no readable sweep, or the `shipped` cell is not among the shared ones — the check could not run, which is a caveat and not a refusal, because a row written before an#140 has no sweep and is otherwise perfectly readable. (A row that DECLARES a sweep and carries none is refused upstream, in `_compare_scene`.) * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> sweep_verdict({"t=1": [1, 10], "t=2": [5, 10]}, {"t=1": [2, 10], "t=2": [4, 10]})["state"] 'unstable' >>> sweep_verdict({"t=1": [1, 10]}, {"t=1": [2, 20]})["state"] 'stable' >>> sweep_verdict({"t=1": [1, 10]}, None)["state"] 'unknown' >>> sweep_verdict(None, None) is None True ``` # _autosummary/an.bench.contract.html.md # an.bench.contract `scene_contract_sha256`: the fact that decides whether two rows are comparable. Two ledger rows measured on different scenes are not “one better and one worse” — every metric in them is **uninterpretable** relative to the other. `edge_transition_width`’s own docstring says so: the absolute value is scene-dependent, because a deliberately 3px black outline is legitimately non-flat. So each row carries a hash of the thing that was actually rendered. Deliberately a hash of the **staged compiled scene**, not of the project directory: the directory carries scene mtimes and a decisions log that move on every load, and hashing it would make every row incomparable with every other for reasons that never reached a pixel. ### Functions | [`count_drawable_entities`](_autosummary/an.bench.contract.html.md#an.bench.contract.count_drawable_entities)(scene_json) | Top-level entities under the synthetic root. | |----------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | [`count_nodes`](_autosummary/an.bench.contract.html.md#an.bench.contract.count_nodes)(scene_json) | Every node in the tree, root included. | | [`frames_sha256`](_autosummary/an.bench.contract.html.md#an.bench.contract.frames_sha256)(frame_paths) | `sha256` over the DECODED pixels of a frame sequence, never file bytes. | | [`scene_contract_sha256`](_autosummary/an.bench.contract.html.md#an.bench.contract.scene_contract_sha256)(scene_json) | A stable digest of what was rendered. | | [`scenes_contract_sha256`](_autosummary/an.bench.contract.html.md#an.bench.contract.scenes_contract_sha256)(scene_jsons) | The contract digest for a whole scene, across every shot in timeline order. | ### an.bench.contract.count_drawable_entities(scene_json) Top-level entities under the synthetic root. Named for what it counts. “n_entities” is ambiguous in this codebase — the IR’s `shot.entities` includes `voice` refs that configure the render rather than appearing in it, so the two numbers differ on every scene with dialogue. Both are recorded; only this one is inside the hash. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> count_drawable_entities({"scene": {"children": [{}, {}]}}) 2 ``` ### an.bench.contract.count_nodes(scene_json) Every node in the tree, root included. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> count_nodes({"scene": {"children": [{"children": [{}]}]}}) 3 ``` ### an.bench.contract.frames_sha256(frame_paths) `sha256` over the DECODED pixels of a frame sequence, never file bytes. The gate for `encode_flicker_on_held_pixels`: without it, half-res-then- nearest-upscale — the most visible possible flat-art regression — reports a 7.1x *improvement*, because a flattened render gives x264 large uniform skip regions. Decoded, not file bytes, for the reason the cross-architecture verdict records: Chromium 1187 -> 1223 changes 144/144 PNG files and **zero** pixels, so a file-byte digest goes red on the first Playwright bump for a reason unrelated to animation quality. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.contract.scene_contract_sha256(scene_json) A stable digest of what was rendered. Hashed over a *reduced* form rather than the whole document, and the reduction is the point: the digest must move when the picture’s contract moves and stay put otherwise. Animation keyframe floats and asset paths are in; nothing time- or machine-dependent is, because the compiled scene is already free of both (every escaping set goes through `sorted()`, the palette hash is `sum(ord(c)) % 5` rather than Python’s `hash()`, and the staged JSON is written with `sort_keys=True`). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> a = scene_contract_sha256({"meta": {"fps": 24}, "scene": {"children": []}}) >>> a == scene_contract_sha256({"scene": {"children": []}, "meta": {"fps": 24}}) True >>> len(a) 64 ``` ### an.bench.contract.scenes_contract_sha256(scene_jsons) The contract digest for a whole scene, across every shot in timeline order. A single-shot scene returns **exactly** [`scene_contract_sha256()`](_autosummary/an.bench.contract.html.md#an.bench.contract.scene_contract_sha256) of its one staged scene, so every row written before the corpus grew a multi-shot fixture stays comparable — `an bench --compare` refuses rows whose contract hash differs, and a gratuitous change here would retire the only committed row as evidence. A multi-shot scene hashes the ordered list of per-shot digests, because hashing only the first shot would let a change to the second one pass as “the same scene” — which is precisely the claim this digest exists to deny. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> a = {"scene": {"children": []}} >>> scenes_contract_sha256([a]) == scene_contract_sha256(a) True >>> scenes_contract_sha256([a, a]) == scene_contract_sha256(a) False ``` # _autosummary/an.bench.core_corpus.html.md # an.bench.core_corpus The core corpus: what `an` renders with no character and no genre (ADR 0001 decision 7). Before any module leaves `an` for `cutan` (P8), the core keeps a pixel gate of its own: **paths, text, planes, camera and transitions**, rendered by the stage engine (`an.stage`) with no character, with goldens and contract hashes of their own. These scenes are [`CORE_FIXTURES`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.CORE_FIXTURES): They live beside the cut-out corpus in `misc/bench/corpus/` and run in the same `an bench` (the cut-out corpus imports them, in [`an.bench.corpus`](_autosummary/an.bench.corpus.html.md#module-an.bench.corpus)), so they are blessed by the same protocol and their contract hashes are checked by the same default-leg guard. What makes them the CORE corpus is what they need: `tests/test_core_corpus.py` renders every one of them with NO GENRE REGISTERED and checks each pinned frame against its bless record. That they render with no cut-out CODE is proven too, since the move (an#225): the same tests run with every cut-out module poisoned. The cut-out corpus lives in `cutan` (`cutan.bench`); this module, the scenes and their goldens stay. This module is CORE (behind no firewall): the fixture type, the pinned render knobs, the throwaway copy and the browser-free contract hash moved here from [`an.bench.corpus`](_autosummary/an.bench.corpus.html.md#module-an.bench.corpus) and [`an.bench.capture`](_autosummary/an.bench.capture.html.md#module-an.bench.capture) (genre), which re-export them. Nothing here imports the stage at module level. ```pycon >>> sorted(CORE_FIXTURES) ['after_plane', 'front_plane', 'path_draw', 'path_shape', 'path_taper', 'path_wobble', 'rig_chain', 'rig_interleave', 'rig_order', 'rig_origin', 'rig_rest', 'stage_pan', 'text_card', 'text_counter', 'text_outline', 'text_swap', 'transitions'] ``` ### Module Attributes | [`BENCH_RENDER_KWARGS`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.BENCH_RENDER_KWARGS) | Rendering knobs pinned for every bench capture, recorded verbatim into the ledger. | |---------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`CORPUS_DIRNAME`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.CORPUS_DIRNAME) | Where the bench-owned fixtures live. | | [`CORE_FIXTURES`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.CORE_FIXTURES) | The core corpus (see the module docstring). | | [`IGNORED_ON_COPY`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.IGNORED_ON_COPY) | they are the previous render's output, and one of them silently extends this one's frame sequence. | | [`IGNORED_RELPATHS_ON_COPY`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.IGNORED_RELPATHS_ON_COPY) | Excluded by their path **relative to the project root**, POSIX-spelled. | | [`RENDER_WORK_RELPATH`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.RENDER_WORK_RELPATH) | Where the renderer leaves its per-shot working tree inside the project. | | [`FRAME_PNG_GLOB`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.FRAME_PNG_GLOB) | How a shot's frames are named on disk. | | [`FILM_SEGMENT_ID`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.FILM_SEGMENT_ID) | The id the bench gives an ASSEMBLED film's frames (transitions, a sound layer) when it measures them as one segment — what the delivered mp4 shows. | | [`FILM_FRAMES_RELPATH`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.FILM_FRAMES_RELPATH) | Where an assembled scene's composed frames are written, under the render's work directory, by [`compose_film_frames()`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.compose_film_frames) (the film itself is a concat of segments and never holds them, an#260). | ### Functions | [`compiled_contract_sha256`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.compiled_contract_sha256)(fixture, \*, repo_root) | The `scene_contract_sha256` a render of `fixture` would record — no browser. | |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`compose_film_frames`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.compose_film_frames)(scene, work_dir) | An assembled scene's composed frames, written under `work_dir` from its shots' frames ([`an.assemble.write_film_frames()`](_autosummary/an.assemble.html.md#an.assemble.write_film_frames)); `None` for a scene that is a plain concatenation of its shots. | | [`frames_dir_for`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.frames_dir_for)(work_dir, shot_id) | Where a render left the frames of `shot_id` (or of the composed film). | | [`golden_agreement`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.golden_agreement)(name, work_dir, \*, ...[, root]) | `{frame key: (blessed sha256, today's sha256)}` for every frame the committed bless record of `name` pins, read from a render's work dir. | | [`render_fixture`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.render_fixture)(fixture, \*, repo_root, base) | Render `fixture` cold, the way the bench does, in a copy under `base`. | | [`stage_copy`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.stage_copy)(fixture_dir, base) | Copy a fixture into `base`, leaving the previous render behind. | ### Classes | [`Fixture`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.Fixture)(path[, prepare, ...]) | A corpus scene: where it lives, how to build it, what it must render. | |----------------------------------------------------------------------------------|-------------------------------------------------------------------------| ### Exceptions | [`CaptureError`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.CaptureError) | A capture could not produce something the metrics need. | |-----------------------------------------------------------------|-----------------------------------------------------------| ### an.bench.core_corpus.BENCH_RENDER_KWARGS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]* *= {'auto_audio': False, 'parallel': 1, 'strict_assets': True}* Rendering knobs pinned for every bench capture, recorded verbatim into the ledger. NOT flags: a bench whose render knobs vary per invocation produces incomparable rows. `auto_audio=False` because audio cannot move a pixel and would otherwise make the frames depend on the audio cache’s warm/cold state; `parallel=1` because a timing-sensitive pool is one more thing to explain if the pixels ever do differ; `strict_assets=True` because a stand-in asset renders happily as a DIFFERENT picture (an#33). ### an.bench.core_corpus.CORE_FIXTURES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Fixture](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.Fixture)]* *= {'after_plane': Fixture(path='misc/bench/corpus/after_plane', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a prop placed BETWEEN two planes under a pan (an#344): a far sky (depth 0.25), a disc with \`stage.after: set/sky\`, then a wall in two pieces with a window gap and a sill, all at depth 1.0, while the camera pans 60 px. The disc is drawn behind the walls and rides the sky's parallax through its band wrapper: between the goldens the walls move 40 px and the sky and disc 10 px. A regression in the draw order (the disc over the wall), in the wrapper's compensation (the disc sliding against the sky), or in the band containers' addressing moves a golden."), 'front_plane': Fixture(path='misc/bench/corpus/front_plane', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="an environment cut by \`characters_after\` with an ANIMATED foreground plane (an#343): \`stage\` draws \`sky\` and \`hill\` behind a world text label and \`rail\` in front of it, in its own container with \`scope: stage\`, so the rail is addressed \`stage/rail\` (never \`stage_\_front/rail\`) and its \`y\` tween rises from 60 to 0 over the label. What moves between the goldens is the rail crossing the label: a regression in the runtime's scoped indexing (the channel would name nothing and the load throws), in the cut, or in the draw order moves a golden."), 'path_draw': Fixture(path='misc/bench/corpus/path_draw', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note="two stroked paths (an#160, an#161), both dashed and both coloured by a StylePack's \`stroke\` role: a marching-ants frame whose \`dash_offset\` runs 0 -> 20 px, and a cubic arrow that draws itself on (\`trim_end\` 0 -> 1) with its head on the moving tip. What moves between the goldens is the ROUTE growing (frame 0 shows none of it) and the frame's dashes sliding 6.7 px along their path; a regression in trim, in the dash phase, in the anchored-at-the-path-start rule that keeps a dash from crawling as the tip advances, or in the pack reaching a path, moves a golden. Butt caps, so a dash's ends are exact rather than rounded past their length."), 'path_shape': Fixture(path='misc/bench/corpus/path_shape', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note='closed and filled paths (an#161): a badge drawn whole (fill under a mitred border joined at its first corner, no caps there), and a region as two entities, a border-less fill whose node \`alpha\` fades 0 -> 1 under a closed border that draws itself on (\`trim_end\` 0 -> 1). Frame 0 shows only the badge; a regression in the fill, the closing join, the fill staying untrimmed or a \`width: 0\` path drawing a stroke moves a golden.'), 'path_taper': Fixture(path='misc/bench/corpus/path_taper', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note="variable-width paths (an#161), drawn as filled outlines: a wobbled brush stroke swelling from nothing to 1.2x and back to a point, and an arrow widening 0.2x -> 1x along a mitred polyline that draws itself on with its head on the tip. The width is anchored to the WHOLE path, so the arrow's base does not thin as it grows; a regression in the profile, the miter, the anchoring or the fill-instead-of-stroke rule moves a golden."), 'path_wobble': Fixture(path='misc/bench/corpus/path_wobble', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note='two hand-drawn paths (an#161): a solid frame wobbling 3 px at a 60 px wavelength, and an arrow wobbling 4 px that draws itself on (\`trim_end\` 0 -> 1). The wobble is compile-time (seeded by the entity id, no trigonometry), so the frame is the same in both goldens and only the route grows; a change to the noise, the seed, the end envelope or the resampling moves both.'), 'rig_chain': Fixture(path='misc/bench/corpus/rig_chain', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a desk-lamp prop with \`nesting: bones\` (an#340): base -> upper arm -> forearm, and a shade NESTED on the forearm's bone (the sword in the hand). The upper arm (rest 30 deg) tweens 0.52 -> -0.3 rad, the forearm (rest -70 deg, relative to the upper arm) -1.22 -> -0.4, the shade 0 -> 0.6: each turns about its joint and carries what hangs from it. A regression that flattened the chain (forearm left behind by the upper arm), inherited a parent's attachment offset, or applied a rest pose twice moves a golden."), 'rig_interleave': Fixture(path='misc/bench/corpus/rig_interleave', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="the rig_chain desk lamp (\`nesting: bones\`, base -> upper arm -> forearm -> shade) with an UNRELATED panel ordered between the upper arm (1) and the forearm (3) (an#430): the panel covers the upper arm's top and the forearm crosses OVER the panel, which no sort of one container's items can give. Painted from the entity's global \`paint_order\`. The same three tweens as rig_chain move the arm between the goldens. A regression that painted the chain together (the panel over both arms, or under both) moves a golden."), 'rig_order': Fixture(path='misc/bench/corpus/rig_order', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a nested chain drawn BEHIND the part it hangs from (an#403): \`rig_chain\`'s desk lamp in \`nesting: bones\` with the whole arm (upper, forearm, shade: draw orders 1-3) behind its base (4). The base's container sorts its own drawing after the arm (\`sortableChildren\`, \`z_index\`), which the stage used to refuse. Between the goldens the arm swings as in \`rig_chain\`; where it passes over the base the base is in front. A regression in the runtime's sort, the compiler's \`z_index\` or the chain refusal moves a golden."), 'rig_origin': Fixture(path='misc/bench/corpus/rig_origin', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="two copies of one three-bone signpost rig (base, post, sign) at the same \`stage.at\` height (an#338): \`footed\` declares its \`origin\` at the foot of its base, so its foot stands ON the placement line; \`centred\` declares none, so the middle of its bones' extent lands there and it hangs lower. \`footed\` tweens \`rotation\` 0 -> -0.4 rad, which turns it about the declared origin: between the goldens its sign swings left while its foot does not move, and \`centred\` does not move at all. A regression that ignored \`origin\` (both posts at one height), placed parts about the wrong point, or broke the shared rig builder moves a golden."), 'rig_rest': Fixture(path='misc/bench/corpus/rig_rest', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a tripod prop whose three legs are ONE drawing on three bones with \`rotation_deg\` 22 / 0 / -22 (an#339): the splay is the bones' rest pose, not pixels. The whole tripod tweens \`rotation\` 0 -> 0.3 rad about its declared origin (the centre foot), and the splayed legs ride it: at frame 8 the rig is tilted 0.2 rad with the splay intact. A regression that dropped the rest pose (three parallel legs), applied it twice, or let the entity's rotation replace a leg's instead of composing with it moves a golden."), 'stage_pan': Fixture(path='misc/bench/corpus/stage_pan', prepare=None, expect_visual_kinds=frozenset({'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="three coloured blocks at depths 0.25 / 1.0 / 2.0 under a zoom-free pan (an#111). What moves between the goldens is the SEPARATION: the blocks start aligned and end 10 / 40 / 80 px apart, which is the parallax and nothing else. Frame 8, not the mid-frame: the camera travels 5 px per frame and the far plane moves a quarter of that, so only every fourth frame lands every block on an exact pixel boundary — at any other frame the anti-aliased edge changes the exact-colour mask's SIZE, and a centroid measured against a different shape is not a displacement (the measurement refuses it outright). Zoom is held constant on purpose: the x = 0 probe that cancels it in the JSON half does not reach a centroid, which sits at the plane's own offset."), 'text_card': Fixture(path='misc/bench/corpus/text_card', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="text under a camera push-in and roll (an#279, the core corpus): two OVERLAY words fading in one after the other (\`word_1\` starts 0.125 s after \`word_0\`) and a WORLD label on a plane block, while the camera zooms 1.0 -> 1.3 and rolls 0.12 rad. What moves between the goldens: the words' alpha (frame 0 shows neither), the label and block growing and turning with the camera, and the overlay title NOT turning — a regression that put overlay text in the world, broke per-word addressing or the camera's zoom/roll moves a golden. The face is Pillow's embedded Aileron, so the glyphs do not depend on the machine's fonts."), 'text_counter': Fixture(path='misc/bench/corpus/text_counter', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.5), golden_note="a calendar counting 1 to 30 with ONE text block (an#342): a right-aligned \`counter: {format: '{d}', start: 1}\` under one linear \`tween day value -> 30\` over 1 s, lowered at compile to a replacement set of the strings the frames show. Frame 0 shows 1; frame 12's value is exactly 15.5, which nearest-half-even rounding shows as 16 (15 would mean ties away from even, 15/17 a sampling or set-time shift). A regression in the sampling grid, the half-frame set time, the rounding or the right-edge geometry moves a golden."), 'text_outline': Fixture(path='misc/bench/corpus/text_outline', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="OUTLINED text (an#313, OverSimplified's labels): white words with a 4 px near-black outline over a mid-blue plate and a pale stripe, the second word fading in from 0.125 s. Frame 0 shows the first word alone, outline and all, and NO outline where the second word will be (the outline lives in the word's own texture, so its alpha hides both); frame 8 shows both, legible over the blue and the stripe alike. A regression in the outline's width, its order under the fill, the box growth that keeps it unclipped, or per-word alpha moves a golden."), 'text_swap': Fixture(path='misc/bench/corpus/text_swap', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note='a text block\\'s CONTENT changing within one shot (an#341): one right-aligned \`unit: block\` label whose \`texts\` set is swapped twice, "Day 1" -> "Day 12" at 0.125 s (the entity-level \`set day text d12\`) -> "Day 300" at 0.25 s (the \`day/block_0\` path). What moves between the goldens is the string, growing LEFTWARDS from a fixed right edge: a regression in the swap set, in the per-key geometry anchored on the \`align\` edge, or in the entity-level fan-out moves a golden.'), 'transitions': Fixture(path='misc/bench/corpus/transitions', prepare=None, expect_visual_kinds=frozenset({'path', 'rect'}), golden_frames=(0.08333333333333333, 0.375, 0.625), golden_note="the delivered film's COMPOSED frames (an#279, the core corpus): \`dusk\` fades in from black over 0.25 s, then \`dawn\` dissolves in over 0.25 s (frames 6-11 are the blend; the film is 12 + 12 - 6 = 18 frames). Frame 2 is mid-fade, frame 9 mid-dissolve (both pictures at once), frame 15 \`dawn\` alone with its arrow. A regression in the fade colour, the dissolve weights, the overlap arithmetic or the order of the shots moves a golden. The only fixture measured on the film's frames rather than the shots' — what the delivered mp4 shows (an.bench.capture's film segment).")}* The core corpus (see the module docstring). ### an.bench.core_corpus.CORPUS_DIRNAME *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'misc/bench/corpus'* Where the bench-owned fixtures live. NOT under `examples/`, and the reason is mechanical rather than tidiness: `.gitignore` excludes every `examples/*/assets/`, so a corpus scene that needs committed art cannot live there without a carve-out per scene. `misc/` is not ignored at all. The second reason is that a metrics fixture must **hold still**. These four carry their whole rig as committed files and have no `prepare` step, so their pixels are a function of the repo alone — where `promote_demo`’s are a function of `cutan.characters.promote`, and would need re-blessing whenever that changes. ### *exception* an.bench.core_corpus.CaptureError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A capture could not produce something the metrics need. ### an.bench.core_corpus.FILM_FRAMES_RELPATH *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'film_frames'* Where an assembled scene’s composed frames are written, under the render’s work directory, by [`compose_film_frames()`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.compose_film_frames) (the film itself is a concat of segments and never holds them, an#260). ### an.bench.core_corpus.FILM_SEGMENT_ID *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'film'* The id the bench gives an ASSEMBLED film’s frames (transitions, a sound layer) when it measures them as one segment — what the delivered mp4 shows. ### an.bench.core_corpus.FRAME_PNG_GLOB *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'frame_\*.png'* How a shot’s frames are named on disk. One constant rather than the literal repeated at each glob site. ### *class* an.bench.core_corpus.Fixture(path, prepare=None, expect_visual_kinds=frozenset({}), golden_frames=, golden_note='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A corpus scene: where it lives, how to build it, what it must render. #### expect_visual_kinds *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)* Visual kinds the staged scene MUST contain — see the module docstring. #### golden_frames *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), ...]* Times (seconds, into the scene’s CONCATENATED timeline) at which a golden frame is blessed. Two per scene, the second chosen so something has actually moved — `--bless` refuses a pair whose two frames are pixel-identical, which is not hypothetical: `promote_demo`’s frame 0 and its `duration/2` frame differ by exactly **zero** pixels. #### golden_note *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* One line saying what moves between the two golden times. Carried as data because “pick a time where something moved” is a rule that decays into a habit, and the reason is what a reviewer needs when a golden goes red. #### prepare *: [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[[Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path)], [None](https://docs.python.org/3/builtins/constants.html#None)] | [None](https://docs.python.org/3/builtins/constants.html#None)* Run against the throwaway copy before loading, to regenerate build products the repo does not track. ### an.bench.core_corpus.IGNORED_ON_COPY *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('.an', 'output', '.anima')* they are the previous render’s output, and one of them silently extends this one’s frame sequence. Matched on the **basename**, at any depth — that is exactly what `shutil.ignore_patterns` does, and it is why `artifacts/shots` cannot be spelled here. See [`IGNORED_RELPATHS_ON_COPY`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.IGNORED_RELPATHS_ON_COPY). * **Type:** Copied for the render, but never these ### an.bench.core_corpus.IGNORED_RELPATHS_ON_COPY *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('artifacts/shots',)* Excluded by their path **relative to the project root**, POSIX-spelled. `mall["shots"]` is `/artifacts/shots`, and `artifacts/` itself is kept on purpose — it holds the audio cache, whose warm/cold state this module records rather than destroys. Neither spelling belongs in [`IGNORED_ON_COPY`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.IGNORED_ON_COPY), and \*\*both fail silently\*\*. `shutil.ignore_patterns` returns a closure handed the NAMES inside one directory, which it `fnmatch.filter``s — so ``"artifacts/shots"` can never match anything (no name contains a separator) and a bare `"shots"` would delete every directory of that name **anywhere** in the tree, a character rig’s included. ### an.bench.core_corpus.RENDER_WORK_RELPATH *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '.an/render_work'* Where the renderer leaves its per-shot working tree inside the project. ### an.bench.core_corpus.compiled_contract_sha256(fixture, , repo_root) The `scene_contract_sha256` a render of `fixture` would record — no browser. Compiles every timeline shot the way the cutout renderer does (the scene’s size, fps, style pack, default easing and stepped-timing policy, with `strict_assets` as the bench sets it) in a throwaway copy, and hashes the documents. It is the default-leg twin of `capture_fixture()`: the contract hash is a function of the compiled JSON alone, so the guards that check it — against the newest ledger row and against each golden’s bless record — run on every PR, not only in the labelled browser lane. It is the contract of a bench render, which passes no overrides: a render given its own `step_hz`, fps or resolution compiles something else. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.core_corpus.compose_film_frames(scene, work_dir) An assembled scene’s composed frames, written under `work_dir` from its shots’ frames ([`an.assemble.write_film_frames()`](_autosummary/an.assemble.html.md#an.assemble.write_film_frames)); `None` for a scene that is a plain concatenation of its shots. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.bench.core_corpus.frames_dir_for(work_dir, shot_id) Where a render left the frames of `shot_id` (or of the composed film). * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ```pycon >>> frames_dir_for(Path("w"), "film").as_posix(), frames_dir_for(Path("w"), "a").as_posix() ('w/film_frames', 'w/shot_a/frames') ``` ### an.bench.core_corpus.golden_agreement(name, work_dir, , chromium_build, root=None) `{frame key: (blessed sha256, today's sha256)}` for every frame the committed bless record of `name` pins, read from a render’s work dir. Decoded pixels, never file bytes (`an.bench.golden`’s criterion). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ### an.bench.core_corpus.render_fixture(fixture, , repo_root, base) Render `fixture` cold, the way the bench does, in a copy under `base`. Through the core API only (`an.project.load` + `an.render.render`) — no bench capture code — so it runs with the cut-out genre absent. Returns the render’s work directory. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.bench.core_corpus.stage_copy(fixture_dir, base) Copy a fixture into `base`, leaving the previous render behind. Split out of `capture_fixture()` so the exclusion is testable without rendering anything — which matters, because the failure it prevents is silent. `frames/` is never cleared and ffmpeg’s image2 demuxer reads the contiguous `frame_%06d.png` run from 0, so a longer previous render is appended to this one’s source leg and to nothing else. Two kinds of exclusion, because one kind cannot say both things: [`IGNORED_ON_COPY`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.IGNORED_ON_COPY) by basename at any depth, and [`IGNORED_RELPATHS_ON_COPY`](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.IGNORED_RELPATHS_ON_COPY) by path from the project root — which is the only way to drop `artifacts/shots` while keeping `artifacts/audio`. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) # _autosummary/an.bench.corpus.html.md # an.bench.corpus The bench corpus: which projects are measured, and what each must actually render. `expect_visual_kinds` is not belt-and-braces. Every `examples/*/assets/` is gitignored, and before an#33 a missing character descriptor made the compiler fall back to the procedural rig with **zero** warnings. The first cross-architecture capture measured exactly that: three CI runners agreed perfectly about a picture that was not the picture, and the agreement read as a clean positive result. It surfaced only because the local machine happened to hold a *stale* build product and therefore disagreed. So a fixture declares the render path it must exercise, and the check reads the scene JSON **the browser actually loaded** — an independent second opinion to `strict_assets=True`, which trusts the compiler that produced it. ### Module Attributes | [`SHOT_DIR_GLOB`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.SHOT_DIR_GLOB) | Per-shot subdirectory naming inside `.an/render_work`, and the staged scene filename. | |------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`DFLT_FIXTURES`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.DFLT_FIXTURES) | The cut-out scenes of the original corpus moved to `cutan` (`cutan.bench.CUTOUT_FIXTURES`, an#225); this is the core's: `prop_swap` and the core corpus (`an.bench.core_corpus`). | ### Functions | [`assert_render_path`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.assert_render_path)(name, fixture, kinds) | Refuse a capture that did not exercise the path its fixture declares. | |---------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`iter_shot_dirs`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.iter_shot_dirs)(work_dir, \*, order) | `(shot_id, shot_dir)` for every rendered shot, in **timeline** order. | | [`staged_scene`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.staged_scene)(shot_dir) | The compiled scene JSON the browser actually loaded, for one shot. | | [`visual_kinds`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.visual_kinds)(scene_json) | Every `visual.kind` in a staged scene's node tree. | ### Exceptions | [`CorpusError`](_autosummary/an.bench.corpus.html.md#an.bench.corpus.CorpusError) | A fixture did not render what it declared. | |----------------------------------------------------------------|----------------------------------------------| ### *exception* an.bench.corpus.CorpusError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A fixture did not render what it declared. ### an.bench.corpus.DFLT_FIXTURES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Fixture](_autosummary/an.bench.core_corpus.html.md#an.bench.core_corpus.Fixture)]* *= {'after_plane': Fixture(path='misc/bench/corpus/after_plane', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a prop placed BETWEEN two planes under a pan (an#344): a far sky (depth 0.25), a disc with \`stage.after: set/sky\`, then a wall in two pieces with a window gap and a sill, all at depth 1.0, while the camera pans 60 px. The disc is drawn behind the walls and rides the sky's parallax through its band wrapper: between the goldens the walls move 40 px and the sky and disc 10 px. A regression in the draw order (the disc over the wall), in the wrapper's compensation (the disc sliding against the sky), or in the band containers' addressing moves a golden."), 'front_plane': Fixture(path='misc/bench/corpus/front_plane', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="an environment cut by \`characters_after\` with an ANIMATED foreground plane (an#343): \`stage\` draws \`sky\` and \`hill\` behind a world text label and \`rail\` in front of it, in its own container with \`scope: stage\`, so the rail is addressed \`stage/rail\` (never \`stage_\_front/rail\`) and its \`y\` tween rises from 60 to 0 over the label. What moves between the goldens is the rail crossing the label: a regression in the runtime's scoped indexing (the channel would name nothing and the load throws), in the cut, or in the draw order moves a golden."), 'path_draw': Fixture(path='misc/bench/corpus/path_draw', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note="two stroked paths (an#160, an#161), both dashed and both coloured by a StylePack's \`stroke\` role: a marching-ants frame whose \`dash_offset\` runs 0 -> 20 px, and a cubic arrow that draws itself on (\`trim_end\` 0 -> 1) with its head on the moving tip. What moves between the goldens is the ROUTE growing (frame 0 shows none of it) and the frame's dashes sliding 6.7 px along their path; a regression in trim, in the dash phase, in the anchored-at-the-path-start rule that keeps a dash from crawling as the tip advances, or in the pack reaching a path, moves a golden. Butt caps, so a dash's ends are exact rather than rounded past their length."), 'path_shape': Fixture(path='misc/bench/corpus/path_shape', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note='closed and filled paths (an#161): a badge drawn whole (fill under a mitred border joined at its first corner, no caps there), and a region as two entities, a border-less fill whose node \`alpha\` fades 0 -> 1 under a closed border that draws itself on (\`trim_end\` 0 -> 1). Frame 0 shows only the badge; a regression in the fill, the closing join, the fill staying untrimmed or a \`width: 0\` path drawing a stroke moves a golden.'), 'path_taper': Fixture(path='misc/bench/corpus/path_taper', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note="variable-width paths (an#161), drawn as filled outlines: a wobbled brush stroke swelling from nothing to 1.2x and back to a point, and an arrow widening 0.2x -> 1x along a mitred polyline that draws itself on with its head on the tip. The width is anchored to the WHOLE path, so the arrow's base does not thin as it grows; a regression in the profile, the miter, the anchoring or the fill-instead-of-stroke rule moves a golden."), 'path_wobble': Fixture(path='misc/bench/corpus/path_wobble', prepare=None, expect_visual_kinds=frozenset({'path'}), golden_frames=(0.0, 0.3333333333333333), golden_note='two hand-drawn paths (an#161): a solid frame wobbling 3 px at a 60 px wavelength, and an arrow wobbling 4 px that draws itself on (\`trim_end\` 0 -> 1). The wobble is compile-time (seeded by the entity id, no trigonometry), so the frame is the same in both goldens and only the route grows; a change to the noise, the seed, the end envelope or the resampling moves both.'), 'prop_swap': Fixture(path='misc/bench/corpus/prop_swap', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.375), golden_note="a two-state prop swapping mid-shot (an#108): a desk lamp whose \`lamp\` asset-set goes \`off\` -> \`on\` at t=0.25. What moves between the goldens is a texture SWAP and nothing else — no transform, no easing, no interpolation — which is why this scene is worth a row the other seven cannot provide: every one of them measures a pose changing continuously, so a regression that broke swap resolution alone (the runtime resolves two swap properties on one node by NAME order, and an#87's failure mode was keeping the PREVIOUS texture in silence) would move no golden anywhere in the corpus. Frame 9 rather than the mid-frame: at 24 fps the swap lands on frame 6, so frame 9 is clear of the boundary in a way that does not depend on how the frame containing t=0.25 rounds."), 'rig_chain': Fixture(path='misc/bench/corpus/rig_chain', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a desk-lamp prop with \`nesting: bones\` (an#340): base -> upper arm -> forearm, and a shade NESTED on the forearm's bone (the sword in the hand). The upper arm (rest 30 deg) tweens 0.52 -> -0.3 rad, the forearm (rest -70 deg, relative to the upper arm) -1.22 -> -0.4, the shade 0 -> 0.6: each turns about its joint and carries what hangs from it. A regression that flattened the chain (forearm left behind by the upper arm), inherited a parent's attachment offset, or applied a rest pose twice moves a golden."), 'rig_interleave': Fixture(path='misc/bench/corpus/rig_interleave', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="the rig_chain desk lamp (\`nesting: bones\`, base -> upper arm -> forearm -> shade) with an UNRELATED panel ordered between the upper arm (1) and the forearm (3) (an#430): the panel covers the upper arm's top and the forearm crosses OVER the panel, which no sort of one container's items can give. Painted from the entity's global \`paint_order\`. The same three tweens as rig_chain move the arm between the goldens. A regression that painted the chain together (the panel over both arms, or under both) moves a golden."), 'rig_order': Fixture(path='misc/bench/corpus/rig_order', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a nested chain drawn BEHIND the part it hangs from (an#403): \`rig_chain\`'s desk lamp in \`nesting: bones\` with the whole arm (upper, forearm, shade: draw orders 1-3) behind its base (4). The base's container sorts its own drawing after the arm (\`sortableChildren\`, \`z_index\`), which the stage used to refuse. Between the goldens the arm swings as in \`rig_chain\`; where it passes over the base the base is in front. A regression in the runtime's sort, the compiler's \`z_index\` or the chain refusal moves a golden."), 'rig_origin': Fixture(path='misc/bench/corpus/rig_origin', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="two copies of one three-bone signpost rig (base, post, sign) at the same \`stage.at\` height (an#338): \`footed\` declares its \`origin\` at the foot of its base, so its foot stands ON the placement line; \`centred\` declares none, so the middle of its bones' extent lands there and it hangs lower. \`footed\` tweens \`rotation\` 0 -> -0.4 rad, which turns it about the declared origin: between the goldens its sign swings left while its foot does not move, and \`centred\` does not move at all. A regression that ignored \`origin\` (both posts at one height), placed parts about the wrong point, or broke the shared rig builder moves a golden."), 'rig_rest': Fixture(path='misc/bench/corpus/rig_rest', prepare=None, expect_visual_kinds=frozenset({'svg_sprite'}), golden_frames=(0.0, 0.3333333333333333), golden_note="a tripod prop whose three legs are ONE drawing on three bones with \`rotation_deg\` 22 / 0 / -22 (an#339): the splay is the bones' rest pose, not pixels. The whole tripod tweens \`rotation\` 0 -> 0.3 rad about its declared origin (the centre foot), and the splayed legs ride it: at frame 8 the rig is tilted 0.2 rad with the splay intact. A regression that dropped the rest pose (three parallel legs), applied it twice, or let the entity's rotation replace a leg's instead of composing with it moves a golden."), 'stage_pan': Fixture(path='misc/bench/corpus/stage_pan', prepare=None, expect_visual_kinds=frozenset({'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="three coloured blocks at depths 0.25 / 1.0 / 2.0 under a zoom-free pan (an#111). What moves between the goldens is the SEPARATION: the blocks start aligned and end 10 / 40 / 80 px apart, which is the parallax and nothing else. Frame 8, not the mid-frame: the camera travels 5 px per frame and the far plane moves a quarter of that, so only every fourth frame lands every block on an exact pixel boundary — at any other frame the anti-aliased edge changes the exact-colour mask's SIZE, and a centroid measured against a different shape is not a displacement (the measurement refuses it outright). Zoom is held constant on purpose: the x = 0 probe that cancels it in the JSON half does not reach a centroid, which sits at the plane's own offset."), 'text_card': Fixture(path='misc/bench/corpus/text_card', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="text under a camera push-in and roll (an#279, the core corpus): two OVERLAY words fading in one after the other (\`word_1\` starts 0.125 s after \`word_0\`) and a WORLD label on a plane block, while the camera zooms 1.0 -> 1.3 and rolls 0.12 rad. What moves between the goldens: the words' alpha (frame 0 shows neither), the label and block growing and turning with the camera, and the overlay title NOT turning — a regression that put overlay text in the world, broke per-word addressing or the camera's zoom/roll moves a golden. The face is Pillow's embedded Aileron, so the glyphs do not depend on the machine's fonts."), 'text_counter': Fixture(path='misc/bench/corpus/text_counter', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.5), golden_note="a calendar counting 1 to 30 with ONE text block (an#342): a right-aligned \`counter: {format: '{d}', start: 1}\` under one linear \`tween day value -> 30\` over 1 s, lowered at compile to a replacement set of the strings the frames show. Frame 0 shows 1; frame 12's value is exactly 15.5, which nearest-half-even rounding shows as 16 (15 would mean ties away from even, 15/17 a sampling or set-time shift). A regression in the sampling grid, the half-frame set time, the rounding or the right-edge geometry moves a golden."), 'text_outline': Fixture(path='misc/bench/corpus/text_outline', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note="OUTLINED text (an#313, OverSimplified's labels): white words with a 4 px near-black outline over a mid-blue plate and a pale stripe, the second word fading in from 0.125 s. Frame 0 shows the first word alone, outline and all, and NO outline where the second word will be (the outline lives in the word's own texture, so its alpha hides both); frame 8 shows both, legible over the blue and the stripe alike. A regression in the outline's width, its order under the fill, the box growth that keeps it unclipped, or per-word alpha moves a golden."), 'text_swap': Fixture(path='misc/bench/corpus/text_swap', prepare=None, expect_visual_kinds=frozenset({'svg_sprite', 'rect'}), golden_frames=(0.0, 0.3333333333333333), golden_note='a text block\\'s CONTENT changing within one shot (an#341): one right-aligned \`unit: block\` label whose \`texts\` set is swapped twice, "Day 1" -> "Day 12" at 0.125 s (the entity-level \`set day text d12\`) -> "Day 300" at 0.25 s (the \`day/block_0\` path). What moves between the goldens is the string, growing LEFTWARDS from a fixed right edge: a regression in the swap set, in the per-key geometry anchored on the \`align\` edge, or in the entity-level fan-out moves a golden.'), 'transitions': Fixture(path='misc/bench/corpus/transitions', prepare=None, expect_visual_kinds=frozenset({'path', 'rect'}), golden_frames=(0.08333333333333333, 0.375, 0.625), golden_note="the delivered film's COMPOSED frames (an#279, the core corpus): \`dusk\` fades in from black over 0.25 s, then \`dawn\` dissolves in over 0.25 s (frames 6-11 are the blend; the film is 12 + 12 - 6 = 18 frames). Frame 2 is mid-fade, frame 9 mid-dissolve (both pictures at once), frame 15 \`dawn\` alone with its arrow. A regression in the fade colour, the dissolve weights, the overlap arithmetic or the order of the shots moves a golden. The only fixture measured on the film's frames rather than the shots' — what the delivered mp4 shows (an.bench.capture's film segment).")}* The cut-out scenes of the original corpus moved to `cutan` (`cutan.bench.CUTOUT_FIXTURES`, an#225); this is the core’s: `prop_swap` and the core corpus (`an.bench.core_corpus`). ### an.bench.corpus.SHOT_DIR_GLOB *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'shot_\*'* Per-shot subdirectory naming inside `.an/render_work`, and the staged scene filename. Mirrored from the renderer rather than restated as literals at each use site. ### an.bench.corpus.assert_render_path(name, fixture, kinds) Refuse a capture that did not exercise the path its fixture declares. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.bench.corpus.iter_shot_dirs(work_dir, , order) `(shot_id, shot_dir)` for every rendered shot, in **timeline** order. `order` is mandatory, and that is the whole point of this signature. `an/render.py` concatenates `[r.mp4_path for r in shot_results]` built from `list(scene.timeline)`, while this function’s previous form returned `sorted(work_dir.glob("shot_*"))` — directory-name order. The two agree only when the shot ids happen to sort into timeline order, and when they do not, every encode-side metric pairs source frame *i* of one shot against decoded frame *i* of another. The `multi_shot` fixture’s ids (`intro` then `beat`) are chosen so they disagree. * **Return type:** [`Iterator`](https://docs.python.org/3/library/typing.html#typing.Iterator)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)]] ```pycon >>> import tempfile >>> from pathlib import Path >>> d = Path(tempfile.mkdtemp()) >>> for name in ("shot_intro", "shot_beat"): (d / name).mkdir() >>> [i for i, _ in iter_shot_dirs(d, order=["intro", "beat"])] ['intro', 'beat'] ``` ### an.bench.corpus.staged_scene(shot_dir) The compiled scene JSON the browser actually loaded, for one shot. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.corpus.visual_kinds(scene_json) Every `visual.kind` in a staged scene’s node tree. Read from the staged file rather than re-compiled, so it reports what was rendered rather than what a second compile would produce. Scoped to `scene` and to the `visual` key specifically. A sweep for every `kind` anywhere in the document — which is what this was before — also collects an#33’s `asset_resolution` entries, whose `kind` is `"character"` / `"environment"`. Those are entity kinds, not visual kinds, and mixing them makes the field mean two things at once. * **Return type:** [`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> sorted(visual_kinds({"scene": {"visual": {"kind": "rect"}, ... "children": [{"visual": {"kind": "eye"}}]}, ... "asset_resolution": [{"kind": "character"}]})) ['eye', 'rect'] ``` # _autosummary/an.bench.environment.html.md # an.bench.environment The environment tuple — the fields that decide whether two rows may be compared. Split into two halves with **different comparison rules**, because the two sides of the pipeline were measured and their answers are opposite: **Render side — comparable on any machine.** Both render paths, four machines (local arm64 macOS, `macos-latest`, `ubuntu-latest` x86-64, `ubuntu-24.04-arm`), 132 frames each: zero differing pixels *and* zero differing PNG bytes, across two different SwiftShader JIT backends. So the render-side metrics need **no cross-machine band column**, and the golden corpus can be a CI gate. Record the Chromium build and the \*\*launch argv verbatim\*\* — all four rasteriser configurations report a byte-identical `UNMASKED_RENDERER_WEBGL` string, so the renderer string is demonstrably blind to the choice it was proposed to guard. **Encode side — machine-scoped, not bandable.** Same ISA + same x264 build is byte-identical; a different ISA moves the decoded stream a little (luma <=2.66% of samples); a different x264 build moves it by two orders of magnitude (up to 99.2% of samples, mean ``` |d| ``` 3.94, max 36). A band that wide would swallow `flat_field_deviation`’s entire crf18->23 signal. So `--compare` (an#40) must **refuse** rows whose `x264_sei` or `isa` differ, in the same way it refuses rows with a different `scene_contract_sha256` — the number is uninterpretable, not good or bad. ### Module Attributes | [`RUNTIME_DIGEST_SUFFIXES`](_autosummary/an.bench.environment.html.md#an.bench.environment.RUNTIME_DIGEST_SUFFIXES) | `_stage_job`'s `shutil.copytree` is a bare copy that DOES deliver everything under the runtime dir into the staged tree, so "what gets staged" cannot be the reason to exclude anything — the real reason is "what the page loads": `index.html`/`preview.html` pull in `.js` (including `vendor/`), `.css` and `.json`, and nothing else under the tree is read by the browser (an#141). | |----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`RUNTIME_IGNORED_SUFFIXES`](_autosummary/an.bench.environment.html.md#an.bench.environment.RUNTIME_IGNORED_SUFFIXES) | Suffixes under the runtime dir that are known to be non-runtime — excluded from the digest on purpose, not by omission. | ### Functions | [`environment_record`](_autosummary/an.bench.environment.html.md#an.bench.environment.environment_record)(\*, pix_fmt[, x264_sei, ...]) | Everything about this machine that could plausibly move a number. | |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`ffmpeg_identity`](_autosummary/an.bench.environment.html.md#an.bench.environment.ffmpeg_identity)() | The ffmpeg build banner. | | [`home_relative`](_autosummary/an.bench.environment.html.md#an.bench.environment.home_relative)(path, \*[, home]) | `path` with the user's home directory spelled `~`. | | [`probe_browser`](_autosummary/an.bench.environment.html.md#an.bench.environment.probe_browser)() | Launch Chromium with the render path's own flags and read back its identity. | | [`runtime_sha256`](_autosummary/an.bench.environment.html.md#an.bench.environment.runtime_sha256)() | A digest of the JS runtime the renderer will stage, files and names. | | `tool_version`(name) | | | [`x264_sei`](_autosummary/an.bench.environment.html.md#an.bench.environment.x264_sei)(mp4) | The encoder build + thread count, read straight out of the file. | ### an.bench.environment.RUNTIME_DIGEST_SUFFIXES *= ('.js', '.html', '.css', '.json')* `_stage_job`’s `shutil.copytree` is a bare copy that DOES deliver everything under the runtime dir into the staged tree, so “what gets staged” cannot be the reason to exclude anything — the real reason is “what the page loads”: `index.html`/`preview.html` pull in `.js` (including `vendor/`), `.css` and `.json`, and nothing else under the tree is read by the browser (an#141). Package metadata (`__init__.py`), docs (`README.md`), vendor licence text can change — a stray `.DS_Store` included — without the page the renderer loads changing at all, and hashing them anyway made the digest answer “did the runtime change” wrong. * **Type:** Suffixes `runtime_sha256` hashes. Deliberately narrow ### an.bench.environment.RUNTIME_IGNORED_SUFFIXES *= ('', '.py', '.pyc', '.md', '.txt')* Suffixes under the runtime dir that are known to be non-runtime — excluded from the digest on purpose, not by omission. `""` covers extension-less dotfiles (`.DS_Store`, the one this issue was filed over); `.pyc` covers a stray `__pycache__/*.pyc` from `__init__.py` (the issue’s other named example — reproducible on this very tree). `test_bench_environment.py` fails on any suffix that lands in neither this set nor `RUNTIME_DIGEST_SUFFIXES`, so a future runtime asset (an `.svg`, `.woff`, `.wasm`, `.mjs`) cannot silently fall outside what the digest sees (an#141). ### an.bench.environment.environment_record(, pix_fmt, x264_sei=None, browser=None) Everything about this machine that could plausibly move a number. `browser` lets the caller supply an already-taken probe. The golden gate needs the Chromium build *before* the run-level provenance is assembled — the path keys on it — and probing twice would launch a second browser and could, in principle, report a different build from the one that rendered. `pix_fmt` is required and has no default, because it is a \*\*comparability key\*\* and the caller is the only one who can measure it. It must be the format the delivered files actually are — `imageio.delivered_pix_fmt` — and not a re-derivation, for the reason an#72 records: the delivered encode resolves its format from `RenderContext.pix_fmt` *or* the module global, so reading either one is a second source of truth that can disagree with the file, and this field is what `bench-compare` uses to decide whether two encode-side rows may be compared at all. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.bench.environment.ffmpeg_identity() The ffmpeg build banner. Informational — the `x264_sei` is the key. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.bench.environment.home_relative(path, , home=None) `path` with the user’s home directory spelled `~`. Ledger rows are committed to a public repository, so a row must not carry the absolute path of the machine that wrote it. Provenance only: nothing compares on this field. POSIX-spelled on every platform. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> home_relative("/home/u/.cache/ms-playwright/chrome", home=Path("/home/u")) '~/.cache/ms-playwright/chrome' >>> home_relative("/opt/chrome", home=Path("/home/u")) '/opt/chrome' ``` ### an.bench.environment.probe_browser() Launch Chromium with the render path’s own flags and read back its identity. Never raises: a probe that crashes must not cost a caller a completed capture, and a recorded `error` is more honest than a missing field that reads as “nothing to report”. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.bench.environment.runtime_sha256() A digest of the JS runtime the renderer will stage, files and names. Provenance, NOT a comparability key: the runtime is the code under test, and two rows rendered by different runtimes are exactly what `an bench --compare` exists to compare. What it buys is that a render-side mutation leaves a fingerprint in the row — before this, the `disabled_aa` lever had no way to prove it applied, and `assert not report["mutation_may_not_have_applied"]` asserted nothing for it (an#41 review). Only files whose suffix is in `RUNTIME_DIGEST_SUFFIXES` are hashed, so a file that is not staged as a runtime asset — a stray `.DS_Store`, a `__pycache__` entry, package metadata — cannot move the digest (an#141). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.environment.x264_sei(mp4) The encoder build + thread count, read straight out of the file. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) # _autosummary/an.bench.golden.html.md # an.bench.golden The golden gate: committed frames, compared on **decoded pixels**. Family B of the panel. Everything else in [`an.bench`](_autosummary/an.bench.html.md#module-an.bench) measures a property of one render; this compares today’s render against a picture a human looked at and blessed, so it is the only part that can catch a change nobody predicted. Four decisions here that are easy to get wrong in a way that still looks like it works: \*\*The criterion is `sha256` of the decoded RGB array, never the file bytes.\*\* Chromium 1187 -> 1223 changed 144 of 144 PNG files and **zero** pixels. A file-byte gate goes red on the first Playwright bump for a reason that has nothing to do with animation quality — and, worse, trains people to re-bless without looking. **The path keys on the Chromium build ALONE** — no platform, no arch. Measured across arm64 macOS, x86-64 Linux and arm64 Linux, across two different SwiftShader JIT backends: zero differing pixels *and* zero differing PNG bytes. Carrying the platform would force one committed copy per platform for no information. What the convention keeps is its real benefit: a Playwright bump becomes a **new path requiring a deliberate re-bless**, not a red test with no explanation. **Three different absences get three different gates.** “This scene declares no golden frames”, “goldens exist but not for this Chromium build” and “the Chromium build could not be determined at all” are three different facts, and a reader who cannot tell them apart cannot act on any of them. The last one matters most: [`an.bench.environment.probe_browser()`](_autosummary/an.bench.environment.html.md#an.bench.environment.probe_browser) never raises, it returns `{"error": ...}` — so without a distinct gate an un-probeable browser reads exactly like a scene nobody has blessed yet. **A comparison against a golden written in the same run is a tautology**, so a `--bless` run records family B as gated rather than as a pass. The row would otherwise carry a perfect score that no code could ever have failed. ### Module Attributes | [`BLESS_MANIFEST_TEMPLATE`](_autosummary/an.bench.golden.html.md#an.bench.golden.BLESS_MANIFEST_TEMPLATE) | Per-scene, per-build bless record, committed beside the frames. | |----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------| | [`REQUIRED_GOLDEN_FRAMES`](_autosummary/an.bench.golden.html.md#an.bench.golden.REQUIRED_GOLDEN_FRAMES) | How many golden frames a scene must declare. | | [`GATE_UNDECLARED`](_autosummary/an.bench.golden.html.md#an.bench.golden.GATE_UNDECLARED) | Gate names. | | [`RETIRED_GATES`](_autosummary/an.bench.golden.html.md#an.bench.golden.RETIRED_GATES) | Gate names that appear in rows written BEFORE this module existed, and what they meant. | ### Functions | [`bless_scene`](_autosummary/an.bench.golden.html.md#an.bench.golden.bless_scene)(capture, \*, times, ...[, ...]) | Write one scene's golden frames and its bless record. | |----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`chromium_build_of`](_autosummary/an.bench.golden.html.md#an.bench.golden.chromium_build_of)(environment) | The Chromium build from an environment record, or `None` if unknown. | | [`compare_scene`](_autosummary/an.bench.golden.html.md#an.bench.golden.compare_scene)(capture, \*, times, chromium_build) | Compare today's render against the committed goldens for one scene. | | [`frame_index_for`](_autosummary/an.bench.golden.html.md#an.bench.golden.frame_index_for)(time, \*, fps, n_frames) | The frame a pinned time names, snapped to the nearest one. | | [`frame_key`](_autosummary/an.bench.golden.html.md#an.bench.golden.frame_key)(index) | The filename stem for a frame, zero-padded so a directory listing sorts. | | [`frame_png_path`](_autosummary/an.bench.golden.html.md#an.bench.golden.frame_png_path)(capture, ref) | Where the renderer left the PNG for one resolved frame. | | [`iter_committed`](_autosummary/an.bench.golden.html.md#an.bench.golden.iter_committed)(scene, chromium_build, \*[, root]) | Every committed golden PNG for one scene and build, in sorted order. | | [`load_manifest`](_autosummary/an.bench.golden.html.md#an.bench.golden.load_manifest)(scene, chromium_build, \*[, root]) | The committed bless record, or `None` when this scene has never been blessed. | | [`manifest_path`](_autosummary/an.bench.golden.html.md#an.bench.golden.manifest_path)(scene, chromium_build, \*[, root]) | Where one scene's bless record for one Chromium build lives. | | [`pixels_sha256`](_autosummary/an.bench.golden.html.md#an.bench.golden.pixels_sha256)(rgb) | `sha256` over the decoded pixels — **shape and dtype included**. | | [`resolve_frames`](_autosummary/an.bench.golden.html.md#an.bench.golden.resolve_frames)(capture, times) | Map each pinned time onto `(global index, shot, index within that shot)`. | ### Classes | [`FrameRef`](_autosummary/an.bench.golden.html.md#an.bench.golden.FrameRef)(key, time, index, shot_id, local_index) | One pinned golden frame, resolved against the render that just happened. | |-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| ### Exceptions | [`GoldenError`](_autosummary/an.bench.golden.html.md#an.bench.golden.GoldenError) | A bless was refused, or a committed golden is unusable. | |----------------------------------------------------------------|-----------------------------------------------------------| ### an.bench.golden.BLESS_MANIFEST_TEMPLATE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'bless-chromium{chromium_build}.json'* Per-scene, per-build bless record, committed beside the frames. Per build rather than per scene: a Playwright bump adds a new set of frames under new names, and the old set stays valid for anyone still on the old build. ### *class* an.bench.golden.FrameRef(key, time, index, shot_id, local_index) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One pinned golden frame, resolved against the render that just happened. #### local_index *: [int](https://docs.python.org/3/builtins/functions.html#int)* Index WITHIN that shot’s frame directory. ### an.bench.golden.GATE_UNDECLARED *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'golden_frames_undeclared'* Gate names. Literals rather than an enum because they are written into the ledger and read back by `an bench --compare` from rows written by older registries, so their spelling is a wire format. ### *exception* an.bench.golden.GoldenError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A bless was refused, or a committed golden is unusable. ### an.bench.golden.REQUIRED_GOLDEN_FRAMES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* How many golden frames a scene must declare. Two, because one frame tests a single instant and cannot notice a scene that renders its first frame correctly and then stops. ### an.bench.golden.RETIRED_GATES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'golden_absent': 'golden_absent_for_chromium_build'}* Gate names that appear in rows written BEFORE this module existed, and what they meant. `an bench --compare` (an#40) reads old rows as fact, so the one place a reader has to look is here rather than in a commit message. The an#36 row carried a single `golden_absent` for both family-B keys, at a time when the corpus had no goldens for ANY build — which is this module’s `GATE_ABSENT`, not its `GATE_UNDECLARED` (the fixtures did declare no times, but the gate was not distinguishing the two). ### an.bench.golden.bless_scene(capture, , times, chromium_build, reason, git, scene_contract_sha256, golden_note='', root=None) Write one scene’s golden frames and its bless record. Refuses, loudly. Every refusal here is a case where writing the file would produce a gate that cannot fail: - **no reason** — a re-bless with no recorded reason is the same failure as a silently widened threshold, which is the named failure mode this whole wave exists to prevent; - **fewer than two frames** — one frame cannot notice a scene that renders its first instant correctly and then stops; - **a pixel-identical pair** — measured on `promote_demo`: frame 0 and the `duration/2` frame differ by exactly zero pixels, so the obvious choice blesses one picture twice and the second golden tests nothing; - **an unknown Chromium build** — the path keys on it, so without it the frames would be written under a name no future run could look up. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.golden.chromium_build_of(environment) The Chromium build from an environment record, or `None` if unknown. `probe_browser` never raises — it reports an `error` key — so “we could not ask the browser” arrives here as a missing field rather than as an exception, and must not be confused with “nobody has blessed this scene”. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.bench.golden.compare_scene(capture, , times, chromium_build, root=None) Compare today’s render against the committed goldens for one scene. Returns a dict with `state` in `{"measured", "gated", "unavailable"}`, the reduced numbers the ledger carries, and a per-frame record for provenance. The reduction is **worst frame wins**: `identical` is the conjunction and `min_ssim_win8` is the minimum, because a maximum or a mean lets one clean frame hide a broken one, and this metric’s own name is “the worst small window”. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.golden.frame_index_for(time, , fps, n_frames) The frame a pinned time names, snapped to the nearest one. `int(time * fps)` is the trap: `0.25 * 24` is `5.999999999999999` in binary floating point, so the obvious spelling silently picks frame 5. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> frame_index_for(0.25, fps=24, n_frames=12) 6 >>> frame_index_for(0.0, fps=24, n_frames=12) 0 ``` ### an.bench.golden.frame_key(index) The filename stem for a frame, zero-padded so a directory listing sorts. Keyed on the frame **index**, not the pinned time: the index is what names the picture. A change to `fps` moves the index, which changes the path, which makes the golden absent and therefore *gated* — loud, and pointing at the right cause. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> frame_key(7) 'f0007' ``` ### an.bench.golden.frame_png_path(capture, ref) Where the renderer left the PNG for one resolved frame. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.bench.golden.iter_committed(scene, chromium_build, , root=None) Every committed golden PNG for one scene and build, in sorted order. * **Return type:** [`Iterator`](https://docs.python.org/3/library/typing.html#typing.Iterator)[[`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)] ### an.bench.golden.load_manifest(scene, chromium_build, , root=None) The committed bless record, or `None` when this scene has never been blessed. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.bench.golden.manifest_path(scene, chromium_build, , root=None) Where one scene’s bless record for one Chromium build lives. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.bench.golden.pixels_sha256(rgb) `sha256` over the decoded pixels — **shape and dtype included**. Never over file bytes, for the reason in the module docstring. And never over the raw buffer alone either: `tobytes()` carries no shape, so a 320x240 frame and a 240x320 one holding the same bytes hash identically, and issue #38’s literal “the criterion is `sha256(decoded RGB array)`” would report PASS on a transposed frame. Both orientations are live in this corpus. [`an.bench.metrics.golden_comparison()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.golden_comparison) catches it separately via its `shape_mismatch` branch; this makes the digest agree with the gate rather than quietly disagreeing with it. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> import numpy as np >>> a = np.arange(24, dtype=np.uint8) >>> pixels_sha256(a.reshape(2, 4, 3)) == pixels_sha256(a.reshape(4, 2, 3)) False ``` ### an.bench.golden.resolve_frames(capture, times) Map each pinned time onto `(global index, shot, index within that shot)`. Indices run over the scene’s **concatenated** timeline — what the delivered mp4 shows — so a pinned time can land in the second shot, which is exactly what `multi_shot`’s second golden does. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`FrameRef`](_autosummary/an.bench.golden.html.md#an.bench.golden.FrameRef)] # _autosummary/an.bench.html.md # an.bench `an bench` — render a fixed corpus, compute a metrics panel, write one ledger row. The instrument Wave 2 exists to build. Its job is not to say whether the animation is good; it is to make a \*\*deliberate degradation move a number in a direction declared in advance\*\*, so that a future regression is caught by something other than someone noticing. Three things about the panel that are easy to assume wrongly: - **It is not the epic’s metric list.** All twelve originally-proposed metrics were refuted; every one here is a corrected form. `mean adjacent-frame SSIM` in particular is *out* — it moves the wrong way (0.958 at crf18 -> 0.977 at crf51, because a crushed video is smoother), so shipping it would put a number in the ledger that rewards the degradation the gate exists to catch. - \*\*Render-side and encode-side metrics are blind to each other’s mutations by construction\*\*, and are labelled so nothing mixes them. Render-side rows compare across any machine; encode-side rows are machine-scoped. - **The vision judge is deliberately not here.** Not because its input is nondeterministic — over frozen frames it is perfectly reproducible — but because a cassetted judge is a *constant*, invariant to the code under test, so it can never move under a deliberate degradation. Entry points: [`an.bench.run.run_bench()`](_autosummary/an.bench.run.html.md#an.bench.run.run_bench), and `an bench` on the CLI. ### Functions | [`bless_scene`](_autosummary/an.bench.html.md#an.bench.bless_scene)(capture, \*, times, ...[, ...]) | Write one scene's golden frames and its bless record. | |----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`compare_scene`](_autosummary/an.bench.html.md#an.bench.compare_scene)(capture, \*, times, chromium_build) | Compare today's render against the committed goldens for one scene. | | [`decode_png`](_autosummary/an.bench.html.md#an.bench.decode_png)(data) | Decode an 8-bit truecolour PNG to `(H, W, C)` uint8, `C` in `{3, 4}`. | | [`encode_png`](_autosummary/an.bench.html.md#an.bench.encode_png)(rgb, \*[, level]) | Encode `(H, W, 3)` uint8 as an 8-bit truecolour PNG, every row filter 0. | | [`frame_key`](_autosummary/an.bench.html.md#an.bench.frame_key)(index) | The filename stem for a frame, zero-padded so a directory listing sorts. | | [`pixels_sha256`](_autosummary/an.bench.html.md#an.bench.pixels_sha256)(rgb) | `sha256` over the decoded pixels — **shape and dtype included**. | | [`png_dimensions`](_autosummary/an.bench.html.md#an.bench.png_dimensions)(data) | `(width, height)` from a PNG's IHDR, without decoding a single pixel. | | [`read_png`](_autosummary/an.bench.html.md#an.bench.read_png)(path) | `(H, W, 3)` uint8 for a PNG on disk, alpha dropped only if opaque. | | [`read_png_dimensions`](_autosummary/an.bench.html.md#an.bench.read_png_dimensions)(path) | `(width, height)` for a PNG on disk, reading only its header. | | [`write_png`](_autosummary/an.bench.html.md#an.bench.write_png)(path, rgb, \*[, level]) | Write `rgb` as a filter-0 PNG and **verify the round trip** before returning. | | [`build_ledger`](_autosummary/an.bench.html.md#an.bench.build_ledger)(\*, provenance, scenes) | The whole row. | | [`build_scene_block`](_autosummary/an.bench.html.md#an.bench.build_scene_block)(\*, provenance, metrics, ...) | Assemble one scene's three blocks, refusing anything unreadable. | | [`witnesses`](_autosummary/an.bench.html.md#an.bench.witnesses)(ledger_scene, mutation) | Which metrics would count for `mutation`, grouped by family. | | `run_bench`(\*[, scenes, out, keep_render, ...]) | Render the corpus, compute the panel, and (by default) write the row. | | `format_panel`(ledger) | A human-readable digest of a row — the thing `an bench` prints. | ### Classes | [`MetricSpec`](_autosummary/an.bench.html.md#an.bench.MetricSpec)(key, family, unit, optimum, ...) | One row of the panel. | |--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`Prediction`](_autosummary/an.bench.html.md#an.bench.Prediction)(expect[, counts, gate, reason, ...]) | What one metric is expected to do under one mutation, declared in advance. | | [`Value`](_autosummary/an.bench.html.md#an.bench.Value)(value[, state, gate, detail, extra]) | One measured (or deliberately absent) number. | ### Exceptions | [`GoldenError`](_autosummary/an.bench.html.md#an.bench.GoldenError) | A bless was refused, or a committed golden is unusable. | |--------------------------------------------------------------------|---------------------------------------------------------------------| | [`PngFormatError`](_autosummary/an.bench.html.md#an.bench.PngFormatError) | A PNG this module deliberately does not decode, or a malformed one. | | [`RegistryError`](_autosummary/an.bench.html.md#an.bench.RegistryError) | A metric declaration violates one of the table's invariants. | | [`LedgerSchemaError`](_autosummary/an.bench.html.md#an.bench.LedgerSchemaError) | A ledger row violates an invariant that would make it misreadable. | | `BenchError` | The bench could not produce a row it would be honest to file. | ### *exception* an.bench.GoldenError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A bless was refused, or a committed golden is unusable. ### *exception* an.bench.LedgerSchemaError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A ledger row violates an invariant that would make it misreadable. ### *class* an.bench.MetricSpec(key, family, unit, optimum, predictions, sentence, role=None, reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=, sweep=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One row of the panel. #### requires *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* What a scene must HAVE for this row to exist at all, or `""` when the row applies to every scene (an#111). The render-side panel rule is “nothing may be null on a real capture, because a null render-side row is a blind panel”. That rule assumes every metric could have been measured. `stage_min_plane_ratio_gap` could not: a displacement ratio needs two planes moving at different depths, and `single_character` has no planes at all — so its null is structural, not a gap in the instrument. Declared rather than hardcoded in the test, so the panel rule keeps naming its own exceptions instead of a test file carrying a list the registry does not know about. #### sweep *: [Sweep](_autosummary/an.bench.registry.html.md#an.bench.registry.Sweep) | [None](https://docs.python.org/3/builtins/constants.html#None)* Set only on a hard-threshold counter (an#140); see `Sweep`. ### *exception* an.bench.PngFormatError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A PNG this module deliberately does not decode, or a malformed one. Typed and specific on purpose: the alternative to refusing is returning a plausible array, and a golden gate that compares a plausible array is worse than one that does not run. ### *class* an.bench.Prediction(expect, counts=False, gate=None, reason='', reference=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What one metric is expected to do under one mutation, declared in advance. `expect=None` means **gated**: the number is uninterpretable rather than good or bad, and `gate` says why. It is not “no change”. ### *exception* an.bench.RegistryError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A metric declaration violates one of the table’s invariants. ### *class* an.bench.Value(value, state='measured', gate=None, detail='', extra=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One measured (or deliberately absent) number. ### an.bench.bless_scene(capture, , times, chromium_build, reason, git, scene_contract_sha256, golden_note='', root=None) Write one scene’s golden frames and its bless record. Refuses, loudly. Every refusal here is a case where writing the file would produce a gate that cannot fail: - **no reason** — a re-bless with no recorded reason is the same failure as a silently widened threshold, which is the named failure mode this whole wave exists to prevent; - **fewer than two frames** — one frame cannot notice a scene that renders its first instant correctly and then stops; - **a pixel-identical pair** — measured on `promote_demo`: frame 0 and the `duration/2` frame differ by exactly zero pixels, so the obvious choice blesses one picture twice and the second golden tests nothing; - **an unknown Chromium build** — the path keys on it, so without it the frames would be written under a name no future run could look up. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.build_ledger(, provenance, scenes) The whole row. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.build_scene_block(, provenance, metrics, tripwires) Assemble one scene’s three blocks, refusing anything unreadable. Completeness is enforced in both directions. A metric the registry declares but the row omits is a silently narrower panel; a metric the row carries but the registry does not declare has no family, no side and no predicted direction, so nothing downstream can count it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.compare_scene(capture, , times, chromium_build, root=None) Compare today’s render against the committed goldens for one scene. Returns a dict with `state` in `{"measured", "gated", "unavailable"}`, the reduced numbers the ledger carries, and a per-frame record for provenance. The reduction is **worst frame wins**: `identical` is the conjunction and `min_ssim_win8` is the minimum, because a maximum or a mean lets one clean frame hide a broken one, and this metric’s own name is “the worst small window”. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.decode_png(data) Decode an 8-bit truecolour PNG to `(H, W, C)` uint8, `C` in `{3, 4}`. Refuses — rather than approximates — 16-bit, palette, greyscale and interlaced images, naming what it found. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> a = np.array([[[1, 2, 3], [4, 5, 6]]], np.uint8) >>> np.array_equal(decode_png(encode_png(a)), a) True ``` ### an.bench.encode_png(rgb, , level=9) Encode `(H, W, 3)` uint8 as an 8-bit truecolour PNG, every row filter 0. * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) ```pycon >>> import numpy as np >>> data = encode_png(np.zeros((2, 3, 3), np.uint8)) >>> data[:8] == PNG_SIGNATURE True >>> decode_png(data).shape (2, 3, 3) ``` ### an.bench.frame_key(index) The filename stem for a frame, zero-padded so a directory listing sorts. Keyed on the frame **index**, not the pinned time: the index is what names the picture. A change to `fps` moves the index, which changes the path, which makes the golden absent and therefore *gated* — loud, and pointing at the right cause. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> frame_key(7) 'f0007' ``` ### an.bench.pixels_sha256(rgb) `sha256` over the decoded pixels — **shape and dtype included**. Never over file bytes, for the reason in the module docstring. And never over the raw buffer alone either: `tobytes()` carries no shape, so a 320x240 frame and a 240x320 one holding the same bytes hash identically, and issue #38’s literal “the criterion is `sha256(decoded RGB array)`” would report PASS on a transposed frame. Both orientations are live in this corpus. [`an.bench.metrics.golden_comparison()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.golden_comparison) catches it separately via its `shape_mismatch` branch; this makes the digest agree with the gate rather than quietly disagreeing with it. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> import numpy as np >>> a = np.arange(24, dtype=np.uint8) >>> pixels_sha256(a.reshape(2, 4, 3)) == pixels_sha256(a.reshape(4, 2, 3)) False ``` ### an.bench.png_dimensions(data) `(width, height)` from a PNG’s IHDR, without decoding a single pixel. Width first, matching the PNG header itself — and deliberately the opposite order from [`read_png()`](_autosummary/an.bench.html.md#an.bench.read_png), which returns `(H, W, C)` like every other array here. Getting it backwards produces a square-looking check that passes on square frames only, so the order is asserted in the tests. Cheap on purpose. The bench reads this for **every** frame on disk rather than sampling one, because the failure it exists to catch — a render whose frame size changed partway through — is exactly the one sampling misses. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`int`](https://docs.python.org/3/builtins/functions.html#int)] ```pycon >>> import numpy as np >>> png_dimensions(encode_png(np.zeros((240, 320, 3), np.uint8))) (320, 240) ``` ### an.bench.read_png(path) `(H, W, 3)` uint8 for a PNG on disk, alpha dropped only if opaque. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.bench.read_png_dimensions(path) `(width, height)` for a PNG on disk, reading only its header. A 1080p frame is megabytes and its declared size is in the first 24 of them. Reading only those is what makes checking every frame of every shot free rather than a second full decode of the corpus. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`int`](https://docs.python.org/3/builtins/functions.html#int)] ### an.bench.witnesses(ledger_scene, mutation) Which metrics would count for `mutation`, grouped by family. Reads the row rather than the registry, so an#41’s criterion is evaluated against what was actually written down. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> witnesses({"metrics": {"m": {"family": "A", ... "under_mutation": {"high_crf": {"counts": True}}}}}, "high_crf") {'A': ['m']} ``` ### an.bench.write_png(path, rgb, , level=9) Write `rgb` as a filter-0 PNG and **verify the round trip** before returning. The verification is not defensive noise: it is the only thing standing between a bug in this module’s own encoder and a committed golden that silently disagrees with the frame it was blessed from. Research §3 asks for exactly this — “assert the round trip at bless time against the in-memory screenshot pixels, so a bug in `an`’s own encoder cannot hide”. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### Modules | [`capture`](_autosummary/an.bench.capture.html.md#module-an.bench.capture) | Render one corpus fixture into a throwaway copy, and hand back its artifacts. | |------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------| | [`compare`](_autosummary/an.bench.compare.html.md#module-an.bench.compare) | `an bench --compare`: read two ledger rows, and **refuse when they are not comparable**. | | [`contract`](_autosummary/an.bench.contract.html.md#module-an.bench.contract) | `scene_contract_sha256`: the fact that decides whether two rows are comparable. | | [`core_corpus`](_autosummary/an.bench.core_corpus.html.md#module-an.bench.core_corpus) | The core corpus: what `an` renders with no character and no genre (ADR 0001 decision 7). | | [`corpus`](_autosummary/an.bench.corpus.html.md#module-an.bench.corpus) | The bench corpus: which projects are measured, and what each must actually render. | | [`environment`](_autosummary/an.bench.environment.html.md#module-an.bench.environment) | The environment tuple — the fields that decide whether two rows may be compared. | | [`golden`](_autosummary/an.bench.golden.html.md#module-an.bench.golden) | The golden gate: committed frames, compared on **decoded pixels**. | | [`imageio`](_autosummary/an.bench.imageio.html.md#module-an.bench.imageio) | The pinned ffmpeg decodes, and the lossless leg every encode-side metric is measured against. | | [`ledger`](_autosummary/an.bench.ledger.html.md#module-an.bench.ledger) | The ledger: three blocks that must never be mixed, and the guards that keep them apart. | | [`masks`](_autosummary/an.bench.masks.html.md#module-an.bench.masks) | Every mask the panel is computed over, and the recorded operator for each. | | [`metrics`](_autosummary/an.bench.metrics.html.md#module-an.bench.metrics) | The metric panel: pure numpy, no I/O, no subprocess. | | [`mutants`](_autosummary/an.bench.mutants.html.md#module-an.bench.mutants) | The guard mutants: "I mutation-tested it" as a runnable artifact, not a claim. | | [`mutations`](_autosummary/an.bench.mutations.html.md#module-an.bench.mutations) | The levers: deliberate, declared changes through seams the shipped code already has. | | [`palette`](_autosummary/an.bench.palette.html.md#module-an.bench.palette) | Derive the set of colours a compiled shot declared — never hand-pin it. | | [`paths`](_autosummary/an.bench.paths.html.md#module-an.bench.paths) | Where the bench reads its corpus from and writes its ledger to. | | [`png`](_autosummary/an.bench.png.html.md#module-an.bench.png) | A filter-0 PNG writer and a full-filter reader — numpy and stdlib only. | | [`registry`](_autosummary/an.bench.registry.html.md#module-an.bench.registry) | The metric declaration table — what each number is, and which way it should move. | | [`run`](_autosummary/an.bench.run.html.md#module-an.bench.run) | `run_bench`: render the corpus, compute the panel, write one ledger row. | | [`stage`](_autosummary/an.bench.stage.html.md#module-an.bench.stage) | Measuring a pan: does the stage move as planes, or as one rigid image? | # _autosummary/an.bench.imageio.html.md # an.bench.imageio The pinned ffmpeg decodes, and the lossless leg every encode-side metric is measured against. \*\*The reference is the lossless encode, not the PNGs — and that is a correction, made because CI caught the alternative.\*\* The obvious design reads the source frames back with an explicit conversion (`-vf scale=out_range=tv:out_color_matrix=bt709 -pix_fmt yuv444p`) and compares the delivered mp4 against that. Measured against a mathematically lossless (`-qp 0`) encode of the same frames, that conversion agrees **exactly** on ffmpeg 8.1 (luma residual 0.0000, max 0) and **does not** on the Linux runner’s older build (0.6290, max 5). A floor of 0.63 is 42% of `coded_luma_edge_error`’s whole crf23 value, so on that build every encode-side luma number would have been measuring a colour-conversion disagreement and reporting it as encoder damage. The fix is not a tolerance. It is to stop having a second conversion at all: `-qp 0` is lossless, so \*\*the qp0 decode’s luma plane IS the plane libx264 received\*\*, on every build, by definition. Referencing the metrics to it removes the assumption instead of widening it, and it costs nothing extra — `encode_ringing_excess` already needed that leg. \*\*That “IS” is a claim about the leg’s INPUT FORMAT as much as its rate control\*\*, and the leg pinned `-pix_fmt yuv420p` until an#72. Against a 4:4:4 delivery the reference was therefore a *different colour pipeline* from the file it referenced, and every metric measured against it carried the whole 4:2:0 conversion this leg exists to cancel — as a term that does not cancel and does vary by build. The leg now takes its format from the **delivered file itself** (`delivered_pix_fmt`, threaded in by `run.lossless_reference`). Probing rather than re-deriving is the load-bearing part: **two** seams set the delivered format — `RenderContext.pix_fmt`, which `an render --pix-fmt` uses and which the mux resolves FIRST, and the `DEFAULT_PIX_FMT` module global, which is only its fallback. A leg that consults either one covers only that one, and an#72’s first fix consulted the global — so it silently re-pinned on the seam a user can actually reach, with every guard green. (No `pix_fmt` lever exists: `MUTATIONS` is `high_crf`/`disabled_aa`/`supersample` and `_check_registered` enforces it at import. The global’s seam is kept for a lever that has never been registered — see `an-dev-bench`’s `pix_fmt` row for why — and outside the product it is driven only by tests. So “the lever rebinds it” is a statement about a seam’s purpose, not about anything that runs.) Note which metrics the mismatch reached: `flat_field_deviation`, `flat_field_p99_dev` and `encode_flicker_on_held_pixels` reduce over RGB, so chroma reaches them, while the luma-domain metrics never moved — `coded_luma_edge_error` and `encode_ringing_excess` are identical to the last digit between a 4:2:0 and a 4:4:4 leg on all ten corpus scenes. Two things this does NOT change: - **The chroma metric still references the direct RGB->444 conversion**, because its subject *is* the 4:2:0 subsampling that happens during the conversion — which is exactly the term this leg cancels, so a lossless-referenced version is blind to it whatever format the leg is encoded in. (With a tracking leg and a 4:4:4 delivery, both legs are 4:4:4 and the subsampling does not exist to be measured; tracking makes the panel honest, not sighted.) It does **not** read ~0, though, and that half of the old wording was wrong: measured 2026-08-29 on four scenes, mean ``` |dCr| ``` over the edge mask reads 1.71 / 1.90 / 2.24 / 2.50 against the shipped metric’s 7.19 / 9.29 / 8.04 / 2.93, because it measures chroma *quantiser* damage instead (an#72). - \*\*The PNG conversion is still performed and its distance from the encoder’s input is still recorded\*\* (`png_to_encoder_input_luma`), because that number is exactly the build-dependence that was hiding inside a hard equality. It is provenance now, not a gate. **an#148 names what the build-dependence WAS, and both legs now pin it.** The varying term was never this PNG leg — it was the *encoder’s* conversion: `-colorspace bt709` sets the auto-inserted RGB->YUV matrix on ffmpeg 8/9 and reaches only the VUI on ffmpeg 6.1, so on 6.1 libx264 received BT.601 planes while the delivered file was tagged BT.709 (pure red at Y=81, against BT.709’s 62.6). `lossless_encode_command` therefore carries `-vf BT709_SCALE_FILTER`, the same filter the delivered mux now passes: a lossless leg that converts differently from the file it references is not “the plane libx264 received” on any build where the two disagree, whatever its rate control. Keeping the two spellings identical is why `SOURCE_SCALE_FILTER` is *bound* to `an.base.BT709_SCALE_FILTER` rather than restating it. `-map 0:v:0 -fps_mode passthrough` on every mp4 decode: the delivered file carries an AAC track, and implicit frame-rate conversion would silently re-time the sequence that every encode-side metric pairs frame-for-frame. ### Module Attributes | [`SOURCE_SCALE_FILTER`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.SOURCE_SCALE_FILTER) | without it the encode-side metrics measure a colour-space conversion. | |------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`YUV_PIX_FMT`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.YUV_PIX_FMT) | 4 for both legs of every encode-side metric — never `rgb24` for the edge metrics, whose defect was clipping precisely at the saturated fills sitting against black outlines that flat 2D art is made of. | ### Functions | [`decoded_rgb`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.decoded_rgb)(mp4, \*, height, width) | `(N, H, W, 3)` uint8 of the delivered mp4. | |----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | [`decoded_rgb_command`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.decoded_rgb_command)(mp4) | Decode the delivered mp4 to raw RGB. | | [`decoded_yuv`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.decoded_yuv)(mp4, \*, height, width) | `(N, 3, H, W)` uint8 planar YUV of the delivered mp4. | | [`decoded_yuv_command`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.decoded_yuv_command)(mp4) | Decode the delivered mp4 to planar YUV. | | [`delivered_pix_fmt`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.delivered_pix_fmt)(mp4) | The pixel format `mp4` is actually encoded in, from the file itself. | | [`lossless_encode_command`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.lossless_encode_command)(frames_dir, fps, out, \*) | `-qp 0` with otherwise identical flags, for `encode_ringing_excess`. | | [`run_raw`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.run_raw)(cmd) | Run an ffmpeg command and return its raw stdout, or raise with the stderr. | | [`source_rgb`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.source_rgb)(frames_dir, \*, height, width, frames) | `(N, H, W, 3)` uint8 of the pre-encode PNGs. | | [`source_rgb_command`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.source_rgb_command)(frames_dir) | Decode the pre-encode PNG sequence to raw RGB. | | [`source_yuv`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.source_yuv)(frames_dir, \*, height, width, frames) | `(N, 3, H, W)` uint8 planar YUV of the pre-encode PNGs, range-pinned. | | [`source_yuv_command`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.source_yuv_command)(frames_dir) | Decode the pre-encode PNG sequence to planar YUV, **range- and matrix-pinned**. | | [`video_stream_bytes`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.video_stream_bytes)(mp4) | Sum of the video stream's packet sizes — the AAC track excluded. | ### Exceptions | [`BenchDecodeError`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.BenchDecodeError) | ffmpeg could not read something the bench needs. | |---------------------------------------------------------------------|----------------------------------------------------| ### *exception* an.bench.imageio.BenchDecodeError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) ffmpeg could not read something the bench needs. ### an.bench.imageio.SOURCE_SCALE_FILTER *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'scale=out_range=tv:out_color_matrix=bt709'* without it the encode-side metrics measure a colour-space conversion. **Bound to the product’s own filter, not restated** (an#148). It used to be a second copy of the same string, which was harmless only while the delivered encode had no `-vf` of its own to disagree with. Now that it has one, two copies is one edit away from the PNG leg and the encoder converting differently — which is exactly the term the encode-side metrics cannot see and would report as encoder damage. * **Type:** The pinned conversion applied to the PNG leg. Never remove it ### an.bench.imageio.YUV_PIX_FMT *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'yuv444p'* 4 for both legs of every encode-side metric — never `rgb24` for the edge metrics, whose defect was clipping precisely at the saturated fills sitting against black outlines that flat 2D art is made of. * **Type:** Planar 4 * **Type:** 4 ### an.bench.imageio.decoded_rgb(mp4, , height, width) `(N, H, W, 3)` uint8 of the delivered mp4. `frames=None`: the run deliberately tolerates the encoder emitting a different count from the source leg and records it as `frame_count_disagreement`, so an equality here would turn a recorded disagreement into a crash. See `_reshape()`. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.bench.imageio.decoded_rgb_command(mp4) Decode the delivered mp4 to raw RGB. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.imageio.decoded_yuv(mp4, , height, width) `(N, 3, H, W)` uint8 planar YUV of the delivered mp4. `frames=None` — see [`decoded_rgb()`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.decoded_rgb). * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.bench.imageio.decoded_yuv_command(mp4) Decode the delivered mp4 to planar YUV. No `scale` filter here, deliberately: the file carries BT.709 tags (an#34) so ffmpeg already decodes it in the space the source leg is pinned to. Adding one would convert twice. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.imageio.delivered_pix_fmt(mp4) The pixel format `mp4` is actually encoded in, from the file itself. The delivered encode resolves its format from `RenderContext.pix_fmt` **or** the module global (`render._check_pix_fmt`), and only the file knows which won — so the lossless leg cannot re-derive it and be sure of matching. Re-deriving is what an#72’s first fix did, and it covered the bench lever’s seam (which rebinds the global) while missing the product’s own (`an render --pix-fmt`, which sets the context and never touches it). Probed, not remembered: this is the one source of truth that no future seam can route around. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.imageio.lossless_encode_command(frames_dir, fps, out, , pix_fmt=None) `-qp 0` with otherwise identical flags, for `encode_ringing_excess`. Identical to the delivered encode except for the rate control, so the difference of the two overshoot means cancels the source-hardness term — which is the whole reason `encode_ringing_excess` replaced raw overshoot. **Pinned in its ENCODER SETTINGS, tracking in its INPUT FORMAT** — and the asymmetry is the correction an#72 turned on. Two module globals reach this command and they must be reached differently: - `DETERMINISTIC_X264_ARGS` is bound at IMPORT, above, so a lever that rebinds it (`high_crf`) cannot move the reference. The reference has to stay lossless, or every encode-side metric is measured against a moving target and the lever produces beautiful numbers about nothing. - `pix_fmt` is resolved at CALL time through the product’s own `_check_pix_fmt()`. The bench passes the > format **probed off the delivered mp4** ([`delivered_pix_fmt()`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.delivered_pix_fmt)); > `None` falls back to `DEFAULT_PIX_FMT`, which is right for a caller > with no delivered file to match and wrong for one that has it. The difference is not a preference. `-pix_fmt` is not an encoder setting: it names **what libx264 receives**, and being what libx264 received is this leg’s entire purpose (see the module docstring). Pinning it does not keep the reference lossless — it makes the reference a \*different colour pipeline\* from the delivered file, so every metric measured against it silently acquires the whole 4:2:0 conversion the reference exists to cancel. Measured on the corpus at 4:4:4: family E (`encode_flicker_on_held_pixels`) changes SIGN on three of ten scenes between a pinned leg and a tracking one — from as-declared to contrary in every case — and family D (`flat_field_deviation`) moves by up to 24.8 percentage points. The affected metrics are exactly the RGB-domain ones, which reduce over three channels so chroma reaches them; the luma-domain metrics were never affected — `coded_luma_edge_error` and `encode_ringing_excess` are identical to the last digit between a 4:2:0 and a 4:4:4 leg on all ten scenes. A default (4:2:0) render is byte-identical to before this change, so no committed ledger row is invalidated. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.imageio.run_raw(cmd) Run an ffmpeg command and return its raw stdout, or raise with the stderr. * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) ### an.bench.imageio.source_rgb(frames_dir, , height, width, frames) `(N, H, W, 3)` uint8 of the pre-encode PNGs. `frames` is how many PNGs are on disk — the caller counted them — and it is required rather than derived, so the decode cannot silently return a different number of them. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.bench.imageio.source_rgb_command(frames_dir) Decode the pre-encode PNG sequence to raw RGB. RGB is correct here and only here: the two metrics that use it (`flat_field_deviation`, `encode_flicker_on_held_pixels`) are masked to the flat interior and to held pixels, both off-edge by construction, so the clipping that ruins the edge metrics cannot reach them. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.imageio.source_yuv(frames_dir, , height, width, frames) `(N, 3, H, W)` uint8 planar YUV of the pre-encode PNGs, range-pinned. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.bench.imageio.source_yuv_command(frames_dir) Decode the pre-encode PNG sequence to planar YUV, **range- and matrix-pinned**. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.imageio.video_stream_bytes(mp4) Sum of the video stream’s packet sizes — the AAC track excluded. `file_bytes` includes the audio track, which the renderer always emits (silent if there is no dialogue), so it varies with the audio cache’s state. This one does not. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) # _autosummary/an.bench.ledger.html.md # an.bench.ledger The ledger: three blocks that must never be mixed, and the guards that keep them apart. `metrics` — numbers, each labelled **render-side** or **encode-side**. The two families are blind to each other’s mutations by construction, and a comparison that mixes them is comparing two different questions. `tripwires` — change detectors. They fire on improvements and regressions alike, so they count **zero** toward any criterion. A tripwire in the metrics block is a boolean wearing a measurement’s clothes. `provenance` — never gated, never counted. Everything needed to decide whether two rows may be compared *at all*: the scene contract hash, the resolved encode and decode commands, the mask parameters, the palette, and the environment tuple split into a render side (**comparable on any machine** — the pixels are ISA- and OS-invariant at a pinned Chromium build) and an encode side (**machine-scoped** — a different x264 build moves the decoded stream by two orders of magnitude, and a band wide enough to absorb that would swallow `flat_field_deviation`’s entire crf18->23 signal). Four value states, not two. `no change` and `null` are famously easy to conflate, and conflating them lets any pre-encode statistic pad the witness count for free: ### Module Attributes | [`SCHEMA_VERSION`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.SCHEMA_VERSION) | Bumped when a reader could misinterpret an older row. | |---------------------------------------------------------------------|---------------------------------------------------------| | [`INLINE_SPEC_FIELDS`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.INLINE_SPEC_FIELDS) | Fields a per-scene row carries inline. | ### Functions | [`build_ledger`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.build_ledger)(\*, provenance, scenes) | The whole row. | |--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`build_scene_block`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.build_scene_block)(\*, provenance, metrics, ...) | Assemble one scene's three blocks, refusing anything unreadable. | | [`gated`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.gated)(gate[, detail]) | Shorthand: this number would be uninterpretable, and here is the gate. | | [`measured`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.measured)(value, \*\*extra) | Shorthand: a real number. | | [`metric_declarations`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.metric_declarations)() | The full declaration of every metric and tripwire, once per ledger row. | | [`unavailable`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.unavailable)(detail) | Shorthand: this check could not run, and here is why. | | [`witnesses`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.witnesses)(ledger_scene, mutation) | Which metrics would count for `mutation`, grouped by family. | | [`write_ledger`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.write_ledger)(ledger, path) | Write a row. | ### Classes | [`Value`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.Value)(value[, state, gate, detail, extra]) | One measured (or deliberately absent) number. | |-----------------------------------------------------------------------------------------------|-------------------------------------------------| ### Exceptions | [`LedgerSchemaError`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.LedgerSchemaError) | A ledger row violates an invariant that would make it misreadable. | |----------------------------------------------------------------------|----------------------------------------------------------------------| ### an.bench.ledger.INLINE_SPEC_FIELDS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('side', 'family', 'comparison_scope', 'reference', 'counts')* Fields a per-scene row carries inline. Everything else about a metric — the sentence, the notes, each prediction’s reason and reference — is identical for every scene in a row and for every row, so it lives once in the ledger-level `metric_declarations` block. The split is not only size (it took a two-scene row from 54 KB to a third of that, and an#38 quadruples the corpus). It is readability: a scene block you can read is one where the numbers are not buried in the prose explaining what the numbers are. What stays inline is exactly what `an bench --compare` (an#40) keys on, so a comparison never has to consult a second block to decide whether two rows may be compared at all. ### *exception* an.bench.ledger.LedgerSchemaError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A ledger row violates an invariant that would make it misreadable. ### an.bench.ledger.SCHEMA_VERSION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 1* Bumped when a reader could misinterpret an older row. `an bench --compare` (an#40) must refuse a version it does not understand rather than guess. ### *class* an.bench.ledger.Value(value, state='measured', gate=None, detail='', extra=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One measured (or deliberately absent) number. ### an.bench.ledger.build_ledger(, provenance, scenes) The whole row. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.ledger.build_scene_block(, provenance, metrics, tripwires) Assemble one scene’s three blocks, refusing anything unreadable. Completeness is enforced in both directions. A metric the registry declares but the row omits is a silently narrower panel; a metric the row carries but the registry does not declare has no family, no side and no predicted direction, so nothing downstream can count it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.ledger.gated(gate, detail='') Shorthand: this number would be uninterpretable, and here is the gate. * **Return type:** [`Value`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.Value) ### an.bench.ledger.measured(value, \*\*extra) Shorthand: a real number. `nan` is refused rather than serialized: `json.dumps` emits the non-standard literal `NaN`, which several strict readers reject, and a metric whose mask was empty is an `unavailable`, not a number. * **Return type:** [`Value`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.Value) ### an.bench.ledger.metric_declarations() The full declaration of every metric and tripwire, once per ledger row. Carried IN the row rather than referenced, because `--compare` reads rows written by older registries: a row from six months ago has to be interpretable without checking out the commit that wrote it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.ledger.unavailable(detail) Shorthand: this check could not run, and here is why. * **Return type:** [`Value`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.Value) ### an.bench.ledger.witnesses(ledger_scene, mutation) Which metrics would count for `mutation`, grouped by family. Reads the row rather than the registry, so an#41’s criterion is evaluated against what was actually written down. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> witnesses({"metrics": {"m": {"family": "A", ... "under_mutation": {"high_crf": {"counts": True}}}}}, "high_crf") {'A': ['m']} ``` ### an.bench.ledger.write_ledger(ledger, path) Write a row. `sort_keys=True` so two rows diff line-for-line. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) # _autosummary/an.bench.masks.html.md # an.bench.masks Every mask the panel is computed over, and the recorded operator for each. Three of them serve the encode-side metrics, plus the ring. `EDGE_OPERATOR` has a second spelling, `RENDER_EDGE_OPERATOR`: the same operator applied on the **render** side, where the luma comes from the source RGB rather than from ffmpeg. It is a second string rather than a reuse because it measures a different plane — which is also what keeps family A’s mask off the encoder’s toolchain, on the branch where ffmpeg is absent. Each mask is derived **only from the reference (pre-encode) frames**, never from the decoded ones. That is not a stylistic choice: a mask derived from the decoded stream moves with the mutation, which is the defect that made `edge_ssim` invisible on the AA arm (Δ = +0.0004, ~11x the machine band, because the reference moved with the mutation). Every operator here is exported as a **string** as well as a function, because the ledger has to record what it measured — a threshold nobody can read back is a threshold that quietly changes. ### Module Attributes | [`EDGE_MASK_THRESHOLD`](_autosummary/an.bench.masks.html.md#an.bench.masks.EDGE_MASK_THRESHOLD) | Two-pixel-apart luma gradient above this counts as an edge. | |------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------| | [`FLAT_DILATE_K`](_autosummary/an.bench.masks.html.md#an.bench.masks.FLAT_DILATE_K) | Structuring element for the flat-field erosion. | | [`RENDER_EDGE_OPERATOR`](_autosummary/an.bench.masks.html.md#an.bench.masks.RENDER_EDGE_OPERATOR) | The SAME operator on the render side, and deliberately a second string rather than a reuse of `EDGE_OPERATOR`. | ### Functions | [`dilate`](_autosummary/an.bench.masks.html.md#an.bench.masks.dilate)(mask[, k]) | Binary dilation by a `k x k` square, numpy-only. | |-----------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`edge_mask`](_autosummary/an.bench.masks.html.md#an.bench.masks.edge_mask)(luma, \*[, threshold]) | Pixels straddling a hard luma step, from the reference plane only. | | [`flat_mask`](_autosummary/an.bench.masks.html.md#an.bench.masks.flat_mask)(rgb, \*[, k]) | The interior of large flat colour fields, from the source frames. | | [`held_mask`](_autosummary/an.bench.masks.html.md#an.bench.masks.held_mask)(rgb) | `(N-1, H, W)`: pixels the animator held perfectly still between frames. | | [`ring_mask`](_autosummary/an.bench.masks.html.md#an.bench.masks.ring_mask)(edge) | The band immediately *around* an edge, excluding the edge itself. | ### an.bench.masks.EDGE_MASK_THRESHOLD *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 40* Two-pixel-apart luma gradient above this counts as an edge. Recorded in the ledger with the operator string, because the research is explicit that the prototype’s absolute numbers are ordinal evidence only and no threshold may be written from them. ### an.bench.masks.FLAT_DILATE_K *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 3* Structuring element for the flat-field erosion. ### an.bench.masks.RENDER_EDGE_OPERATOR *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'max(|Y[:,2:]-Y[:,:-2]|, |Y[2:,:]-Y[:-2,:]|) > 40, on FULL-RANGE BT.709 luma from the SOURCE RGB (an.bench.metrics.luma_u8)'* The SAME operator on the render side, and deliberately a second string rather than a reuse of `EDGE_OPERATOR`. `an.bench.imageio`’s `SOURCE_SCALE_FILTER` pins `out_range=tv`, so ffmpeg’s Y lives in [16,235] and its two-apart gradients are 219/255 of the full-range ones this operator sees. At one threshold that makes this the wider mask ON A HARD SYNTHETIC STEP — measured, a 45-code-value step selects 4 pixels here and 0 on the limited-range plane — but NOT uniformly on real frames, where the two run within a percent either way and the render-side one is the narrower on `graded_field` and `single_character`. Which is the point: the two are different measurements, and a reader can only know which one a row carries if the row says which plane it measured. ### an.bench.masks.dilate(mask, k=3) Binary dilation by a `k x k` square, numpy-only. Implemented as shifted ORs rather than a convolution: `k` is 2 or 3 here, so nine shifts beat pulling in scipy, and the package’s dependency perimeter is four names wide on purpose. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> m = np.zeros((1, 5, 5), bool); m[0, 2, 2] = True >>> int(dilate(m, 3)[0].sum()) 9 ``` ### an.bench.masks.edge_mask(luma, , threshold=40) Pixels straddling a hard luma step, from the reference plane only. `luma` is `(N, H, W)` uint8. The border ring is excluded because a two-apart difference is undefined there; excluding it is what keeps the operator string honest. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> y = np.zeros((1, 5, 6), np.uint8); y[0, :, 3:] = 255 >>> int(edge_mask(y).sum()) 6 ``` ### an.bench.masks.flat_mask(rgb, , k=3) The interior of large flat colour fields, from the source frames. ~90% of a flat-cutout frame, and the part no edge metric touches. Banding and blocking live here, and without this mask they are invisible. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> a = np.zeros((1, 9, 9, 3), np.uint8); a[0, :, 5:] = 255 >>> bool(flat_mask(a)[0, 0, 0]) and not bool(flat_mask(a)[0, 0, 5]) True ``` ### an.bench.masks.held_mask(rgb) `(N-1, H, W)`: pixels the animator held perfectly still between frames. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> a = np.zeros((2, 3, 3, 3), np.uint8); a[1, 0, 0] = 5 >>> int(held_mask(a).sum()) 8 ``` ### an.bench.masks.ring_mask(edge) The band immediately *around* an edge, excluding the edge itself. Where ringing and mosquito noise land. Excluding the edge is what makes it a different measurement from `coded_luma_edge_error` rather than a second name for it. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> e = np.zeros((1, 5, 5), bool); e[0, 2, 2] = True >>> int(ring_mask(e).sum()) 8 ``` # _autosummary/an.bench.metrics.html.md # an.bench.metrics The metric panel: pure numpy, no I/O, no subprocess. Every function here is `f(arrays, mask) -> float`. Loading is [`an.bench.imageio`](_autosummary/an.bench.imageio.html.md#module-an.bench.imageio)’s job. The split is what lets the whole panel run in the default CI leg — numpy is a hard dependency, ffmpeg and Playwright are not — which is the only part of this wave that main CI can ever see. **The set is the research’s corrected one, and it is not the epic’s draft.** All twelve originally-proposed metrics were refuted. The corrections that are easiest to undo by accident, each guarded by a test: - `edge_transition_width`’s flatness tolerance must not be 0. With `> 0`, ±3-LSB dither sends the metric to 255.0. - `off_palette_pixel_fraction` must not use `np.unique(..., axis=0)`: 1.833 s/frame at 1080p against 0.019 s for the packed form, 94x, identical result. - `encode_flicker_on_held_pixels` must **cast before subtracting**. `np.abs(a - b)` on uint8 is the identity on unsigned dtypes, so the literal proposed form measured the *sign* of the change. It stayed monotone, which is exactly why it would have shipped unnoticed. And it must report a **rate**, not a mean: the median held-pixel delta is 0 at every CRF. - `encode_ringing_excess` is the difference of two overshoot means, so the source-hardness term cancels. Raw overshoot is a joint function of source hardness and encoder fidelity with one degree of freedom, which is why any move toward crisper outlines raised it under an unchanged encoder. - `edge_masked_distinct_colours` must be handed a mask built from [`luma_u8()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma_u8), never from [`luma709()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma709) directly. `luma709` returns > **float in [0,1]** and [`an.bench.masks.edge_mask()`](_autosummary/an.bench.masks.html.md#an.bench.masks.edge_mask) thresholds at \*\*40 on > 0-255\*\*, so the float form makes every two-apart gradient <= 1.0 and the mask > comes back **entirely empty** — measured: 0 selected pixels against 4 for the > same hard step. The metric would then be `nan` on every scene, which reads > as “the check could not run” rather than as a bug (an#55). One metric the epic named is deliberately absent: `mean_adjacent_frame_ssim` moves the **wrong way** (0.958 at crf18 -> 0.977 at crf51, because a crushed video is smoother). Its existing use as a frozen-render detector in [`an.verify.media_quality`](_autosummary/an.verify.media_quality.html.md#module-an.verify.media_quality) is a different and legitimate job. ### Module Attributes | [`EDGE_FLAT_TOL`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.EDGE_FLAT_TOL) | Two neighbours within this many code values count as "flat". | |---------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`EDGE_TRIM`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.EDGE_TRIM) | Trim fraction for `edge_transition_width`'s mean, so one pathological run cannot carry the number. | | [`FLAT_DEV_TOL`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.FLAT_DEV_TOL) | A flat-field pixel more than this far off is "deviated". | | [`FLICKER_DELTA_TOL`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.FLICKER_DELTA_TOL) | A held pixel that moved by at least this much "flickered". | | [`SSIM_RADIUS`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.SSIM_RADIUS) | `ssim_map` window radius; 7x7, matched to feature size rather than the global-moment form. | | [`FLAT_DEV_TOL_SWEEP`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.FLAT_DEV_TOL_SWEEP) | The neighbourhood of each threshold counter's OWN free parameters over which its verdict must agree before `an bench-compare` will call it a direction (an#140). | | [`BLEND_TOLERANCE`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.BLEND_TOLERANCE) | How far off the line between two palette colours a pixel may sit and still be called a blend of them. | | [`LUMA_709`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.LUMA_709) | BT.709 luma coefficients, recorded in the ledger so a future change to the reduction is visible rather than folded into the number. | ### Functions | [`classify_off_palette`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.classify_off_palette)(entries, palette) | Say, for each off-palette colour, whether it is a blend of two declared ones. | |-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | [`edge_masked_distinct_colours`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.edge_masked_distinct_colours)(packed, edge) | Mean distinct colours per frame, counted ONLY on the edge mask. | | [`edge_transition_width`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.edge_transition_width)(rgb, \*[, tol, trim]) | Average thickness, in pixels, of the fuzzy band between two flat areas. | | [`encode_flicker_on_held_pixels`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.encode_flicker_on_held_pixels)(src_rgb, ...) | Fraction of perfectly-held pixels that moved in the delivered video. | | [`encode_flicker_sweep`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.encode_flicker_sweep)(src_rgb, dec_rgb, \*[, tols]) | `encode_flicker_on_held_pixels`' count at every `tol` of its sweep. | | [`encode_ringing_excess`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.encode_ringing_excess)(dec_luma, ...) | How much more the lossy encode overshoots than a lossless one does. | | [`flat_field_deviation`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.flat_field_deviation)(src_rgb, dec_rgb, flat, \*) | Fraction of flat-field pixels the encoder moved by more than `tol`. | | [`flat_field_deviation_sweep`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.flat_field_deviation_sweep)(src_rgb, dec_rgb, ...) | `flat_field_deviation`'s count at every `(dilate_k, tol)` of its sweep. | | [`frame_distinct_colours`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.frame_distinct_colours)(packed) | Mean number of distinct colours per frame. | | [`golden_comparison`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.golden_comparison)(today_rgb, golden_rgb) | The full-frame identity gate plus its diagnostics. | | [`luma709`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma709)(rgb) | `(H,W,3)` uint8 -> `(H,W)` float in [0,1]. | | [`luma_u8`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma_u8)(rgb) | `(...,3)` uint8 -> `(...)` uint8 luma, on the 0-255 scale a plane uses. | | [`masked_mean_abs`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.masked_mean_abs)(a, b, mask) | `|a - b|` averaged over `mask`, with the cast that makes it correct. | | [`off_palette_pixel_fraction`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.off_palette_pixel_fraction)(packed, palette) | Fraction of the frame whose colour is not one the compiler declared. | | [`off_palette_top_colours`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.off_palette_top_colours)(packed, palette, \*) | The most frequent off-palette colours, as `[{"hex", "count"}]`. | | [`overshoot_mean`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.overshoot_mean)(dec_luma, src_luma, ring) | Mean positive excursion above the source, over the ring band. | | [`pack_rgb`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.pack_rgb)(rgb) | `(N,H,W,3)` uint8 -> `(N,H,W)` uint32, one integer per colour. | | [`ssim_map`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.ssim_map)(a, b, \*[, r]) | Windowed SSIM at stride 1, as a per-pixel map. | | [`sweep_cell_key`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.sweep_cell_key)(\*\*params) | The label of one cell of a parameter sweep, stable across rows. | ### an.bench.metrics.BLEND_TOLERANCE *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 3* How far off the line between two palette colours a pixel may sit and still be called a blend of them. 8-bit channels, so a couple of code values covers rounding in the compositor. ### an.bench.metrics.EDGE_FLAT_TOL *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 4* Two neighbours within this many code values count as “flat”. NOT 0 — see the module docstring. ### an.bench.metrics.EDGE_TRIM *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.1* Trim fraction for `edge_transition_width`’s mean, so one pathological run cannot carry the number. ### an.bench.metrics.FLAT_DEV_TOL *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 6* A flat-field pixel more than this far off is “deviated”. ### an.bench.metrics.FLAT_DEV_TOL_SWEEP *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), ...]* *= (4, 5, 6, 7, 8)* The neighbourhood of each threshold counter’s OWN free parameters over which its verdict must agree before `an bench-compare` will call it a direction (an#140). `flat_field_deviation` is `(dev > tol).mean()` over a mask eroded by `FLAT_DILATE_K`; both are free, and measured on one machine and one x264 build its direction under a 4:2:0 -> 4:4:4 change reversed on three of six scenes somewhere on this grid (`graded_field` +84.2% at tol 6, -81.6% at tol 8). Every shipped value sits inside its own sweep, so a sweep that disagrees is the row saying “somewhere near my own settings, my direction reverses”. The grids are the ones the defect was measured on, not tuned ones; the flicker grid is one-sided below because tol 0 counts every pixel. ### an.bench.metrics.FLICKER_DELTA_TOL *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* A held pixel that moved by at least this much “flickered”. ### an.bench.metrics.LUMA_709 *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= (0.2126, 0.7152, 0.0722)* BT.709 luma coefficients, recorded in the ledger so a future change to the reduction is visible rather than folded into the number. ### an.bench.metrics.SSIM_RADIUS *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 3* `ssim_map` window radius; 7x7, matched to feature size rather than the global-moment form. ### an.bench.metrics.classify_off_palette(entries, palette) Say, for each off-palette colour, whether it is a blend of two declared ones. This is the difference between a diagnostic and a list of hex codes. The metric’s whole meaning is “not one of the colours the compiler declared”, so a palette that under-collects turns it into a large, plausible number with no error anywhere. Anti-aliasing legitimately produces colours \*on the segment between\* two declared colours; a missed literal does not. So each entry gains `blend_of` (the two palette colours it sits between, or `None`). A row whose top off-palette colours are all blends is reporting anti-aliasing correctly. One that is not is a derivation bug, and now it says so in the ledger rather than waiting for someone to look. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)] ```pycon >>> classify_off_palette([{"hex": "#808080"}], [0x000000, 0xffffff])[0]["blend_of"] ['#000000', '#ffffff'] >>> classify_off_palette([{"hex": "#ff00ff"}], [0x000000, 0xffffff])[0]["blend_of"] ``` ### an.bench.metrics.edge_masked_distinct_colours(packed, edge) Mean distinct colours per frame, counted ONLY on the edge mask. The half of `frame_distinct_colours` that is about edges: an interior-only change — a gradient laid into a flat field, a soft shadow — moves the whole-frame count and cannot reach this one at all. The second doctest below is that property, and it is the whole of what the mask buys. \*\*It does NOT make the number blind to a whole-frame blur, and an#55’s premise that it would is refuted.\*\* The mask is recomputed from the frame being measured, and a blur WIDENS the edge band, so the mask grows to admit the new gradation. Measured on the six committed goldens, 3x3 box blur, ratio against k=1: | scene | whole-frame | edge-masked | |-------------------|---------------|---------------| | aa_probe | 10.25x | 9.50x | | graded_field | 2.04x | 2.35x | | multi_shot | 7.92x | 4.63x | | promote_demo | 1.25x | 0.83x | | saturated_outline | 1.49x | 1.14x | | single_character | 8.60x | 5.70x | Damped on four of six, WORSE on `graded_field`, and nowhere near blind. (an#55 quotes “1.8x-9.3x” for the whole-frame column; the real range on these goldens is 1.25x-10.25x, wider at both ends.) \*\*What separates a blur from a supersample is the WIDTH half of the pair, not this one.\*\* The same blur puts `edge_transition_width` at 2.1x-3.4x (`aa_probe` 2.655 -> 5.594 px), while an exact k=2 resolve moves it +2.6% to +8.0% (research §4). So read this metric BESIDE `edge_transition_width`: colours up with width flat is gradation added; colours up with width doubled is a soft picture. **Evidence for a human reader, never a gate.** an#41’s criterion counts metrics independently and cannot express a conjunction, so neither half of the pair may be declared as counting on the strength of the other. `edge` must come from [`an.bench.masks.edge_mask()`](_autosummary/an.bench.masks.html.md#an.bench.masks.edge_mask) applied to [`luma_u8()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma_u8) — **not** to [`luma709()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma709), which is float in [0,1] against a threshold of 40 on 0-255 and yields an empty mask every time. Returns `(mean, frames_measured)`. A frame whose mask is empty is **skipped, not averaged in as zero** — a zero would drag the mean down and read as exactly the regression this metric exists to notice. With no such frame the answer is `nan`, which the caller records as `unavailable`; [`an.bench.ledger.measured()`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.measured) refuses it. ```pycon >>> import numpy as np >>> from an.bench.masks import edge_mask >>> c = np.zeros((1, 4, 16, 3), np.uint8); c[0, :, 8:] = 255 >>> edge_masked_distinct_colours(pack_rgb(c), edge_mask(luma_u8(c))) (2.0, 1) ``` A change entirely inside a flat field moves the whole-frame count and not this one — this, and only this, is what the mask buys: ```pycon >>> d = c.copy() >>> for x in range(2, 6): d[0, :, x] = 8 * (x - 1) ... >>> frame_distinct_colours(pack_rgb(d)) 6.0 >>> edge_masked_distinct_colours(pack_rgb(d), edge_mask(luma_u8(d))) (2.0, 1) ``` An empty mask is not a colour count of zero: ```pycon >>> flat = np.full((1, 4, 8, 3), 128, np.uint8) >>> edge_masked_distinct_colours(pack_rgb(flat), edge_mask(luma_u8(flat))) (nan, 0) ``` * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`int`](https://docs.python.org/3/builtins/functions.html#int)] ### an.bench.metrics.edge_transition_width(rgb, , tol=4, trim=0.1) Average thickness, in pixels, of the fuzzy band between two flat areas. Under 1 is a jagged staircase; ~1 is clean AA; 3+ means the picture has gone soft. **Two-sided**, which is the whole reason it replaced a palette cardinality count: cardinality reads AA-off as 4, AA-on as 45 and a 3x3 blur as 416, so “the number went up” means “AA restored” and “the picture went soft” indiscriminately. Returns `(trimmed_mean, median)`. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)] ```pycon >>> import numpy as np >>> a = np.zeros((1, 4, 8, 3), np.uint8); a[0, :, 4:] = 255 >>> round(edge_transition_width(a)[0], 3) # one hard step = a 2px band 2.0 ``` ### an.bench.metrics.encode_flicker_on_held_pixels(src_rgb, dec_rgb, , tol=2) Fraction of perfectly-held pixels that moved in the delivered video. Held-pose “boiling” — the worst artefact for limited-motion animation. Pooled over every frame pair rather than averaged per pair, so a pair with three held pixels does not weigh as much as one with seventy thousand. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> import numpy as np >>> s = np.zeros((2, 1, 4, 3), np.uint8) >>> d = s.copy(); d[1, 0, 0] = 5 >>> encode_flicker_on_held_pixels(s, d) 0.25 ``` ### an.bench.metrics.encode_flicker_sweep(src_rgb, dec_rgb, , tols=(1, 2, 3, 4)) `encode_flicker_on_held_pixels`’ count at every `tol` of its sweep. Same shape and same purpose as [`flat_field_deviation_sweep()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.flat_field_deviation_sweep): this is the panel’s other hard-threshold counter, and measured under the same 4:2:0 -> 4:4:4 change its direction reverses between tol 2 and tol 3 on `single_character` (+25% -> -15%), and under `high_crf` between tol 1 and tol 2 on `graded_field` (-9% -> +29%). Empty when nothing is held. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`int`](https://docs.python.org/3/builtins/functions.html#int)]] ```pycon >>> import numpy as np >>> s = np.zeros((2, 1, 4, 3), np.uint8) >>> d = s.copy(); d[1, 0, 0] = 2 >>> encode_flicker_sweep(s, d, tols=(2, 3)) {'tol=2': [1, 4], 'tol=3': [0, 4]} ``` ### an.bench.metrics.encode_ringing_excess(dec_luma, lossless_luma, src_luma, ring) How much more the lossy encode overshoots than a lossless one does. Both legs share the source, so the source-spectrum term cancels: AA-off raises both together (correctly reporting “the encoder did not get worse”), a genuine crispness improvement also raises both (no false regression), and a CRF change raises only the lossy leg. **Provisional.** `edge_band_mae` is recorded beside it so research open question 4 — “does plain edge-band MAE beat this?” — is answered by the ledger rather than by nobody. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> import numpy as np >>> s = np.zeros((1, 1, 2), np.uint8) >>> encode_ringing_excess(np.array([[[9, 0]]], np.uint8), ... np.array([[[3, 0]]], np.uint8), s, np.ones((1, 1, 2), bool)) 3.0 ``` ### an.bench.metrics.flat_field_deviation(src_rgb, dec_rgb, flat, , tol=6) Fraction of flat-field pixels the encoder moved by more than `tol`. The strongest metric in the set and the only one measured genuinely orthogonal to the edge/AA axis: monotone over a 133x span on the CRF ladder (0.0003 -> 0.0399, crf18 -> crf51) and flat under every AA variant. Returns `(fraction_over_tol, p99_of_the_deviation)`. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)] ```pycon >>> import numpy as np >>> s = np.zeros((1, 3, 3, 3), np.uint8) >>> d = s.copy(); d[0, 1, 1] = 20 >>> flat_field_deviation(s, d, np.ones((1, 3, 3), bool))[0] 0.1111111111111111 ``` ### an.bench.metrics.flat_field_deviation_sweep(src_rgb, dec_rgb, , mask_rgb, tols=(4, 5, 6, 7, 8), ks=(1, 3, 5)) `flat_field_deviation`’s count at every `(dilate_k, tol)` of its sweep. `{cell_key: [counted, of]}` — integers, so a comparison between two rows is exact rather than a comparison of two rounded fractions. The positional pair is `flat_field_deviation`’s own (reference, decoded); `mask_rgb` — what the flat mask is derived from, the SOURCE frames in `run.py` — is keyword-only so the two roles cannot be swapped positionally. A `k` whose mask selects nothing is omitted, not recorded as `[0, 0]`. It is not a new number for the panel. It is what lets `an bench-compare` tell a verdict from a threshold accident (an#140): the shipped cell IS the metric, and the others say whether anywhere else on the declared grid of its own two parameters the direction reverses. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`int`](https://docs.python.org/3/builtins/functions.html#int)]] ```pycon >>> import numpy as np >>> s = np.zeros((1, 9, 9, 3), np.uint8) >>> d = s.copy(); d[0, 4, 4] = 7 >>> cells = flat_field_deviation_sweep(s, d, mask_rgb=s, tols=(6, 7), ks=(3,)) >>> cells {'dilate_k=3,tol=6': [1, 81], 'dilate_k=3,tol=7': [0, 81]} ``` ### an.bench.metrics.frame_distinct_colours(packed) Mean number of distinct colours per frame. A flatness / palette-discipline **guard**, with no predicted direction on an AA change. Do not count it alongside `off_palette_pixel_fraction`; they are the same family. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> import numpy as np >>> frame_distinct_colours(np.array([[[1, 1, 2]], [[3, 4, 5]]], np.uint32)) 2.5 ``` ### an.bench.metrics.golden_comparison(today_rgb, golden_rgb) The full-frame identity gate plus its diagnostics. Full-frame, not edge-masked: that is what makes the one sentence true, and what catches the flat-interior regressions an edge mask is blind to — and for this look the flat fields are most of the picture. `changed_px` and `max_delta` belong in a failure message, not in the metrics block; they are returned here so the caller can put them there. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ```pycon >>> import numpy as np >>> a = np.zeros((4, 4, 3), np.uint8) >>> golden_comparison(a, a)["identical"] True ``` ### an.bench.metrics.luma709(rgb) `(H,W,3)` uint8 -> `(H,W)` float in [0,1]. PIL-free. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> round(float(luma709(np.full((1, 1, 3), 255, np.uint8))[0, 0]), 6) 1.0 ``` ### an.bench.metrics.luma_u8(rgb) `(...,3)` uint8 -> `(...)` uint8 luma, on the 0-255 scale a plane uses. The one conversion between [`luma709()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.luma709), which returns \*\*float in [0,1]\*\*, and [`an.bench.masks.edge_mask()`](_autosummary/an.bench.masks.html.md#an.bench.masks.edge_mask), whose threshold is \*\*40 on 0-255\*\*. Handing the float straight to the mask is not a wrong number, it is an **empty mask**: every two-apart gradient is <= 1.0, so nothing is ever an edge and the metric downstream reads `unavailable` on every scene. Written once, named and tested here rather than open-coded at each call site, because it cost a debugging round the first time (an#55). **This is FULL-RANGE luma and the encode-side plane is not.** [`an.bench.imageio.SOURCE_SCALE_FILTER`](_autosummary/an.bench.imageio.html.md#an.bench.imageio.SOURCE_SCALE_FILTER) pins `out_range=tv`, so ffmpeg’s Y sits in [16,235] and its gradients are 219/255 of these. At one threshold that makes the render-side mask the **wider** of the two — measured: a 45-code-value step selects 4 pixels here and 0 there — which is why the row records it under its own operator string rather than reusing `an.bench.masks.EDGE_OPERATOR`. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> a = np.zeros((1, 1, 2, 3), np.uint8); a[0, 0, 1] = 255 >>> luma_u8(a).tolist() [[[0, 255]]] ``` ### an.bench.metrics.masked_mean_abs(a, b, mask) `|a - b|` averaged over `mask`, with the cast that makes it correct. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> import numpy as np >>> x = np.array([[[10, 200]]], np.uint8); y = np.array([[[12, 190]]], np.uint8) >>> masked_mean_abs(x, y, np.ones((1, 1, 2), bool)) 6.0 ``` ### an.bench.metrics.off_palette_pixel_fraction(packed, palette) Fraction of the frame whose colour is not one the compiler declared. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> import numpy as np >>> p = np.array([[[0x000000, 0xffffff, 0x808080]]], np.uint32) >>> round(off_palette_pixel_fraction(p, [0x000000, 0xffffff]), 4) 0.3333 ``` ### an.bench.metrics.off_palette_top_colours(packed, palette, , top=10) The most frequent off-palette colours, as `[{"hex", "count"}]`. Not decoration: this metric’s whole meaning is “not one of the colours the compiler declared”, so a palette that under-collects turns it into a large plausible number with no error anywhere. If the top entries are exact hex literals from the staged art, the derivation missed them; if they are blends sitting between two palette entries, that is anti-aliasing and the number is right. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)] ```pycon >>> import numpy as np >>> p = np.array([[[1, 1, 2]]], np.uint32) >>> off_palette_top_colours(p, [2], top=1) [{'hex': '#000001', 'count': 2}] ``` ### an.bench.metrics.overshoot_mean(dec_luma, src_luma, ring) Mean positive excursion above the source, over the ring band. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> import numpy as np >>> s = np.zeros((1, 1, 2), np.uint8); d = np.array([[[5, 0]]], np.uint8) >>> overshoot_mean(d, s, np.ones((1, 1, 2), bool)) 2.5 ``` ### an.bench.metrics.pack_rgb(rgb) `(N,H,W,3)` uint8 -> `(N,H,W)` uint32, one integer per colour. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> hex(int(pack_rgb(np.array([[[[0x12, 0x34, 0x56]]]], np.uint8))[0, 0, 0])) '0x123456' ``` ### an.bench.metrics.ssim_map(a, b, , r=3) Windowed SSIM at stride 1, as a per-pixel map. Added **beside** [`an.verify.media.ssim()`](_autosummary/an.verify.media.html.md#an.verify.media.ssim), never replacing it: that function’s global-moment form is what [`an.verify.media_quality`](_autosummary/an.verify.media_quality.html.md#module-an.verify.media_quality)’s frozen-render threshold was tuned against, and `MediaQualityVerifier` sits in the default orchestrate chain. Why it exists at all: the metrics survey concluded SSIM should be excluded because whole-frame SSIM scores a total eye-blink at 0.9989. That conclusion was **refuted** — only the *global-moment* reduction is blind. With the window matched to feature size, min-over-windows scores the same blink at 0.279 (1080p) and 0.063 (native). Do not cross-check against ffmpeg’s `ssim` filter: it uses overlapped 8x8 block sums at 4-pixel stride, disagrees by up to 0.0201, and the disagreement *grows* with degradation. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> x = np.linspace(0, 1, 64).reshape(8, 8) >>> round(float(ssim_map(x, x).min()), 6) 1.0 ``` ### an.bench.metrics.sweep_cell_key(\*\*params) The label of one cell of a parameter sweep, stable across rows. Keyword order is irrelevant — the key is sorted — so two rows written by code that spells the call differently still match cell for cell. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> sweep_cell_key(tol=6, dilate_k=3) 'dilate_k=3,tol=6' ``` # _autosummary/an.bench.mutants.html.md # an.bench.mutants The guard mutants: “I mutation-tested it” as a runnable artifact, not a claim. Wave 1 shipped three guards that stayed green when the bug they guarded was reintroduced — one flagged the sentence *explaining* a deprecation, one exonerated everything via neighbouring prose, and one keyed on a string the fix itself removed. Wave 2’s own an#36 sweep lost five mutants, two of them to guards that asserted a table’s *contents* rather than the check that reads it. Every commit in this wave has said “N mutants, all caught”. That sentence is unfalsifiable after the fact: the mutations lived in a scratch script and were thrown away. This module is the correction — each one is **declared data**, so a future reader can re-run the proof instead of trusting the commit message. Three properties the declaration is shaped to have: **Each mutant names the guard it must break.** A mutation nobody expected to be caught is a fact about the code; a mutation with a named catcher is a claim about a *test*, and that is what is worth pinning. \*\*The whole file runs, never a `-k` filter.\*\* A filter that happens to exclude the catching test reports “not caught” and sends the reader to write a test that already exists. \*\*The `old` text is pinned exactly.\*\* A mutant whose source text has moved is a mutant that silently stops proving anything, so `tests/test_bench_mutation.py` asserts every site still exists — cheaply, in the default CI leg, with no pytest subprocesses at all. The full sweep is `an bench-mutants`: it is a deliberate act, and it takes about half a minute. **A killed sweep must not leave the tree mutated** (an#67), and that is two mechanisms rather than one, because they cover different kills. SIGTERM is turned into an exception for the duration ([`restore_on_termination()`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.restore_on_termination)) so the restoring `finally` runs; SIGKILL cannot be caught by anything, so [`check_sites()`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.check_sites) — which every sweep runs first, and which the default CI leg runs too — recognises a file whose mutated text is present and whose original is gone, and reports it as an interrupted run with the exact repair. The recovery path is the load-bearing half: what makes a leftover dangerous is that every mutation here is chosen to be *plausible*, so the tree compiles, renders and stays green apart from one test, and a developer can commit it without noticing. That recovery reads “the mutation is present and the original is gone”, which is an assumption about the DECLARATION — so `check_sites` also refuses a mutant whose substitution leaves its own `old` text behind, because such a mutant is invisible to the recovery and a later sweep would restore *to* the leftover. ### Module Attributes | [`PYTEST_ARGS`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.PYTEST_ARGS) | see the module docstring. | |------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`RESTORE_ON_SIGNALS`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.RESTORE_ON_SIGNALS) | Terminating signals turned into an exception for the duration of a sweep, so the restoring `finally` runs. | | [`INTERRUPTED_EXIT_CODE`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.INTERRUPTED_EXIT_CODE) | the shell convention of 128 + SIGINT. | | [`SWEEP_COPY_IGNORE`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.SWEEP_COPY_IGNORE) | Left out of a sweep's throwaway tree. | | [`MUTANTS`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.MUTANTS) | A representative sweep rather than an exhaustive one, chosen so each entry pins a *different* class of failure: a silently widened comparison, a guard that reads the same table twice, a refusal that stops refusing, an unknown-is-not-zero substitution, a decoder that only works on its own output, and an instrument that goes blind without saying so. | | [`RESTORE_TMP_SUFFIX`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.RESTORE_TMP_SUFFIX) | Suffix for the sibling file the restore is staged through. | ### Functions | [`check_sites`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.check_sites)([root]) | Problems with the declarations themselves, as a list of sentences. | |------------------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`format_results`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.format_results)(results) | The digest, with the survivors and errors last because they are the finding. | | [`restore_on_termination`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.restore_on_termination)([signals]) | Turn a terminating signal into an exception for the duration. | | [`run_mutants`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.run_mutants)([names, root]) | Apply each mutant, run its whole guard file, restore, and report. | | [`sweep_tree`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.sweep_tree)(source) | A throwaway copy of `source` for a sweep to do its damage in. | | [`verdict_of`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.verdict_of)(result) | `CAUGHT` / `SURVIVED` / `ERRORED`, as three separate answers. | ### Classes | [`Mutant`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.Mutant)(name, file, old, new, caught_by, why) | One deliberate defect, and the guard that must notice it. | |-------------------------------------------------------------------------------------------------|-------------------------------------------------------------| ### Exceptions | [`MutantError`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.MutantError) | A declared mutant no longer applies, or the tree was left dirty. | |-----------------------------------------------------------------------|------------------------------------------------------------------------| | [`MutantRunInterrupted`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.MutantRunInterrupted) | A terminating signal arrived mid-sweep, raised so the restore can run. | ### an.bench.mutants.INTERRUPTED_EXIT_CODE *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 130* the shell convention of 128 + SIGINT. Nonzero, and distinguishable from the 1 a surviving mutant gives — “you stopped it” and “a guard is decoration” are different answers. * **Type:** What the CLI exits with after an interrupted sweep ### an.bench.mutants.MUTANTS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Mutant](_autosummary/an.bench.mutants.html.md#an.bench.mutants.Mutant), ...]* *= (Mutant(name='png_paeth_tiebreak', file='an/bench/png.py', old='if (pa <= pb and pa <= pc) else (b if pb <= pc else c)', new='if (pa <= pb and pa <= pc) else (b if pb < pc else c)', caught_by='tests/test_bench_png.py', why="the Paeth predictor's tie-break. Wrong, it still decodes this module's own filter-0 output perfectly and corrupts every real Chromium frame — the exact asymmetry that makes an encoder validating its own decoder worthless."), Mutant(name='png_first_idat_only', file='an/bench/png.py', old=' idat.append(payload)', new=' idat = [payload]', caught_by='tests/test_bench_png.py', why='Chromium splits the stream: a real frame has 2-9 IDAT chunks and our own output has one, so a first-chunk-only reader passes its own tests and fails on everything else.'), Mutant(name='png_no_write_verification', file='an/bench/png.py', old=' if not np.array_equal(decode_png(out.read_bytes()), np.asarray(rgb)):', new=' if False:', caught_by='tests/test_bench_png.py', why="the only thing between a bug in this module's own encoder and a committed golden that silently disagrees with the frame it was blessed from."), Mutant(name='golden_criterion_becomes_file_bytes', file='an/bench/golden.py', old=' digest.update(f"{arr.dtype.str}:{arr.shape}|".encode("ascii"))', new=' pass', caught_by='tests/test_bench_golden.py', why='\`ndarray.tobytes()\` carries no shape, so a transposed frame hashes identically and satisfies the criterion an#38 literally states.'), Mutant(name='golden_blesses_a_blank_reason', file='an/bench/golden.py', old=' if not reason.strip():', new=' if reason is None:', caught_by='tests/test_bench_golden.py', why='a re-bless with no recorded reason is the same failure as a silently widened threshold — the named failure mode this wave exists to end.'), Mutant(name='golden_blesses_an_identical_pair', file='an/bench/golden.py', old=' if np.array_equal(decoded[i], decoded[j]):', new=' if False:', caught_by='tests/test_bench_golden.py', why='measured on \`promote_demo\`: frame 0 and the duration/2 frame differ by ZERO pixels, so the obvious second time blesses one picture twice and the second golden tests nothing forever after.'), Mutant(name='compare_gains_a_tolerance_band', file='an/bench/compare.py', old=' if before == after:\\n return "no_change"', new=' if abs(float(before) - float(after)) < 1e-9:\\n return "no_change"', caught_by='tests/test_bench_compare.py', why='two consecutive runs on one machine are bit-identical, so a band can only ever hide a true movement.'), Mutant(name='compare_refuses_on_an_absent_key', file='an/bench/compare.py', old=' elif b is \_ABSENT or a is \_ABSENT:', new=' elif False:', caught_by='tests/test_bench_compare.py', why='the ledger grows additively, so treating absence as difference makes every future field retroactively destroy comparability with every row already written.'), Mutant(name='compare_counts_metrics_not_families', file='an/bench/compare.py', old=' block["family_count"] = len(families)', new=' block["family_count"] = sum(len(v) for v in families.values())', caught_by='tests/test_bench_compare.py', why="counting bare metrics is satisfiable by shipping one signal under three names, which is exactly what family A's three edge metrics would do."), Mutant(name='compare_exempts_the_whole_environment', file='an/bench/compare.py', old=' touched = {t.label for t in MUTATION_TOUCHES.get(mutation, ())}', new=' touched = {i["key"] for i in common + render + encode}', caught_by='tests/test_bench_compare.py', why='the knob the lever pulls is the independent variable; the ISA is not. A blanket exemption lets a row from another machine in through the same door.'), Mutant(name='compare_exempts_by_path_not_by_value', file='an/bench/registry.py', old=' if self.differs_only_in is None:\\n return True', new=' if True:\\n return True', caught_by='tests/test_bench_compare.py', why="\`x264_argv\` is the WHOLE encode command, so exempting the path exempts every flag in it. A \`-preset medium\` -> \`-preset veryslow\` change moves every encode-side number and rode in as 'the lever moved it — expected'. The exemption must match the change the lever actually makes."), Mutant(name='compare_trusts_an_edited_prediction', file='an/bench/compare.py', old=' if not isinstance(inline, dict) or not isinstance(declared, dict):\\n return []', new=' if True:\\n return []', caught_by='tests/test_bench_compare.py', why="the prediction IS the criterion, and it is read from the after row's inline block alone. Flipping one \`expect\` turns \`contrary\` into \`as_declared\` with nothing else in the report moving — the cheapest possible way to fake a caught mutation."), Mutant(name='compare_lets_a_row_forge_its_own_scope', file='an/bench/compare.py', old=' "comparison_scope",\\n "reference",', new=' "reference",', caught_by='tests/test_bench_compare.py', why="\`comparison_scope\` decides whether a metric may be compared ACROSS MACHINES, and \`compare\` reads the row's INLINE copy. Editing that one word compared an encode-side metric across a different ISA with no refusal — the single invariant this module exists to hold, defeated from inside the row."), Mutant(name='ledger_substitutes_zero_for_unknown', file='an/bench/ledger.py', old=' if self.state == "measured":\\n if self.value is None:', new=' if self.state == "measured":\\n if False:', caught_by='tests/test_bench_ledger_schema.py', why='a substituted number — 0.0 especially — is read downstream as a measurement, which is the unknown-is-not-zero failure the whole schema exists to prevent.'), Mutant(name='ledger_lets_a_tripwire_vanish', file='an/bench/ledger.py', old=' absent_tw = sorted(set(TRIPWIRES) - set(tripwires))', new=' absent_tw = []', caught_by='tests/test_bench_ledger_schema.py', why='a change detector that quietly stopped being computed reads exactly like one that fired and found nothing.'), Mutant(name='registry_counts_a_tautology', file='an/bench/registry.py', old=' if self.expect in ("no_change", "not_applicable") and self.counts:', new=' if False:', caught_by='tests/test_bench_ledger_schema.py', why="'no change by construction' is a tautology; counting it lets any pre-encode statistic pad the witness count for free."), Mutant(name='golden_fabricates_a_zero_pixel_count', file='an/bench/golden.py', old='"changed_px": max((int(f["changed_px"]) for f in compared), default=None),', new='"changed_px": max((int(f["changed_px"] or 0) for f in frames), default=0),', caught_by='tests/test_bench_golden.py', why="a shape mismatch has no per-pixel comparison to count, and turning that into 0 printed 'GOLDEN MISMATCH: 0 px changed' — a fabricated number in the one schema whose whole premise is that unknown is not zero."), Mutant(name='compare_scope_absence_fails_open', file='an/bench/compare.py', old=' if scope not in env_refusals:', new=' if False:', caught_by='tests/test_bench_compare.py', why="an absent \`comparison_scope\` read as 'no refusals apply', so an encode-side metric from another ISA and another x264 build compared cleanly and reported a regression."), Mutant(name='strict_passes_a_comparison_that_compared_nothing', file='an/tools.py', old=' not report.get("answered")', new=' False', caught_by='tests/test_bench_compare.py', why="the documented CI gate exited 0 on a run in which every scene was refused, while printing '0 regression(s)' — a zero the compare module's own docstring calls worse than no number at all."), Mutant(name='cli_returns_nothing_to_the_terminal', file='an/_\_main_\_.py', old=' if result is not None:\\n typer.echo(result)', new=' pass', caught_by='tests/test_cli_dispatch.py', why='typer discards return values and every \`an.tools\` function returns its report as a string, so the CLI would run correctly and print NOTHING — the worst possible failure for a diagnostic tool.'), Mutant(name='cli_loses_the_signature_that_is_the_command_line', file='an/_\_main_\_.py', old=' @functools.wraps(func)\\n def run(', new=' def run(', caught_by='tests/test_cli_dispatch.py', why='\`inspect.signature\` follows \`_\_wrapped_\_\`, and that signature IS the command line. Without it typer sees \`(\*args, \*\*kwargs)\` and every flag on all 17 commands disappears at once, while \`--help\` still renders.'), Mutant(name='corpus_reads_shot_order_from_the_directory', file='an/bench/corpus.py', old=' for shot_id in order:\\n shot_dir = root / f"shot_{shot_id}"', new=' for shot_dir in sorted(root.glob(SHOT_DIR_GLOB)):\\n shot_id = shot_dir.name[len("shot_") :]', caught_by='tests/test_bench_corpus.py', why="\`an/render.py\` concatenates in timeline order; a directory sort agrees only by luck, and when it does not every encode-side metric pairs one shot's source frames against another's decode."), Mutant(name='reshape_checks_divisibility_not_shape', file='an/bench/imageio.py', old=' if frames is not None and len(buf) != per_frame \* frames:', new=' if False:', caught_by='tests/test_bench_shape_guard.py', why='a k-times supersample makes the decoded buffer exactly k\*\*2 larger, so a divisibility check ALWAYS passes and family A is computed over k\*\*2 as many scrambled frames — plausibly, because at k=2 most horizontal runs survive the wrong reshape.'), Mutant(name='bench_measures_a_supersampled_render', file='an/bench/run.py', old=' if sizes != {capture.resolution}:', new=' if False:', caught_by='tests/test_bench_shape_guard.py', why="\`capture.resolution\` comes from the staged scene's meta and never from a file, so without an independent read of the PNGs' own IHDRs nothing in the pipeline ever compares the declared size to the size on disk."), Mutant(name='png_dimensions_trusts_a_non_ihdr_first_chunk', file='an/bench/png.py', old=' if data[_IHDR_TAG] != b"IHDR":', new=' if False:', caught_by='tests/test_bench_png.py', why='without the tag check the four bytes that happen to sit at offset 16 are returned as a resolution — a plausible number fed straight into the shape guard, which is the failure class an#54 closes.'), Mutant(name='read_png_dimensions_reads_the_whole_file', file='an/bench/png.py', old=' return png_dimensions(handle.read(PNG_HEADER_BYTES))', new=' return png_dimensions(handle.read())', caught_by='tests/test_bench_png.py', why='the answer stays right and the cost stops being free: the bench reads one of these per frame of every shot, and a 1080p frame is megabytes against a 24-byte header.'), Mutant(name='strict_exits_zero_on_a_row_it_cannot_read', file='an/tools.py', old=' if strict:\\n print(refusal)', new=' if False:\\n print(refusal)', caught_by='tests/test_bench_compare.py', why='the documented CI gate exited 0 on an unreadable schema_version or an undeclared --mutation — precisely the state a \`--strict --mutation supersample\` run is in before the lever is registered. Same class an#51 closed for the refusal path.'), Mutant(name='latest_rows_orders_by_filename', file='an/bench/compare.py', old=' return sorted(rows, key=key)[-count:]', new=' return sorted(rows, key=lambda p: p.name)[-count:]', caught_by='tests/test_bench_compare.py', why="filenames are -.json, so within one date the order is sha HEX order. A re-baseline and its after-run on the same day swap silently when the after-commit's sha sorts lower, and every improvement is then reported as a regression."), Mutant(name='compare_hides_that_a_row_was_blessed', file='an/bench/compare.py', old=' "blessed_scenes": sorted(after["provenance"].get("blessed") or ()),', new=' "blessed_scenes": [],', caught_by='tests/test_bench_compare.py', why="a bless run gates family B \`blessed_this_run\`, and \`format_comparison\` skips \`unchanged\` entries — so family B vanishes from the table entirely. 'Family B agreed' and 'family B was never asked' are the same blank space."), Mutant(name='capture_inherits_the_previous_renders_shots', file='an/bench/core_corpus.py', old='IGNORED_RELPATHS_ON_COPY: tuple[str, ...] = ("artifacts/shots",)', new='IGNORED_RELPATHS_ON_COPY: tuple[str, ...] = ()', caught_by='tests/test_bench_corpus.py', why="\`mall['shots']\` is \`/artifacts/shots\`, and it is gitignored — so a previous render's per-shot mp4s cross into every bench run on a developer machine and on no clean checkout, in the module whose docstring is 'do not inherit a stale render'."), Mutant(name='capture_excludes_shots_by_basename_at_any_depth', file='an/bench/core_corpus.py', old=' n for n in names if prefix + n in IGNORED_RELPATHS_ON_COPY', new=' n\\n for n in names\\n if n in {p.rsplit("/", 1)[-1] for p in IGNORED_RELPATHS_ON_COPY}', caught_by='tests/test_bench_corpus.py', why="the obvious \`shutil.ignore_patterns('shots')\` spelling, restated. It fnmatches BASENAMES against the names in every directory, so it also deletes a character rig's \`assets/.../shots\` — and the other obvious spelling, \`'artifacts/shots'\` as a pattern, matches NOTHING, because no name contains a separator. Both fail silently."), Mutant(name='bless_names_its_row_after_the_tree_it_did_not_leave', file='an/bench/run.py', old=' return git_state(root) if blessed else git', new=' return git', caught_by='tests/test_bench_bless_protocol.py', why='\`git_state\` is read before the corpus loop and a \`--bless\` run writes inside it, so a bless on a clean tree filed itself as \`-.json\` — a filename naming a commit whose tree that very run then modified, which is what the \`-dirty\` suffix exists to prevent.'), Mutant(name='golden_trusts_a_frame_its_own_record_disowns', file='an/bench/golden.py', old=' if expected is not None and expected != record["golden_sha256"]:', new=' if False:', caught_by='tests/test_bench_golden.py', why='the bless record and the committed PNG carry the same digest of the same file, written by two different calls. A disagreement means the golden is not the picture a human blessed — an edited file, a half-finished re-bless — and every one of those read as a clean PASS.'), Mutant(name='bench_asks_a_mutated_run_the_unmutated_question', file='an/tools.py', old=' compare_rows(load_row(compare), ledger, mutation=mutation or None)', new=' compare_rows(load_row(compare), ledger)', caught_by='tests/test_bench_mutation_cli.py', why="without the mutation, \`compare\` answers 'is the second row worse' of a run degraded on purpose — so the declared per-mutation predictions are never scored and the an#41 criterion cannot appear in the mandated \`--compare\` artifact at all."), Mutant(name='bench_blesses_a_deliberately_degraded_picture', file='an/tools.py', old=' if bless:\\n return (\\n "refusing --bless with --mutation: a lever renders a"', new=' if False:\\n return (\\n "refusing --bless with --mutation: a lever renders a"', caught_by='tests/test_bench_mutation_cli.py', why='blessing under a lever commits the degraded picture as the reference every future run is measured against — a permanent, silent re-baseline, and the one bless refusal that cannot be recovered by reading the recorded reason.'), Mutant(name='pix_fmt_knob_cannot_reach_the_encode', file='an/media/mp4.py', old=' resolved = pix_fmt or DEFAULT_PIX_FMT', new=' resolved = pix_fmt or "yuv420p"', caught_by='tests/test_encode_pins.py', why='reading the literal instead of the module global severs the seam any outside caller pulls — the same shape hoisting \`DETERMINISTIC_X264_ARGS\` into a default argument would sever for \`high_crf\`. That is why the seam is kept even though an#59 ships no lever — see the note there. (Until an#72 the row would ALSO have said 4:4:4 while the file stayed 4:2:0, because \`environment_record\` re-derived the format from the same global; it is measured off the delivered files now, so the row no longer lies about its own file — only the knob is broken.)'), Mutant(name='mux_argv_is_checked_by_subset_not_equality', file='an/media/mp4.py', old=' "-c:v",\\n "libx264",\\n "-pix_fmt",', new=' "-c:v",\\n "libx264",\\n "-tune",\\n "animation",\\n "-pix_fmt",', caught_by='tests/test_encode_pins.py', why='\`-tune animation\` is a measured-and-rejected flag (0.8%) and this is what adding it looks like. A SUBSET check passes — every pin is still present — and the encode moves and every encode-side metric is silently refused against every committed row. Only argv equality notices.'), Mutant(name='canvas_capture_flips_rows', file='an/stage/canvas_capture.py', old='rgb = image.convert("RGB")', new='rgb = image.transpose(Image.Transpose.FLIP_TOP_BOTTOM).convert("RGB")', caught_by='tests/test_canvas_capture.py', why='the \`readPixels\` trap in reverse: WebGL readback is bottom-up and a PNG is top-down, so a capture path is one flip away from writing every frame upside down at exactly the declared size — past every shape check. The offline catcher is named here because a sweep runs the whole file per mutant; the browser equivalence gate (tests/test_canvas_capture_equivalence.py) catches the same flip in its own test.'), Mutant(name='capture_page_stops_compositing_the_canvas', file='an/stage/runtime/index.html', old='#stage { display: block; }', new='#stage { display: none; }', caught_by='tests/test_cutout_runtime_files.py', why="an#57's proposal. The element screenshot (the \`--capture screenshot\` path, which shares this page with the canvas default) is a PAGE capture clipped to the element, so hiding the canvas does not make it cheaper — it makes \`Locator.screenshot\` time out after 30 s per frame. The two spellings Playwright does accept return an all-white frame."), Mutant(name='supersample_autodensity_true', file='an/stage/runtime/runtime.js', old=' autoDensity: false,', new=' autoDensity: true,', caught_by='tests/test_bench_supersample_lever.py', why="\`autoDensity: true\` makes Chromium composite the k-times backbuffer down before the screenshot — a blind downscale with no filter choice and no record. The PNGs come out the DECLARED size, so every shape check passes and the whole knob silently measures nothing. It is the option whose name most suggests it is the right one. Lives on the PRODUCT's file since an#58, because the product owns the key."), Mutant(name='supersample_skips_the_frame_stage', file='an/bench/mutations.py', old=' capture.capture_frames = \_capture_then_resolve', new=' capture.capture_frames = original', caught_by='tests/test_bench_supersample_lever.py', why='drops the resolve, leaving k-times PNGs on disk. Before an#54 that was silent — \`_reshape\` checked byte-count divisibility and k\*\*2 always divides — and family A was computed on k\*\*2 scrambled frames that still produced a believable \`edge_transition_width\`. It is a loud refusal now, which is what makes this lever safe to run.'), Mutant(name='supersample_verify_is_merely_not_shipped', file='an/bench/mutations.py', old=' if recorded != expected:', new=' if False:', caught_by='tests/test_bench_supersample_lever.py', why="reduces the supersample fingerprint to \`disabled_aa\`'s inequality, which ANY render lever satisfies — both stage through one seam and both move \`render_side.runtime_sha256\`. A row rendered with \`antialias: false\` then verifies as a supersample row and the whole lever table is written from the wrong lever's numbers."), Mutant(name='edge_masked_colour_count_is_not_masked', file='an/bench/metrics.py', old=' per_frame = [len(np.unique(f[m])) for f, m in zip(packed, edge) if m.any()]', new=' per_frame = [len(np.unique(f)) for f, m in zip(packed, edge) if m.any()]', caught_by='tests/test_bench_metrics.py', why='unmasked it is \`frame_distinct_colours\` under a second name, and the one property the mask does buy — that an interior-only change cannot reach the number — is gone with no other symptom.'), Mutant(name='empty_edge_mask_reads_as_zero_colours', file='an/bench/metrics.py', old=' return float("nan"), 0', new=' return 0.0, 0', caught_by='tests/test_bench_metrics.py', why='a substituted zero is the largest possible DOWNWARD move in the one metric that exists to notice a downward move, on exactly the scenes where the number means nothing at all.'), Mutant(name='lossless_leg_pinned_to_420', file='an/bench/imageio.py', old=' "-pix_fmt",\\n resolved,\\n "-qp",', new=' "-pix_fmt",\\n "yuv420p",\\n "-qp",', caught_by='tests/test_bench_lossless_leg.py', why='a reference PINNED in the one dimension it has to track. The leg exists to be the plane libx264 received; \`-pix_fmt\` names what libx264 receives, so pinning it does not keep the reference lossless — it makes the reference a different colour pipeline from the delivered file, and every encode-side metric silently acquires the whole 4:2:0 conversion the reference exists to cancel. Distinct from every other entry here because the mutated code stays correct on the default path and is wrong only under a knob: measured on the corpus at 4:4:4, it changes the SIGN of family E on three of ten scenes (an#72).'), Mutant(name='sweep_never_finds_a_reversal', file='an/bench/compare.py', old=' unstable = tally["increase"] > 0 and tally["decrease"] > 0', new=' unstable = tally["increase"] > 0 and tally["decrease"] < 0', caught_by='tests/test_bench_compare.py', why="the robustness gate that stops being able to fire. Every row still carries its sweep and every report still prints a \`sweep\` block reading \`stable\`, so the instrument looks exactly like one that checked and found nothing — while \`graded_field\`'s +84.2% at tol 6, which is -81.6% at tol 8, counts toward family D again (an#140)."), Mutant(name='sweep_counts_a_different_statistic', file='an/bench/metrics.py', old='int((dev > t).sum())', new='int((dev >= t).sum())', caught_by='tests/test_bench_metrics.py', why="a sweep of a statistic the row does not report. Off by one code value, every cell stays a plausible, monotone survival count, and the comparer then certifies the robustness of \`>=\` while the ledger's number is \`>\` (an#140)."), Mutant(name='sweep_deletion_is_excused', file='an/bench/compare.py', old=' spec = declared.get("threshold_sweep")\\n', new=' spec = None\\n', caught_by='tests/test_bench_compare.py', why="a row that declares a threshold sweep and carries none reads as 'written before an#140' — so deleting one field from a row turns an \`unstable\` verdict back into a counted witness, the cheapest possible way to fake a caught mutation."), Mutant(name='strict_passes_an_unstable_movement', file='an/tools.py', old='else bool(report.get("has_regressions") or report.get("unstable"))', new='else bool(report.get("has_regressions"))', caught_by='tests/test_bench_compare.py', why="\`unstable\` is neither a regression nor a pass; with no mutation it means some cell of the metric's own grid got worse. A CI gate that exits 0 on it reads 'cannot tell' as 'fine' (an#140)."))* A representative sweep rather than an exhaustive one, chosen so each entry pins a *different* class of failure: a silently widened comparison, a guard that reads the same table twice, a refusal that stops refusing, an unknown-is-not-zero substitution, a decoder that only works on its own output, and an instrument that goes blind without saying so. ### *class* an.bench.mutants.Mutant(name, file, old, new, caught_by, why) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One deliberate defect, and the guard that must notice it. #### caught_by *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* The test file that must go red. The whole file runs. #### file *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Repo-relative path of the file to break. #### old *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Exact source text to replace. Must occur **exactly once**. ### *exception* an.bench.mutants.MutantError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A declared mutant no longer applies, or the tree was left dirty. ### *exception* an.bench.mutants.MutantRunInterrupted Bases: [`KeyboardInterrupt`](https://docs.python.org/3/builtins/exceptions.html#KeyboardInterrupt) A terminating signal arrived mid-sweep, raised so the restore can run. Derived from `KeyboardInterrupt` — a `BaseException` — rather than from `Exception`, on purpose: an `except Exception` anywhere between here and the top would swallow it and the sweep would carry on with a mutated file on disk, which is the outcome the whole mechanism exists to prevent. ### an.bench.mutants.PYTEST_ARGS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('-q', '--no-header', '--tb=no', '-p', 'no:cacheprovider')* see the module docstring. No `--cache-provider` so a failed mutant cannot leave a `--lf` trail behind. * **Type:** pytest flags for a mutant run. No `-k` ### an.bench.mutants.RESTORE_ON_SIGNALS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), ...]* *= (Signals.SIGTERM, Signals.SIGHUP)* Terminating signals turned into an exception for the duration of a sweep, so the restoring `finally` runs. SIGINT is deliberately absent: it already raises `KeyboardInterrupt`, and re-handling it would only replace a working mechanism. Built from what the platform actually has — Windows has no SIGHUP, and asking for one is an `AttributeError` at import time. ### an.bench.mutants.RESTORE_TMP_SUFFIX *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '.an-restore-tmp'* Suffix for the sibling file the restore is staged through. Same directory, so `os.replace` is a rename within one filesystem and therefore atomic. ### an.bench.mutants.SWEEP_COPY_IGNORE *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('_\_pycache_\_', '.pytest_cache', '.ruff_cache', '.venv', 'node_modules', 'out')* Left out of a sweep’s throwaway tree. Caches and build output only — **\`.git\` IS copied**, because six of the thirteen guard files call `dirty_paths` or `repo_root`, and a tree with no history fails them for the wrong reason. Measured at 0.26 s for this repository, once per sweep. ### an.bench.mutants.check_sites(root=None) Problems with the declarations themselves, as a list of sentences. Separate from running them because it is nearly free and catches the failure that matters most: a refactor moved the code, so a mutant no longer applies and has silently stopped proving anything. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.bench.mutants.format_results(results) The digest, with the survivors and errors last because they are the finding. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.mutants.restore_on_termination(signals=(Signals.SIGTERM, Signals.SIGHUP)) Turn a terminating signal into an exception for the duration. `run_mutants` restores in a `finally`, which covers everything that *raises* — an exploding pytest, Ctrl-C — and covers nothing about SIGTERM, which stops the interpreter without raising, so no `finally` runs and the mutated file stays on disk. A `kill`, a timeout, an agent harness reaping a background task and a closing terminal are all SIGTERM, and the sweep is slow enough that interrupting it is the normal thing to do. The previous handlers are restored on the way out, because this module is importable and a library that permanently rewires SIGTERM is a worse defect than the one it fixes. Yields the signals it actually took, which is empty off the main thread (`signal.signal` refuses there), on a platform that will not have them, and for any signal arriving already `SIG_IGN` — a caller that wants to *report* the coverage can, and the restore itself never depends on it. An inherited `SIG_IGN` is left alone. `nohup` and most detach wrappers ignore SIGHUP so a long job survives the terminal closing, and a sweep is exactly the job someone detaches; taking the signal there would convert a deliberately-protected run into a partial one exiting 130. There is nothing to protect against either way — a signal that is ignored is never delivered, so it cannot leave a mutation on disk. **SIGKILL cannot be handled at all**, which is why the recovery path in [`check_sites()`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.check_sites) is the load-bearing half of this fix and this is the convenience. * **Return type:** [`Iterator`](https://docs.python.org/3/library/typing.html#typing.Iterator)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)]] ### an.bench.mutants.run_mutants(names=None, , root=None) Apply each mutant, run its whole guard file, restore, and report. \*\*With no `root`, the sweep runs against a COPY of the repository\*\* and the real working tree is never written (an#124). See [`sweep_tree()`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.sweep_tree) for why that is not merely tidiness. An explicit `root` is swept IN PLACE, because a caller who names a tree has already chosen a throwaway. Restoration is in a `finally` and rewrites the ORIGINAL text rather than reversing the substitution: a reversal that itself failed would leave the tree broken, which is a worse outcome than any mutant surviving. A `finally` covers everything that *raises*, which is why the loop runs inside [`restore_on_termination()`](_autosummary/an.bench.mutants.html.md#an.bench.mutants.restore_on_termination): SIGTERM does not raise. What no handler can cover is SIGKILL, so `check_sites` — which runs first, here — also recognises a file left mutated by a previous kill and says so in those words rather than as declaration rot. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)] ### an.bench.mutants.sweep_tree(source) A throwaway copy of `source` for a sweep to do its damage in. \*\*A sweep mutates real source files, and every mutation here is chosen to be plausible\*\* — it compiles, it renders, and the suite stays green apart from the one test that names it. So a concurrent reader of the working tree does not get an error, it gets a believable wrong answer. That reader is not hypothetical: `test_a_representative_mutant_is_really_caught` runs in the DEFAULT leg, so a plain `pytest -q` mutates `an/bench/compare.py` for a few seconds, and a second suite, an editor re-indexing, a `git status` from another shell or a lint job sees it (an#124 — three pytest processes against one checkout, and which of them owned the file’s contents was unanswerable). Copying is what makes that structurally impossible rather than merely coordinated. A lock would order the *writers*; it cannot reach a reader that never took it. It also retires an#67’s hazard for this path: a sweep killed by SIGKILL can now only leave a mutated file inside a temp directory that nothing reads. * **Return type:** [`Iterator`](https://docs.python.org/3/library/typing.html#typing.Iterator)[[`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)] ### an.bench.mutants.verdict_of(result) `CAUGHT` / `SURVIVED` / `ERRORED`, as three separate answers. `ERRORED` is not a third flavour of caught: a mutant that stops the guard file from being collected has demonstrated nothing about the guard. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) # _autosummary/an.bench.mutations.html.md # an.bench.mutations The levers: deliberate, declared changes through seams the shipped code already has. This is the other half of the instrument. `an bench` records numbers; these change the pipeline on purpose so a test can check the numbers move the way the registry declared **in advance**. A metric that never moves under any lever is decoration, and the only way to know which is which is to pull one. **Two of the three are degradations and the third is an improvement**, and that asymmetry is the point rather than an untidiness. `high_crf` and `disabled_aa` make the picture worse; `supersample` makes it better. A panel that has only ever been shown things getting worse cannot tell an improvement from a regression — run as a plain commit-to-commit diff, a k=2 supersample reports **2 false regressions** (`off_palette_pixel_fraction` rises as blends multiply, `min_ssim_win8_vs_golden` falls away from the golden) and \*\*7 unearned improvements\*\* (every family C/D/E/G metric whose mask derives from the source frames: gates live inside `Prediction`, which exists only per declared mutation, so with `mutation=None` no gate is consulted and a softer source shrinks each mask to its easiest members). Declared as a lever, none of that happens. So what a lever has to be is **declared in advance**, not bad — and the word “degradations” in the old first line was quietly making the stronger, false claim (an#56). **Two of the three levers have no production knob, and that is deliberate.** The third, `supersample`, has had one since an#58 (`an render --supersample N`) and the lever now FORCES the product’s own parameter rather than carrying a second copy of the resolve — a lever that reproduces the code it examines is examining itself. The inverse also exists: `step_hz` (an#89) is a product knob with **no lever**, on measurement — a per-frame instrument cannot judge a temporal choice (the `an-dev-bench` skill’s table has the numbers). Each lever reaches an existing seam from the outside: - `high_crf` rebinds `an.stage.render.DETERMINISTIC_X264_ARGS`. `_ffmpeg_mux` reads that name as a module global at call time, so the rebinding reaches the delivered encode. It does **not** reach `an.bench.imageio.lossless_encode_command`, which bound the tuple at import — and that is exactly right: the lossless reference must stay lossless, or every encode-side metric would be measured against a moving target and the lever would produce beautiful numbers about nothing. - `disabled_aa` copies the staged runtime, flips PixiJS’s `antialias` in the copy, and rebinds `an.stage.render.runtime_dir`. The shipped `runtime.js` is never written to. - `supersample` reaches the SAME runtime seam — `resolution: k, autoDensity: false` in the Pixi application options — and then a second one it cannot do without: it rebinds `an.engines.capture.capture_frames` (the core frame stage’s capture loop since an#247; before it, the stage’s own `_capture_frames`) so the k-times PNGs are block-mean-resolved back to the declared size **in the frame stage**, before ffmpeg or the metrics or the golden gate read them. That is not tidiness. A lever must measure what the product will produce, and everything downstream reads the declared resolution off the STAGED SCENE, never off the files. A knob in the product is a cost each of the other two levers avoids: it has to be documented, defended, and kept from being switched on by accident — which is why supersampling is opt-in and off is free. **Each lever verifies that it applied.** A lever that silently failed to take produces a run in which nothing moved — which reads exactly like an instrument that cannot see it, and sends the reader to fix the wrong thing. So `verify_applied` is part of the declaration rather than a courtesy, and the two levers verify it in different places for a structural reason: the encode argv is recorded in the ledger row, and the runtime is not (the runtime is the code under test, not a comparability key — see `an.bench.registry.MUTATION_TOUCHES`). ### Module Attributes | [`HIGH_CRF`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.HIGH_CRF) | measured on the CRF ladder, 40 gives C x8.4, D x8.0 and F -42% on `single_character` — large, unambiguous, and still a rate a human might plausibly ship. | |-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`AA_ON`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.AA_ON) | The exact text the AA lever flips, and where. | | [`SUPERSAMPLE_K`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.SUPERSAMPLE_K) | The supersample lever's factor, read at call time so a test can move it. | | [`APP_OPEN`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.APP_OPEN) | The exact text the supersample lever anchors to, and what it inserts. | | [`STAGING_IGNORE`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.STAGING_IGNORE) | Excluded from the staged copy so the staged tree is a pure function of the shipped source and the patch — which is what lets `_verify_supersample` RECOMPUTE the digest it expects instead of settling for "not the shipped one". | | [`LEVERS`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.LEVERS) | The levers, keyed by the mutation name the registry declares. | ### Functions | [`mutated_row`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.mutated_row)(name, \*\*run_kwargs) | Render the corpus with one lever pulled, and prove the lever took. | |--------------------------------------------------------------------------------------|----------------------------------------------------------------------| ### Classes | [`Lever`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.Lever)(name, side, what, why, apply[, verify_row]) | One deliberate, declared change to the pipeline, with the evidence that it took. | |------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| ### Exceptions | [`MutationError`](_autosummary/an.bench.mutations.html.md#an.bench.mutations.MutationError) | A lever could not be applied, or applied and left no trace. | |------------------------------------------------------------------|---------------------------------------------------------------| ### an.bench.mutations.AA_ON *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'antialias: true'* The exact text the AA lever flips, and where. Pinned as a literal so a rename in `runtime.js` fails here — loudly, at the lever — rather than producing a “mutation” that changes nothing. ### an.bench.mutations.APP_OPEN *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'const resolution = Math.max(1, (NS.anSupersample | 0) || 1);'* The exact text the supersample lever anchors to, and what it inserts. Pinned for the same reason `AA_ON` is: a reformat of the Pixi options object must fail here rather than produce a “mutation” that renders at 1x and then reads as an instrument that cannot see a supersample. `app = new PIXI.Application({` and NOT `new PIXI.Application(`: the shorter form occurs twice in `runtime.js` — the second is inside a comment — and a two-hit anchor would patch prose. **\`autoDensity: false\` is load-bearing and is the whole plumbing finding.** With it `true`, Pixi sets the canvas CSS size to the LOGICAL size and Chromium composites the k-times backbuffer down before the screenshot — a blind browser downscale with no filter choice and no record of having happened, i.e. the `device_scale_factor` failure wearing the name that most suggests it is the right one. Measured on `aa_probe`, declared 320x240: neither key -> 320x240 PNGs; `resolution: 2, autoDensity: false` -> 640x480; `resolution: 2, autoDensity: true` -> 320x240. Neither key is in the shipped options today, so the engine default `RESOLUTION: 1` applies silently and both have to be introduced. Since an#58 the product owns `resolution` / `autoDensity: false` and reads the factor from an injected global, so the lever \*\*overrides the line that reads it\*\* rather than writing a second copy of the product’s Pixi options. A lever that reproduces the code it is examining is examining itself. Injecting the global does NOT work and the reason is worth keeping: the product sets `window.anSupersample` from `ctx.supersample` immediately before `anLoadScene`, so it would overwrite whatever the lever put there. Caught by an#54’s shape guard — 160x120 frames against a 320x240 declaration — which is what that guard is for. ### an.bench.mutations.HIGH_CRF *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '40'* measured on the CRF ladder, 40 gives C x8.4, D x8.0 and F -42% on `single_character` — large, unambiguous, and still a rate a human might plausibly ship. 51 is pathological, and a lever nobody would ever pull by accident is a weaker proxy for the regressions this instrument exists to catch. * **Type:** The CRF the encoder lever raises to. 40 rather than 51 ### an.bench.mutations.LEVERS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Lever](_autosummary/an.bench.mutations.html.md#an.bench.mutations.Lever)]* *= {'disabled_aa': Lever(name='disabled_aa', side='render', what='build the PixiJS application with multisampling off', why='moves the render-side families and fires the golden tripwire. Its effect is scene-dependent by measurement, not by accident: MSAA applies to WebGL geometry, so an SVG sprite is nearly blind to it (96 differing pixels of 12.4M) and axis-aligned \`drawRect\` edges are bit-identical with it on or off. \`aa_probe\` exists so the corpus contains edges this lever can actually change.', apply=, verify_row=), 'high_crf': Lever(name='high_crf', side='encode', what='raise the delivered encode from the pinned CRF to 40', why='moves only post-encode metrics. The golden corpus is upstream of the encoder, so family B cannot see this by construction — which is the reason two disjoint levers are mandatory.', apply=, verify_row=), 'supersample': Lever(name='supersample', side='render', what='build the PixiJS application at resolution 2 with \`autoDensity: false\`, and resolve the frames back to the declared size with an exact 2x2 block mean before anything reads them', why="the instrument's exam against a change somebody WANTS to ship (an#56). Run instead as a plain commit-to-commit diff, \`_verdict_by_optimum\` reports it as 2 false regressions and 7 unearned improvements, plus 7 unscored \`changed\`s including the metric the wave's done-when names — a table that looks like evidence and is not. Its effect is scene-dependent BY MEASUREMENT and in the exact inverse of \`disabled_aa\`: +2.6% to +8.0% edge width on the five procedural scenes and -34.8% on \`promote_demo\`. The two render levers therefore reach complementary scenes, which strengthens the harness rather than diluting it.", apply=, verify_row=)}* The levers, keyed by the mutation name the registry declares. At least one per SIDE is mandatory and the two sides are **disjoint on purpose**: an encoder lever cannot touch a golden-frame metric, because the corpus sits UPSTREAM of the encoder. So requiring three families from a CRF change alone would fail for a reason that has nothing to do with the instrument being blind — and that failure would be misdiagnosed as the harness being wrong. The two RENDER levers are not redundant: measured, they reach complementary scenes. `disabled_aa` is nearly blind to the descriptor path (96 differing pixels of 12.4M on `promote_demo`, because MSAA applies to WebGL geometry and an SVG sprite is a pre-rasterised texture); `supersample` hits that same scene hardest of all six (-34.8% edge width, because the sprite rasterises AT 2x rather than being stretched up from a 1x texture). ### *class* an.bench.mutations.Lever(name, side, what, why, apply, verify_row=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One deliberate, declared change to the pipeline, with the evidence that it took. #### verify_row *: [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[[dict](https://docs.python.org/3/builtins/stdtypes.html#dict)], [None](https://docs.python.org/3/builtins/constants.html#None)] | [None](https://docs.python.org/3/builtins/constants.html#None)* Given the ledger row the mutated run produced, raise unless the lever’s fingerprint is in it. `None` when the row cannot carry one — see the module docstring. ### *exception* an.bench.mutations.MutationError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) A lever could not be applied, or applied and left no trace. ### an.bench.mutations.STAGING_IGNORE *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('_\_pycache_\_',)* Excluded from the staged copy so the staged tree is a pure function of the shipped source and the patch — which is what lets `_verify_supersample` RECOMPUTE the digest it expects instead of settling for “not the shipped one”. `runtime_sha256()` walks whatever `render.runtime_dir()` returns, so with this excluded on the staging side and on the recompute side, the two hash byte-identical file sets. ### an.bench.mutations.SUPERSAMPLE_K *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* The supersample lever’s factor, read at call time so a test can move it. 2 rather than 3, deliberately and with the residual on the record: research §3 renders each corpus scene at rising k and lets `edge_transition_width` converge, and k=3 reaches that ceiling on every scene that has one while k=2 falls 43% short on `saturated_outline` and 33% short on `graded_field` (0.09-0.17 px). It is 2 because \*\*the lever must be the change the product will ship\*\* — an#58 ships k=2 — and a lever measuring a factor nobody will run is a beautiful number about nothing. Cost, read off 1080p because the corpus cannot inform it: 0.126 s/f at k=1, 0.319 at k=2 (2.54x), 0.640 at k=3. ### an.bench.mutations.mutated_row(name, \*\*run_kwargs) Render the corpus with one lever pulled, and prove the lever took. Deliberately returns a row rather than a comparison: what to do with it is [`an.bench.compare`](_autosummary/an.bench.compare.html.md#module-an.bench.compare)’s job, and keeping the two apart is what lets the criterion be evaluated against a row written months ago. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) # _autosummary/an.bench.palette.html.md # an.bench.palette Derive the set of colours a compiled shot declared — never hand-pin it. `off_palette_pixel_fraction`’s whole meaning is “not one of the colours the compiler declared for this shot”. A hand-tuned palette constant would make it a per-scene magic number, which is exactly what killed its predecessor (`blend_pixel_fraction`: a 12-flat-fill, anti-aliasing-free frame read 2.46% at `K=10`, i.e. 4.8x the entire claimed signal). So the palette is read out of the artifacts the browser actually loaded — the staged `scene.json` and the staged SVG files beside it — never from a re-compile. A re-compile can differ from what ran: a missing character descriptor makes the compiler fall back to the procedural rig, and before an#33 it did so without a word. **Three things this module must get right, each a silent failure otherwise:** 1. `parse_color` is a **verbatim mirror of the runtime’s rule** (`hex.padEnd(6,'0').slice(0,6)`), not a CSS parser. A CSS-correct 3-digit expander maps `"#222"` to `0x222222`; the runtime paints `0x222000`. 2. Some colours are **runtime constants, never present in the JSON** — the eye whites, the four mouth colours. A JSON-only sweep under-collects them and the metric reads high with no error anywhere. 3. Some `visual.color` values are **inert**: `drawMouthShape` never reads its node’s colour, and every `svg_sprite` carries the `#888888` schema default. Collecting those over-collects. Both directions are recorded in `palette_sources` so a reviewer can see which half moved when the number does. ### Module Attributes | [`RUNTIME_DEFAULT_COLOUR`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_DEFAULT_COLOUR) | The runtime's fallback when a `visual.color` is absent or not a string. | |----------------------------------------------------------------------------|------------------------------------------------------------------------------| | [`RUNTIME_EYE_COLOURS`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_EYE_COLOURS) | the sclera fill and the 0.6-alpha outline. | | [`RUNTIME_MOUTH_COLOURS`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_MOUTH_COLOURS) | lip, fill, teeth, tongue. | | [`RUNTIME_EYE_PUPIL_DEFAULT`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_EYE_PUPIL_DEFAULT) | The runtime's fallback pupil colour when a `visual.color` is absent. | | [`COLOURED_KINDS`](_autosummary/an.bench.palette.html.md#an.bench.palette.COLOURED_KINDS) | `visual.kind` values whose `visual.color` the runtime actually paints. | | [`INERT_COLOUR_KINDS`](_autosummary/an.bench.palette.html.md#an.bench.palette.INERT_COLOUR_KINDS) | `visual.kind` values whose `visual.color` is inert. | | [`RUNTIME_JS_RELPATH`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_JS_RELPATH) | Where the runtime's own hard-coded colours live, for the source cross-check. | ### Functions | [`palette_for_scene`](_autosummary/an.bench.palette.html.md#an.bench.palette.palette_for_scene)(scene_json, \*, runtime_dir) | The declared palette of one staged shot. | |---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | [`parse_color`](_autosummary/an.bench.palette.html.md#an.bench.palette.parse_color)(value) | The runtime's own colour rule, mirrored exactly. | | [`runtime_literal_colours`](_autosummary/an.bench.palette.html.md#an.bench.palette.runtime_literal_colours)(runtime_js) | Every 6-digit hex literal the runtime source paints. | | [`svg_colours`](_autosummary/an.bench.palette.html.md#an.bench.palette.svg_colours)(svg_path) | Every colour literal an SVG paints, plus the tokens that could not be resolved. | ### an.bench.palette.COLOURED_KINDS *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'ellipse', 'path', 'rect'})* `visual.kind` values whose `visual.color` the runtime actually paints. A stroked path (an#160) paints `path.color` — the compiler stamps the same value onto `visual.color` (asserted by `tests/test_styles.py`), so one read covers the stroke and the arrowhead, which is filled in that colour. ### an.bench.palette.INERT_COLOUR_KINDS *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'mouth', 'sprite', 'svg_sprite'})* `visual.kind` values whose `visual.color` is inert. ### an.bench.palette.RUNTIME_DEFAULT_COLOUR *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 8947848* The runtime’s fallback when a `visual.color` is absent or not a string. ### an.bench.palette.RUNTIME_EYE_COLOURS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), ...]* *= (16777215, 2236962)* the sclera fill and the 0.6-alpha outline. The outline’s alpha means it paints BLENDS, so it is a lower bound on that node’s contribution — the safe direction. * **Type:** Painted by `makeEye` regardless of `visual.color` ### an.bench.palette.RUNTIME_EYE_PUPIL_DEFAULT *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '#1a1a1a'* The runtime’s fallback pupil colour when a `visual.color` is absent. ### an.bench.palette.RUNTIME_JS_RELPATH *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'an/stage/runtime/runtime.js'* Where the runtime’s own hard-coded colours live, for the source cross-check. ### an.bench.palette.RUNTIME_MOUTH_COLOURS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), ...]* *= (7023403, 2756624, 16448250, 11552840)* lip, fill, teeth, tongue. The mouth node’s own `visual.color` is never read. * **Type:** Painted by `drawMouthShape` ### an.bench.palette.palette_for_scene(scene_json, , runtime_dir) The declared palette of one staged shot. `scene_json` is the **staged** compiled scene (what the browser loaded); `runtime_dir` is the directory it was served from, which is where its SVGs were staged. Returns a dict carrying the palette itself plus enough provenance to explain a move: which half of the derivation each colour came from, whether the palette is a superset of what was painted, and every token that could not be resolved. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.palette.parse_color(value) The runtime’s own colour rule, mirrored exactly. `runtime.js`: ```default function parseColor(s) { if (typeof s !== 'string') return 0x888888; const hex = s.startsWith('#') ? s.slice(1) : s; return parseInt(hex.padEnd(6, '0').slice(0, 6), 16); } ``` Note what that is **not**: a 3-digit CSS shorthand expander. `"#222"` pads to `"222000"`, so the runtime paints `0x222000` and so must this. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> hex(parse_color("#222")) '0x222000' >>> hex(parse_color("#ffffffaa")) '0xffffff' >>> hex(parse_color(None)) '0x888888' ``` ### an.bench.palette.runtime_literal_colours(runtime_js) Every 6-digit hex literal the runtime source paints. Used to cross-check [`RUNTIME_EYE_COLOURS`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_EYE_COLOURS) and [`RUNTIME_MOUTH_COLOURS`](_autosummary/an.bench.palette.html.md#an.bench.palette.RUNTIME_MOUTH_COLOURS) against the file that actually paints them, so adding a fifth mouth colour reddens a test instead of silently inflating `off_palette_pixel_fraction`. * **Return type:** [`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`int`](https://docs.python.org/3/builtins/functions.html#int)] ### an.bench.palette.svg_colours(svg_path) Every colour literal an SVG paints, plus the tokens that could not be resolved. Parsed as XML rather than scraped with a regex, so `style="fill:#abc"` and a `display:none` subtree are both handled — the first is a spelling a regex over `fill="…"` misses entirely, and the second contributes colours to a palette that never reach a pixel. An unresolvable token (a named colour, a `url(#gradient)` reference) is **returned rather than guessed**: guessing puts a wrong colour in the palette, and the metric then reads low with no error anywhere. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`int`](https://docs.python.org/3/builtins/functions.html#int)], [`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] # _autosummary/an.bench.paths.html.md # an.bench.paths Where the bench reads its corpus from and writes its ledger to. One module owns every path so the “bench needs a source checkout” constraint is stated once, with a typed error, rather than surfacing as a `FileNotFoundError` from inside `shutil.copytree`. ### Module Attributes | [`LEDGER_DIRNAME`](_autosummary/an.bench.paths.html.md#an.bench.paths.LEDGER_DIRNAME) | Ledger rows live here, one file per (date, commit). | |-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | [`GOLDEN_DIRNAME`](_autosummary/an.bench.paths.html.md#an.bench.paths.GOLDEN_DIRNAME) | Golden frames (an#38 fills this; the path convention ships now so the cassette work and the corpus work do not have to agree on it later). | ### Functions | [`git_state`](_autosummary/an.bench.paths.html.md#an.bench.paths.git_state)([root]) | `sha` / `branch` / `dirty` for the checkout, or

```
``
```

None\`\`s off-git. | |----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------| | [`golden_dir`](_autosummary/an.bench.paths.html.md#an.bench.paths.golden_dir)([root]) | The golden-frame directory (an#38). | | [`golden_path`](_autosummary/an.bench.paths.html.md#an.bench.paths.golden_path)(scene, frame_key, chromium_build, \*) | Where one golden frame lives. | | [`ledger_dir`](_autosummary/an.bench.paths.html.md#an.bench.paths.ledger_dir)([root]) | The ledger directory, created if absent. | | [`ledger_path`](_autosummary/an.bench.paths.html.md#an.bench.paths.ledger_path)(\*[, root, git]) | `-[-dirty].json`. | | [`repo_root`](_autosummary/an.bench.paths.html.md#an.bench.paths.repo_root)() | The source checkout `an` was imported from. | ### Exceptions | [`BenchLayoutError`](_autosummary/an.bench.paths.html.md#an.bench.paths.BenchLayoutError) | The bench was run somewhere it cannot find the corpus. | |---------------------------------------------------------------------|----------------------------------------------------------| ### *exception* an.bench.paths.BenchLayoutError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The bench was run somewhere it cannot find the corpus. ### an.bench.paths.GOLDEN_DIRNAME *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'misc/bench/golden'* Golden frames (an#38 fills this; the path convention ships now so the cassette work and the corpus work do not have to agree on it later). ### an.bench.paths.LEDGER_DIRNAME *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'misc/bench/ledger'* Ledger rows live here, one file per (date, commit). Append-only by convention: an existing row is evidence about a commit, and editing it rewrites history that `an bench --compare` (an#40) reads as fact. ### an.bench.paths.git_state(root=None) `sha` / `branch` / `dirty` for the checkout, or ``` `` ``` None\`\`s off-git. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.paths.golden_dir(root=None) The golden-frame directory (an#38). * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.bench.paths.golden_path(scene, frame_key, chromium_build, , root=None) Where one golden frame lives. Keyed on the **Chromium build alone** — no platform or arch segment. The cross-architecture verdict measured those segments to be inert (zero differing pixels and zero differing PNG bytes across arm64 macOS, x86-64 Linux and arm64 Linux, across two different SwiftShader JIT backends), so carrying them would force one committed copy per platform for no information. What the convention keeps is its real benefit: a Playwright bump becomes a **new path requiring a deliberate re-bless** rather than a red test with no explanation. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ```pycon >>> golden_path("s", "f0", "140.0.7339.16").name 'f0-chromium140.0.7339.16.png' ``` ### an.bench.paths.ledger_dir(root=None) The ledger directory, created if absent. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.bench.paths.ledger_path(, root=None, git=None) `-[-dirty].json`. The `-dirty` suffix is not decoration: a row measured against uncommitted edits describes no commit, and a filename that claims one would be read by an#40 as that commit’s evidence. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ```pycon >>> ledger_path(git={"sha": "abc1234def", "dirty": True}).name.endswith("-dirty.json") True ``` ### an.bench.paths.repo_root() The source checkout `an` was imported from. Raises rather than returning a plausible-but-wrong path, because the failure it guards is running the bench against an installed wheel: the corpus lives under `misc/bench/`, which is not packaged, so the first symptom would be a missing-fixture error three frames deep. The checkout’s folder name is not asserted: a git worktree or a clone under another name is still a source checkout. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ```pycon >>> (repo_root() / "an" / "bench" / "paths.py").is_file() True ``` # _autosummary/an.bench.png.html.md # an.bench.png A filter-0 PNG writer and a full-filter reader — numpy and stdlib only. The golden corpus is committed as PNGs, and the gate compares \*\*decoded pixels\*\*. Both halves of that sentence need this module. **Why write our own encoder rather than copy Chromium’s bytes.** A committed golden written by copying the screenshot file is a function of Chromium’s libpng settings as well as of the picture. Re-encoding every row with filter type 0 makes the committed file a function of the **pixel data alone**, so a future Chromium bump that changes its filter heuristic produces no diff at all when the picture has not moved. Measured on the five real frames in this repo, filter-0 re-encoding is also *smaller* every time — between -5.2% and -22.3% (research §3 recorded -0.30%, from a single frame; the range is wider both ways than one sample suggested). **Why the reader must handle all five filter types.** The bless path reads Chromium’s own screenshots, and Chromium emits Sub / Up / Paeth. Only the files this module writes are filter-0. \*\*Why the filters are unfiltered over a `bytearray` rather than a numpy array.\*\* Sub, Average and Paeth are sequential along the row — byte *x* depends on byte *x - bpp* of the same row — so they cannot be vectorised, and the inner loop is scalar either way. Scalar indexing into a `bytearray` is measurably cheaper than into a numpy array: 32 ms against 111 ms for a 320x240 Chromium frame, and 444 ms against 2,430 ms for a mixed-filter 1920x1080 one. A filter-0 file skips the loop entirely (a whole-row slice), which is why reading a golden costs ~0.1 ms at 320x240 and ~1.8 ms at 1080p. The round trip is exact, and it is verified in both directions against an independent decoder: `ffmpeg -pix_fmt rgb24` agrees with [`decode_png()`](_autosummary/an.bench.png.html.md#an.bench.png.decode_png) on every rendered frame in the repo, and reads back what [`encode_png()`](_autosummary/an.bench.png.html.md#an.bench.png.encode_png) writes. ### Module Attributes | [`PNG_SIGNATURE`](_autosummary/an.bench.png.html.md#an.bench.png.PNG_SIGNATURE) | PNG's fixed 8-byte signature. | |----------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------| | [`DFLT_ZLIB_LEVEL`](_autosummary/an.bench.png.html.md#an.bench.png.DFLT_ZLIB_LEVEL) | zlib level for the IDAT stream. | | [`RGB_CHANNELS`](_autosummary/an.bench.png.html.md#an.bench.png.RGB_CHANNELS) | What [`encode_png()`](_autosummary/an.bench.png.html.md#an.bench.png.encode_png) writes, and the only channel count the golden gate compares. | | [`SUPPORTED_BIT_DEPTH`](_autosummary/an.bench.png.html.md#an.bench.png.SUPPORTED_BIT_DEPTH) | Bit depth. | | [`PNG_HEADER_BYTES`](_autosummary/an.bench.png.html.md#an.bench.png.PNG_HEADER_BYTES) | the 8-byte signature, a 4-byte chunk length, the 4-byte `IHDR` tag, and two big-endian uint32s. | ### Functions | [`decode_png`](_autosummary/an.bench.png.html.md#an.bench.png.decode_png)(data) | Decode an 8-bit truecolour PNG to `(H, W, C)` uint8, `C` in `{3, 4}`. | |------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`encode_png`](_autosummary/an.bench.png.html.md#an.bench.png.encode_png)(rgb, \*[, level]) | Encode `(H, W, 3)` uint8 as an 8-bit truecolour PNG, every row filter 0. | | [`png_dimensions`](_autosummary/an.bench.png.html.md#an.bench.png.png_dimensions)(data) | `(width, height)` from a PNG's IHDR, without decoding a single pixel. | | [`read_png`](_autosummary/an.bench.png.html.md#an.bench.png.read_png)(path) | `(H, W, 3)` uint8 for a PNG on disk, alpha dropped only if opaque. | | [`read_png_dimensions`](_autosummary/an.bench.png.html.md#an.bench.png.read_png_dimensions)(path) | `(width, height)` for a PNG on disk, reading only its header. | | [`to_rgb`](_autosummary/an.bench.png.html.md#an.bench.png.to_rgb)(arr) | Drop a **fully opaque** alpha channel, refusing to drop a meaningful one. | | [`write_png`](_autosummary/an.bench.png.html.md#an.bench.png.write_png)(path, rgb, \*[, level]) | Write `rgb` as a filter-0 PNG and **verify the round trip** before returning. | ### Exceptions | [`PngFormatError`](_autosummary/an.bench.png.html.md#an.bench.png.PngFormatError) | A PNG this module deliberately does not decode, or a malformed one. | |-------------------------------------------------------------------|-----------------------------------------------------------------------| ### an.bench.png.DFLT_ZLIB_LEVEL *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 9* zlib level for the IDAT stream. 9 because a golden is written rarely and read often, and because the committed bytes are reviewed in a diff. ### an.bench.png.PNG_HEADER_BYTES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 24* the 8-byte signature, a 4-byte chunk length, the 4-byte `IHDR` tag, and two big-endian uint32s. PNG requires IHDR to be the FIRST chunk, so this prefix is always enough. * **Type:** Bytes needed to read an image’s declared size ### an.bench.png.PNG_SIGNATURE *: [bytes](https://docs.python.org/3/builtins/stdtypes.html#bytes)* *= b'\\x89PNG\\r\\n\\x1a\\n'* PNG’s fixed 8-byte signature. ### *exception* an.bench.png.PngFormatError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A PNG this module deliberately does not decode, or a malformed one. Typed and specific on purpose: the alternative to refusing is returning a plausible array, and a golden gate that compares a plausible array is worse than one that does not run. ### an.bench.png.RGB_CHANNELS *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 3* What [`encode_png()`](_autosummary/an.bench.png.html.md#an.bench.png.encode_png) writes, and the only channel count the golden gate compares. Alpha is dropped at the boundary (see [`to_rgb()`](_autosummary/an.bench.png.html.md#an.bench.png.to_rgb)), never here. ### an.bench.png.SUPPORTED_BIT_DEPTH *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 8* Bit depth. 16-bit PNGs are refused rather than truncated — a silently halved code value is exactly the class of bug this corpus exists to catch. ### an.bench.png.decode_png(data) Decode an 8-bit truecolour PNG to `(H, W, C)` uint8, `C` in `{3, 4}`. Refuses — rather than approximates — 16-bit, palette, greyscale and interlaced images, naming what it found. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> a = np.array([[[1, 2, 3], [4, 5, 6]]], np.uint8) >>> np.array_equal(decode_png(encode_png(a)), a) True ``` ### an.bench.png.encode_png(rgb, , level=9) Encode `(H, W, 3)` uint8 as an 8-bit truecolour PNG, every row filter 0. * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) ```pycon >>> import numpy as np >>> data = encode_png(np.zeros((2, 3, 3), np.uint8)) >>> data[:8] == PNG_SIGNATURE True >>> decode_png(data).shape (2, 3, 3) ``` ### an.bench.png.png_dimensions(data) `(width, height)` from a PNG’s IHDR, without decoding a single pixel. Width first, matching the PNG header itself — and deliberately the opposite order from [`read_png()`](_autosummary/an.bench.png.html.md#an.bench.png.read_png), which returns `(H, W, C)` like every other array here. Getting it backwards produces a square-looking check that passes on square frames only, so the order is asserted in the tests. Cheap on purpose. The bench reads this for **every** frame on disk rather than sampling one, because the failure it exists to catch — a render whose frame size changed partway through — is exactly the one sampling misses. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`int`](https://docs.python.org/3/builtins/functions.html#int)] ```pycon >>> import numpy as np >>> png_dimensions(encode_png(np.zeros((240, 320, 3), np.uint8))) (320, 240) ``` ### an.bench.png.read_png(path) `(H, W, 3)` uint8 for a PNG on disk, alpha dropped only if opaque. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.bench.png.read_png_dimensions(path) `(width, height)` for a PNG on disk, reading only its header. A 1080p frame is megabytes and its declared size is in the first 24 of them. Reading only those is what makes checking every frame of every shot free rather than a second full decode of the corpus. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`int`](https://docs.python.org/3/builtins/functions.html#int)] ### an.bench.png.to_rgb(arr) Drop a **fully opaque** alpha channel, refusing to drop a meaningful one. The golden gate compares RGB ([`an.bench.metrics.golden_comparison()`](_autosummary/an.bench.metrics.html.md#an.bench.metrics.golden_comparison) takes three channels). Dropping alpha unconditionally would make a transparency regression invisible to the one gate that exists to see changes, so a non-opaque alpha is an error rather than a silent narrowing. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> import numpy as np >>> to_rgb(np.full((1, 1, 4), 255, np.uint8)).shape (1, 1, 3) ``` ### an.bench.png.write_png(path, rgb, , level=9) Write `rgb` as a filter-0 PNG and **verify the round trip** before returning. The verification is not defensive noise: it is the only thing standing between a bug in this module’s own encoder and a committed golden that silently disagrees with the frame it was blessed from. Research §3 asks for exactly this — “assert the round trip at bless time against the in-memory screenshot pixels, so a bug in `an`’s own encoder cannot hide”. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) # _autosummary/an.bench.registry.html.md # an.bench.registry The metric declaration table — what each number is, and which way it should move. This is **data, not prose**, because an#41’s criterion is a query over it: “>=3 metrics from >=3 distinct causal families, evaluated per mutation, with a per-metric per-mutation sign declared in advance”. A second, hand-maintained table of families is how that criterion silently stops being true. Three things the research requires this table to carry, all three of which invalidate every prior ledger row if retrofitted: 1. **A per-metric per-mutation direction**, two-sided where the optimum is interior. `edge_transition_width` has an interior optimum — under 1 is a staircase, 3+ is soft — and the sharpness family moves in *opposite* directions for the two mutations, so a single per-metric sign mis-reports one of them. 2. **\`\`null\`\` (gated) distinguished from “no change”.** “No change by construction” is a tautology and must never count as a satisfied prediction, or any pre-encode statistic pads the count for free. Four states, not two: `gated` (the reference moved, or the source hash differs), `unavailable` (the check could not run — a crashed check is not evidence anything is fine), `no_change` (tautology), `not_applicable` (wrong side of the encoder). 3. **The family letters**, so the redundancy rule is checkable. Family C counts as **one** until the correlation between `coded_luma_edge_error` and `chroma_edge_dCr` is measured across the encoder matrix — they were r=0.990 in their broken forms and the corrections are *expected* to decorrelate them, which is not the same as measured. The invariants are enforced in `__post_init__`, not by convention. ### Module Attributes | [`MUTATIONS`](_autosummary/an.bench.registry.html.md#an.bench.registry.MUTATIONS) | an encoder lever cannot touch a golden-frame metric because the corpus is UPSTREAM of the encoder, so requiring ">=3 metrics" from a CRF change alone would fail because of where the corpus sits, not because the instrument is blind — and that failure would be misdiagnosed as the harness being wrong. | |-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`REFUSED_LEVERS`](_autosummary/an.bench.registry.html.md#an.bench.registry.REFUSED_LEVERS) | Levers that were TRIED and refused, each with the measured reason — data, so `an bench --mutation ` answers with the reason instead of "unknown", and the next person meets the measurement before re-registering one. | | [`REFERENCE_NOTE`](_autosummary/an.bench.registry.html.md#an.bench.registry.REFERENCE_NOTE) | What an encode-side metric is measured AGAINST. | | [`FAMILY_SIDE`](_autosummary/an.bench.registry.html.md#an.bench.registry.FAMILY_SIDE) | Which side of the encoder each causal family lives on. | | [`METRICS`](_autosummary/an.bench.registry.html.md#an.bench.registry.METRICS) | The panel. | | [`TRIPWIRES`](_autosummary/an.bench.registry.html.md#an.bench.registry.TRIPWIRES) | Tripwires. | ### Classes | [`MetricSpec`](_autosummary/an.bench.registry.html.md#an.bench.registry.MetricSpec)(key, family, unit, optimum, ...) | One row of the panel. | |--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------| | [`Optimum`](_autosummary/an.bench.registry.html.md#an.bench.registry.Optimum)(kind[, expect, note]) | Which way "better" points, and whether the optimum is interior. | | [`Prediction`](_autosummary/an.bench.registry.html.md#an.bench.registry.Prediction)(expect[, counts, gate, reason, ...]) | What one metric is expected to do under one mutation, declared in advance. | | [`Sweep`](_autosummary/an.bench.registry.html.md#an.bench.registry.Sweep)(grid, shipped) | The grid of a threshold counter's OWN free parameters its verdict is checked on. | | [`Touch`](_autosummary/an.bench.registry.html.md#an.bench.registry.Touch)(path[, differs_only_in]) | One environment key a lever is expected to change, and HOW. | ### Exceptions | [`RegistryError`](_autosummary/an.bench.registry.html.md#an.bench.registry.RegistryError) | A metric declaration violates one of the table's invariants. | |------------------------------------------------------------------|----------------------------------------------------------------| ### an.bench.registry.FAMILY_SIDE *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'A': 'render', 'B': 'render', 'C': 'encode', 'D': 'encode', 'E': 'encode', 'F': 'encode', 'G': 'encode'}* Which side of the encoder each causal family lives on. Render-side metrics are computed on the pre-encode PNG and are blind to the encoder BY CONSTRUCTION; encode-side metrics compare a decoded frame to its own source and are structurally blind to render regressions, because the reference moves with the mutation. They must never be mixed. ### an.bench.registry.METRICS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [MetricSpec](_autosummary/an.bench.registry.html.md#an.bench.registry.MetricSpec)]* *= {'chroma_edge_dCr': MetricSpec(key='chroma_edge_dCr', family='C', unit='code values (8-bit Cr)', optimum=Optimum(kind='one_sided', expect='minimize', note=''), predictions={'high_crf': Prediction(expect='increase', counts=False, gate=None, reason='family C counts as ONE family until the correlation with coded_luma_edge_error is measured across the encoder matrix', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='reference_moved', reason='measured -0.7% on a faithful AA-off simulation; the claimed +10.7% was refuted. Predict no render-side direction.', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='reference_moved', reason='its subject IS the 4:2:0 subsampling of a conversion whose input this lever changes, so there is no fixed reference. Predict no render-side direction, exactly as for \`disabled_aa\`.', reference=None)}, sentence='How much the colour shifts on the pixels straddling a hard outline once the video is encoded.', role=None, reference='source_png', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'chroma_edge_dCr_over_dY': MetricSpec(key='chroma_edge_dCr_over_dY', family='C', unit='ratio', optimum=Optimum(kind='guard', expect=None, note="3.3 at qp0 yuv420p is real 4:2:0 bleed; 0.96 at crf51 is generic damage wearing the metric's name. The denominator IS \`coded_luma_edge_error\` — the research's \`chroma_edge_dY\` control is mean |dY| over the edge mask, which is that metric's definition verbatim. Measured identical (1.484149 for both on the first real row), so it is recorded once rather than twice: one signal under two names is exactly how a witness count is padded dishonestly."), predictions={'high_crf': Prediction(expect='decrease', counts=False, gate=None, reason='the chroma claim collapses as damage becomes generic', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='reference_moved', reason='', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='reference_moved', reason='', reference=None)}, sentence='dCr/dY on the edge mask: large means real chroma bleed, ~1 means generic blocking.', role='diagnostic', reference='source_png', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'chroma_edge_dY': MetricSpec(key='chroma_edge_dY', family='C', unit='code values (8-bit Y)', optimum=Optimum(kind='guard', expect=None, note="Read only as the ratio's denominator. NOT a second name for \`coded_luma_edge_error\`: that one references the lossless leg and this one references the PNG conversion, so they differ by exactly the conversion term. They were identical (1.484149) while both referenced the PNG conversion, which is why one of them was removed and then restored when the references diverged."), predictions={'high_crf': Prediction(expect='increase', counts=False, gate=None, reason='control for the ratio below', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='reference_moved', reason='', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='reference_moved', reason='', reference=None)}, sentence='The luma error on the SAME mask and the SAME reference as \`chroma_edge_dCr\` — a control, not a quality metric.', role='control', reference='source_png', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'coded_luma_edge_error': MetricSpec(key='coded_luma_edge_error', family='C', unit='code values (8-bit Y)', optimum=Optimum(kind='one_sided', expect='minimize', note=''), predictions={'high_crf': Prediction(expect='increase', counts=True, gate=None, reason="family C's witness", reference='0.419 (qp0) -> 1.875 (crf23) -> 41.2 (crf51)'), 'disabled_aa': Prediction(expect=None, counts=False, gate='reference_moved', reason='the source PNG moves with the mutation, so the delta is uninterpretable', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='reference_moved', reason='same gate, same mechanism as \`disabled_aa\`: the source PNG moves with the mutation. A render lever of EITHER sign disqualifies it — and this one is the reason to say so out loud, because a softer source shrinks the edge mask to its easiest members and the number improves MECHANICALLY. Ungated it is one of the 7 unearned improvements a \`mutation=None\` diff reports for this change (an#56).', reference=None)}, sentence="How much the encoder's quantiser roughens the brightness step at a line's edge, measured on the codec's own luma plane.", role=None, reference='lossless', provisional=False, unreviewed=False, tripwire=False, requires='', notes=("Read the coded luma plane; NEVER recompute Y from decoded RGB. The RGB round trip clips at saturated edges, and ~83% of the broken form's baseline was chroma leakage.",), sweep=None), 'edge_masked_distinct_colours': MetricSpec(key='edge_masked_distinct_colours', family='A', unit='count', optimum=Optimum(kind='guard', expect=None, note="A guard, not a dial, for the exact reason Wave 2 deleted the ONE-SIDED \`edge_distinct_colours\`: a 3x3 blur raised that 9.2x and +/-3-LSB noise 55x, and BOTH degradations read as 'AA restored'. What the mask buys is narrower than an#55 assumed, and the difference was MEASURED before this row shipped: an INTERIOR-ONLY change cannot reach the number, but a whole-frame blur can, because the mask is recomputed from the frame being measured and a blur widens the edge band. 3x3 box blur on the six committed goldens, ratio against k=1, whole-frame vs edge-masked: aa_probe 10.25x/9.50x, graded_field 2.04x/2.35x, multi_shot 7.92x/4.63x, promote_demo 1.25x/0.83x, saturated_outline 1.49x/1.14x, single_character 8.60x/5.70x — damped on four of six, WORSE on one, blind on none. So the metric that separates a blur from a supersample is \`edge_transition_width\` (2.1x-3.4x under the same blur against +2.6% to +8.0% under an exact k=2 resolve), and this row is the second half of that reading, not the first. \*\*The pair is evidence for a human reader and NOT a gate\*\* — an#41's criterion counts metrics independently and cannot express a conjunction, so nothing here may be read as one. No figure for THIS metric under a lever exists yet, which is why \`reference\` is unset rather than borrowed from \`frame_distinct_colours\` (an#55)."), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='pre-encode, and blind to the encoder BY CONSTRUCTION like every family A row: both the mask and the colours come from the source PNG, which sits upstream of the encoder', reference=None), 'disabled_aa': Prediction(expect='decrease', counts=False, gate=None, reason="the same direction as \`frame_distinct_colours\`, deliberately: for flat cutout art essentially all colour variety lives at edges, so the mask is close to a no-op for the COUNT (wave2 research §1.3 measured the two within 6%). The whole-frame count under the lever on \`aa_probe\` goes 7.6 -> 3.0 at k=1 and 21.7 -> 6.9 at k=2 (wave3 research §5) — those are \`frame_distinct_colours\` numbers, NOT this metric's, and \`reference\` is deliberately left unset until a real row measures THIS one. NOT counted: family A spends its one witness on \`edge_transition_width\` and this is the same family. NOT gated either, and the distinction is the one most likely to be flipped by a later reviewer: the mask does move with the lever, but the mask and the number come from the SAME frames, so there is no reference to move. That is what makes \`flat_field_deviation\` further down gated and this one not.", reference=None), 'supersample': Prediction(expect='increase', counts=False, gate=None, reason="MEASURED under the lever before it was declared, on all six scenes, because this metric's whole-frame sibling has a scene-dependent sign and there was no reason to assume the masked one would not. Up on four: \`aa_probe\` +184.6%, \`single_character\` +179.3%, \`multi_shot\` +146.3%, \`graded_field\` +13.6%. Down on the two colour-rich scenes: \`saturated_outline\` -12.0%, \`promote_demo\` -7.6% — where 1x MSAA already emits many one-off blend values and an exact 2x resolve replaces them with fewer, more regular ones, so the picture gets better and the count goes down. \`increase\` is declared because the criterion is evaluated PER SCENE and met on four. NOT counted: family A spends its one witness on \`edge_transition_width\` and this is the same family — read the two together (aa_probe +184.6% colours with +7.4% width is gradation added; the same 3x3 blur that raises this metric 9.5x doubles the width) and the pair separates gradation from softening. It is evidence for a human, never a gate: an#41's criterion counts metrics independently and cannot express a conjunction.", reference='7.58 -> 21.58 on \`aa_probe\`; 422.25 -> 371.75 on \`saturated_outline\`')}, sentence='How many different colours sit ON the edges — the row above, restricted to the edge mask.', role=None, reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=("Its mask is NOT the \`masks.edge\` block the encode-side rows use. That one is ffmpeg's limited-range Y; this one is full-range BT.709 luma from the source RGB, so at the shared threshold of 40 it is the wider mask. The row records it separately as \`masks.render_edge\`, with its own operator.",), sweep=None), 'edge_transition_width': MetricSpec(key='edge_transition_width', family='A', unit='px', optimum=Optimum(kind='interior', expect=None, note='Two-sided: both lost AA and accidental softening (blur, non-integer canvas scale, LINEAR texel filtering) are failures. The absolute value is scene-dependent — a deliberately 3px black outline is legitimately non-flat — so compare deltas on a fixed scene, never absolutes across scenes.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='computed on the pre-encode PNG; the encoder cannot move it', reference=None), 'disabled_aa': Prediction(expect='decrease', counts=True, gate=None, reason="family A's single witness. Holds on five of six corpus scenes; on \`promote_demo\` it moves +0.0001 the OTHER way, because the descriptor path is nearly blind to MSAA (96 differing pixels of 12.4M — an SVG sprite is a pre-rasterised texture, and multisampling applies to WebGL geometry). A \`contrary\` verdict at that magnitude is the lever not reaching the scene, which is why the comparison reports the relative delta beside the direction (an#41).", reference='2.88 -> 2.00 on \`aa_probe\`; 5.6368 -> 5.6369 on \`promote_demo\`'), 'supersample': Prediction(expect='increase', counts=True, gate=None, reason="family A's witness for THIS lever, and scene-dependent by measurement in the exact inverse of \`disabled_aa\`. Holds on the five procedural scenes (\`graded_field\` +8.0%, \`aa_probe\` +7.4%, \`saturated_outline\` +5.2%, \`multi_shot\` +5.1%, \`single_character\` +2.6%) and is \`contrary\` on \`promote_demo\` at -34.8%. That inversion is REAL, not the +0.0001 nothing \`disabled_aa\` produces on the same scene: the SVG sprite rasterises AT 2x instead of being stretched up from a 1x texture, so the descriptor path is the one scene this lever reaches hardest and the AA lever cannot reach at all. The two render levers reach complementary scenes. \`increase\` is declared because the criterion is evaluated PER SCENE and met on at least one — the same shape \`video_stream_bytes\` already carries under \`disabled_aa\`. An increase here is not a regression: the optimum is interior, and this walks TOWARD a measured ceiling (2.5846 \`saturated_outline\`, 2.9167 \`graded_field\`, ~2.452 \`multi_shot\`, ~2.140 \`single_character\`, ~3.503 \`promote_demo\`). \`aa_probe\` has NO ceiling — its diagonals land the block-mean grid differently at every k, so it oscillates +/-5-8% with no settling — and gets no declared target, because a value nobody measured is not a value (research §3a).", reference='2.3685 -> 2.4921 on \`saturated_outline\`; 5.6368 -> 3.6775 on \`promote_demo\`')}, sentence='The average thickness, in pixels, of the fuzzy band between two flat colour areas — under 1 is a jagged staircase, ~1 is clean AA, 3+ means the picture has gone soft.', role=None, reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'encode_flicker_on_held_pixels': MetricSpec(key='encode_flicker_on_held_pixels', family='E', unit='fraction of held px moving >=2', optimum=Optimum(kind='one_sided', expect='minimize', note=''), predictions={'high_crf': Prediction(expect='increase', counts=True, gate=None, reason="family E's witness — and the least reliable of the four. It is NON-MONOTONE across the CRF ladder on the real corpus (0.000648 / 0.007018 / 0.000985 / 0.000916 / 0.001137 / 0.001685 over crf 18/23/28/33/40/51 on \`single_character\`, peaking at crf23), because at high CRF the whole frame flattens into large uniform skip regions and held pixels stop moving — the same mechanism the \`disabled_aa\` gate below documents. At the crf23 -> crf40 step the lever uses it holds on five of six scenes and inverts on \`single_character\`, so it is kept and not leaned on: C, D and F are monotone across the whole ladder and satisfy the criterion on all six scenes without it (an#41).", reference='0.0113 -> 0.0243 on aa_probe; 0.0070 -> 0.0011 on single_character'), 'disabled_aa': Prediction(expect=None, counts=False, gate='source_hash_differs', reason="excluded from EVERY renderer mutation's witness count: without the source gate, half-res-then-nearest-upscale — the most visible possible flat-art regression — reports a 7.1x IMPROVEMENT, because a flattened render gives x264 large uniform skip regions.", reference=None), 'supersample': Prediction(expect=None, counts=False, gate='source_hash_differs', reason="'excluded from EVERY renderer mutation's witness count' is what the declaration beside \`disabled_aa\` says, and this is the second renderer mutation it was written for. Worth restating because THIS lever is the exact shape of the failure that gate exists for: without it, half-res-then-nearest-upscale — the most visible possible flat-art regression — reports a 7.1x improvement, because a flattened render gives x264 large uniform skip regions. A block-mean resolve flattens the source in the same direction, so ungated this metric would reward the improvement for the identical wrong reason and nobody could tell the two apart.", reference=None)}, sentence='The fraction of pixels the animator held perfectly still that moved by at least 2 code values in the delivered video.', role=None, reference='lossless', provisional=False, unreviewed=False, tripwire=False, requires='', notes=("The panel's other hard-threshold counter, so its row carries the count at every tol of \`metrics.FLICKER_DELTA_TOL_SWEEP\` and \`an bench-compare\` reports a direction that grid disagrees with as \`unstable\` (an#140). Measured: under \`high_crf\` \`graded_field\` reads -9% at tol 1 and +29% at tol 2; under 4:2:0 -> 4:4:4 \`single_character\` reads +25% at tol 2 and -15% at tol 3.",), sweep=Sweep(grid=(('tol', (1, 2, 3, 4)),), shipped=(('tol', 2),))), 'encode_ringing_excess': MetricSpec(key='encode_ringing_excess', family='G', unit='code values', optimum=Optimum(kind='one_sided', expect='minimize', note=''), predictions={'high_crf': Prediction(expect='increase', counts=False, gate=None, reason='provisional; kept out of the witness count until open question 4 is settled', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='source_hash_differs', reason="declared 'both legs rise together by construction'; measured moving on ALL SIX corpus scenes under the real MSAA lever (an#41). The cancellation is exact only when both legs share a FIXED source, and a renderer mutation moves the source — so what is left is uninterpretable rather than zero.", reference=None), 'supersample': Prediction(expect=None, counts=False, gate='source_hash_differs', reason='the cancellation is exact only when both legs share a FIXED source; this lever moves it. Measured moving on all six scenes under \`disabled_aa\`, and nothing about the sign of the render change makes it hold still.', reference=None)}, sentence='How much more the encoder overshoots around outlines than a mathematically lossless encode of the same frames does.', role=None, reference='source_png', provisional=True, unreviewed=False, tripwire=False, requires='', notes=('Provisional pending a cheap comparison against plain edge-band MAE over the identical mask. \`edge_band_mae\` is recorded beside it so the first ledger row answers that question.',), sweep=None), 'expression_min_pairwise_changed_px': MetricSpec(key='expression_min_pairwise_changed_px', family='B', unit='pixels', optimum=Optimum(kind='guard', expect=None, note="Not a quality dial: larger is not better beyond 'the presets are apart'. It exists so a regression that makes two expressions render alike moves a ledger number instead of waiting for someone to look."), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='computed on the pre-encode PNGs; no encode change can reach it', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate="AA-off moves every edge on every pinned frame, so the count of differing pixels between two frames moves with it in an undeclared direction — measured on the lane: it MOVED under \`supersample\` when first declared \`not_applicable\`. Gated, not predicted: the delta is uninterpretable, not good or bad. Family B's witness is \`min_ssim_win8_vs_golden\`.", reason='', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='same as disabled_aa: an edge-quality lever softens every edge on every pinned frame and the pairwise count moves with it; not a face-solver lever, no declared sign', reason='', reference=None)}, sentence="The smallest number of pixels by which any two of the scene's pinned frames differ in TODAY'S render — on \`expressions\`, the closest pair of presets; a collapse of two emotions onto one face drives it to zero (an#98). On a two-frame scene it is that pair's own change, measured rather than withheld: a render-side row is never null on a real capture.", role='diagnostic', reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=('Measured at the first bless (an#98): 106 px between \`thinking\` and \`skeptical\`, the two asymmetric presets, and 384 px at the far end. \`tests/test_expression_goldens.py\` pins half the minimum on the COMMITTED goldens; this row reports the same quantity on the live render, so the ledger sees it before a re-bless does.',), sweep=None), 'file_bytes': MetricSpec(key='file_bytes', family='F', unit='bytes', optimum=Optimum(kind='guard', expect=None, note='Contaminated by the audio cache: the renderer always emits an AAC track, silent or not. Prefer video_stream_bytes.'), predictions={'high_crf': Prediction(expect='decrease', counts=False, gate=None, reason='', reference=None), 'disabled_aa': Prediction(expect='increase', counts=False, gate=None, reason='companion to \`video_stream_bytes\`, SCENE-DEPENDENT in the same way, and additionally contaminated by the audio track. Measured AA-on -> off across the corpus: +3.6% / -2.7% / +7.0% / -0.0% / +4.0% / -2.9%, so it is \`contrary\` on half of it. Counts nothing; kept only as the companion the sentence above calls it (an#41 review).', reference=None), 'supersample': Prediction(expect='decrease', counts=False, gate=None, reason='companion to \`video_stream_bytes\`, contaminated by the AAC track the renderer always emits, silent or not, and therefore scene-dependent in the same way and then some. MEASURED alongside it rather than assumed to follow: it does follow, on every scene and with the same three-three split — \`single_character\` -5.9%, \`multi_shot\` -4.8%, \`saturated_outline\` -2.4%; up and small on \`promote_demo\` +0.6%, \`aa_probe\` +0.5%, \`graded_field\` +0.4%. Counts nothing — prefer \`video_stream_bytes\`, as its own \`optimum\` note says.', reference=None)}, sentence='The whole mp4 on disk, audio track included.', role='companion', reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'flat_field_deviation': MetricSpec(key='flat_field_deviation', family='D', unit='fraction of flat px with |d|>6', optimum=Optimum(kind='one_sided', expect='minimize', note=''), predictions={'high_crf': Prediction(expect='increase', counts=True, gate=None, reason="family D's witness; monotone over a 133x span", reference='0.0003 / 0.0005 / 0.0035 / 0.0127 / 0.0399 (crf18->51)'), 'disabled_aa': Prediction(expect=None, counts=False, gate='source_hash_differs', reason="The research measured this flat across a SIMULATED AA matrix and called the orthogonality 'the metric's whole value'. Run against the real MSAA lever it moves on ALL SIX corpus scenes, in both directions (an#41). The mechanism is structural rather than surprising: the flat mask is derived from the SOURCE frames, which this lever changes, so the mask itself moves and the comparison has no fixed reference. That is the definition of gated — uninterpretable, not good or bad — and it is the same gate \`encode_flicker_on_held_pixels\` already carries for every renderer mutation, for the same reason.", reference=None), 'supersample': Prediction(expect=None, counts=False, gate='source_hash_differs', reason='the flat mask is derived from the SOURCE frames, which this lever changes, so the mask itself moves and the comparison has no fixed reference — structurally identical to \`disabled_aa\`, and the DIRECTION of the render change is irrelevant to it. Note the gate is \`source_hash_differs\` and NOT \`reference_moved\`: an#56 describes every C/D/E/G row as \`reference_moved\`, which is right for 5 of the 9 and wrong for this one, \`flat_field_p99_dev\`, \`encode_flicker_on_held_pixels\` and \`encode_ringing_excess\`. The two gates are recorded separately on purpose: one says the reference moved, this one says the MASK moved.', reference=None)}, sentence='Of the pixels the renderer painted inside a large flat colour field, what fraction came back more than 6 code values off.', role=None, reference='lossless', provisional=False, unreviewed=False, tripwire=False, requires='', notes=('Covers the ~90% of the frame no edge metric touches. Banding regressions are invisible without it.', 'A hard-threshold count over a mask eroded by a second free parameter, so its row carries the count at every (dilate_k, tol) of \`metrics.FLAT_DILATE_K_SWEEP\` x \`FLAT_DEV_TOL_SWEEP\`, and \`an bench-compare\` reports a direction the grid disagrees with as \`unstable\` — neither counted nor contrary (an#140). Measured under 4:2:0 -> 4:4:4: 3 of 6 scenes reverse on that grid (\`graded_field\` +84.2% at tol 6, -81.6% at tol 8), and so does \`graded_field\` under \`high_crf\` (tol 5). No scalar replacement was stable on the same grid — mean excess over tol, the threshold-free mean, p99 and p99.9 each reverse on at least one scene — because the two deviation distributions CROSS (16 of 18 scene x k cells): some deviations shrink and others grow, and any scalar then encodes a choice of weighting as a direction.'), sweep=Sweep(grid=(('dilate_k', (1, 3, 5)), ('tol', (4, 5, 6, 7, 8))), shipped=(('dilate_k', 3), ('tol', 6)))), 'flat_field_p99_dev': MetricSpec(key='flat_field_p99_dev', family='D', unit='code values', optimum=Optimum(kind='one_sided', expect='minimize', note=''), predictions={'high_crf': Prediction(expect='increase', counts=False, gate=None, reason='companion to the rate above', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='source_hash_differs', reason='gated for the same structural reason as the rate above: the flat mask moves with the source. Measured moving on one of six scenes and holding on five, which is what a metric with no fixed reference looks like — not evidence of orthogonality (an#41).', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='source_hash_differs', reason='gated for the same structural reason as the rate above: the flat mask moves with the source, under a render lever of either sign.', reference=None)}, sentence='The 99th percentile of the same deviation, in human units.', role='companion', reference='lossless', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'frame_distinct_colours': MetricSpec(key='frame_distinct_colours', family='A', unit='count', optimum=Optimum(kind='guard', expect=None, note='No predicted direction on AA changes. A guard, not a dial.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='pre-encode', reference=None), 'disabled_aa': Prediction(expect='decrease', counts=False, gate=None, reason='do not count it alongside off_palette_pixel_fraction; same family', reference=None), 'supersample': Prediction(expect='increase', counts=False, gate=None, reason="do not count it alongside \`edge_transition_width\`; same family. SCENE-DEPENDENT and measured (research §4): +197% \`single_character\`, +186% \`aa_probe\`, +184% \`multi_shot\`, +10% \`graded_field\` — and DOWN 18% on \`saturated_outline\` and 23% on \`promote_demo\`. On a scene that already carries a lot of colour, 1x MSAA emits many one-off blend values and an exact 2x resolve replaces them with fewer, more regular ones: the picture gets BETTER and the count goes DOWN. This is what refutes epic #9's 'edge distinct-colour count materially up on every corpus scene' — the statistic has a scene-dependent sign, which is not a magnitude problem and cannot be fixed by rendering harder. (The metric that done-when literally names, \`edge_distinct_colours\`, does not exist: refuted and deleted in Wave 2.) Read as a PAIR with \`edge_transition_width\` — colours up + width up slightly = gradation added; colours +3600% + width +45% = lanczos ringing; colours down + width down = sharpened. an#41's criterion counts metrics INDEPENDENTLY and cannot express that conjunction, so the pair is evidence for a human reader and is NOT a gate.", reference='7.6 -> 21.7 on \`aa_probe\`; 478.2 -> 392.3 on \`saturated_outline\`')}, sentence='How many different colours are in the frame at all.', role=None, reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'min_ssim_win8_vs_golden': MetricSpec(key='min_ssim_win8_vs_golden', family='B', unit='ssim', optimum=Optimum(kind='one_sided', expect='maximize', note='SIGN AMBIGUITY, recorded deliberately: a supersampling IMPROVEMENT moves this away from 1.0 exactly as an AA regression does, and in changed-pixel terms reports the improvement as the LARGER change. It is a change detector, and must be paired with the no-reference family to say whether a change was good.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='the golden corpus is UPSTREAM of the encoder; no encode change can reach it', reference=None), 'disabled_aa': Prediction(expect='decrease', counts=True, gate=None, reason="family B's single witness. \`golden_identity\` is the tripwire beside it and counts ZERO — one family, at most one witness, and a boolean change detector is not it.", reference='0.9999 -> 0.279 at 1080p / 0.063 at native for a total eye-blink'), 'supersample': Prediction(expect='decrease', counts=True, gate=None, reason="family B's single witness, and THIS lever is what the SIGN AMBIGUITY note above was written about: a supersampling IMPROVEMENT moves this away from 1.0 exactly as an AA regression does, and reports the improvement as the LARGER change. It counts as evidence the render CHANGED, which is what family B measures; it is NOT evidence the change was good, and the note beside \`optimum\` is the standing disclaimer that must be read with it. Fires on all six scenes: the committed baseline is 1.0 on every one, and research §2/§4 measured a real pixel move on every one — including \`promote_demo\`, which \`disabled_aa\` cannot reach at all. The magnitude is the lever's own, from the exam run recorded in the an#56 PR body — not a figure lifted from a research table, which is the an#41-review defect this panel already caught once.", reference="1.0 -> 0.4380 on \`single_character\`, 0.4449 on \`promote_demo\`, 0.6144 on \`saturated_outline\`, 0.7756 on \`aa_probe\`, 0.7969 on \`multi_shot\`, 0.8201 on \`graded_field\` — every scene, because every scene's pixels move")}, sentence='The worst small window in the frame, scored against the committed golden — magnitude AND location of a golden failure.', role='diagnostic', reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=('The metrics survey concluded SSIM should be excluded because whole-frame SSIM scores a total eye-blink at 0.9989. That was REFUTED: only the global-moment reduction is blind. Killing SSIM outright would have discarded the best numpy-only detector available.',), sweep=None), 'off_palette_pixel_fraction': MetricSpec(key='off_palette_pixel_fraction', family='A', unit='fraction', optimum=Optimum(kind='one_sided', expect='minimize', note='Honest caveat: a blur, drop shadow, gradient or sub-pixel offset moves this UP, indistinguishably from better AA. It is a change detector on that axis. Its floor is scene-dependent and is NOT zero on the SVG-sprite path.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason="pre-encode. NOT MEASURED — which is not the same as 'no change'", reference=None), 'disabled_aa': Prediction(expect='decrease', counts=False, gate=None, reason='family A already supplies edge_transition_width as its witness', reference=None), 'supersample': Prediction(expect='increase', counts=False, gate=None, reason="family A already supplies \`edge_transition_width\` as its witness — count at most one per family. \`increase\` and NOT \`not_applicable\`: this is a render lever and the metric is render-side, so \`not_applicable\` would make every scene report \`unexpected_movement\` for a metric doing exactly what it should. An exact block-mean resolve replaces hard edge pixels with blends, and a blend is off-palette by definition. MEASURED on the corpus and scene-dependent, like everything else this lever touches: \`single_character\` +28.9%, \`multi_shot\` +24.2%, \`aa_probe\` +21.8%, \`graded_field\` +0.0%; contrary on the two scenes whose k=1 frames are already the most off-palette, \`promote_demo\` -22.8% and \`saturated_outline\` -9.9%, where an exact resolve REPLACES many one-off MSAA blends with fewer, more regular ones. It counts nothing either way. And the optimum says \`minimize\` while this improvement moves it UP, which is the metric's own caveat stated in its \`note\`: on this axis it is a change detector, not a quality dial.", reference=None)}, sentence='The fraction of the frame whose pixels are not exactly one of the colours the compiler declared for this shot.', role=None, reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'ring_band_mae': MetricSpec(key='ring_band_mae', family='G', unit='code values', optimum=Optimum(kind='one_sided', expect='minimize', note="Research §1.8 calls this 'plain edge-band MAE over the identical mask'. Named for the mask it actually uses, because MAE over the EDGE mask is \`coded_luma_edge_error\`'s definition verbatim — measured identical on the first real row — and recording it twice would answer open question 4 with a tautology."), predictions={'high_crf': Prediction(expect='increase', counts=False, gate=None, reason='the comparison arm', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='reference_moved', reason='', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='reference_moved', reason='', reference=None)}, sentence='Plain mean absolute luma error over the RING band — the simpler rival to \`encode_ringing_excess\`, on the same mask and with no second encode.', role='q4_comparator', reference='source_png', provisional=False, unreviewed=False, tripwire=False, requires='', notes=(), sweep=None), 'stage_min_plane_ratio_gap': MetricSpec(key='stage_min_plane_ratio_gap', family='B', unit='ratio', optimum=Optimum(kind='guard', expect=None, note='Not a quality dial: a larger gap is not a better picture, it is a fixture whose depths are further apart. It exists so a regression that flattens the parallax moves a ledger number instead of waiting for someone to look at a GIF.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='computed on the pre-encode PNGs; no encode change can reach it', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate="AA-off changes which pixels carry a plane's exact colour along its edges, so a centroid can shift by a fraction of a pixel and the mask COUNT can change — which the measurement refuses outright as a clipped plane. Gated, not predicted: the outcome is 'the instrument declines', which is neither better nor worse.", reason='', reference=None), 'supersample': Prediction(expect=None, counts=False, gate="same as disabled_aa: an edge-quality lever moves the exact-colour mask's boundary, and this measurement is defined on exact colours", reason='', reference=None)}, sentence="The smallest gap between any two planes' displacement RATIOS on a panning multiplane stage (an#111). Each plane's centroid displacement is divided by the reference plane's, so a stage that parallaxes gives the declared depths back — on \`stage_pan\`, 0.25 / 1.0 / 2.0 — and a stage that flattened gives every plane 1.0 and this row zero. \`unavailable\`, never zero, for a scene with fewer than two colour-filled planes: a scene with nothing to compare has no ratio, and reporting that as flattened would fire on every other fixture.", role='diagnostic', reference='none', provisional=False, unreviewed=False, tripwire=False, requires='a multiplane stage: two or more colour-filled planes', notes=("The trap this metric is shaped around: today's centre-anchored zoom ALREADY gives unequal per-plane displacements, so 'the planes moved at different rates' is satisfied by a scene with no parallax at all. The JSON half of the measurement probes at scene-space x = 0, where the zoom term cancels exactly; the pixel half cannot (a centroid sits at the plane's own offset), so the \`stage_pan\` fixture holds zoom CONSTANT instead.", 'Ratios are taken against the LARGEST mover, always. The pixel half cannot see a \`depth\`, so a depth-aware reference makes the two halves report different numbers for one stage — measured while this landed: 0.75 against the \`depth == 1\` plane and 0.375 against the largest mover, for the same measurement.', "Measured at the first bless: 0.375, the far/mid gap on depths 0.25 / 1.0 / 2.0 (reported as ratios 0.125 / 0.5 / 1.0). The \`stage_planes_parallaxed\` tripwire's floor is half of it, which is the \`expression_min_pairwise_changed_px\` precedent followed literally."), sweep=None), 'stage_planes_parallaxed': MetricSpec(key='stage_planes_parallaxed', family='B', unit='boolean', optimum=Optimum(kind='guard', expect=None, note='A change detector. Counts zero toward any criterion.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='computed on the pre-encode PNGs', reference=None), 'disabled_aa': Prediction(expect=None, counts=False, gate='see stage_min_plane_ratio_gap', reason='', reference=None), 'supersample': Prediction(expect=None, counts=False, gate='see stage_min_plane_ratio_gap', reason='', reference=None)}, sentence='True when the planes moved at DIFFERENT rates — i.e. the stage parallaxed rather than panning as one rigid image. The same measurement as \`stage_min_plane_ratio_gap\`, read as a verdict: a boolean and the number beside it must be the same evidence, or a reader has to reconcile them.', role='tripwire', reference='none', provisional=False, unreviewed=False, tripwire=False, requires='a multiplane stage: two or more colour-filled planes', notes=("There is deliberately NO \`flat_camera\` mutation lever to prove this fires. A compile-time parallax change moves the scene's contract hash, so \`bench-compare\` refuses the row at comparability before any family is examined — the recorded \`step_hz\` verdict, verbatim. The proof belongs in \`an bench-mutants\` as a declared guard mutant.",), sweep=None), 'video_stream_bytes': MetricSpec(key='video_stream_bytes', family='F', unit='bytes', optimum=Optimum(kind='guard', expect=None, note='Not a quality dial in either direction — a cross-check that the metrics read the file they think they do.'), predictions={'high_crf': Prediction(expect='decrease', counts=True, gate=None, reason='free fourth cross-check', reference='x1.18 to x1.77 at crf23 -> crf40; x2.07 across the whole ladder'), 'disabled_aa': Prediction(expect='increase', counts=True, gate=None, reason="hard edges cost more to code. THE WEAKEST of this mutation's three witnesses, the only unreviewed metric in the set — and SCENE-DEPENDENT, measured. It holds where the lever has non-axis-aligned edges to change (aa_probe +6.6%, multi_shot +9.7%, saturated_outline +6.9%) and INVERTS where it does not (single_character -6.1%, graded_field -5.7%, promote_demo -0.1%), because AA-off on axis-aligned art removes intermediate colours and the picture gets CHEAPER instead of harder. So this mutation's criterion is met per scene, on the scenes the lever can reach — which is the measured reason \`aa_probe\` is in the corpus at all (an#38, an#41).", reference='+6.6% / -6.1%, scene-dependent'), 'supersample': Prediction(expect='decrease', counts=True, gate=None, reason="family F's witness, and the ONLY third family available to a render lever: A and B can count, C/D/E/G are all gated because their masks and references derive from the source frames, and F is the one encode-side family whose reference is \`none\` — a property of the encoded file rather than a comparison against a moving source. So an#41's three-family criterion for this lever is A + B + F, forced, with no substitute. MEASURED before it was declared, because two mechanisms fight here and guessing was not available: a block-mean resolve ADDS distinct values at edges (+184-197% on the three colour-poor scenes) and it LOWERS edge frequency, which is cheaper for the DCT. The second wins where there is geometry to smooth. Scene-dependent, the same shape this row already carries under \`disabled_aa\` — and \`decrease\` is declared because that is the sign that holds on the scenes where family A also holds, and because it is the side carrying the magnitude: the three down-moves are -4.0% to -12.2% and the three up-moves are +0.8% to +2.8%.", reference='single_character -12.2%, multi_shot -6.6%, saturated_outline -4.0%; contrary and small on graded_field +2.8%, promote_demo +1.1%, aa_probe +0.8%')}, sentence='How large the encoded video stream is, with the audio track excluded.', role=None, reference='none', provisional=False, unreviewed=True, tripwire=False, requires='', notes=('The one metric in the panel that went through NO adversarial pass.',), sweep=None)}* The panel. Order is display order; the ledger sorts keys anyway. ### an.bench.registry.MUTATIONS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('high_crf', 'disabled_aa', 'supersample')* an encoder lever cannot touch a golden-frame metric because the corpus is UPSTREAM of the encoder, so requiring “>=3 metrics” from a CRF change alone would fail because of where the corpus sits, not because the instrument is blind — and that failure would be misdiagnosed as the harness being wrong. `supersample` is the third and it is the odd one out on purpose: the other two make the picture worse and it makes the picture BETTER. A panel that has only ever been shown degradations cannot tell an improvement from a regression — run as a plain commit-to-commit diff this change reports 2 false regressions and 7 unearned improvements (an#56). Declaring it is how that gets found before it is believed. * **Type:** The levers an#41 and an#56 use. At least one per SIDE is mandatory ### *class* an.bench.registry.MetricSpec(key, family, unit, optimum, predictions, sentence, role=None, reference='none', provisional=False, unreviewed=False, tripwire=False, requires='', notes=, sweep=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One row of the panel. #### requires *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* What a scene must HAVE for this row to exist at all, or `""` when the row applies to every scene (an#111). The render-side panel rule is “nothing may be null on a real capture, because a null render-side row is a blind panel”. That rule assumes every metric could have been measured. `stage_min_plane_ratio_gap` could not: a displacement ratio needs two planes moving at different depths, and `single_character` has no planes at all — so its null is structural, not a gap in the instrument. Declared rather than hardcoded in the test, so the panel rule keeps naming its own exceptions instead of a test file carrying a list the registry does not know about. #### sweep *: [Sweep](_autosummary/an.bench.registry.html.md#an.bench.registry.Sweep) | [None](https://docs.python.org/3/builtins/constants.html#None)* Set only on a hard-threshold counter (an#140); see [`Sweep`](_autosummary/an.bench.registry.html.md#an.bench.registry.Sweep). ### *class* an.bench.registry.Optimum(kind, expect=None, note='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Which way “better” points, and whether the optimum is interior. ### *class* an.bench.registry.Prediction(expect, counts=False, gate=None, reason='', reference=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What one metric is expected to do under one mutation, declared in advance. `expect=None` means **gated**: the number is uninterpretable rather than good or bad, and `gate` says why. It is not “no change”. ### an.bench.registry.REFERENCE_NOTE *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'lossless': 'the decode of a -qp 0 encode — the plane libx264 received', 'none': 'a property of the encoded file, not a comparison', 'source_png': 'an explicit RGB->YUV conversion of the pre-encode PNGs'}* What an encode-side metric is measured AGAINST. Two answers, and the choice is per metric rather than global: - `lossless` — the decode of a `-qp 0` encode of the same frames. That IS the plane libx264 received, on any build, so the metric is pure quantiser damage with no colour-conversion term. The default, and what every counting encode-side metric uses. - `source_png` — an explicit RGB->YUV conversion of the pre-encode PNGs. Required by exactly two things. The chroma metric’s subject IS the 4:2:0 subsampling that happens during that conversion – the term the lossless leg cancels, so a lossless-referenced version is blind to it (it does NOT read ~0; measured, it reads 1.7-2.5 against this metric’s 2.9-9.3, because it measures chroma quantiser damage instead – an#72). And `encode_ringing_excess` cancels a term that only exists when BOTH its legs share this reference — against the lossless leg it degenerates to raw overshoot, which is the refuted form. The distinction became visible when CI measured the PNG conversion to be build-dependent (exact on ffmpeg 8.1, mean 0.63 / max 5 on the Linux runner’s older build). It is recorded per metric so a reader can tell which numbers carry that term. ### an.bench.registry.REFUSED_LEVERS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'flat_camera': 'a compile-time change to the plane-compensation channels, refused at comparability for the same reason as \`step_hz\`; the parallax claim is carried render-side by \`stage_min_plane_ratio_gap\` (an#111).', 'pix_fmt': "4:2:0 -> 4:4:4 at fixed CRF fails its own exam on the machine it was designed on, not only on Linux (an#72). Re-measured 2026-09-30 on macOS/arm64, ffmpeg 9.0.1, lossless leg tracking the delivered format (an#138) and with an#140's robustness gate: the three-family criterion is met on 1 of 10 scenes (\`dialogue\`); the pre-an#138 'four scenes' was taken against a contaminated reference. Three reasons, each measured: (1) the lever is not one variable — at fixed CRF 4:4:4 encodes at a coarser quantiser (I-frame Avg QP +2.9 to +9.5) and spends fewer bits, so every encode-side direction is the sum of two opposed effects; (2) family D cannot carry it — the flat-field deviation distributions CROSS (16 of 18 scene x dilate cells on the six lever scenes), so its direction is \`unstable\` over its own tol/dilate grid on 5 of 10 scenes; (3) family E's held mask is derived from the lossless leg, which moves with the format (0.02-2.65% of held pixels), so E has no fixed mask under this lever. The one witness whose subject IS chroma, \`chroma_edge_dCr\`, references \`source_png\` and may not count. The knob ships (\`an render --pix-fmt\`); a QUANTISER-matched lever is the route the evidence leaves open.", 'step_hz': 'moves \`scene_contract_sha256\` on every scene with a tween, so \`bench-compare\` refuses the row before any family is examined; the instrument is per-frame and stepping is a temporal choice (an#89).'}* Levers that were TRIED and refused, each with the measured reason — data, so `an bench --mutation ` answers with the reason instead of “unknown”, and the next person meets the measurement before re-registering one. Never pulled, never predicted for; disjoint from `MUTATIONS` by test. ### *exception* an.bench.registry.RegistryError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A metric declaration violates one of the table’s invariants. ### *class* an.bench.registry.Sweep(grid, shipped) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The grid of a threshold counter’s OWN free parameters its verdict is checked on. Declared rather than merely written by `run.py`, so a row says a metric SHOULD carry a sweep: a sweep deleted from a row is then refused by `an bench-compare` instead of silently reading as “never had one” (an#140). `shipped` names the cell that IS the metric’s value. ### an.bench.registry.TRIPWIRES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [MetricSpec](_autosummary/an.bench.registry.html.md#an.bench.registry.MetricSpec)]* *= {'golden_identity': MetricSpec(key='golden_identity', family='B', unit='boolean', optimum=Optimum(kind='guard', expect=None, note='Full-frame, never edge-masked.'), predictions={'high_crf': Prediction(expect='not_applicable', counts=False, gate=None, reason='the corpus is UPSTREAM of the encoder; no encode change can reach it', reference=None), 'disabled_aa': Prediction(expect='decrease', counts=False, gate=None, reason='it FAILS — a change detector firing, not a quality measurement, which is why it counts ZERO. Spelled \`decrease\` (True -> False) rather than \`no_change\`: the prediction was \`no_change\` while this very sentence said it fails, so the row reported \`unexpected_movement\` on every scene for a tripwire doing exactly its job. Found by \`an bench-compare\` (an#41).', reference=None), 'supersample': Prediction(expect='decrease', counts=False, gate=None, reason='it FAILS — \`True -> False\` — on all six scenes, because a block-mean resolve changes pixels on all six and the committed baseline is \`True\` on all six. A change detector firing, not a quality measurement, which is why it counts ZERO — and under THIS lever that distinction is the whole point: the tripwire fires identically for an improvement and for a regression, so it can never be the evidence that a supersample was worth shipping. Spelled \`decrease\` rather than \`no_change\` for the reason recorded beside \`disabled_aa\`.', reference=None)}, sentence="Today's frame is pixel-for-pixel the committed golden frame.", role=None, reference='none', provisional=False, unreviewed=False, tripwire=True, requires='', notes=('Compare sha256 of DECODED pixels, never file bytes: Chromium 1187 -> 1223 changes 144/144 PNG files and zero pixels.',), sweep=None)}* Tripwires. A separate block from `METRICS` because they count ZERO toward any criterion — they fire on improvements and regressions alike. ### *class* an.bench.registry.Touch(path, differs_only_in=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One environment key a lever is expected to change, and HOW. `differs_only_in` names the argv flags whose values the lever may move. Without it the exemption is by PATH, and `x264_argv` is the whole encode command — so a `-preset medium` -> `-preset veryslow` change, which moves every encode-side number, rode in on the CRF lever’s exemption and was reported as “the lever moved it — expected” (an#41 review). `None` means any difference is the lever’s, which is right for an opaque digest. #### is_the_levers_change(before, after) True when the observed difference is the one this lever makes. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) # _autosummary/an.bench.run.html.md # an.bench.run `run_bench`: render the corpus, compute the panel, write one ledger row. \*\*Every encode-side metric is measured against a lossless (`-qp 0`) encode of the same frames, not against a second conversion of the PNGs.\*\* That is a correction, and CI is what made it: the PNG conversion agrees with the encoder’s own exactly on ffmpeg 8.1 and disagrees by mean 0.63 / max 5 on the Linux runner’s older build — 42% of `coded_luma_edge_error`’s whole crf23 value, which would have been measured as encoder damage on that machine and as nothing on this one. `-qp 0` is lossless, so its decoded luma **is** the plane libx264 received, on any build. Referencing to it removes the assumption rather than widening it. See [`an.bench.imageio`](_autosummary/an.bench.imageio.html.md#module-an.bench.imageio). The PNG conversion is still performed and its distance from the encoder’s input is recorded as `png_to_encoder_input_luma` — that number is the build dependence, and it belongs in provenance rather than inside a gate. ### Module Attributes | [`GOLDEN_METRIC_KEY`](_autosummary/an.bench.run.html.md#an.bench.run.GOLDEN_METRIC_KEY) | Family B's two rows, one in each block. | |---------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`MIN_PINNED_FRAMES_FOR_PAIRWISE`](_autosummary/an.bench.run.html.md#an.bench.run.MIN_PINNED_FRAMES_FOR_PAIRWISE) | A pairwise minimum needs two frames; every fixture pins at least two, so on a real capture this row is always measured (the render-side panel may not be null — `tests/test_bench_capture.py`). | | [`STAGE_METRIC_KEY`](_autosummary/an.bench.run.html.md#an.bench.run.STAGE_METRIC_KEY) | The pan measurement (an#111). | | [`STAGE_MIN_RATIO_GAP`](_autosummary/an.bench.run.html.md#an.bench.run.STAGE_MIN_RATIO_GAP) | The floor the tripwire fires below, set at HALF the first bless's measured minimum — the `expression_min_pairwise_changed_px` precedent followed literally. | | [`JUST_BLESSED_DETAIL`](_autosummary/an.bench.run.html.md#an.bench.run.JUST_BLESSED_DETAIL) | Said when a run blessed the goldens it would otherwise have compared against. | ### Functions | [`conversion_distance`](_autosummary/an.bench.run.html.md#an.bench.run.conversion_distance)(frames_dir, ...) | How far this build's PNG->YUV conversion sits from the encoder's own. | |----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`format_panel`](_autosummary/an.bench.run.html.md#an.bench.run.format_panel)(ledger) | A human-readable digest of a row — the thing `an bench` prints. | | [`lossless_reference`](_autosummary/an.bench.run.html.md#an.bench.run.lossless_reference)(frames_dir, fps, out, \*, ...) | Encode the frames losslessly and return the decode — the encoder's input. | | [`naming_git_state`](_autosummary/an.bench.run.html.md#an.bench.run.naming_git_state)(git, \*, blessed, root) | Which git state NAMES the row: the tree the run **left**, not the one it read. | | [`pinned_frames_min_pairwise_changed_px`](_autosummary/an.bench.run.html.md#an.bench.run.pinned_frames_min_pairwise_changed_px)(...) | `expression_min_pairwise_changed_px` for one scene: decode the pinned frames from today's render and take the minimum over every pair of the count of pixels that differ (an#98). | | [`run_bench`](_autosummary/an.bench.run.html.md#an.bench.run.run_bench)(\*[, scenes, out, keep_render, ...]) | Render the corpus, compute the panel, and (by default) write the row. | | [`shot_policy_provenance`](_autosummary/an.bench.run.html.md#an.bench.run.shot_policy_provenance)(shots) | The per-shot COMPILE POLICIES a scene rendered under, keyed by shot id. | | [`viseme_keyframes_per_second`](_autosummary/an.bench.run.html.md#an.bench.run.viseme_keyframes_per_second)(scene_json) | Viseme keyframes per second of dialogue in a compiled shot, or `None` when nothing speaks (an#97). | ### Exceptions | [`BenchError`](_autosummary/an.bench.run.html.md#an.bench.run.BenchError) | The bench could not produce a row it would be honest to file. | |---------------------------------------------------------------|-----------------------------------------------------------------| ### *exception* an.bench.run.BenchError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The bench could not produce a row it would be honest to file. ### an.bench.run.GOLDEN_METRIC_KEY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'min_ssim_win8_vs_golden'* Family B’s two rows, one in each block. Named here because the golden result fills both from one comparison, and a reader has to be able to see that the boolean and the number are the same evidence read two ways. ### an.bench.run.JUST_BLESSED_DETAIL *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'this run WROTE these goldens, so comparing against them is a tautology: the identity holds by construction and no code could have failed it. Run \`an bench\` again, without --bless, for a comparison that can fail.'* Said when a run blessed the goldens it would otherwise have compared against. ### an.bench.run.MIN_PINNED_FRAMES_FOR_PAIRWISE *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* A pairwise minimum needs two frames; every fixture pins at least two, so on a real capture this row is always measured (the render-side panel may not be null — `tests/test_bench_capture.py`). ### an.bench.run.STAGE_METRIC_KEY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'stage_min_plane_ratio_gap'* The pan measurement (an#111). Metric and tripwire come from ONE measurement, as the golden pair does: the boolean and the number must be the same evidence read two ways, or a reader has to reconcile them. ### an.bench.run.STAGE_MIN_RATIO_GAP *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.1875* The floor the tripwire fires below, set at HALF the first bless’s measured minimum — the `expression_min_pairwise_changed_px` precedent followed literally. Measured on `stage_pan` at the first bless: **0.375**. Ratios are taken against the largest mover, so depths 0.25 / 1.0 / 2.0 report as 0.125 / 0.5 / 1.0 and the closest pair is far/mid. (An earlier draft of this comment said 0.75, which is the same measurement taken against the `depth == 1` plane — a reference the pixel half cannot see, which is why `_reference` is now always the largest mover.) ### an.bench.run.conversion_distance(frames_dir, lossless_mp4, , height, width, frames) How far this build’s PNG->YUV conversion sits from the encoder’s own. Recorded, never gated. It was a gate — a hard equality — and it failed on the Linux runner while passing here, which is precisely the shape of a machine-dependent fact masquerading as a universal one. Now the metrics no longer depend on it, and the number is kept because it is the thing that will explain a future cross-build surprise. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.run.format_panel(ledger) A human-readable digest of a row — the thing `an bench` prints. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.bench.run.lossless_reference(frames_dir, fps, out, , delivered) Encode the frames losslessly and return the decode — the encoder’s input. Returned as a path rather than an array so the caller controls its lifetime; every encode-side reference comes from here. `delivered` is the delivered mp4 this leg is the reference FOR, and passing it is what makes the leg’s pixel format match — \*\*probed off the file rather than re-derived\*\* (an#72). Re-deriving is not enough: the delivered encode resolves its format from `RenderContext.pix_fmt` *or* from `render.DEFAULT_PIX_FMT`, so a leg that consults the global tracks the bench’s lever and silently misses `an render --pix-fmt yuv444p`, which sets the context instead. Only the file knows which seam won. `delivered` is keyword-only and has **no default**, deliberately — the same argument `imageio._reshape` makes for its own `frames`: a default here would let a caller opt out of the match by omission, and the failure is invisible (a 4:2:0 reference silently measuring a 4:4:4 delivery). Passing `None` explicitly means “no delivered file to match” and falls back to the module default; that is right for a caller building a reference for its own sake and wrong for the bench, which always has the file in hand. ### an.bench.run.naming_git_state(git, , blessed, root) Which git state NAMES the row: the tree the run **left**, not the one it read. [`run_bench()`](_autosummary/an.bench.run.html.md#an.bench.run.run_bench) reads `git_state` once, *before* the corpus loop, because that is the tree the pixels came from. A `--bless` run then WRITES into that same tree inside the loop — the golden PNGs, and a bless record whose `blessed_at` moves on every run — so by the time the row is named the two are no longer one fact. Named under the pre-bless state, a bless on a clean tree lands as `-.json`: a filename claiming a commit whose tree that very run then modified, which is exactly what the `-dirty` suffix exists to prevent ([`an.bench.paths.ledger_path()`](_autosummary/an.bench.paths.html.md#an.bench.paths.ledger_path)). So the row records both — `git` is what rendered, `git_after_bless` is what the run left behind — and the *filename* follows the second. A non-bless run re-reads nothing. Deliberately a plain function of `blessed` rather than an inline conditional: it is the whole of the fix, and a guard for it must not have to render the corpus to reach it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.run.pinned_frames_min_pairwise_changed_px(capture, times) `expression_min_pairwise_changed_px` for one scene: decode the pinned frames from today’s render and take the minimum over every pair of the count of pixels that differ (an#98). On a two-frame scene that is the pair’s own change; `unavailable`, never zero, only when a scene pins a single frame, which the fixture rule forbids. * **Return type:** [`Value`](_autosummary/an.bench.ledger.html.md#an.bench.ledger.Value) ### an.bench.run.run_bench(, scenes=None, out=None, keep_render=None, write=True, bless='', golden_root=None, lossless_scratch_root=None, root=None) Render the corpus, compute the panel, and (by default) write the row. `bless` is the **reason** a re-bless is being made, and passing it is what turns the run into a bless. One argument rather than a `--bless` flag plus a `--reason` string, so “blessed with no recorded reason” — the failure this rule exists to prevent — is not expressible. `lossless_scratch_root` is forwarded to `_lossless_scratch_dir()` for every scene (an#143) — a caller may point it at a shared parent to prove that two concurrent lossless-leg encodes still get distinct scratch directories under it; production code has no reason to pass it. `golden_root` redirects where goldens are read and written, and it exists because without it a test of the bless path has no choice but to overwrite the committed corpus. That is not hypothetical: the first version of an#38’s bless test did exactly that, replacing a real bless record’s reason with the test’s own. `root` is the source checkout whose corpus `scenes` names (default: `an`’s own); a genre package runs its own corpus with its own checkout (`cutan.bench`). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict) ### an.bench.run.shot_policy_provenance(shots) The per-shot COMPILE POLICIES a scene rendered under, keyed by shot id. Additive scene-provenance facts read off each staged `scene_json`’s `meta`; `shots` is any iterable of objects with `shot_id` and `scene_json` (a [`ShotCapture`](_autosummary/an.bench.capture.html.md#an.bench.capture.ShotCapture), or a stand-in). - `blink_phases` (an#88): the per-entity blink phase each shot was compiled with. A renamed corpus character re-phases every blink and moves every pixel metric; this makes that a visible diff in the row instead of an unexplained shift. - `step_hz` (an#89): the stepped-timing policy each shot’s tweens were compiled under; `None` = smooth (the meta key is absent then, by the serializer). Stepping moves `scene_contract_sha256` by construction — the resampled keyframes ARE the contract — and this says the movement was a timing policy, not a mystery. ```pycon >>> from types import SimpleNamespace as NS >>> shot_policy_provenance([NS(shot_id="s1", scene_json={"meta": {"step_hz": 12.0, "blink_phases": {"a": 0.5}}}), ... NS(shot_id="s2", scene_json={"meta": {}})]) {'blink_phases': {'s1': {'a': 0.5}, 's2': {}}, 'step_hz': {'s1': 12.0, 's2': None}, 'viseme_keyframes_per_second': {'s1': None, 's2': None}} ``` * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.bench.run.viseme_keyframes_per_second(scene_json) Viseme keyframes per second of dialogue in a compiled shot, or `None` when nothing speaks (an#97). Counted over the `__viseme__` clips: keyframes minus one per channel (the trailing rest is an invariant, not a decision — today’s emission has one channel per clip), over the clips’ summed durations, which are the frame-ceiled windows rather than the lines’ exact lengths (a small downward bias, the same for every row). Keyframes, not distinct shapes — a repeated code (the carried rest before the terminal one) counts. The co-articulation passes bring this below the RAW provider track’s rate; against the old drop-not-hold condenser it can rise, because that loop was cheaper only by dropping shapes. Recorded as provenance rather than a panel metric because no lever in the registry moves it. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> viseme_keyframes_per_second({"animations": {}}) >>> viseme_keyframes_per_second({"animations": {"__viseme__s_0_m": {"duration": 2.0, ... "channels": [{"keyframes": [{"time": 0}, {"time": 0.5}, {"time": 1.0}, {"time": 2.0}]}]}}}) 1.5 ``` # _autosummary/an.bench.stage.html.md # an.bench.stage Measuring a pan: does the stage move as planes, or as one rigid image? **The trap the epic’s own sentence sets.** “The planes moved at different rates” is satisfied by a scene with *no parallax whatsoever*, because a centre-anchored zoom already produces unequal per-plane displacements. The honest null hypothesis is **“the camera moved the whole stage as one rigid image”**, and a zoom has to be excluded rather than assumed away. **The quantity.** Probe each plane at scene-space `x = 0` — the canvas centre column. There the zoom term vanishes *exactly*: > Δ_i = s₁ · p_i · D₁ ratio_ij = Δ_i / Δ_j = p_i / p_j (any zoom) Under a rigid pan every ratio is exactly 1, so the measurement can tell a parallaxing stage from a zooming one. Two additions the epic does not require: - assert `Δy ≈ 0`, so a pan is distinguishable from a zoom — but only for a ZOOM-FREE pan: §4 endorses zoom composing through the pivot, and a pan+zoom shot measures a non-zero Δy by design; - assert the ORDERING `p_far < p_mid < p_near`, because wrong-order parallax is a real bug that a bare inequality passes. It is a \*\*bonus, not a second gate\*\*: the zoom false positive satisfies the ordering too. Only the x = 0 probe excludes a zoom. Two measurements, deliberately different instruments: **(a) JSON** — free, on every PR, from the compiled document through [`an.stage.timeline.screen_position()`](_autosummary/an.stage.timeline.html.md#an.stage.timeline.screen_position). Composed screen space, not local channel values: a rigid pan on `root` leaves every plane’s local `Δx` at zero. **(b) Pixels** — on a labelled PR, per-plane centroids over exact-colour masks. The `x = 0` cancellation does **not** reach (b): a centroid sits at the plane’s own offset, not at `x = 0`, so the fixture holds zoom constant. And each mask’s pixel COUNT is asserted unchanged between frames, because a plane panning partly off-canvas biases its centroid — measured, that read a `depth = 2` plane as 1.975. ### Functions | [`measure_pan_json`](_autosummary/an.bench.stage.html.md#an.bench.stage.measure_pan_json)(scene, plane_paths, times, \*) | Measurement (a): composed screen displacement, probed at `x = 0`. | |----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | [`plane_centroids`](_autosummary/an.bench.stage.html.md#an.bench.stage.plane_centroids)(frame, colours) | `{plane: (cx, cy, pixel count)}` for exact-colour masks. | | [`measure_pan_pixels`](_autosummary/an.bench.stage.html.md#an.bench.stage.measure_pan_pixels)(frames, colours, \*[, depths]) | Measurement (b): per-plane centroid displacement between two frames. | | [`min_ratio_gap`](_autosummary/an.bench.stage.html.md#an.bench.stage.min_ratio_gap)(ratios) | The smallest gap between any two planes' ratios. | ### Classes | [`PlaneTrack`](_autosummary/an.bench.stage.html.md#an.bench.stage.PlaneTrack)(name, dx, dy[, depth]) | One plane's displacement between the two probed times. | |--------------------------------------------------------------------------------------|----------------------------------------------------------| | [`PanMeasurement`](_autosummary/an.bench.stage.html.md#an.bench.stage.PanMeasurement)(tracks, reference) | What a pan did, plane by plane. | ### Exceptions | [`RotatingCamera`](_autosummary/an.bench.stage.html.md#an.bench.stage.RotatingCamera) | The camera rolls, so a per-axis ratio is not a depth ratio. | |-------------------------------------------------------------------|---------------------------------------------------------------| ### *class* an.bench.stage.PanMeasurement(tracks, reference) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a pan did, plane by plane. #### *property* is_rigid *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* True when every plane moved by the same amount — the null hypothesis, and what a stage with no parallax looks like. Computed from the DISPLACEMENTS, not from the ratios, because a stage that did not move at all has no ratios (the reference is zero, so every ratio is NaN) and is nonetheless as rigid as a stage can be. Reading it off the ratios made a pure zoom — which cancels to zero displacement at the probe column, exactly as intended — report as parallaxing. ```pycon >>> PanMeasurement((PlaneTrack("a", 10.0, 0.0), PlaneTrack("b", 10.0, 0.0)), "b").is_rigid True >>> PanMeasurement((PlaneTrack("a", 0.0, 0.0), PlaneTrack("b", 0.0, 0.0)), "b").is_rigid True >>> PanMeasurement((PlaneTrack("a", 5.0, 0.0), PlaneTrack("b", 10.0, 0.0)), "b").is_rigid False ``` #### *property* ratios *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [float](https://docs.python.org/3/builtins/functions.html#float)]* `{plane: Δ_i / Δ_ref}`. A rigid stage gives 1.0 for every plane. ```pycon >>> m = PanMeasurement((PlaneTrack("a", 10.0, 0.0), PlaneTrack("b", 40.0, 0.0)), "b") >>> m.ratios {'a': 0.25, 'b': 1.0} ``` #### reference *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* always the largest mover, so the JSON and pixel halves agree and the number does not depend on what a descriptor declares (`_reference()`). * **Type:** The plane every ratio is taken against ### *class* an.bench.stage.PlaneTrack(name, dx, dy, depth=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One plane’s displacement between the two probed times. #### depth *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* The declared parallax factor, when the caller knows it. ### *exception* an.bench.stage.RotatingCamera Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The camera rolls, so a per-axis ratio is not a depth ratio. Under a rotation the composed x-displacement is `−fx·A + fy·B` with plane-independent `A`/`B`, so the axes mix and `Δ_i/Δ_j` stops being `f_i/f_j`. Measured with `rotation = 0.6` and per-axis factors: one plane reported a NEGATIVE ratio and the resulting gap was *larger* than the honest one, so the tripwire passed on a number that meant nothing (an#111 review, M2). Refused rather than reported. The measurement’s whole job is to exclude a camera move that mimics depth; silently reporting one is the failure it exists to prevent, pointed the other way. ### an.bench.stage.measure_pan_json(scene, plane_paths, times, , depths=None) Measurement (a): composed screen displacement, probed at `x = 0`. `plane_paths` are full node paths (`"depths/far"`); the returned tracks are keyed by the LAST segment, which is the plane’s own name. * **Return type:** [`PanMeasurement`](_autosummary/an.bench.stage.html.md#an.bench.stage.PanMeasurement) ### an.bench.stage.measure_pan_pixels(frames, colours, , depths=None) Measurement (b): per-plane centroid displacement between two frames. * **Return type:** [`PanMeasurement`](_autosummary/an.bench.stage.html.md#an.bench.stage.PanMeasurement) ### an.bench.stage.min_ratio_gap(ratios) The smallest gap between any two planes’ ratios. This is the number the ledger row reports and the tripwire guards. Zero means two planes moved together, which on a stage that declares distinct depths means the parallax flattened. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> min_ratio_gap({"far": 0.25, "mid": 1.0, "near": 2.0}) 0.75 >>> min_ratio_gap({"far": 1.0, "mid": 1.0}) 0.0 ``` ### an.bench.stage.plane_centroids(frame, colours) `{plane: (cx, cy, pixel count)}` for exact-colour masks. `an/bench/masks.py` is deliberately not reused: it has no colour selection. The primitive is `metrics.pack_rgb` plus equality — one integer per colour, compared exactly, so a plane’s mask cannot pick up an anti-aliased edge pixel from its neighbour. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`int`](https://docs.python.org/3/builtins/functions.html#int)]] # _autosummary/an.build.cli.html.md # an.build.cli `an cache …` — the shot cache from the shell (an#274). Wired into the top-level dispatcher as the `cache` namespace (`an.tools._dispatch_namespaces`), programmatically, per pillar 8: plain functions taking strings and booleans and returning the text to print; the business logic is [`an.build.gc`](_autosummary/an.build.gc.html.md#module-an.build.gc). Subcommands: `info` (size, entries, how much the current scene reaches) and `gc` (delete what nothing reaches; `--dry-run` first). ### Functions | [`gc`](_autosummary/an.build.cli.html.md#an.build.cli.gc)(project_dir[, dry_run, max_size, ...]) | Delete the shot-cache entries nothing reaches: not the current scene (under the default render settings or any a recorded render used), and not the latest render of each output on each machine. | |----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`info`](_autosummary/an.build.cli.html.md#an.build.cli.info)(project_dir[, no_reachability]) | Show the project's shot cache: its size, its entries by kind, and how much of it the current scene still reaches. | ### an.build.cli.gc(project_dir, dry_run=False, max_size='', max_age='', force=False) Delete the shot-cache entries nothing reaches: not the current scene (under the default render settings or any a recorded render used), and not the latest render of each output on each machine. Never deletes a reachable entry, nor anything written since a render of this project still in progress began. A render running meanwhile can at worst re-render a shot, never use a wrong one. project_dir: path to an an project dry_run: report what would be deleted, delete nothing max_size: keep the most recently written unreachable entries that fit in a cache of this size (e.g. 2G, 500MB) — the shot cache and the Manim stores together; reachable entries are never removed, so the cache can stay above it max_age: keep only the unreachable entries written within this age (e.g. 7d, 36h); a recorded render older than it stops naming its entries, but the current scene under its settings is still kept (and when the current scene cannot be keyed under its settings, a line’s audio not cached under them, its entries are kept whatever its age) force: collect a cache no render of this project has recorded what it used in (one written before `an cache gc` existed): keep only what the current scene reaches (a setting whose audio is no longer cached is not kept; an#311) * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.cli.info(project_dir, no_reachability=False) Show the project’s shot cache: its size, its entries by kind, and how much of it the current scene still reaches. project_dir: path to an an project no_reachability: skip computing what the current scene reaches (which compiles every shot and probes this machine’s browser, like a render’s first second) * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) # _autosummary/an.build.derived.html.md # an.build.derived A renderer’s derived stores, as `an cache gc` collects them (an#299). An opaque renderer keeps intermediates of its own beside the shot cache — Manim its raw pictures, their measurement records and contact sheets — content-keyed, so every edit adds entries and nothing removes them. A renderer declares them here, beside its shot keyer ([`an.build.keys.register_shot_keyer()`](_autosummary/an.build.keys.html.md#an.build.keys.register_shot_keyer)), with [`register_derived_stores()`](_autosummary/an.build.derived.html.md#an.build.derived.register_derived_stores); [`an.build.gc`](_autosummary/an.build.gc.html.md#module-an.build.gc) collects every registered store under the shot cache’s guarantees. A declaration ([`DerivedStores`](_autosummary/an.build.derived.html.md#an.build.derived.DerivedStores)) names: - `record_store` — the store whose entries NAME others (Manim’s `measurements`: a record names its picture and its contact sheet), deleted first, so a record never names something already gone; - `named_stores` — the stores records name (`pictures`, `contact_sheets`); - `entries(renderer, shot, ctx)` — the record-store keys a render of `shot` under `ctx` reads, COMPUTED (never rendered); - `provenance(render_provenance)` — the entries a cached shot’s provenance names, by store; - `names(record_bytes)` — what one record names, by store; it raises [`UnreadableRecordError`](_autosummary/an.build.derived.html.md#an.build.derived.UnreadableRecordError) for bytes it cannot read (a record half > written by a concurrent render), and the collector then deletes nothing a > record could name. A store belongs to one renderer: a second claim is refused, so one renderer’s `names` never reads another’s records. ```pycon >>> spec = DerivedStores( ... record_store="records", named_stores=("blobs",), ... entries=lambda renderer, shot, ctx: set(), ... provenance=lambda provenance: {}, ... names=lambda data: {"blobs": {data.decode()}}, ... ) >>> sorted(spec.stores) ['blobs', 'records'] >>> sorted(spec.closure({"records": {"r": b"b1"}}, {"records": {"r"}})["blobs"]) ['b1'] ``` ### Functions | `derived_stores_for`(renderer_name) | | |---------------------------------------------------------------------------------------------------|-------------------------------------------------------------| | [`register_derived_stores`](_autosummary/an.build.derived.html.md#an.build.derived.register_derived_stores)(renderer_name, spec, \*) | Declare `renderer_name`'s derived stores for `an cache gc`. | | [`registered_derived_stores`](_autosummary/an.build.derived.html.md#an.build.derived.registered_derived_stores)() | Every declaration, by renderer name. | ### Classes | [`DerivedStores`](_autosummary/an.build.derived.html.md#an.build.derived.DerivedStores)(record_store, named_stores, ...) | One renderer's derived stores (see the module docstring). | |---------------------------------------------------------------------------------------------------|-------------------------------------------------------------| ### Exceptions | [`DerivedStoresRegistrationError`](_autosummary/an.build.derived.html.md#an.build.derived.DerivedStoresRegistrationError) | A derived-store declaration that cannot be collected safely. | |-----------------------------------------------------------------------------------|----------------------------------------------------------------| | [`UnreadableRecordError`](_autosummary/an.build.derived.html.md#an.build.derived.UnreadableRecordError) | A record's bytes cannot be read (half written, damaged). | ### *class* an.build.derived.DerivedStores(record_store, named_stores, entries, provenance, names) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One renderer’s derived stores (see the module docstring). #### closure(mall, entries) `entries` plus what each of its records names. A record that is absent names nothing; one that cannot be read raises [`UnreadableRecordError`](_autosummary/an.build.derived.html.md#an.build.derived.UnreadableRecordError). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] #### *property* stores *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* Every store, the record store first (the deletion order). ### *exception* an.build.derived.DerivedStoresRegistrationError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A derived-store declaration that cannot be collected safely. ### *exception* an.build.derived.UnreadableRecordError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A record’s bytes cannot be read (half written, damaged). ### an.build.derived.register_derived_stores(renderer_name, spec, , replace=False) Declare `renderer_name`’s derived stores for `an cache gc`. Refused: a store another renderer already claims, and a second registration for the name unless `replace` (a module reloaded passes the same stores again, which is allowed). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.build.derived.registered_derived_stores() Every declaration, by renderer name. Loads the renderer registry first (a backend behind the import firewall declares when it is imported), its load warnings about unrelated backends silenced: they are the render’s to give. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`DerivedStores`](_autosummary/an.build.derived.html.md#an.build.derived.DerivedStores)] # _autosummary/an.build.gc.html.md # an.build.gc Garbage collection of the shot cache: `an cache gc` and `an cache info` (an#274). ADR 0004 decision 6: invalidation is by digest, never by deletion, so every edit leaves the old entries behind — an end user’s `artifacts/shot_cache` reached 4.9 GB after nine renders of a 16 s film. Collecting them is a separate, explicit command, and this module is it. **What is kept (reachable).** An entry is reachable when either - a render of the project’s CURRENT scene would read it — under any knob set a recorded render ever used, or under a plain `an render`’s — computed by the render loop’s own setup and the engine’s own key code, with the dialogue stamped from the audio stores as the render stamps it ([`an.render.cache_entries()`](_autosummary/an.render.html.md#an.render.cache_entries)); or - the latest render of an output, under one knob set, on one machine, used it — its *root* ([`an.build.ShotCache.record_root()`](_autosummary/an.build.html.md#an.build.ShotCache.record_root)). This keeps what a render on ANOTHER machine of a synced project used, which this machine cannot recompute (its environment digest differs). A cache no render of the project has recorded a root in (one written before an#274) is refused unless `force`: the current scene’s keys alone are then the only evidence, and a render’s knobs or providers that differ from the defaults would leave its entries looking unreachable. **A knob set under which the current scene has a line with no audio** (an#306) — a line edited since the last render under it, or the plain render’s hypothetical knobs for a project only ever spoken by ElevenLabs — has no keys to compute until that line is synthesised, so nothing in the cache can be its entry for that shot. It is skipped rather than refused, and what each root recorded under it is kept whatever `--max-age` says, so its unchanged shots stay. Only when the current scene can be keyed under NO knob set (every one lacks some line’s audio: the scene has lines nothing has synthesised) is the collection refused — render first. Each knob set is replayed with its OWN providers (a root’s recorded `tts`), never with a command line’s defaults. Everything else is unreachable: the entries of shots as they were before an edit, parts cut for an old neighbour, whole-frame entries (`.frames`) that no render reads since an#260, and unreadable records. **What is never deleted.** A reachable entry, whatever the caps say (a cap trims unreachable history only; `--max-age` lets an old root stop naming its entries, never stops its knob set being recomputed). A root. An entry written after the collection began, or after the start of any render of the project still in progress (`.an/render_work/runs//.live`), minus [`CLOCK_SLACK_S`](_autosummary/an.build.gc.html.md#an.build.gc.CLOCK_SLACK_S): a render’s entries are protected from the moment its run starts until its root records them. A blob still named by a kept record. **What a concurrent render can see**, at worst: an entry it looked up being collected between reading its record and its blob — a miss, so that shot renders again. Never a wrong picture: every blob is checked against its id (its sha256) when read, and a reused shot’s bytes are copied into the render’s own run directory at lookup, before anything can remove them. **Deletion is permanent.** `dol.Files` would move each file to the OS trash, which frees nothing (and on macOS asks Finder once per file), so on a filesystem store the catalog record and the blob are unlinked directly, in the layout `lacing.ArtifactStore.from_directory` documents. ```pycon >>> parse_size("2G"), parse_size("500MB"), parse_age("36h"), parse_age("7d") (2147483648, 524288000, 129600.0, 604800.0) ``` ### Module Attributes | [`CLOCK_SLACK_S`](_autosummary/an.build.gc.html.md#an.build.gc.CLOCK_SLACK_S) | a file system's timestamp granularity, and the gap between a record's provenance time and the moment it lands. | |------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`DEFAULT_PROFILE`](_autosummary/an.build.gc.html.md#an.build.gc.DEFAULT_PROFILE) | The render knobs of a plain `an render` (and of `render_project`'s defaults), as `ShotCache.record_root()` records them: `tts` is each voice's own provider (an#305). | | [`HYPOTHETICAL_PROFILES`](_autosummary/an.build.gc.html.md#an.build.gc.HYPOTHETICAL_PROFILES) | today's ([`DEFAULT_PROFILE`](_autosummary/an.build.gc.html.md#an.build.gc.DEFAULT_PROFILE)) and the one before an#305, which spoke every line offline — what a cache written before roots existed was rendered with. | ### Functions | [`cache_info`](_autosummary/an.build.gc.html.md#an.build.gc.cache_info)(project_dir, \*[, reachability, ...]) | What `project_dir`'s shot cache holds; never fails on reachability (it says why it is unknown instead). | |-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| | [`collect_garbage`](_autosummary/an.build.gc.html.md#an.build.gc.collect_garbage)(project_dir, \*[, dry_run, ...]) | Delete the shot-cache entries of `project_dir` that nothing reaches. | | [`inventory`](_autosummary/an.build.gc.html.md#an.build.gc.inventory)(store) | Every catalog record of `store`, read once. | | [`parse_age`](_autosummary/an.build.gc.html.md#an.build.gc.parse_age)(text) | `"7d"`, `"36h"`, `"90m"`, `"2w"`, `"30s"` → seconds. | | [`parse_size`](_autosummary/an.build.gc.html.md#an.build.gc.parse_size)(text) | `"2G"`, `"500MB"`, `"1.5GB"`, `"1048576"` → bytes (1024-based). | | [`reachable_entries`](_autosummary/an.build.gc.html.md#an.build.gc.reachable_entries)(project, store, \*[, ...]) | What the project's current scene and its recorded roots reach. | ### Classes | [`CacheEntry`](_autosummary/an.build.gc.html.md#an.build.gc.CacheEntry)(id, role[, asset_id, bytes_size, ...]) | One catalog record: its id, what it holds, its blob, and when it was written. | |------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | [`CacheInfo`](_autosummary/an.build.gc.html.md#an.build.gc.CacheInfo)(path[, total_bytes, by_role, ...]) | The shot cache's size, what it holds, and how much of it is reachable. | | [`GcReport`](_autosummary/an.build.gc.html.md#an.build.gc.GcReport)(dry_run[, deleted, deleted_blobs, ...]) | What a collection deleted (or, with `dry_run`, would delete), and why the rest was kept. | | [`Reachability`](_autosummary/an.build.gc.html.md#an.build.gc.Reachability)([from_scene, from_roots, ...]) | What the current scene and the recorded roots keep, and why. | ### Exceptions | [`CacheGcError`](_autosummary/an.build.gc.html.md#an.build.gc.CacheGcError) | The collection cannot be done safely; nothing was deleted. | |-----------------------------------------------------------------|--------------------------------------------------------------| ### an.build.gc.CLOCK_SLACK_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 2.0* a file system’s timestamp granularity, and the gap between a record’s provenance time and the moment it lands. * **Type:** Seconds before a protection horizon still treated as “after” it ### *class* an.build.gc.CacheEntry(id, role, asset_id=None, bytes_size=0, written_at=None, record=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One catalog record: its id, what it holds, its blob, and when it was written. ### *exception* an.build.gc.CacheGcError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The collection cannot be done safely; nothing was deleted. ### *class* an.build.gc.CacheInfo(path, total_bytes=0, by_role=, reachable=None, unreachable=None, orphan_blobs=(0, 0), roots=, reachability_error='', skipped=, derived=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The shot cache’s size, what it holds, and how much of it is reachable. #### derived *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), DerivedUsage]* The renderers’ derived stores (an#299), by store name. ### an.build.gc.DEFAULT_PROFILE *: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]* *= {'capture': None, 'fps': None, 'language': 'en', 'lipsync': 'offline', 'pix_fmt': None, 'resolution': None, 'step_hz': None, 'strict_assets': False, 'supersample': 1, 'tts': 'voice'}* The render knobs of a plain `an render` (and of `render_project`’s defaults), as `ShotCache.record_root()` records them: `tts` is each voice’s own provider (an#305). Always among the profiles the current scene is keyed under, so a cache written before roots existed keeps what a plain render of the current scene reads. ### *class* an.build.gc.GcReport(dry_run, deleted=, deleted_blobs=, kept_reachable=0, kept_protected=, kept_retained=0, failed=, bytes_before=0, reach=None, deleted_derived=, derived_freed=0, kept_derived=0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a collection deleted (or, with `dry_run`, would delete), and why the rest was kept. #### deleted_derived *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]]* what was (or would be) deleted, by store, and the bytes that frees. * **Type:** The renderers’ derived stores (an#299) ### an.build.gc.HYPOTHETICAL_PROFILES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)], ...]* *= ({'capture': None, 'fps': None, 'language': 'en', 'lipsync': 'offline', 'pix_fmt': None, 'resolution': None, 'step_hz': None, 'strict_assets': False, 'supersample': 1, 'tts': 'voice'}, {'capture': None, 'fps': None, 'language': 'en', 'lipsync': 'offline', 'pix_fmt': None, 'resolution': None, 'step_hz': None, 'strict_assets': False, 'supersample': 1, 'tts': 'offline'})* today’s ([`DEFAULT_PROFILE`](_autosummary/an.build.gc.html.md#an.build.gc.DEFAULT_PROFILE)) and the one before an#305, which spoke every line offline — what a cache written before roots existed was rendered with. * **Type:** The knob sets a plain render used or uses, recorded by a root or not ### *class* an.build.gc.Reachability(from_scene=, from_roots=, profiles=, roots=, skipped=, derived=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What the current scene and the recorded roots keep, and why. `profiles` are the knob sets the current scene was keyed under; `skipped` the ones it could not be (`(profile, why)`: a line’s audio is not cached under it — an#306), whose roots keep what they recorded. #### derived *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [set](https://docs.python.org/3/builtins/stdtypes.html#set)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]]* The renderers’ derived-store entries the current scene reads, by store (a Manim picture, its measurement and contact sheet; an#299). ### an.build.gc.cache_info(project_dir, , reachability=True, engine=None, now=None) What `project_dir`’s shot cache holds; never fails on reachability (it says why it is unknown instead). * **Return type:** [`CacheInfo`](_autosummary/an.build.gc.html.md#an.build.gc.CacheInfo) ### an.build.gc.collect_garbage(project_dir, , dry_run=False, max_size=None, max_age=None, engine=None, now=None, force=False) Delete the shot-cache entries of `project_dir` that nothing reaches. With no cap, every unreachable entry goes. With caps, unreachable history is kept within them, newest first, and both bind: `max_age` (seconds) keeps only unreachable entries written more recently than that (and lets a recorded render older than that stop protecting its entries); `max_size` (bytes) keeps only those that fit in a cache of that size. Neither ever removes a reachable entry, so the cache can stay above `max_size`. `dry_run` reports and deletes nothing. `force` collects a cache no render of this project has recorded a root in (see [`reachable_entries()`](_autosummary/an.build.gc.html.md#an.build.gc.reachable_entries)). See the module docstring for the reachability and concurrency argument. * **Return type:** [`GcReport`](_autosummary/an.build.gc.html.md#an.build.gc.GcReport) ### an.build.gc.inventory(store) Every catalog record of `store`, read once. An unreadable record is listed with role `"unreadable"` and, on disk, its file’s mtime. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`CacheEntry`](_autosummary/an.build.gc.html.md#an.build.gc.CacheEntry)] ### an.build.gc.parse_age(text) `"7d"`, `"36h"`, `"90m"`, `"2w"`, `"30s"` → seconds. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> parse_age("90m") 5400.0 ``` ### an.build.gc.parse_size(text) `"2G"`, `"500MB"`, `"1.5GB"`, `"1048576"` → bytes (1024-based). * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> parse_size("1.5k") 1536 ``` ### an.build.gc.reachable_entries(project, store, , entries=None, engine=None, root_max_age=None, now=None, force=False) What the project’s current scene and its recorded roots reach. The current scene is keyed under the knobs of EVERY recorded root (of any project, any age: a knob set is a few values, and dropping one would orphan that render’s entries of the unchanged scene), each with its own recorded providers, and under [`HYPOTHETICAL_PROFILES`](_autosummary/an.build.gc.html.md#an.build.gc.HYPOTHETICAL_PROFILES) (a plain render’s). A root younger than `root_max_age` seconds (all, when `None`) also keeps the entries it names; roots themselves are always kept. A knob set under which some line’s audio is not cached cannot be keyed without a synthesis (an#306): it is skipped, listed in `skipped`, and every root recorded under it keeps its entries whatever `root_max_age`. `engine` computes the keys (its environment seam included); `None` is a default [`ShotCache`](_autosummary/an.build.html.md#an.build.ShotCache) over `store`, which probes this machine like a render does. Raises [`CacheGcError`](_autosummary/an.build.gc.html.md#an.build.gc.CacheGcError) when the current scene’s keys cannot be computed for any other reason, or under no knob set at all (guessing is never safe), and when no render of THIS project has recorded a root yet — a cache written before roots existed (an#274) — unless `force`. * **Return type:** [`Reachability`](_autosummary/an.build.gc.html.md#an.build.gc.Reachability) # _autosummary/an.build.html.md # an.build Incremental re-processing: content-addressed build stages (ADR 0004). A draft must stay adjustable without re-processing everything: an edit re-renders only what depends on it. The first slice is the **shot cache** — `an render` skips any shot whose key (everything its render reads, digested; never `shot.id`) already has an entry, and reuses that entry’s mp4. - [`an.build.keys`](_autosummary/an.build.keys.html.md#module-an.build.keys) — canonical digests, the project-wide fallback dependency, and the registry through which a renderer says what its shot render reads ([`register_shot_keyer()`](_autosummary/an.build.html.md#an.build.register_shot_keyer)). - [`an.build.reads`](_autosummary/an.build.reads.html.md#module-an.build.reads) — what a shot read: the recording view of the mall a keyer compiles against, and the digests of the entries it saw (an#316). - [`an.build.shot_cache`](_autosummary/an.build.shot_cache.html.md#module-an.build.shot_cache) — the `incremental=` seam ([`IncrementalEngine`](_autosummary/an.build.html.md#an.build.IncrementalEngine)), its built-in engine [`ShotCache`](_autosummary/an.build.html.md#an.build.ShotCache), and the entries, shaped as `lacing` artifacts in a `lacing.ArtifactStore`. - [`an.build.gc`](_autosummary/an.build.gc.html.md#module-an.build.gc) — garbage collection: what the current scene and the recorded renders reach, and deleting the rest (`an cache gc`, `an cache info`; [`an.build.cli`](_autosummary/an.build.cli.html.md#module-an.build.cli)). The core names no renderer; the cut-out keyer lives with the cut-out backend (`an.stage.cache_key`) and registers on its import. ```pycon >>> from an.build import ShotCache, resolve_incremental >>> isinstance(resolve_incremental(True), ShotCache) True ``` ### Functions | [`cache_info`](_autosummary/an.build.html.md#an.build.cache_info)(project_dir, \*[, reachability, ...]) | What `project_dir`'s shot cache holds; never fails on reachability (it says why it is unknown instead). | |-----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`canonical_digest`](_autosummary/an.build.html.md#an.build.canonical_digest)(obj) | The hex sha256 of `canonical_json()` of `obj`. | | [`collect_garbage`](_autosummary/an.build.html.md#an.build.collect_garbage)(project_dir, \*[, dry_run, ...]) | Delete the shot-cache entries of `project_dir` that nothing reaches. | | [`compose_shot_key`](_autosummary/an.build.html.md#an.build.compose_shot_key)(parts) | The shot key: one digest over the named parts and the key's own version. | | [`every_asset_digest`](_autosummary/an.build.html.md#an.build.every_asset_digest)(mall, \*[, project_root]) | Every asset in the project (decision 3's fallback), without the root files — those are [`project_dependencies()`](_autosummary/an.build.html.md#an.build.project_dependencies)'. | | [`default_environment_digest`](_autosummary/an.build.html.md#an.build.default_environment_digest)(renderer_name) | The digest of `renderer_name`'s registered environment probe, once per process. | | [`in_memory_shot_cache_store`](_autosummary/an.build.html.md#an.build.in_memory_shot_cache_store)() | A shot cache held in dicts — for tests, and for a mall with no disk. | | [`project_assets_digest`](_autosummary/an.build.html.md#an.build.project_assets_digest)(mall, \*[, stores, ...]) | One digest over every asset store of the project (ADR 0004 decision 3). | | [`project_dependencies`](_autosummary/an.build.html.md#an.build.project_dependencies)(mall, \*[, project_root]) | What every shot depends on project-wide: the project-root files (`PROJECT_ROOT_FILES`, the library lockfile), read by path. | | [`read_digests`](_autosummary/an.build.html.md#an.build.read_digests)(mall, reads) | `{"store/key": digest}` for every recorded read — the shot's dependency edges. | | [`register_shot_keyer`](_autosummary/an.build.html.md#an.build.register_shot_keyer)(renderer_name, keyer, \*) | Declare how shots of `renderer_name` are keyed, and how its machine is probed. | | [`registered_shot_keyers`](_autosummary/an.build.html.md#an.build.registered_shot_keyers)() | The renderer names that have a keyer. | | [`resolve_incremental`](_autosummary/an.build.html.md#an.build.resolve_incremental)(incremental) | `incremental=` → an engine, or `None` for "render every shot cold". | | [`shot_artifact_type`](_autosummary/an.build.html.md#an.build.shot_artifact_type)() | The record type (`lacing.Artifact` subclass), built on first use. | | [`shot_cache_store`](_autosummary/an.build.html.md#an.build.shot_cache_store)(root) | A filesystem shot cache under `root`: `catalog/` + `blobs/` (lacing's layout). | | [`shot_keyer_for`](_autosummary/an.build.html.md#an.build.shot_keyer_for)(renderer) | The keyer that describes `renderer` (an instance, or a name), or `None`. | ### Classes | [`RecordingMall`](_autosummary/an.build.html.md#an.build.RecordingMall)(mall, \*[, recorded]) | A view of `mall` that records which asset entries are read through it. | |--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`BuildReport`](_autosummary/an.build.html.md#an.build.BuildReport)([outcomes, store_bytes, ...]) | Every shot's outcome, in timeline order. | | [`IncrementalEngine`](_autosummary/an.build.html.md#an.build.IncrementalEngine)(\*args, \*\*kwargs) | The `incremental=` seam of `an.render.render` (ADR 0004 decision 5). | | [`ShotCache`](_autosummary/an.build.html.md#an.build.ShotCache)([store, environment, ...]) | The built-in engine: look a shot's key up in an ArtifactStore; record misses. | | [`ShotKeyInputs`](_autosummary/an.build.html.md#an.build.ShotKeyInputs)(parts[, compile_s, details]) | What a renderer's keyer returns for one shot. | | [`ShotOutcome`](_autosummary/an.build.html.md#an.build.ShotOutcome)(shot_id, renderer, status[, ...]) | What happened to one shot in one render, with its wall times (seconds). | | [`ShotPlan`](_autosummary/an.build.html.md#an.build.ShotPlan)(shot_id, renderer, key[, inputs, ...]) | The engine's answer for one shot: its key, and what to reuse if anything. | ### Exceptions | [`CacheGcError`](_autosummary/an.build.html.md#an.build.CacheGcError) | The collection cannot be done safely; nothing was deleted. | |-------------------------------------------------------------------|--------------------------------------------------------------------------------| | [`ShotCacheWarning`](_autosummary/an.build.html.md#an.build.ShotCacheWarning) | The shot cache could not do something it should have; the render still stands. | ### *class* an.build.BuildReport(outcomes=, store_bytes=None, store_entries=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Every shot’s outcome, in timeline order. #### store_bytes *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The shot cache’s size after the render, when the engine measured it. #### store_line() How big the shot cache is after the render, or `""` if unmeasured. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> BuildReport(store_bytes=3 * 1024**2, store_entries=4).store_line() '3.0 MB in 4 entries' ``` #### summary() One line: what was rendered, what reused, and WHY each rendered shot was not reused — a cache that silently re-renders everything reads as a broken cache (an#243 review, R2-1). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> BuildReport([ShotOutcome("a", "cutout", "uncached", reason=FRAMES_NOT_CACHED)]).summary() '1 shot(s): 1 rendered (a), 0 reused (-); not reused: frames not cached: film has transitions/sound; pass --cache-frames (a)' ``` #### timing_table() A Markdown table of the per-shot wall times. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### *exception* an.build.CacheGcError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The collection cannot be done safely; nothing was deleted. ### *class* an.build.IncrementalEngine(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) The `incremental=` seam of `an.render.render` (ADR 0004 decision 5). `begin` once per render with the project mall (and its root, for the root files every shot depends on); `plan` once per shot, BEFORE any shot renders (in the calling thread); `record` once per shot that was rendered (possibly from a worker thread); `finish` returns the report. Two hooks are OPTIONAL (the render loop calls them when an engine has them): `record_parts(plan, parts)` once per rendered shot whose film window is not whole (an#260), and `record_root(output_name, profile=..., output=...)` once the film is delivered (what the garbage collector keeps). ### *class* an.build.RecordingMall(mall, , recorded=('characters', 'environments', 'props', 'styles', 'voices', 'sounds')) Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping) A view of `mall` that records which asset entries are read through it. Stores named in `recorded` come back wrapped in a `RecordingStore` (one per store, so identity is stable across lookups); every other store comes back as it is. [`reads`](_autosummary/an.build.reads.html.md#module-an.build.reads) is the set of `(store, key)` read so far, `key` being `WHOLE_STORE` for a store that was listed. ### *class* an.build.ShotCache(store=None, \*, environment=, dependencies=, fallback=, record_reads=True, cache_frames=False) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The built-in engine: look a shot’s key up in an ArtifactStore; record misses. `store` is the injected `lacing.ArtifactStore`; `None` means the mall’s `shot_cache` (resolved in `begin()`), and a mall without one renders every shot. `environment(renderer_name) -> digest` is the environment seam — injectable so a test (or a remote-render backend) can state its machine rather than probe this one. Three dependency seams (see `Dependencies`): - `record_reads` (on by default) keys a shot whose keyer is registered with `records_reads=True` on the asset entries its compile read ([`an.build.reads`](_autosummary/an.build.reads.html.md#module-an.build.reads), an#316: the `assets` part), so an edit to an asset re-renders only the shots that read it; - `fallback` is the `assets` part of every OTHER shot — a keyer that cannot vouch for its reads, or every shot under `record_reads=False`: by default every asset in the project (decision 3’s first slice); - `dependencies` is what EVERY shot depends on (the `project` part): by default the library lockfile. `None` drops it, and `fallback=None` keys an unrecorded shot on its own parts alone — use either knowingly. An engine built with other seams writes keys `an cache gc` (which recomputes the current scene’s keys with the defaults) does not reach: collect such a cache with the same engine. `cache_frames` also stores each shot’s whole PNG sequence when a caller plans with `needs_frames=True`. The render loop no longer does (an#260): an assembled film takes a shot’s mp4 and, at a transition, its *parts* (`window=`), which are cached by default at a few MB. Kept for callers of the engine that need every frame; `an cache gc` collects old frames. After a render, `report` holds what happened to each shot. #### entry_ids(shot, renderer, ctx, , window=None) The catalog ids a [`plan()`](_autosummary/an.build.html.md#an.build.ShotCache.plan) of this shot would read — computed by the same code, looking nothing up and rendering nothing. What `an.build.gc` keeps for the current scene. Call `begin()` first. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] #### plan(shot, renderer, ctx, , needs_frames=False, window=None, force=False) `window` is what an assembled film needs from this shot (`an.assemble.ShotWindow`; `None` for a plain concat): a shot whose window is not whole is reused only when its parts entry is there too. * **Return type:** [`ShotPlan`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotPlan) #### record_parts(plan, parts) Store a freshly rendered shot’s `an.assemble.ShotParts` under `plan.parts_id`: its body mp4 and its window’s PNGs, one stored zip. A failed write never fails the render (the next render renders it). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) #### record_root(output_name, , profile, output) Record what this render used, as a ROOT for `an.build.gc`; return its id. A root is keyed by the project (`project_id()`), the output name, the render `profile` (the knobs as passed — `None` meaning “the scene’s own”) and this machine (`machine_id()`), so the next render of the same output with the same knobs on the same machine replaces it — a browser upgrade included — while a render on another machine of a synced project, or of another project sharing the store, keeps its own. Its record is a `lacing.Artifact` of the delivered film, derived from the shot keys. Also measures the store, for the summary. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### *exception* an.build.ShotCacheWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) The shot cache could not do something it should have; the render still stands. ### *class* an.build.ShotKeyInputs(parts, compile_s=None, details=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a renderer’s keyer returns for one shot. `parts` are named sha256 hex digests (the key’s content half); the engine adds `renderer`, `project` and `environment`. `compile_s` is the wall time of the compile the keyer ran to get its digest, or `None` for a renderer that has no compile stage. #### details *: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]* Diagnostics a keyer wants on the record beside the digests — never part of the key (the digests are). ### *class* an.build.ShotOutcome(shot_id, renderer, status, key=None, reason='', key_s=None, compile_s=None, render_s=None, cached_render_s=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What happened to one shot in one render, with its wall times (seconds). `key_s` is the whole key computation, of which `compile_s` is the compile; `render_s` is this render’s wall time (`None` when reused) and `cached_render_s` the wall time of the render being reused. ### *class* an.build.ShotPlan(shot_id, renderer, key, inputs=, reads=, code=, cached=None, reason='', key_s=None, compile_s=None, cached_render_s=None, needs_frames=False, window=None, parts_id=None, parts=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The engine’s answer for one shot: its key, and what to reuse if anything. #### code *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* The render path’s modules, digested (`{module: digest}`, an#395). #### parts *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* The reused parts (`an.assemble.ShotParts`), materialised for this plan. #### parts_id *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The catalog id of this shot’s parts entry, when its window is not whole. #### reads *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* The asset entries the shot read, digested (`{"store/key": digest}`). #### window *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* What an assembled film needs from this shot (`an.assemble.ShotWindow`); `None` for a film that is a plain concat of shot mp4s. ### an.build.cache_info(project_dir, , reachability=True, engine=None, now=None) What `project_dir`’s shot cache holds; never fails on reachability (it says why it is unknown instead). * **Return type:** [`CacheInfo`](_autosummary/an.build.gc.html.md#an.build.gc.CacheInfo) ### an.build.canonical_digest(obj) The hex sha256 of `canonical_json()` of `obj`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.collect_garbage(project_dir, , dry_run=False, max_size=None, max_age=None, engine=None, now=None, force=False) Delete the shot-cache entries of `project_dir` that nothing reaches. With no cap, every unreachable entry goes. With caps, unreachable history is kept within them, newest first, and both bind: `max_age` (seconds) keeps only unreachable entries written more recently than that (and lets a recorded render older than that stop protecting its entries); `max_size` (bytes) keeps only those that fit in a cache of that size. Neither ever removes a reachable entry, so the cache can stay above `max_size`. `dry_run` reports and deletes nothing. `force` collects a cache no render of this project has recorded a root in (see `reachable_entries()`). See the module docstring for the reachability and concurrency argument. * **Return type:** [`GcReport`](_autosummary/an.build.gc.html.md#an.build.gc.GcReport) ### an.build.compose_shot_key(parts) The shot key: one digest over the named parts and the key’s own version. The parts are a MAPPING so the record can keep them by name, and a re-render can be explained (”`textures` moved”) rather than merely observed. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.default_environment_digest(renderer_name) The digest of `renderer_name`’s registered environment probe, once per process. Memoised per renderer NAME (each backend has its own machine: Chromium and ffmpeg for cut-out, a Manim install for Manim), and once per process, because the cut-out probe launches a browser and encodes a frame. So a long-lived host does not see a `playwright install` or a `brew upgrade` made after its first render: restart it, or pass `force_render`. A renderer with no probe has the empty environment. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.every_asset_digest(mall, , project_root=None) Every asset in the project (decision 3’s fallback), without the root files — those are [`project_dependencies()`](_autosummary/an.build.html.md#an.build.project_dependencies)’. The `assets` part of a shot whose keyer cannot vouch for its reads. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> every_asset_digest({"props": {"a": 1}}) != every_asset_digest({"props": {"a": 2}}) True ``` ### an.build.in_memory_shot_cache_store() A shot cache held in dicts — for tests, and for a mall with no disk. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.build.project_assets_digest(mall, , stores=('characters', 'environments', 'props', 'styles', 'voices', 'sounds'), project_root=None, root_files=('assets.lock.json',)) One digest over every asset store of the project (ADR 0004 decision 3). The first slice’s dependency edge for every shot: safe — no asset can change without every shot’s key moving — at the price of the per-character saving, which read recording buys back. A store the mall does not have is recorded as absent rather than skipped, so adding one later moves the digest. With `project_root`, the files in `root_files` (the library lockfile) are hashed by PATH as well — so a re-pin moves every key whether or not the mall has a store for the file yet. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> a = project_assets_digest({"characters": {"c": {"v": 1}}}, stores=["characters"]) >>> b = project_assets_digest({"characters": {"c": {"v": 2}}}, stores=["characters"]) >>> a == b False ``` ### an.build.project_dependencies(mall, , project_root=None) What every shot depends on project-wide: the project-root files (`PROJECT_ROOT_FILES`, the library lockfile), read by path. A re-pin changes what is checked out, so it moves every key, conservatively. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> project_dependencies({}) == project_dependencies({"props": {"a": 1}}) True ``` ### an.build.read_digests(mall, reads) `{"store/key": digest}` for every recorded read — the shot’s dependency edges. A read of a store the mall does not have is recorded as `ABSENT`, so the day the store appears the key moves. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> read_digests({}, [("props", "logo")]) {'props/logo': 'absent'} ``` ### an.build.register_shot_keyer(renderer_name, keyer, , environment=None, renderer_type=None, records_reads=False, replace=False) Declare how shots of `renderer_name` are keyed, and how its machine is probed. The registration seam for every backend (cut-out here; Manim’s opaque shots, keyed on source hash + Manim version + quality, are the next). `renderer_type` binds the keyer to one renderer class: a renderer whose type is not exactly it is never cached. `records_reads=True` claims that every asset the shot depends on is read through `ctx.mall` (or is already digested by one of the keyer’s parts): the engine then keys the shot on the entries it read rather than on the whole project. A second registration for a name is refused unless `replace=True` — a silent replacement would drop the first keyer’s parts from every key without anyone saying so. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.build.registered_shot_keyers() The renderer names that have a keyer. A keyer registers beside its renderer, and a backend behind the import firewall registers when the renderer registry first loads it (an#247), so this loads the registry first. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> "cutout" in registered_shot_keyers() True ``` ### an.build.resolve_incremental(incremental) `incremental=` → an engine, or `None` for “render every shot cold”. `True` is a fresh [`ShotCache`](_autosummary/an.build.html.md#an.build.ShotCache) over the mall’s store; `False` or `None` is off; anything else must be an [`IncrementalEngine`](_autosummary/an.build.html.md#an.build.IncrementalEngine). * **Return type:** [`IncrementalEngine`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.IncrementalEngine) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> resolve_incremental(False) is None True >>> isinstance(resolve_incremental(True), ShotCache) True ``` ### an.build.shot_artifact_type() The record type (`lacing.Artifact` subclass), built on first use. ### an.build.shot_cache_store(root) A filesystem shot cache under `root`: `catalog/` + `blobs/` (lacing’s layout). * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.build.shot_keyer_for(renderer) The keyer that describes `renderer` (an instance, or a name), or `None`. `None` means the shot is never cached: no keyer for the name, or a renderer whose class is not the one the keyer was registered for. * **Return type:** `_KeyerEntry` | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### Modules | [`cli`](_autosummary/an.build.cli.html.md#module-an.build.cli) | `an cache …` — the shot cache from the shell (an#274). | |----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| | [`derived`](_autosummary/an.build.derived.html.md#module-an.build.derived) | A renderer's derived stores, as `an cache gc` collects them (an#299). | | [`gc`](_autosummary/an.build.gc.html.md#module-an.build.gc) | Garbage collection of the shot cache: `an cache gc` and `an cache info` (an#274). | | [`keys`](_autosummary/an.build.keys.html.md#module-an.build.keys) | Cache keys for build stages: canonical digests, the project fallback, keyers. | | [`reads`](_autosummary/an.build.reads.html.md#module-an.build.reads) | What a shot read: a read-recording view of the mall, and the digests of what it saw. | | [`shot_cache`](_autosummary/an.build.shot_cache.html.md#module-an.build.shot_cache) | The content-keyed shot cache: ADR 0004's first slice, behind the `incremental=` seam. | # _autosummary/an.build.keys.html.md # an.build.keys Cache keys for build stages: canonical digests, the project fallback, keyers. ADR 0004 decision 2: *every key covers everything that changes the output*, and `shot.id` is never one of them (pillar 11). A shot key is composed from NAMED parts, each a sha256 hex digest, so a re-render can say which input moved: The core names no renderer: a backend joins by [`register_shot_keyer()`](_autosummary/an.build.keys.html.md#an.build.keys.register_shot_keyer). A renderer with no keyer is never cached, which is the safe default — an opaque shot is re-rendered, never reused on a guess. ```pycon >>> canonical_digest({"b": 1, "a": [1, 2]}) == canonical_digest({"a": [1, 2], "b": 1}) True >>> len(compose_shot_key({"renderer": canonical_digest("cutout")})) 64 ``` ### Module Attributes | [`SHOT_KEY_IMPL_VERSION`](_autosummary/an.build.keys.html.md#an.build.keys.SHOT_KEY_IMPL_VERSION) | The key's own version — the `impl_version` salt of `nw.Transform` and of `burns.RESOLVER_IMPL_VERSION` ("a lock, not a receipt"). | |------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`PROJECT_ASSET_STORES`](_autosummary/an.build.keys.html.md#an.build.keys.PROJECT_ASSET_STORES) | the art the compiler reads (characters, environments, props, styles) and the two the audio path reads (voices, sounds). | | [`PROJECT_ROOT_FILES`](_autosummary/an.build.keys.html.md#an.build.keys.PROJECT_ROOT_FILES) | Files at the project ROOT that every shot depends on, whether or not a mall store exposes them. | | [`IGNORED_ASSET_NAME_PREFIXES`](_autosummary/an.build.keys.html.md#an.build.keys.IGNORED_ASSET_NAME_PREFIXES) | an OS's folder metadata must not re-render a film. | | [`ABSENT`](_autosummary/an.build.keys.html.md#an.build.keys.ABSENT) | a missing texture, an audio ref the store does not hold. | | [`ShotKeyer`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyer) | `keyer(shot, ctx) -> ShotKeyInputs`. | | [`EnvironmentProbe`](_autosummary/an.build.keys.html.md#an.build.keys.EnvironmentProbe) | the renderer's environment record. | | [`ShotKeyPart`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyPart) | one more named digest for a renderer's key — the additive seam for an input read OUTSIDE the compiled document (a genre's side file, a vocabulary entry's version). | ### Functions | [`bytes_digest`](_autosummary/an.build.keys.html.md#an.build.keys.bytes_digest)(data) | The hex sha256 of `data`. | |-----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`callable_identity`](_autosummary/an.build.keys.html.md#an.build.keys.callable_identity)(obj) | `module.qualname` of a function or class (of an instance: of its type). | | [`canonical_digest`](_autosummary/an.build.keys.html.md#an.build.keys.canonical_digest)(obj) | The hex sha256 of [`canonical_json()`](_autosummary/an.build.keys.html.md#an.build.keys.canonical_json) of `obj`. | | [`canonical_json`](_autosummary/an.build.keys.html.md#an.build.keys.canonical_json)(obj) | `obj` as sorted, whitespace-free JSON — the one spelling every digest hashes. | | [`compose_shot_key`](_autosummary/an.build.keys.html.md#an.build.keys.compose_shot_key)(parts) | The shot key: one digest over the named parts and the key's own version. | | [`every_asset_digest`](_autosummary/an.build.keys.html.md#an.build.keys.every_asset_digest)(mall, \*[, project_root]) | Every asset in the project (decision 3's fallback), without the root files — those are [`project_dependencies()`](_autosummary/an.build.keys.html.md#an.build.keys.project_dependencies)'. | | [`file_digest`](_autosummary/an.build.keys.html.md#an.build.keys.file_digest)(path) | The hex sha256 of a file's bytes, read NOW. | | [`project_assets_digest`](_autosummary/an.build.keys.html.md#an.build.keys.project_assets_digest)(mall, \*[, stores, ...]) | One digest over every asset store of the project (ADR 0004 decision 3). | | [`project_dependencies`](_autosummary/an.build.keys.html.md#an.build.keys.project_dependencies)(mall, \*[, project_root]) | What every shot depends on project-wide: the project-root files ([`PROJECT_ROOT_FILES`](_autosummary/an.build.keys.html.md#an.build.keys.PROJECT_ROOT_FILES), the library lockfile), read by path. | | [`project_root_files_digest`](_autosummary/an.build.keys.html.md#an.build.keys.project_root_files_digest)(project_root, \*[, ...]) | `{name: sha256 or ABSENT}` for the project-root files every shot depends on. | | [`register_shot_key_part`](_autosummary/an.build.keys.html.md#an.build.keys.register_shot_key_part)(renderer_name, ...) | Add one named input to every key of `renderer_name`'s shots — additively. | | [`register_shot_keyer`](_autosummary/an.build.keys.html.md#an.build.keys.register_shot_keyer)(renderer_name, keyer, \*) | Declare how shots of `renderer_name` are keyed, and how its machine is probed. | | [`registered_shot_keyers`](_autosummary/an.build.keys.html.md#an.build.keys.registered_shot_keyers)() | The renderer names that have a keyer. | | [`shot_keyer_for`](_autosummary/an.build.keys.html.md#an.build.keys.shot_keyer_for)(renderer) | The keyer that describes `renderer` (an instance, or a name), or `None`. | | [`store_digest`](_autosummary/an.build.keys.html.md#an.build.keys.store_digest)(store) | A digest of one store's whole content. | ### Classes | [`ShotKeyInputs`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyInputs)(parts[, compile_s, details]) | What a renderer's keyer returns for one shot. | |-----------------------------------------------------------------------------------------------|-------------------------------------------------| ### Exceptions | [`ShotKeyerRegistrationError`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyerRegistrationError) | A shot keyer or key part was registered twice, or collides with another. | |-------------------------------------------------------------------------------|----------------------------------------------------------------------------| ### an.build.keys.ABSENT *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'absent'* a missing texture, an audio ref the store does not hold. Still deterministic, and different from any present value, so a part that later appears re-renders. * **Type:** A part’s value when the thing it digests is absent ### an.build.keys.EnvironmentProbe the renderer’s environment record. Called once per process per renderer (see `ShotCache`), because a browser probe costs a launch. * **Type:** `probe() -> Mapping` alias of [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[], [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.build.keys.IGNORED_ASSET_NAME_PREFIXES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('.',)* an OS’s folder metadata must not re-render a film. * **Type:** File names under an asset root that are never assets ### an.build.keys.PROJECT_ASSET_STORES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('characters', 'environments', 'props', 'styles', 'voices', 'sounds')* the art the compiler reads (characters, environments, props, styles) and the two the audio path reads (voices, sounds). What a recording view records ([`an.build.reads`](_autosummary/an.build.reads.html.md#module-an.build.reads)), and what “every asset in the project” means for decision 3’s fallback. The scene document is deliberately NOT here — each shot’s own slice reaches its key through its compiled document, which is what lets an edit to one shot re-render only that shot. * **Type:** The mall’s ASSET stores ### an.build.keys.PROJECT_ROOT_FILES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('assets.lock.json',)* Files at the project ROOT that every shot depends on, whether or not a mall store exposes them. `assets.lock.json` is the asset library’s lockfile of pinned library versions (ADR 0005, P5): a re-pin changes what is checked out, so it must move every key — and it must do so before (and independently of) its registration in the mall (an#240). Read by path, through [`project_root_files_digest()`](_autosummary/an.build.keys.html.md#an.build.keys.project_root_files_digest); an absent file is recorded as absent. ### an.build.keys.SHOT_KEY_IMPL_VERSION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* The key’s own version — the `impl_version` salt of `nw.Transform` and of `burns.RESOLVER_IMPL_VERSION` (“a lock, not a receipt”). Bump it when the COMPOSITION of a key changes (a part added, renamed or re-spelled). It is NOT how a renderer’s code changes reach the key — a hand-bumped constant is one someone forgets — that is each keyer’s `code` part, a digest of the render path’s source. Bumping it orphans every entry; nothing is deleted (decision 6). ### *class* an.build.keys.ShotKeyInputs(parts, compile_s=None, details=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a renderer’s keyer returns for one shot. `parts` are named sha256 hex digests (the key’s content half); the engine adds `renderer`, `project` and `environment`. `compile_s` is the wall time of the compile the keyer ran to get its digest, or `None` for a renderer that has no compile stage. #### details *: [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]* Diagnostics a keyer wants on the record beside the digests — never part of the key (the digests are). ### an.build.keys.ShotKeyPart one more named digest for a renderer’s key — the additive seam for an input read OUTSIDE the compiled document (a genre’s side file, a vocabulary entry’s version). See [`register_shot_key_part()`](_autosummary/an.build.keys.html.md#an.build.keys.register_shot_key_part). * **Type:** `part(shot, ctx) -> str` alias of [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)], [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.build.keys.ShotKeyer `keyer(shot, ctx) -> ShotKeyInputs`. Raises what the render itself would raise for the same inputs (a compile error, an invalid knob), so a bad shot fails before any browser launches. alias of [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)], [`ShotKeyInputs`](_autosummary/an.build.keys.html.md#an.build.keys.ShotKeyInputs)] ### *exception* an.build.keys.ShotKeyerRegistrationError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A shot keyer or key part was registered twice, or collides with another. ### an.build.keys.bytes_digest(data) The hex sha256 of `data`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> bytes_digest(b"")[:8] 'e3b0c442' ``` ### an.build.keys.callable_identity(obj) `module.qualname` of a function or class (of an instance: of its type). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> callable_identity(callable_identity) 'an.build.keys.callable_identity' ``` ### an.build.keys.canonical_digest(obj) The hex sha256 of [`canonical_json()`](_autosummary/an.build.keys.html.md#an.build.keys.canonical_json) of `obj`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.keys.canonical_json(obj) `obj` as sorted, whitespace-free JSON — the one spelling every digest hashes. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> canonical_json({"b": (1, 2), "a": None}) '{"a":null,"b":[1,2]}' ``` ### an.build.keys.compose_shot_key(parts) The shot key: one digest over the named parts and the key’s own version. The parts are a MAPPING so the record can keep them by name, and a re-render can be explained (”`textures` moved”) rather than merely observed. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.keys.every_asset_digest(mall, , project_root=None) Every asset in the project (decision 3’s fallback), without the root files — those are [`project_dependencies()`](_autosummary/an.build.keys.html.md#an.build.keys.project_dependencies)’. The `assets` part of a shot whose keyer cannot vouch for its reads. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> every_asset_digest({"props": {"a": 1}}) != every_asset_digest({"props": {"a": 2}}) True ``` ### an.build.keys.file_digest(path) The hex sha256 of a file’s bytes, read NOW. Deliberately unmemoised. A (path, mtime, size) memo — `an.stage.raster`’s, which is fine for a texture alias inside one compile — let a same-size edit whose mtime was restored (`cp -p`, `rsync -t`, `tar x`, a sync client) be served stale from cache in a long-running process (an#243 review, S2). A cache KEY is only as good as its weakest input, so every byte is read on every render; on the golden corpus the whole project digest is under 10 ms. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.keys.project_assets_digest(mall, , stores=('characters', 'environments', 'props', 'styles', 'voices', 'sounds'), project_root=None, root_files=('assets.lock.json',)) One digest over every asset store of the project (ADR 0004 decision 3). The first slice’s dependency edge for every shot: safe — no asset can change without every shot’s key moving — at the price of the per-character saving, which read recording buys back. A store the mall does not have is recorded as absent rather than skipped, so adding one later moves the digest. With `project_root`, the files in `root_files` (the library lockfile) are hashed by PATH as well — so a re-pin moves every key whether or not the mall has a store for the file yet. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> a = project_assets_digest({"characters": {"c": {"v": 1}}}, stores=["characters"]) >>> b = project_assets_digest({"characters": {"c": {"v": 2}}}, stores=["characters"]) >>> a == b False ``` ### an.build.keys.project_dependencies(mall, , project_root=None) What every shot depends on project-wide: the project-root files ([`PROJECT_ROOT_FILES`](_autosummary/an.build.keys.html.md#an.build.keys.PROJECT_ROOT_FILES), the library lockfile), read by path. A re-pin changes what is checked out, so it moves every key, conservatively. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> project_dependencies({}) == project_dependencies({"props": {"a": 1}}) True ``` ### an.build.keys.project_root_files_digest(project_root, , files=('assets.lock.json',)) `{name: sha256 or ABSENT}` for the project-root files every shot depends on. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> import tempfile >>> with tempfile.TemporaryDirectory() as d: ... project_root_files_digest(d, files=["assets.lock.json"]) {'assets.lock.json': 'absent'} ``` ### an.build.keys.register_shot_key_part(renderer_name, part_name, part) Add one named input to every key of `renderer_name`’s shots — additively. For an input the render reads OUTSIDE its compiled document (whatever changes the document is already covered by the `compiled` part, with early cutoff for free): a genre package’s side file, a vocabulary entry’s version (P7). Refuses a duplicate `part_name`; a name that collides with one of the keyer’s own parts is refused when the key is computed. A renderer registered LAZILY (the stage, an#247) brings its keyer when the renderer registry first loads, so this loads it first – a genre adding a key part at install (`cutan`, P8) needs no prior lookup. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.build.keys.register_shot_keyer(renderer_name, keyer, , environment=None, renderer_type=None, records_reads=False, replace=False) Declare how shots of `renderer_name` are keyed, and how its machine is probed. The registration seam for every backend (cut-out here; Manim’s opaque shots, keyed on source hash + Manim version + quality, are the next). `renderer_type` binds the keyer to one renderer class: a renderer whose type is not exactly it is never cached. `records_reads=True` claims that every asset the shot depends on is read through `ctx.mall` (or is already digested by one of the keyer’s parts): the engine then keys the shot on the entries it read rather than on the whole project. A second registration for a name is refused unless `replace=True` — a silent replacement would drop the first keyer’s parts from every key without anyone saying so. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.build.keys.registered_shot_keyers() The renderer names that have a keyer. A keyer registers beside its renderer, and a backend behind the import firewall registers when the renderer registry first loads it (an#247), so this loads the registry first. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> "cutout" in registered_shot_keyers() True ``` ### an.build.keys.shot_keyer_for(renderer) The keyer that describes `renderer` (an instance, or a name), or `None`. `None` means the shot is never cached: no keyer for the name, or a renderer whose class is not the one the keyer was registered for. * **Return type:** `_KeyerEntry` | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.build.keys.store_digest(store) A digest of one store’s whole content. A filesystem store (one exposing `_root`) is digested from its FILES, sidecars included — a character’s `meta.json` is not its art; the SVG parts beside it are. That reads behind the mapping, which is ADR 0004’s gap 3 (“art bypasses the mall”), and it is exactly why this is the fallback: once art is read through the stores (the asset library, ADR 0005), a read-recording view replaces it with the keys a shot actually read. Any other mapping is digested from its items. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> store_digest({"a": {"x": 1}}) == store_digest({"a": {"x": 1}}) True >>> store_digest({"a": {"x": 1}}) == store_digest({"a": {"x": 2}}) False ``` # _autosummary/an.build.reads.html.md # an.build.reads What a shot read: a read-recording view of the mall, and the digests of what it saw. ADR 0004 decision 3: *a shot’s inputs are recorded, not assumed.* The mall a keyer compiles against is wrapped in a [`RecordingMall`](_autosummary/an.build.reads.html.md#an.build.reads.RecordingMall), which notes every asset entry the compile asks for — `props["logo"]`, a `get`, an `in` test — and every store it LISTS (iterating a store, or taking its length, depends on all of it). Those reads become the shot’s dependency edges: [`read_digests()`](_autosummary/an.build.reads.html.md#an.build.reads.read_digests) digests exactly them, and an edit to an asset no shot read moves no key. Before an#316 every shot depended on every asset in its project ([`an.build.keys.project_assets_digest()`](_autosummary/an.build.keys.html.md#an.build.keys.project_assets_digest), the first slice’s fallback), so a one-prop edit re-rendered the whole film. Only the asset stores ([`PROJECT_ASSET_STORES`](_autosummary/an.build.keys.html.md#an.build.keys.PROJECT_ASSET_STORES)) are recorded. Everything else a render reads already has a part of its own: the scene reaches the key through each shot’s compiled document, the dialogue audio through `audio`, art staged by path through `textures`. An entry’s digest covers what the mapping returns AND, for a filesystem store, the files of the entry beside it (a prop’s `prop.json`, its `parts/` SVGs, a relative font) — so a sidecar edited behind the mapping still moves it. ```pycon >>> mall = RecordingMall({"props": {"logo": {"text": "A"}, "intro": {}}}) >>> mall["props"]["logo"]["text"] 'A' >>> sorted(mall.reads) [('props', 'logo')] >>> sorted(read_digests({"props": {"logo": {"text": "A"}}}, mall.reads)) ['props/logo'] ``` ### Module Attributes | [`WHOLE_STORE`](_autosummary/an.build.reads.html.md#an.build.reads.WHOLE_STORE) | The key a read of a WHOLE store is recorded under (iteration, `len`): the shot depends on every entry, present and future. | |----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| ### Functions | [`entry_digest`](_autosummary/an.build.reads.html.md#an.build.reads.entry_digest)(store, key) | One entry's digest: what the mapping returns, plus its files on disk. | |-----------------------------------------------------------------------------|--------------------------------------------------------------------------------| | [`entry_files`](_autosummary/an.build.reads.html.md#an.build.reads.entry_files)(store, key) | The files of entry `key` in a filesystem store (one exposing `_root`). | | [`read_digests`](_autosummary/an.build.reads.html.md#an.build.reads.read_digests)(mall, reads) | `{"store/key": digest}` for every recorded read — the shot's dependency edges. | ### Classes | [`RecordingMall`](_autosummary/an.build.reads.html.md#an.build.reads.RecordingMall)(mall, \*[, recorded]) | A view of `mall` that records which asset entries are read through it. | |----------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------| | [`RecordingStore`](_autosummary/an.build.reads.html.md#an.build.reads.RecordingStore)(store, name, reads) | One store of a [`RecordingMall`](_autosummary/an.build.reads.html.md#an.build.reads.RecordingMall): reads are noted, writes pass through. | ### *class* an.build.reads.RecordingMall(mall, , recorded=('characters', 'environments', 'props', 'styles', 'voices', 'sounds')) Bases: [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping) A view of `mall` that records which asset entries are read through it. Stores named in `recorded` come back wrapped in a [`RecordingStore`](_autosummary/an.build.reads.html.md#an.build.reads.RecordingStore) (one per store, so identity is stable across lookups); every other store comes back as it is. `reads` is the set of `(store, key)` read so far, `key` being [`WHOLE_STORE`](_autosummary/an.build.reads.html.md#an.build.reads.WHOLE_STORE) for a store that was listed. ### *class* an.build.reads.RecordingStore(store, name, reads) Bases: [`MutableMapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.MutableMapping) One store of a [`RecordingMall`](_autosummary/an.build.reads.html.md#an.build.reads.RecordingMall): reads are noted, writes pass through. Attribute access (`_root`, a store’s own helpers) reaches the wrapped store unchanged — the compiler reads art by path through `_root`, and those bytes are keyed by the `textures` part, not here. `bool()` is NOT a read: `mall.get(name) or {}` asks whether the store has anything, and recording it would make every shot depend on the whole store. So a read of an EMPTY store (which that idiom replaces with `{}`) goes unrecorded — safe, because what the shot draws from an entry that appears later reaches its compiled document. ### an.build.reads.WHOLE_STORE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '\*'* The key a read of a WHOLE store is recorded under (iteration, `len`): the shot depends on every entry, present and future. ### an.build.reads.entry_digest(store, key) One entry’s digest: what the mapping returns, plus its files on disk. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> entry_digest({"a": 1}, "a") == entry_digest({"a": 1}, "a") True >>> entry_digest({"a": 1}, "a") == entry_digest({"a": 2}, "a") False >>> entry_digest({}, "a") == entry_digest({}, "a") # absent is a value too True ``` ### an.build.reads.entry_files(store, key) The files of entry `key` in a filesystem store (one exposing `_root`). Both store layouts are covered: a sidecar store’s folder `//` (everything under it) and a file store’s `/.` (one suffix: `logo.json` is entry `logo`’s; `logo.v2/` and `logo.v2.json` are entry `logo.v2`’s). Operating-system clutter is never an asset (`an.stores._common.is_os_junk()`). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path)] ### an.build.reads.read_digests(mall, reads) `{"store/key": digest}` for every recorded read — the shot’s dependency edges. A read of a store the mall does not have is recorded as `ABSENT`, so the day the store appears the key moves. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> read_digests({}, [("props", "logo")]) {'props/logo': 'absent'} ``` # _autosummary/an.build.shot_cache.html.md # an.build.shot_cache The content-keyed shot cache: ADR 0004’s first slice, behind the `incremental=` seam. `render_project` asks an *incremental engine*, per shot, for a plan: the shot’s key, and — when an entry with that key exists — the rendered shot to reuse. It renders only the misses, and hands each fresh render back to be recorded. The engine is a seam (`incremental=` on `an.render.render`), and [`ShotCache`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCache) is its built-in default; an `nw`-backed engine is the planned alternative (ADR 0004 decision 5). \*\*Data model: `lacing`’s\*\* (decision 4). An entry is a `ShotArtifact` — a `lacing.Artifact` (`asset_id` = sha256 of the mp4, W3C-PROV provenance whose `was_derived_from` lists the key’s input digests) plus the named parts of its key and the timings that produced it. Entries live in a `lacing.ArtifactStore`: a catalog (`key -> record`) and a content-addressed blob store, both injected `dol` mappings. In a project the store is `mall["shot_cache"]` (`artifacts/shot_cache/{catalog,blobs}/`). An ASSEMBLED film (transitions, a sound layer) is a stream-copy concat of segments (`an.assemble`, an#260): a shot no transition touches needs only its mp4, and a shot one touches also needs its *parts* — its body, encoded once, and the PNGs inside its transition window — a second entry, `.parts..h.t`, of a few MB. So such a film reuses its shots by default. (The older whole-frames entry, `.frames`, is read only by a caller that asks for it with `needs_frames=True`; the render loop no longer does.) Each cached render also records a *root* (`root.`): which entries a render of output `` under one set of render knobs on one machine used. Roots are what `an.build.gc` keeps alive, beside what the current scene reaches. **Invalidation is by digest, never by deletion** (decision 6): a changed input is a different key, and the old entry simply stops being asked for. The pre-cache `artifacts/shots/.mp4` archive is not read. Collecting unreachable entries is a separate, explicit command: `an cache gc` ([`an.build.gc`](_autosummary/an.build.gc.html.md#module-an.build.gc)). ```pycon >>> from an.build.shot_cache import BuildReport, ShotOutcome >>> r = BuildReport([ShotOutcome("a", "cutout", "reused", key="k" * 64), ... ShotOutcome("b", "cutout", "rendered", key="j" * 64, reason="new or changed")]) >>> r.summary() '2 shot(s): 1 rendered (b), 1 reused (a); not reused: new or changed (b)' ``` ### Module Attributes | [`SHOT_CACHE_STORE`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.SHOT_CACHE_STORE) | The mall key of the shot cache. | |---------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | [`PARTS_INFIX`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.PARTS_INFIX) | what an assembled film takes from a shot its transitions touch — its body, encoded once, and the PNGs inside its window. | | [`ROOT_PREFIX`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ROOT_PREFIX) | what one render used (see [`ShotCache.record_root()`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCache.record_root)). | ### Functions | [`default_environment_digest`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.default_environment_digest)(renderer_name) | The digest of `renderer_name`'s registered environment probe, once per process. | |---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------| | [`explain_change`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.explain_change)(before, before_reads, after, ...) | Why a shot keyed `after` is not the entry keyed `before`, in words. | | [`human_bytes`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.human_bytes)(n) | `n` bytes for a person: 1024-based, one decimal. | | [`in_memory_shot_cache_store`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.in_memory_shot_cache_store)() | A shot cache held in dicts — for tests, and for a mall with no disk. | | [`machine_id`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.machine_id)() | A short digest naming this machine (its host name and hardware address), so each machine's renders of a synced project keep a root of their own. | | [`project_id`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.project_id)(project_root) | A short digest naming a project by its resolved directory, so two projects sharing one cache store keep a root each (`""` for none). | | [`parts_entry_id`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.parts_entry_id)(key, window) | The catalog id of the parts entry of shot `key` for `window`. | | [`resolve_incremental`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.resolve_incremental)(incremental) | `incremental=` → an engine, or `None` for "render every shot cold". | | [`shot_artifact_type`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.shot_artifact_type)() | The record type (`lacing.Artifact` subclass), built on first use. | | [`shot_cache_store`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.shot_cache_store)(root) | A filesystem shot cache under `root`: `catalog/` + `blobs/` (lacing's layout). | | [`store_usage`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.store_usage)(store) | `(bytes, entries)` of a shot cache store: every blob byte on disk (or, off disk, every distinct blob its records name) and its catalog entries. | ### Classes | [`BuildReport`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.BuildReport)([outcomes, store_bytes, ...]) | Every shot's outcome, in timeline order. | |--------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`IncrementalEngine`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.IncrementalEngine)(\*args, \*\*kwargs) | The `incremental=` seam of `an.render.render` (ADR 0004 decision 5). | | [`ShotCache`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCache)([store, environment, ...]) | The built-in engine: look a shot's key up in an ArtifactStore; record misses. | | [`ShotOutcome`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotOutcome)(shot_id, renderer, status[, ...]) | What happened to one shot in one render, with its wall times (seconds). | | [`ShotPlan`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotPlan)(shot_id, renderer, key[, inputs, ...]) | The engine's answer for one shot: its key, and what to reuse if anything. | ### Exceptions | [`ShotCacheWarning`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCacheWarning) | The shot cache could not do something it should have; the render still stands. | |---------------------------------------------------------------------|----------------------------------------------------------------------------------| ### *class* an.build.shot_cache.BuildReport(outcomes=, store_bytes=None, store_entries=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Every shot’s outcome, in timeline order. #### store_bytes *: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The shot cache’s size after the render, when the engine measured it. #### store_line() How big the shot cache is after the render, or `""` if unmeasured. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> BuildReport(store_bytes=3 * 1024**2, store_entries=4).store_line() '3.0 MB in 4 entries' ``` #### summary() One line: what was rendered, what reused, and WHY each rendered shot was not reused — a cache that silently re-renders everything reads as a broken cache (an#243 review, R2-1). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> BuildReport([ShotOutcome("a", "cutout", "uncached", reason=FRAMES_NOT_CACHED)]).summary() '1 shot(s): 1 rendered (a), 0 reused (-); not reused: frames not cached: film has transitions/sound; pass --cache-frames (a)' ``` #### timing_table() A Markdown table of the per-shot wall times. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### *class* an.build.shot_cache.IncrementalEngine(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) The `incremental=` seam of `an.render.render` (ADR 0004 decision 5). `begin` once per render with the project mall (and its root, for the root files every shot depends on); `plan` once per shot, BEFORE any shot renders (in the calling thread); `record` once per shot that was rendered (possibly from a worker thread); `finish` returns the report. Two hooks are OPTIONAL (the render loop calls them when an engine has them): `record_parts(plan, parts)` once per rendered shot whose film window is not whole (an#260), and `record_root(output_name, profile=..., output=...)` once the film is delivered (what the garbage collector keeps). ### an.build.shot_cache.PARTS_INFIX *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '.parts.'* what an assembled film takes from a shot its transitions touch — its body, encoded once, and the PNGs inside its window. See [`parts_entry_id()`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.parts_entry_id). * **Type:** The catalog id infix of a shot’s PARTS entry (an#260) ### an.build.shot_cache.ROOT_PREFIX *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'root.'* what one render used (see [`ShotCache.record_root()`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCache.record_root)). * **Type:** The catalog id prefix of a ROOT ### an.build.shot_cache.SHOT_CACHE_STORE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'shot_cache'* The mall key of the shot cache. ### *class* an.build.shot_cache.ShotCache(store=None, \*, environment=, dependencies=, fallback=, record_reads=True, cache_frames=False) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The built-in engine: look a shot’s key up in an ArtifactStore; record misses. `store` is the injected `lacing.ArtifactStore`; `None` means the mall’s `shot_cache` (resolved in `begin()`), and a mall without one renders every shot. `environment(renderer_name) -> digest` is the environment seam — injectable so a test (or a remote-render backend) can state its machine rather than probe this one. Three dependency seams (see `Dependencies`): - `record_reads` (on by default) keys a shot whose keyer is registered with `records_reads=True` on the asset entries its compile read ([`an.build.reads`](_autosummary/an.build.reads.html.md#module-an.build.reads), an#316: the `assets` part), so an edit to an asset re-renders only the shots that read it; - `fallback` is the `assets` part of every OTHER shot — a keyer that cannot vouch for its reads, or every shot under `record_reads=False`: by default every asset in the project (decision 3’s first slice); - `dependencies` is what EVERY shot depends on (the `project` part): by default the library lockfile. `None` drops it, and `fallback=None` keys an unrecorded shot on its own parts alone — use either knowingly. An engine built with other seams writes keys `an cache gc` (which recomputes the current scene’s keys with the defaults) does not reach: collect such a cache with the same engine. `cache_frames` also stores each shot’s whole PNG sequence when a caller plans with `needs_frames=True`. The render loop no longer does (an#260): an assembled film takes a shot’s mp4 and, at a transition, its *parts* (`window=`), which are cached by default at a few MB. Kept for callers of the engine that need every frame; `an cache gc` collects old frames. After a render, `report` holds what happened to each shot. #### entry_ids(shot, renderer, ctx, , window=None) The catalog ids a [`plan()`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCache.plan) of this shot would read — computed by the same code, looking nothing up and rendering nothing. What `an.build.gc` keeps for the current scene. Call `begin()` first. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] #### plan(shot, renderer, ctx, , needs_frames=False, window=None, force=False) `window` is what an assembled film needs from this shot (`an.assemble.ShotWindow`; `None` for a plain concat): a shot whose window is not whole is reused only when its parts entry is there too. * **Return type:** [`ShotPlan`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotPlan) #### record_parts(plan, parts) Store a freshly rendered shot’s `an.assemble.ShotParts` under `plan.parts_id`: its body mp4 and its window’s PNGs, one stored zip. A failed write never fails the render (the next render renders it). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) #### record_root(output_name, , profile, output) Record what this render used, as a ROOT for `an.build.gc`; return its id. A root is keyed by the project ([`project_id()`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.project_id)), the output name, the render `profile` (the knobs as passed — `None` meaning “the scene’s own”) and this machine ([`machine_id()`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.machine_id)), so the next render of the same output with the same knobs on the same machine replaces it — a browser upgrade included — while a render on another machine of a synced project, or of another project sharing the store, keeps its own. Its record is a `lacing.Artifact` of the delivered film, derived from the shot keys. Also measures the store, for the summary. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### *exception* an.build.shot_cache.ShotCacheWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) The shot cache could not do something it should have; the render still stands. ### *class* an.build.shot_cache.ShotOutcome(shot_id, renderer, status, key=None, reason='', key_s=None, compile_s=None, render_s=None, cached_render_s=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What happened to one shot in one render, with its wall times (seconds). `key_s` is the whole key computation, of which `compile_s` is the compile; `render_s` is this render’s wall time (`None` when reused) and `cached_render_s` the wall time of the render being reused. ### *class* an.build.shot_cache.ShotPlan(shot_id, renderer, key, inputs=, reads=, code=, cached=None, reason='', key_s=None, compile_s=None, cached_render_s=None, needs_frames=False, window=None, parts_id=None, parts=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The engine’s answer for one shot: its key, and what to reuse if anything. #### code *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* The render path’s modules, digested (`{module: digest}`, an#395). #### parts *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* The reused parts (`an.assemble.ShotParts`), materialised for this plan. #### parts_id *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The catalog id of this shot’s parts entry, when its window is not whole. #### reads *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* The asset entries the shot read, digested (`{"store/key": digest}`). #### window *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* What an assembled film needs from this shot (`an.assemble.ShotWindow`); `None` for a film that is a plain concat of shot mp4s. ### an.build.shot_cache.default_environment_digest(renderer_name) The digest of `renderer_name`’s registered environment probe, once per process. Memoised per renderer NAME (each backend has its own machine: Chromium and ffmpeg for cut-out, a Manim install for Manim), and once per process, because the cut-out probe launches a browser and encodes a frame. So a long-lived host does not see a `playwright install` or a `brew upgrade` made after its first render: restart it, or pass `force_render`. A renderer with no probe has the empty environment. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.build.shot_cache.explain_change(before, before_reads, after, after_reads, , before_code=None, after_code=None) Why a shot keyed `after` is not the entry keyed `before`, in words. The assets it read that moved come first, by name (`asset changed: props/logo`), then every other key part that moved, appeared or went, by `PART_LABELS` (an optional part — `fonts`, `runtime_extensions` — comes and goes with what the shot draws). The parts that follow from an asset (`FOLLOWS_ASSETS`) are left out when one is named. Both keys are of one composition: a different `key_version` is `KEY_FORMAT_CHANGED`, decided before this is called. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> explain_change({"compiled": "a", "assets": "x"}, {"props/logo": "1"}, ... {"compiled": "b", "assets": "y"}, {"props/logo": "2"}) 'asset changed: props/logo' >>> explain_change({"knobs": "a", "compiled": "c"}, {}, {"knobs": "b", "compiled": "c"}, {}) 'render settings changed' >>> explain_change({"compiled": "a"}, {}, {"compiled": "a", "fonts": "f"}, {}) 'the system fonts changed' >>> explain_change({"assets": "a"}, {}, {"assets": "b"}, {}) # an unrecorded shot 'a project asset changed' >>> explain_change({"code": "a"}, {}, {"code": "b"}, {}, ... before_code={"an.motion": "1"}, after_code={"an.motion": "2"}) "an's render code (an.motion) changed" ``` ### an.build.shot_cache.human_bytes(n) `n` bytes for a person: 1024-based, one decimal. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> human_bytes(0), human_bytes(1536), human_bytes(5 * 1024**3) ('0 B', '1.5 KB', '5.0 GB') ``` ### an.build.shot_cache.in_memory_shot_cache_store() A shot cache held in dicts — for tests, and for a mall with no disk. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.build.shot_cache.machine_id() A short digest naming this machine (its host name and hardware address), so each machine’s renders of a synced project keep a root of their own. A digest, never the names themselves. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> len(machine_id()) 16 ``` ### an.build.shot_cache.parts_entry_id(key, window) The catalog id of the parts entry of shot `key` for `window`. The id names the window (the same shot cut for another neighbour is a different entry) and the digest of the code that cuts and encodes the parts (`parts_code_digest()`): a parts entry is produced by `an.assemble`, not by the renderer, so the renderer’s own `code` key part does not cover it. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> from an.assemble import ShotWindow >>> parts_entry_id("k" * 64, ShotWindow(frames=30, head=0, tail=4)).endswith(".h0.t4") True ``` ### an.build.shot_cache.project_id(project_root) A short digest naming a project by its resolved directory, so two projects sharing one cache store keep a root each (`""` for none). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> project_id(None) '' >>> len(project_id(".")) 16 ``` ### an.build.shot_cache.resolve_incremental(incremental) `incremental=` → an engine, or `None` for “render every shot cold”. `True` is a fresh [`ShotCache`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.ShotCache) over the mall’s store; `False` or `None` is off; anything else must be an [`IncrementalEngine`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.IncrementalEngine). * **Return type:** [`IncrementalEngine`](_autosummary/an.build.shot_cache.html.md#an.build.shot_cache.IncrementalEngine) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> resolve_incremental(False) is None True >>> isinstance(resolve_incremental(True), ShotCache) True ``` ### an.build.shot_cache.shot_artifact_type() The record type (`lacing.Artifact` subclass), built on first use. ### an.build.shot_cache.shot_cache_store(root) A filesystem shot cache under `root`: `catalog/` + `blobs/` (lacing’s layout). * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.build.shot_cache.store_usage(store) `(bytes, entries)` of a shot cache store: every blob byte on disk (or, off disk, every distinct blob its records name) and its catalog entries. On a filesystem store this is a directory listing, not a read of every record, so the render summary can afford it on every render. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`int`](https://docs.python.org/3/builtins/functions.html#int)] # _autosummary/an.capabilities.html.md # an.capabilities Capabilities: what an asset, an engine or the environment affords, and the one matcher. ADR 0002 (capability-based applicability, with a universal default) and the core study §2.13 (three subjects). This is the LOWER layer of the pair: it knows capabilities, analysers, requirements and substitution records, and nothing about vocabulary entries, methods or aspects — [`an.semantic`](_autosummary/an.semantic.html.md#module-an.semantic) imports it, never the reverse, and neither imports [`an.ir`](_autosummary/an.ir.html.md#module-an.ir) at module level. - A **capability** is a named, possibly parametrised fact (`limbs.legs`, `face.mouth` with chart `rhubarb9`, `env.latex`). Names use one dotted grammar, are registered with a description and a **remedy** (what would add it, and the command where one exists), and are **persisted identifiers**: the asset library’s facets and the substitution records store them. A capability belongs to one **subject**: `asset`, `engine` or `environment`. - An **analyser** derives a subject’s capabilities — a **profile**, `{capability: params}` — from what is there (a descriptor and its art, a renderer’s implemented members, the tools on `PATH`), never from a list typed beside it (ADR 0002 decision 2). It is versioned: a stored snapshot made by an older analyser is recomputed ([`current_affordances()`](_autosummary/an.capabilities.html.md#an.capabilities.current_affordances)). Declared facts used *instead of* deriving are listed under the `overrides` param, so the derivation reports which overrides it used. - A **requirement** is a predicate over a profile, spelled as a string. The whole grammar (consult on P7, §3): `cap` (afforded), `cap:key` (`key` among the capability’s `keys`), `cap>=N` (its `count` param — else its number of `keys` — is at least `N`) and `a|b` (any of). No callables: a requirement must name its remedy, render into the generated docs and the MCP surface, and diff when a method’s version bumps. - [`missing()`](_autosummary/an.capabilities.html.md#an.capabilities.missing) is THE matcher: the requirement terms a profile (or a [`Subjects`](_autosummary/an.capabilities.html.md#an.capabilities.Subjects) triple) does not meet, in the order asked. `why_not`, > `applicable` and `resolve` (in [`an.semantic`](_autosummary/an.semantic.html.md#module-an.semantic)) and the library’s > `find(…, near=True)` are all calls to it. - A [`Substitution`](_autosummary/an.capabilities.html.md#an.capabilities.Substitution) records that a method other than the requested one was used (generalising the compiled document’s `asset_resolution`). `policy` choices are information; `missing` and `noop` are warnings that `--strict-assets` makes fatal ([`FATAL_REASONS`](_autosummary/an.capabilities.html.md#an.capabilities.FATAL_REASONS)). ```pycon >>> profile = {"swap.view": {"keys": ["front", "side"]}, "limbs.legs": {}} >>> matches(profile, "swap.view:side"), matches(profile, "swap.view:back"), matches(profile, "limbs.legs") (True, False, True) >>> missing(profile, ["limbs.legs", "face.mouth|face.jaw", "swap.view>=3"]) ['face.mouth|face.jaw', 'swap.view>=3'] ``` ### Module Attributes | [`SUBJECTS`](_autosummary/an.capabilities.html.md#an.capabilities.SUBJECTS) | The three subjects a capability can belong to (core study §2.13). | |------------------------------------------------------------------|--------------------------------------------------------------------------------------| | [`KEY_SEP`](_autosummary/an.capabilities.html.md#an.capabilities.KEY_SEP) | Separates a capability from one of its keys in a term (`swap.view:side`). | | [`KEYS_PARAM`](_autosummary/an.capabilities.html.md#an.capabilities.KEYS_PARAM) | The params entry listing the discrete values a capability affords. | | [`OVERRIDES_PARAM`](_autosummary/an.capabilities.html.md#an.capabilities.OVERRIDES_PARAM) | The params entry listing the declared facts the derivation used instead of deriving. | | [`Profile`](_autosummary/an.capabilities.html.md#an.capabilities.Profile) | `{capability: params}` — what an analyser derives, and the matcher's only input. | | [`CAPABILITIES`](_autosummary/an.capabilities.html.md#an.capabilities.CAPABILITIES) | Registered capabilities, by name. | | [`ANALYSERS`](_autosummary/an.capabilities.html.md#an.capabilities.ANALYSERS) | Registered analysers, by kind. | | [`FATAL_REASONS`](_autosummary/an.capabilities.html.md#an.capabilities.FATAL_REASONS) | The reasons `--strict-assets` makes fatal (a test pins this set). | ### Functions | [`affordances`](_autosummary/an.capabilities.html.md#an.capabilities.affordances)(asset[, art, kind]) | `affordances(asset)` (ADR 0002 decision 2): what `asset` affords, derived. | |----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| | [`analyse`](_autosummary/an.capabilities.html.md#an.capabilities.analyse)(kind, doc[, art]) | `(profile, analysers)` of one subject: its capabilities and the analyser versions used. | | [`art_in_dir`](_autosummary/an.capabilities.html.md#an.capabilities.art_in_dir)(directory, \*[, exclude]) | The art an asset folder holds, as an analyser reads it: `{relative path: True}`. | | [`capability_names`](_autosummary/an.capabilities.html.md#an.capabilities.capability_names)(\*[, subject, owner]) | The registered capability names, sorted; filtered by `subject`/`owner`. | | [`capability_of`](_autosummary/an.capabilities.html.md#an.capabilities.capability_of)(query) | `(capability, key)` of a query term (the library's `find` form). | | [`current_affordances`](_autosummary/an.capabilities.html.md#an.capabilities.current_affordances)(kind, doc, art, \*, ...) | The stored snapshot when its analyser version is current, else a fresh derivation. | | [`matches`](_autosummary/an.capabilities.html.md#an.capabilities.matches)(profile, term) | Whether `profile` (or the subject of `term` in a [`Subjects`](_autosummary/an.capabilities.html.md#an.capabilities.Subjects)) meets `term`. | | [`missing`](_autosummary/an.capabilities.html.md#an.capabilities.missing)(profile, requires) | The requirement terms `profile` does not meet, spelled, in the order asked. | | [`parse_requirement`](_autosummary/an.capabilities.html.md#an.capabilities.parse_requirement)(spec) | A [`Requirement`](_autosummary/an.capabilities.html.md#an.capabilities.Requirement) from its spelling (`cap`, `cap:key`, `cap>=N`, `a|b`). | | [`register_analyser`](_autosummary/an.capabilities.html.md#an.capabilities.register_analyser)(kind, \*[, version, ...]) | Register an analyser. | | [`register_capability`](_autosummary/an.capabilities.html.md#an.capabilities.register_capability)(name, \*[, description, ...]) | Register a capability (or a [`Capability`](_autosummary/an.capabilities.html.md#an.capabilities.Capability)). | | [`remedy_for`](_autosummary/an.capabilities.html.md#an.capabilities.remedy_for)(term) | What would add the capability a requirement term asks for. | | [`subject_of`](_autosummary/an.capabilities.html.md#an.capabilities.subject_of)(term) | The subject whose profile a requirement term is matched against. | ### Classes | [`Analyser`](_autosummary/an.capabilities.html.md#an.capabilities.Analyser)(kind, version, derive[, subject, ...]) | The derivation of one kind's profile, versioned. | |----------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------| | [`Capability`](_autosummary/an.capabilities.html.md#an.capabilities.Capability)(name, description, remedy[, ...]) | A registered capability: its name, what it means, and how to add it. | | [`Requirement`](_autosummary/an.capabilities.html.md#an.capabilities.Requirement)([capability, key, at_least, any_of]) | One requirement term: a capability, optionally a key or a count, or a disjunction. | | [`Subjects`](_autosummary/an.capabilities.html.md#an.capabilities.Subjects)([asset, engine, environment]) | The three profiles a requirement can be matched against. | | [`Substitution`](_autosummary/an.capabilities.html.md#an.capabilities.Substitution)(aspect, entity, requested, ...) | One recorded substitution: the method asked for, the one used, and why. | ### Exceptions | [`CapabilityError`](_autosummary/an.capabilities.html.md#an.capabilities.CapabilityError) | A capability, analyser or requirement is malformed, or collides with one registered. | |--------------------------------------------------------------------|----------------------------------------------------------------------------------------| ### an.capabilities.ANALYSERS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Analyser](_autosummary/an.capabilities.html.md#an.capabilities.Analyser)]* *= {'engine': Analyser(kind='engine', version='3', subject='engine', declares=()), 'environment': Analyser(kind='environment', version='2', subject='environment', declares=())}* Registered analysers, by kind. ### *class* an.capabilities.Analyser(kind, version, derive, subject='asset', declares=(), overrides=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The derivation of one kind’s profile, versioned. `kind` is an asset kind (`character`) or a subject that has one analyser (`engine`, `environment`). Bump `version` whenever the output can change for the same input: snapshots made under the old one are then recomputed on read. The version is NOT a compile input (consult §5): the derived profile is, so touching an analyser without changing its output re-renders nothing. #### declares *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ()* The document’s declared facts the derivation honours instead of deriving (`rest_view`, `face_overlay`) or reads as a request (`gait`): reported by `describe_asset` (ADR 0002 decision 2). #### overrides *: [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[Any](https://docs.python.org/3/library/typing.html#typing.Any), [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]], [Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* `(doc, art) -> declared field names` the derivation USED as overrides that do not show on an afforded capability’s params: a declared fact that REMOVES a capability (a character’s `occluded`, an#381). Those on an afforded capability are already in its `overrides` param. `None`: none beyond those. Reporting only: it changes no profile, so adding it does not bump `version`. ### an.capabilities.CAPABILITIES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Capability](_autosummary/an.capabilities.html.md#an.capabilities.Capability)]* *= {'engine.compile': Capability(name='engine.compile', description='the engine implements the optional \`compile\` member', remedy='use an engine that implements \`compile\`', subject='engine', command=None, version='1'), 'engine.measure_duration': Capability(name='engine.measure_duration', description='the engine implements the optional \`measure_duration\` member', remedy='use an engine that implements \`measure_duration\`', subject='engine', command=None, version='1'), 'engine.paint_order': Capability(name='engine.paint_order', description="the engine paints parts in an order that is not their tree's (keys: \`container\`, reorder one container's items; \`global\`, one paint list across containers)", remedy="render the shot with an engine that declares that paint order (the stage does), or give the rig a draw order its tree already paints (\`nesting: flat\`, or each chain's parts together in draw order)", subject='engine', command=None, version='1'), 'engine.preview': Capability(name='engine.preview', description='the engine implements the optional \`preview\` member', remedy='use an engine that implements \`preview\`', subject='engine', command=None, version='1'), 'engine.render': Capability(name='engine.render', description='the engine renders shots (keys: the Shot.renderer values it claims)', remedy="register a renderer that claims the shot's \`renderer\` (an.adapters.register_renderer)", subject='engine', command=None, version='1'), 'engine.render_frames': Capability(name='engine.render_frames', description='the engine implements the optional \`render_frames\` member', remedy='use an engine that implements \`render_frames\`', subject='engine', command=None, version='1'), 'engine.seek': Capability(name='engine.seek', description='the engine implements the optional \`seek\` member', remedy='use an engine that implements \`seek\`', subject='engine', command=None, version='1'), 'env.browser': Capability(name='env.browser', description='Playwright with a Chromium build, which the stage engine renders in', remedy="pip install 'an[cutout]' && playwright install chromium", subject='environment', command=None, version='1'), 'env.ffmpeg': Capability(name='env.ffmpeg', description='\`ffmpeg\` is on PATH', remedy='install ffmpeg (\`brew install ffmpeg\` on macOS, \`apt install ffmpeg\` on Debian)', subject='environment', command=None, version='1'), 'env.key.anthropic': Capability(name='env.key.anthropic', description='the ANTHROPIC_API_KEY environment variable is set (its value is never read)', remedy='set ANTHROPIC_API_KEY (needed by \`an iterate\` and the vision verifier)', subject='environment', command=None, version='1'), 'env.key.elevenlabs': Capability(name='env.key.elevenlabs', description='the ELEVEN_API_KEY environment variable is set (its value is never read)', remedy='set ELEVEN_API_KEY (needed by the ElevenLabs voices)', subject='environment', command=None, version='1'), 'env.latex': Capability(name='env.latex', description='\`latex\` is on PATH', remedy='install a TeX distribution (MacTeX / TeX Live) so \`latex\` is on PATH', subject='environment', command=None, version='1'), 'env.manim': Capability(name='env.manim', description='the manim, manimkit Python package(s) are importable', remedy="pip install 'an[manim]' (Manim Community Edition and manimkit; on Linux first \`apt install libcairo2-dev libpango1.0-dev\`)", subject='environment', command=None, version='1'), 'env.node': Capability(name='env.node', description='\`node\` is on PATH', remedy='install Node.js (\`brew install node\`)', subject='environment', command=None, version='1'), 'env.rhubarb': Capability(name='env.rhubarb', description='\`rhubarb\` is on PATH', remedy='install Rhubarb Lip Sync (\`brew install rhubarb-lipsync\`)', subject='environment', command=None, version='1'), 'rig.hierarchy': Capability(name='rig.hierarchy', description="the rig nests its parts in chains (\`nesting: bones\`): keys = the chain roots, count = the deepest chain's length in parts", remedy="declare \`nesting: bones\` on the rig document and parent each part's bone to the bone it hangs from (an elbow's to the shoulder's)", subject='asset', command=None, version='1'), 'space.framing2d': Capability(name='space.framing2d', description='the engine lowers moves through the framing2d view space: a 2D framing of a flat picture: position, zoom (log), roll (angle)', remedy='render with an engine that lowers the framing2d view space', subject='engine', command=None, version='1'), 'space.orbit3d': Capability(name='space.orbit3d', description='the engine lowers moves through the orbit3d view space: an orbit camera around a 3D target: azimuth and elevation (angles), distance (log)', remedy='render with an engine that lowers the orbit3d view space', subject='engine', command=None, version='1')}* Registered capabilities, by name. ### *class* an.capabilities.Capability(name, description, remedy, subject='asset', command=None, version='1') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A registered capability: its name, what it means, and how to add it. `command` is the CLI that adds it, when one exists (`an character add-views`); `version` bumps when the *meaning* of the name changes (a persisted name is never redefined in place). #### to_json() The capability as the generated docs and the MCP surface list it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *exception* an.capabilities.CapabilityError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A capability, analyser or requirement is malformed, or collides with one registered. ### an.capabilities.FATAL_REASONS *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'missing', 'noop'})* The reasons `--strict-assets` makes fatal (a test pins this set). ### an.capabilities.KEYS_PARAM *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'keys'* The params entry listing the discrete values a capability affords. ### an.capabilities.KEY_SEP *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= ':'* Separates a capability from one of its keys in a term (`swap.view:side`). ### an.capabilities.OVERRIDES_PARAM *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'overrides'* The params entry listing the declared facts the derivation used instead of deriving. ### an.capabilities.Profile `{capability: params}` — what an analyser derives, and the matcher’s only input. alias of [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### *class* an.capabilities.Requirement(capability='', key=None, at_least=None, any_of=()) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One requirement term: a capability, optionally a key or a count, or a disjunction. ```pycon >>> str(parse_requirement("swap.view:side")), str(parse_requirement("rig.slots>=2")) ('swap.view:side', 'rig.slots>=2') >>> [str(r) for r in parse_requirement("face.eyes|face.brows").any_of] ['face.eyes', 'face.brows'] ``` #### capabilities() Every capability name this term mentions. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.capabilities.SUBJECTS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('asset', 'engine', 'environment')* The three subjects a capability can belong to (core study §2.13). ### *class* an.capabilities.Subjects(asset=, engine=, environment=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The three profiles a requirement can be matched against. A bare profile passed where `Subjects` is expected is the asset’s. ```pycon >>> Subjects.of({"limbs.legs": {}}).asset {'limbs.legs': {}} ``` ### *class* an.capabilities.Substitution(aspect, entity, requested, chosen, reason, requested_version=None, chosen_version='', missing=(), remedies=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One recorded substitution: the method asked for, the one used, and why. It generalises the compiled document’s `asset_resolution` (ADR 0002 decision 6): a requested method replaced by a default is said out loud, and fatal under `--strict-assets` unless it was a policy choice. ```pycon >>> s = Substitution("locomotion", "bob", requested="loco.hem_sway", chosen="loco.rock", ... reason="missing", missing=("limbs.legs",)) >>> s.fatal, s.sentence() (True, "bob: locomotion 'loco.hem_sway' does not apply (missing limbs.legs); used 'loco.rock'") ``` #### sentence() One human sentence saying what happened. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### an.capabilities.affordances(asset, art=None, , kind='character') `affordances(asset)` (ADR 0002 decision 2): what `asset` affords, derived. `asset` is the document (a mapping, or a pydantic model, dumped to JSON first); `art` the files present, `{relative path: ref}`. The kind’s registered analyser decides; with none, nothing is afforded. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.capabilities.analyse(kind, doc, art=None) `(profile, analysers)` of one subject: its capabilities and the analyser versions used. A kind with no registered analyser affords nothing *derived* and records no analyser — an honest empty answer, not a guess. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> analyse("no-such-kind", {}) ({}, {}) ``` ### an.capabilities.art_in_dir(directory, , exclude=()) The art an asset folder holds, as an analyser reads it: `{relative path: True}`. `exclude` drops the document files themselves (`character.json`). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`bool`](https://docs.python.org/3/builtins/functions.html#bool)] ```pycon >>> import tempfile, pathlib >>> with tempfile.TemporaryDirectory() as d: ... _ = (pathlib.Path(d) / "parts").mkdir(); _ = (pathlib.Path(d) / "parts" / "head.svg").write_text("", encoding="utf-8") ... sorted(art_in_dir(d)) ['parts/head.svg'] ``` ### an.capabilities.capability_names(, subject=None, owner=None) The registered capability names, sorted; filtered by `subject`/`owner`. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.capabilities.capability_of(query) `(capability, key)` of a query term (the library’s `find` form). * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)] ```pycon >>> capability_of("swap.view:side"), capability_of("limbs.legs") (('swap.view', 'side'), ('limbs.legs', None)) ``` ### an.capabilities.current_affordances(kind, doc, art, , stored, stored_analysers) The stored snapshot when its analyser version is current, else a fresh derivation. Affordances are derived data, so recomputing them is always safe; trusting a snapshot made by an older analyser is what would make a facet lie. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.capabilities.matches(profile, term) Whether `profile` (or the subject of `term` in a [`Subjects`](_autosummary/an.capabilities.html.md#an.capabilities.Subjects)) meets `term`. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ### an.capabilities.missing(profile, requires) The requirement terms `profile` does not meet, spelled, in the order asked. THE matcher (ADR 0002 decision 4): `why_not`, `applicable`, `resolve` and the library’s `find(…, near=True)` all call it. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> missing({}, ["env.ffmpeg"]), missing(Subjects(environment={"env.ffmpeg": {}}), ["env.ffmpeg"]) (['env.ffmpeg'], []) ``` ### an.capabilities.parse_requirement(spec) A [`Requirement`](_autosummary/an.capabilities.html.md#an.capabilities.Requirement) from its spelling (`cap`, `cap:key`, `cap>=N`, `a|b`). * **Return type:** [`Requirement`](_autosummary/an.capabilities.html.md#an.capabilities.Requirement) ```pycon >>> parse_requirement("rig.slots>=2").at_least 2 >>> parse_requirement("limbs.legs(hips)") Traceback (most recent call last): ... an.capabilities.CapabilityError: requirement 'limbs.legs(hips)': ... ``` ### an.capabilities.register_analyser(kind, , version='', subject='asset', owner='an') Register an analyser. Two forms. `register_analyser(Analyser(...), owner=...)` registers the object and returns it (a genre’s `analysers` field goes this way). With a `kind` string it is a decorator: `@register_analyser("character", version="0.1.0")` registers the decorated derivation. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.capabilities.register_capability(name, , description='', remedy='', subject='asset', command=None, version='1', owner='an') Register a capability (or a [`Capability`](_autosummary/an.capabilities.html.md#an.capabilities.Capability)). Returns it. Re-registering the same definition is a no-op; a different definition under a name another owner holds raises, because capability names are persisted and two meanings for one name would make a stored facet lie. * **Return type:** [`Capability`](_autosummary/an.capabilities.html.md#an.capabilities.Capability) ```pycon >>> cap = register_capability("demo.thing", description="a thing", remedy="add one", owner="demo") >>> CAPABILITIES["demo.thing"] is cap True >>> _ = drop_owner("demo") ``` ### an.capabilities.remedy_for(term) What would add the capability a requirement term asks for. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> remedy_for("no.such.capability") 'no registered capability no.such.capability; see vocabulary() for the known names' ``` ### an.capabilities.subject_of(term) The subject whose profile a requirement term is matched against. An unregistered capability is matched against the asset (and reported missing there): [`an.semantic.check_registry()`](_autosummary/an.semantic.html.md#an.semantic.check_registry) is what refuses it. * **Return type:** str ```pycon >>> subject_of("env.latex") == subject_of("limbs.legs") False ``` ### Modules | [`subjects`](_autosummary/an.capabilities.subjects.html.md#module-an.capabilities.subjects) | The core's two non-asset subjects: the engine (a renderer) and the environment. | |---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| # _autosummary/an.capabilities.subjects.html.md # an.capabilities.subjects The core’s two non-asset subjects: the engine (a renderer) and the environment. Core study §2.13: a requirement can name what the **engine** draws (which shot kinds it claims, which optional members it implements — previz’s rule, “a flag can never disagree with the code”) and what the **environment** has (ffmpeg, a browser, LaTeX, an API key). Each gets one minimal, real analyser here, owned by the core and registered on import of [`an.capabilities`](_autosummary/an.capabilities.html.md#module-an.capabilities): - `engine` — derived from the renderer object’s *implemented members*: `engine.render` (`keys`: the `Shot.renderer` values it claims) and one `engine.` per optional member it implements. When the `Engine` protocol (P3) lands, its optional members join [`ENGINE_OPTIONAL_MEMBERS`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENGINE_OPTIONAL_MEMBERS) and nothing else changes. A stub whose `render` always raises still claims its renderer here — the protocol cannot tell yet, and saying so is better than a declared flag that could lie. `space.`: the view spaces it lowers (an#257), from a `view_spaces` member, else `DFLT_ENGINE_VIEW_SPACES`. - `environment` — cheap probes only (`PATH` lookups, an import spec — `env.manim` is `manim` and `manimkit` both importable —, the Playwright browser cache, the *presence* of API-key variables — never their values). No subprocess, no import of the probed package. Both analysers take their evidence as `doc` so a test can inject it: `environment_affordances(probe={"which": {...}, "env": {...}})`. ```pycon >>> profile = environment_affordances(probe={"which": {"ffmpeg"}, "env": {}, "modules": set(), "browsers": False}) >>> sorted(profile) ['env.ffmpeg'] ``` ### Module Attributes | [`ENGINE_ANALYSER_VERSION`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENGINE_ANALYSER_VERSION) | `engine.measure_duration` joined the derivation (an#279). | |-------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------| | [`ENVIRONMENT_ANALYSER_VERSION`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENVIRONMENT_ANALYSER_VERSION) | `env.manim` joined the derivation (an#279). | | [`ENGINE_OPTIONAL_MEMBERS`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENGINE_OPTIONAL_MEMBERS) | Optional engine members a renderer may implement, each afforded as `engine.` when it is a callable attribute of the renderer. | | [`ENV_TOOLS`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENV_TOOLS) | `capability: (executables, remedy)` — afforded when any executable is on PATH. | | [`ENV_KEYS`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENV_KEYS) | `capability: (environment variables, remedy)` — afforded when any is set. | | [`ENV_MODULES`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.ENV_MODULES) | `capability: (python modules, remedy)` — afforded when EVERY module is importable (an import spec only: the module is never imported to find out). | ### Functions | [`engine_affordances`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.engine_affordances)(renderer) | What a renderer (or a registered renderer's name) affords, from its members. | |---------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | [`environment_affordances`](_autosummary/an.capabilities.subjects.html.md#an.capabilities.subjects.environment_affordances)(\*[, probe]) | What this machine affords: tools on PATH, a browser, API keys set. | ### an.capabilities.subjects.ENGINE_ANALYSER_VERSION *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '3'* `engine.measure_duration` joined the derivation (an#279). “3”: `engine.paint_order` joined it (an#430). * **Type:** ”2” ### an.capabilities.subjects.ENGINE_OPTIONAL_MEMBERS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('compile', 'preview', 'render_frames', 'seek', 'measure_duration')* Optional engine members a renderer may implement, each afforded as `engine.` when it is a callable attribute of the renderer. `measure_duration` is how a whole-shot renderer that OWNS ITS CLOCK (Manim: only its own `play`/`wait` calls decide how long a shot runs) says so — the core asks it for the length before laying out the film (an#279). ### an.capabilities.subjects.ENVIRONMENT_ANALYSER_VERSION *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '2'* `env.manim` joined the derivation (an#279). * **Type:** ”2” ### an.capabilities.subjects.ENV_KEYS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], [str](https://docs.python.org/3/builtins/stdtypes.html#str)]]* *= {'env.key.anthropic': (('ANTHROPIC_API_KEY',), 'set ANTHROPIC_API_KEY (needed by \`an iterate\` and the vision verifier)'), 'env.key.elevenlabs': (('ELEVEN_API_KEY', 'ELEVENLABS_API_KEY'), 'set ELEVEN_API_KEY (needed by the ElevenLabs voices)')}* `capability: (environment variables, remedy)` — afforded when any is set. ### an.capabilities.subjects.ENV_MODULES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], [str](https://docs.python.org/3/builtins/stdtypes.html#str)]]* *= {'env.manim': (('manim', 'manimkit'), "pip install 'an[manim]' (Manim Community Edition and manimkit; on Linux first \`apt install libcairo2-dev libpango1.0-dev\`)")}* `capability: (python modules, remedy)` — afforded when EVERY module is importable (an import spec only: the module is never imported to find out). ### an.capabilities.subjects.ENV_TOOLS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...], [str](https://docs.python.org/3/builtins/stdtypes.html#str)]]* *= {'env.ffmpeg': (('ffmpeg',), 'install ffmpeg (\`brew install ffmpeg\` on macOS, \`apt install ffmpeg\` on Debian)'), 'env.latex': (('latex', 'pdflatex', 'xelatex'), 'install a TeX distribution (MacTeX / TeX Live) so \`latex\` is on PATH'), 'env.node': (('node',), 'install Node.js (\`brew install node\`)'), 'env.rhubarb': (('rhubarb',), 'install Rhubarb Lip Sync (\`brew install rhubarb-lipsync\`)')}* `capability: (executables, remedy)` — afforded when any executable is on PATH. ### an.capabilities.subjects.engine_affordances(renderer) What a renderer (or a registered renderer’s name) affords, from its members. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ```pycon >>> class Fake: ... supported_renderers = ("toy",) ... def render(self, shot, ctx): ... ... def preview(self, shot): ... >>> engine_affordances(Fake()) {'engine.render': {'keys': ['toy']}, 'engine.preview': {}} ``` ### an.capabilities.subjects.environment_affordances(, probe=None) What this machine affords: tools on PATH, a browser, API keys set. `probe` injects the evidence (`which`, `env`, `modules`, `browsers`); `None` probes the real machine (cheap: no subprocess). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] # _autosummary/an.captions.html.md # an.captions Captions from the word timings the audio pipeline already computes (an#175). Epic #9 Wave 8, second slice. The audio pipeline stamps each dialogue line with the provider’s word timings (`Dialogue.word_timings`, line-relative, an#96) for lip-sync; this module turns them into captions, opt-in through `meta.captions` ([`Captions`](_autosummary/an.ir.schema.html.md#an.ir.schema.Captions)). **One cue list, two outputs.** [`caption_pages()`](_autosummary/an.captions.html.md#an.captions.caption_pages) is the single statement of what is captioned and on which frames. Both outputs are derived from it: - the picture — [`captioned_shot()`](_autosummary/an.captions.html.md#an.captions.captioned_shot) adds each page as an OVERLAY text block ([`an.stage.text`](_autosummary/an.stage.text.html.md#module-an.stage.text); camera-immune, placed at a title-safe anchor) plus ordinary `set` actions that show it for exactly its frames, and optionally tint the word being spoken; - the sidecar — [`caption_cues()`](_autosummary/an.captions.html.md#an.captions.caption_cues) places the same pages in FILM time and [`dump_srt()`](_autosummary/an.captions.html.md#an.captions.dump_srt) writes SubRip, stored through the `captions` store beside > the delivered mp4. So the two cannot disagree: a page’s cue starts at the first frame that shows it and ends at the first frame that does not. Times are frames, not seconds, until the last step: ```pycon >>> from an.ir.schema import Dialogue, SceneIR, Shot, WordTimingIR >>> line = Dialogue(speaker="a", text="Hello there, friend.", start=0.5, duration=1.5, ... word_timings=[WordTimingIR(text=w, start=s, end=s + 0.3) ... for w, s in (("Hello", 0.0), ("there,", 0.4), ("friend.", 0.8))]) >>> scene = SceneIR(timeline=[Shot(id="s", duration=3.0, dialogue=[line])]) >>> [(p.start, p.end, p.text) for p in caption_pages(scene, fps=10)] [(5, 20, 'Hello there, friend.')] ``` **Film time follows the delivered timeline.** A cue’s time is its shot’s first frame in the film ([`an.assemble.film_timeline()`](_autosummary/an.assemble.html.md#an.assemble.film_timeline) — the same function the assembler lays the picture out with) plus its shot-local frame, so a dissolve, which overlaps two shots and shortens the film, moves every later cue earlier by exactly its overlap. **Timing is materialised into ordinary actions**, the way [`an.stage.text.reveal_units()`](_autosummary/an.stage.text.html.md#an.stage.text.reveal_units) works: nothing in the compiler or the runtime knows what a caption is. The caption blocks are added to the shot at RENDER time, never written back to the scene — the word timings are the audio pipeline’s output, and a caption baked into `scene.json` would go stale the moment a line is re-voiced. **When a line has no word timings** (the offline and Rhubarb providers keep none), its words are spread evenly over the line’s duration and a [`CaptionTimingWarning`](_autosummary/an.captions.html.md#an.captions.CaptionTimingWarning) says so; `Captions(strict=True)` raises instead. A line the audio pipeline has not placed (no `start`) cannot be captioned and is skipped the same loud way. \*\*The SubRip cue type is a pinned mirror of `mixing.srt``**, not an import (epic #9, Decision 2, departed from on measurement): ``mixing`’s package facade is lazy, so importing `mixing.srt` is cheap — but INSTALLING `mixing` pulls `moviepy`, `opencv-contrib-python`, `scipy` and `imageio-ffmpeg`, whose wheel ships an ffmpeg binary built with `--enable-gpl`. A hard dependency would put a GPL binary inside every `pip install an`, past a licence perimeter that reads declared metadata (BSD-2) and would never see it. [`Cue`](_autosummary/an.captions.html.md#an.captions.Cue), [`seconds_to_srt_time()`](_autosummary/an.captions.html.md#an.captions.seconds_to_srt_time) and [`dump_srt()`](_autosummary/an.captions.html.md#an.captions.dump_srt) therefore mirror `mixing.srt` field for field and byte for byte, and `tests/test_captions.py` pins both against `mixing` whenever it is importable, and against a literal otherwise; thorwhalen/mixing#54 asks for the light base install that would let this become an import. WebVTT is `lacing`’s (its adapter owns the body schema), so it is not written here. ### Module Attributes | [`CAPTION_ID_PREFIX`](_autosummary/an.captions.html.md#an.captions.CAPTION_ID_PREFIX) | A caption page's entity id is this plus its index within the shot. | |----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | [`CAPTION_PROP_REF`](_autosummary/an.captions.html.md#an.captions.CAPTION_PROP_REF) | The props-store key the caption blocks resolve against — a style-only `TextDescriptor` supplied at render time, never stored in the project. | ### Functions | [`caption_cues`](_autosummary/an.captions.html.md#an.captions.caption_cues)(pages, timeline) | `pages` in FILM time on `timeline` (an [`an.assemble.FilmTimeline`](_autosummary/an.assemble.html.md#an.assemble.FilmTimeline)). | |-------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------| | [`caption_pages`](_autosummary/an.captions.html.md#an.captions.caption_pages)(scene, \*, fps[, captions]) | Every caption page of `scene`, shot by shot, in the order shown. | | [`captioned_shot`](_autosummary/an.captions.html.md#an.captions.captioned_shot)(shot, pages, captions, \*, ...) | `shot` with its caption pages burned in, and the mall to compile it with. | | [`dump_srt`](_autosummary/an.captions.html.md#an.captions.dump_srt)(cues) | Serialize cues to SubRip text, renumbering from 1. | | [`paginate`](_autosummary/an.captions.html.md#an.captions.paginate)(words, \*, max_chars, max_lines) | Split `words` into pages of at most `max_lines` wrapped lines, a new page starting after each sentence end. | | [`seconds_to_srt_time`](_autosummary/an.captions.html.md#an.captions.seconds_to_srt_time)(seconds) | `HH:MM:SS,mmm`, milliseconds ROUNDED with carry; negatives clamp to 0. | | [`srt_for_scene`](_autosummary/an.captions.html.md#an.captions.srt_for_scene)(scene, \*, fps[, pages]) | The SubRip sidecar of `scene` rendered at `fps`. | | [`wrap_words`](_autosummary/an.captions.html.md#an.captions.wrap_words)(words, max_chars) | Greedy line breaks at `max_chars` characters (spaces counted); a word longer than a line gets a line of its own and is never split. | ### Classes | [`CaptionPage`](_autosummary/an.captions.html.md#an.captions.CaptionPage)(shot, start, end, lines, word_frames) | One caption as shown: which shot, which frames, which words. | |------------------------------------------------------------------------------------------------------|----------------------------------------------------------------| | [`Cue`](_autosummary/an.captions.html.md#an.captions.Cue)(index, start, end, text) | One SubRip cue — `mixing.srt.Cue`'s fields, in its order. | ### Exceptions | [`CaptionError`](_autosummary/an.captions.html.md#an.captions.CaptionError) | Captions cannot be built as asked. | |-----------------------------------------------------------------------|-----------------------------------------------------------------| | [`CaptionTimingWarning`](_autosummary/an.captions.html.md#an.captions.CaptionTimingWarning) | A line is captioned on estimated timing, or not at all. | | [`CaptionWarning`](_autosummary/an.captions.html.md#an.captions.CaptionWarning) | Captions were built, but not everything was captioned as asked. | ### an.captions.CAPTION_ID_PREFIX *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'caption_'* A caption page’s entity id is this plus its index within the shot. ### an.captions.CAPTION_PROP_REF *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'an.captions'* The props-store key the caption blocks resolve against — a style-only `TextDescriptor` supplied at render time, never stored in the project. ### *exception* an.captions.CaptionError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) Captions cannot be built as asked. Carries the fix. ### *class* an.captions.CaptionPage(shot, start, end, lines, word_frames, speaker=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One caption as shown: which shot, which frames, which words. `start`/`end` are SHOT-local frames — the first that shows the page and the first that does not. `lines` are the words per line, broken by [`wrap_words()`](_autosummary/an.captions.html.md#an.captions.wrap_words); `word_frames[j]` is the frame word `j` (in reading order) starts being spoken, clamped into the page. #### *property* text *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* words joined by spaces, lines by newlines. * **Type:** The page as both outputs write it #### *property* words *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* Every word of the page, in reading order. ### *exception* an.captions.CaptionTimingWarning Bases: [`CaptionWarning`](_autosummary/an.captions.html.md#an.captions.CaptionWarning) A line is captioned on estimated timing, or not at all. ### *exception* an.captions.CaptionWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) Captions were built, but not everything was captioned as asked. ### *class* an.captions.Cue(index, start, end, text) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One SubRip cue — `mixing.srt.Cue`’s fields, in its order. ```pycon >>> Cue(index=1, start=0.5, end=2.0, text="Hi").duration 1.5 ``` #### *property* duration *: [float](https://docs.python.org/3/builtins/functions.html#float)* Cue duration in seconds (never negative). ### an.captions.caption_cues(pages, timeline) `pages` in FILM time on `timeline` (an [`an.assemble.FilmTimeline`](_autosummary/an.assemble.html.md#an.assemble.FilmTimeline)). A cue starts on the film frame that first shows its page and ends on the first that does not — the same frames the picture shows it on. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Cue`](_autosummary/an.captions.html.md#an.captions.Cue)] ### an.captions.caption_pages(scene, , fps, captions=None) Every caption page of `scene`, shot by shot, in the order shown. `captions` defaults to `scene.meta.captions` (and to the defaults when that is unset). Dialogue and narration are both captioned (though the audio pipeline does not voice narration yet, so a narration line has no `start` in a rendered scene and is skipped with a warning). Within a shot a page is cut off when the next one starts, so two pages are never drawn over each other at one anchor; ACROSS a transition they can be — a dissolve blends the tail of one shot, captions included, with the head of the next, and a fade takes the burned caption through the colour with the rest of the picture, while the sidecar’s cue is simply on. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`CaptionPage`](_autosummary/an.captions.html.md#an.captions.CaptionPage)] ### an.captions.captioned_shot(shot, pages, captions, , fps, mall, shot_index=None, base_dir=None, resolution=None) `shot` with its caption pages burned in, and the mall to compile it with. Each page becomes an overlay text block `caption_` and the `set` actions that show it for exactly its frames. With `shot_index`, only the pages of that shot are used, so a caller can pass the scene’s whole list; without it every page must belong to one shot. The returned mall is `mall` with the caption style laid over its props store — nothing is written to the project. `base_dir` resolves a relative caption `font`. With `resolution`, every page is typeset now, so a caption the face cannot draw (an em dash in the embedded face) raises a [`CaptionError`](_autosummary/an.captions.html.md#an.captions.CaptionError) naming the shot and the words — before a browser launches, rather than from inside a shot’s compile after others have rendered. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`Shot`](_autosummary/an.ir.schema.html.md#an.ir.schema.Shot), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.captions.dump_srt(cues) Serialize cues to SubRip text, renumbering from 1. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> print(dump_srt([Cue(7, 1.0, 2.5, "Hello\nthere")])) 1 00:00:01,000 --> 00:00:02,500 Hello there ``` ### an.captions.paginate(words, , max_chars, max_lines) Split `words` into pages of at most `max_lines` wrapped lines, a new page starting after each sentence end. Returns index ranges. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`range`](https://docs.python.org/3/builtins/stdtypes.html#range)] ```pycon >>> paginate("One two. Three four five six".split(), max_chars=10, max_lines=1) [range(0, 2), range(2, 4), range(4, 6)] ``` ### an.captions.seconds_to_srt_time(seconds) `HH:MM:SS,mmm`, milliseconds ROUNDED with carry; negatives clamp to 0. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> seconds_to_srt_time(2592.187), seconds_to_srt_time(-3) ('00:43:12,187', '00:00:00,000') ``` ### an.captions.srt_for_scene(scene, , fps, pages=None) The SubRip sidecar of `scene` rendered at `fps`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> from an.ir.schema import Dialogue, SceneIR, Shot, Transition, WordTimingIR >>> def shot(sid, **kw): ... line = Dialogue(speaker="a", text="Hi.", start=0.2, duration=0.5, ... word_timings=[WordTimingIR(text="Hi.", start=0.0, end=0.4)]) ... return Shot(id=sid, duration=2.0, dialogue=[line], **kw) >>> scene = SceneIR(timeline=[shot("a"), shot("b", transition=Transition(kind="dissolve"))]) >>> print(srt_for_scene(scene, fps=10)) # b starts at 1.5 s: the dissolve's 0.5 s overlap 1 00:00:00,200 --> 00:00:00,700 Hi. 2 00:00:01,700 --> 00:00:02,200 Hi. ``` ### an.captions.wrap_words(words, max_chars) Greedy line breaks at `max_chars` characters (spaces counted); a word longer than a line gets a line of its own and is never split. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> wrap_words("the quick brown fox jumps".split(), 10) [['the', 'quick'], ['brown', 'fox'], ['jumps']] ``` # _autosummary/an.conftest.html.md # an.conftest Collection rules for the package’s own doctests. `an` is in `testpaths` so CI’s `--doctest-modules` reaches the package (an#61). That flag **imports every module it scans**, which makes one module a problem: `tests/test_doctest_gate.py` asserts that no module under `an/` imports an undeclared dependency at module level — one would break CI collection (which installs no optional extras) the same way, and is much easier to catch there than here. (The one such module, the `nw` declaration of the cut-out genre, moved to `cutan`, which skips it when `nw` is absent.) # _autosummary/an.credits.html.md # an.credits What a rendered video owes, and to whom. `an` composes work it did not create into a video its user ships. Recording where that work came from (`an.ir.assets.AssetSource`) is half the job; the other half is being able to *produce* the credits, because \*\*a licence recorded and never displayed is not compliance\*\* — it is a note to oneself. So this module walks a project’s reachable assets and answers three questions a user actually has: - what third-party work is in this video? - may I ship it at all? (an#211 — material that is all rights reserved, used for private study only, is recognised and said LOUDLY: the report opens with it, and a render that uses it ends with a warning that it is not publishable); - what must I display, verbatim, to ship it? - is anything in here unverified? The last is the one that matters most and is easiest to lose. An asset with no licence is reported as **UNKNOWN**, never as “nothing owed”: those are different answers, and collapsing them is exactly how an obligation goes missing. Public domain (`pd`, `public-domain`, `cc-pdm-1.0`, `cc0-*`) is recognised as nothing owed, and an environment’s planes may each carry their own `source`, so a composite stage — a carved plate plus a CC0 prop — credits both. A character’s (or prop’s) attachments may too (an#220): a figure composed from parts carved out of several clips credits each clip, part by part. ### Functions | [`is_factory_stamp`](_autosummary/an.credits.html.md#an.credits.is_factory_stamp)(raw) | Whether a source is the character factory's own stamp (an#236, an#251). | |----------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | [`is_generated_source`](_autosummary/an.credits.html.md#an.credits.is_generated_source)(raw) | Whether a descriptor's source was written by a generator rather than a person. | | [`collect_credits`](_autosummary/an.credits.html.md#an.credits.collect_credits)(mall, \*[, only]) | Walk a project mall and gather every recorded `AssetSource`. | | [`credits_for_project`](_autosummary/an.credits.html.md#an.credits.credits_for_project)(project_dir) | Credits for the project at `project_dir`. | | [`credits_for_scene`](_autosummary/an.credits.html.md#an.credits.credits_for_scene)(mall, scene) | Credits for exactly the assets `scene` draws or plays (an#211). | | [`speech_credits`](_autosummary/an.credits.html.md#an.credits.speech_credits)(mall, scene) | One entry per voice whose lines a render synthesized with a named provider (an#271). | | [`warn_if_private_study`](_autosummary/an.credits.html.md#an.credits.warn_if_private_study)(report, \*[, output]) | Warn, loudly, when `report` holds private-study material. | ### Classes | [`CreditsReport`](_autosummary/an.credits.html.md#an.credits.CreditsReport)([entries, conflicts]) | Everything a project owes, split by whether we actually know. | |----------------------------------------------------------------------------------------|-----------------------------------------------------------------| ### Exceptions | [`PrivateStudyWarning`](_autosummary/an.credits.html.md#an.credits.PrivateStudyWarning) | A render used material that is all rights reserved, private study only. | |------------------------------------------------------------------------|---------------------------------------------------------------------------| ### *class* an.credits.CreditsReport(entries=, conflicts=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Everything a project owes, split by whether we actually know. #### *property* commercial *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* Whether a COMMERCIAL video may contain everything here (publishable, and nothing non-commercial). #### conflicts *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]]]* rights conflicts a library check-out carried (an#357) — a statement about some bytes freer than the one that binds them. Informative: the binding statement is already among the entries. * **Type:** `(asset, conflict)` #### format() Human-readable, and honest about what it does not know. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) #### *property* noncommercial *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[CreditEntry]* fine in a personal or private video, never in a monetised, sponsored or client one. Flagged, never blocking. * **Type:** Entries for NON-COMMERCIAL use only (an#373) #### *property* owed *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[CreditEntry]* Entries that definitely require an attribution (a non-commercial licence owes one too). #### *property* private *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[CreditEntry]* all rights reserved, private study only (an#211). A video containing any of them is not shippable, whatever else it credits. * **Type:** Entries that may NOT be published #### *property* publishable *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* `False` when any entry is private-study material. #### *property* unverified *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[CreditEntry]* Entries whose licence we could not classify. Deliberately its own list rather than folded into [`owed`](_autosummary/an.credits.html.md#an.credits.CreditsReport.owed). Folding them in cries wolf; folding them into “nothing owed” hides a real obligation. Neither is honest, so they are counted separately — the same reason `priv`’s upkeep keeps `unavailable` apart from `findings`. ### *exception* an.credits.PrivateStudyWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) A render used material that is all rights reserved, private study only. Raised as a warning at the END of a render (an#211), so the last thing the author reads about the mp4 is that it must not be published. ### an.credits.collect_credits(mall, , only=None) Walk a project mall and gather every recorded `AssetSource`. `only` restricts the walk to those `store/key` names (what a render used, [`credits_for_scene()`](_autosummary/an.credits.html.md#an.credits.credits_for_scene)) — nothing else is read. Four stores carry provenance: characters, **props** (an#108), **environments** (an#110) and **sounds**. Each was added by the PR that gave that store real art, which is the rule rather than a coincidence — a walk that skips a store holding third-party plates does not return less information, it returns an affirmative false statement to exactly the people who need the opposite. **Sounds** joined with the sound layer (an#163) — a sound is third-party work more often than any other asset. Styles will join when a StylePack has art (#112). Legacy reconstruction runs on characters only: it recovers a DiceBear record from `metadata.dicebear_*`, which no other store has ever written. * **Return type:** [`CreditsReport`](_autosummary/an.credits.html.md#an.credits.CreditsReport) ### an.credits.credits_for_project(project_dir) Credits for the project at `project_dir`. * **Return type:** [`CreditsReport`](_autosummary/an.credits.html.md#an.credits.CreditsReport) ### an.credits.credits_for_scene(mall, scene) Credits for exactly the assets `scene` draws or plays (an#211). [`collect_credits()`](_autosummary/an.credits.html.md#an.credits.collect_credits) walks the whole project; a render owes only what it used, and a private-study plate sitting unused in the store must not make an unrelated render “not publishable”. Kept: every entry under a `store/ref` some shot’s entity names, and every sound a cue names. * **Return type:** [`CreditsReport`](_autosummary/an.credits.html.md#an.credits.CreditsReport) ### an.credits.is_factory_stamp(raw) Whether a source is the character factory’s own stamp (an#236, an#251). The factory stamps every part it draws `cc0` with the part’s digest, and the descriptor with its `source_svg`’s, so the asset library can tell its shared parts from carved ones. It is `an`’s own work, not third-party: a credits report lists what is OWED, and listing fifty generated parts per character would bury the one carved head. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ### an.credits.is_generated_source(raw) Whether a descriptor’s source was written by a generator rather than a person. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> is_generated_source({"provider": "dicebear", "license": "cc0-1.0"}) True >>> is_generated_source({"provider": "a-film", "license": "all-rights-reserved"}) False ``` ### an.credits.speech_credits(mall, scene) One entry per voice whose lines a render synthesized with a named provider (an#271). Read from what the audio pipeline already keeps — no record of its own: the scene’s lines that carry an `audio_ref` (stamped when synthesized), each line’s voice as the pipeline resolves it ([`an.audio.voices.line_voice_id()`](_autosummary/an.audio.voices.html.md#an.audio.voices.line_voice_id)), and that voice’s document in `mall["voices"]` (its `provider`, `voice_id` and `model_id`). A voice document may declare its own `source` (the provider’s terms, the licence the user holds); otherwise the speech is listed UNVERIFIED — the provider’s terms decide what is owed, and nobody recorded them. The licence that counts for synthesized speech is a provider-terms code (`an.ir.assets.PROVIDER_TERMS`: `elevenlabs-paid-plan` is `free`; `elevenlabs-free-plan` is `noncommercial`: it owes a credit and is flagged for commercial use, an#373), or any licence `an` recognises; it is read as the voice’s provider’s, so another provider’s terms count for nothing (an#307). A voice whose document names no provider (the offline default) is not listed: which provider spoke it is not recorded anywhere. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[`CreditEntry`] ```pycon >>> from types import SimpleNamespace as NS >>> line = NS(voice_ref="bob", speaker="bob", audio_ref="k1") >>> scene = NS(timeline=[NS(dialogue=[line], entities=[])]) >>> mall = {"voices": {"bob": {"provider": "elevenlabs", "voice_id": "TX3", ... "model_id": "eleven_v3"}}} >>> [(e.asset, e.license_class, e.source.extra["model"]) for e in speech_credits(mall, scene)] [('speech/bob', 'unknown', 'eleven_v3')] >>> mall["voices"]["bob"]["source"] = {"provider": "elevenlabs", "license": "elevenlabs-paid-plan"} >>> [e.license_class for e in speech_credits(mall, scene)] ['free'] ``` ### an.credits.warn_if_private_study(report, , output=None) Warn, loudly, when `report` holds private-study material. Returns whether it warned. Called at the end of a render, so the warning is the last word about the file; `output` names it. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) # _autosummary/an.data.cutout_runtime.html.md # an.data.cutout_runtime Moved to [`an.stage.runtime`](_autosummary/an.stage.runtime.html.md#module-an.stage.runtime) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.data.html.md # an.data Bundled non-Python resources (cutout JS runtime, etc.). ### Modules | [`cutout_runtime`](_autosummary/an.data.cutout_runtime.html.md#module-an.data.cutout_runtime) | Moved to [`an.stage.runtime`](_autosummary/an.stage.runtime.html.md#module-an.stage.runtime) (an#247); this path is a LIVE alias of it. | |-------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| # _autosummary/an.determinism.html.md # an.determinism The determinism perimeter: what must stay true for a render to be reproducible. `an` renders by driving a headless Chromium and screenshotting a WebGL canvas. Two classes of thing can make that non-reproducible, and they need different treatment: **Pinned inputs** — the rasteriser, the browser build, the encoder. Those are *settings*, and they are pinned unconditionally in [`an.stage.render`](_autosummary/an.stage.render.html.md#module-an.stage.render) (an#31, an#34). Nothing here. **Latent randomness** — machinery that is deterministic today by accident. The vendored PixiJS carries `Math.random`, `Date.now`, `performance.now` and `requestAnimationFrame` calls, and `NoiseFilter`’s default seed is `Math.random()`. All of it is dormant because the runtime creates the app with `autoStart: false` and drives it with explicit `app.render()` calls, and because nothing attaches a filter. Neither fact is written down anywhere that would go red if it stopped being true. That is what this module watches. The division of labour is deliberate: `runtime.js`’s `anDeterminismReport` **observes** and this module **judges**. So the rule is a pure function of a plain dict — testable with no browser, no ffmpeg and no render — and changing the rule is a Python diff rather than a runtime re-stage. Enforcement is **on by default**, which is a deliberate deviation from the issue’s `AN_DETERMINISTIC=1` framing and follows the same reasoning an#31 used for the launch flags: a property that only holds when someone remembers to export a variable is not a property of the system. An assertion nobody runs is worse than no assertion, because the perimeter reads as guarded. The escape hatch is the same variable read the other way — `AN_DETERMINISTIC=0`. ```pycon >>> capture_violations({"page": "/index.html", "stage_filter_count": 0, ... "filtered_node_paths": [], "shared_ticker_started": False, ... "auto_start": False}) [] ``` ### Module Attributes | [`AN_DETERMINISTIC_ENV_VAR`](_autosummary/an.determinism.html.md#an.determinism.AN_DETERMINISTIC_ENV_VAR) | Read as an OFF switch, not an on switch — see the module docstring. | |-----------------------------------------------------------------------------|-----------------------------------------------------------------------| | [`CAPTURE_PAGE`](_autosummary/an.determinism.html.md#an.determinism.CAPTURE_PAGE) | The page the capture path must be on. | ### Functions | [`capture_violations`](_autosummary/an.determinism.html.md#an.determinism.capture_violations)(report, \*[, capture_page]) | Return one sentence per breach of the perimeter; empty means clean. | |---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | [`determinism_enforced`](_autosummary/an.determinism.html.md#an.determinism.determinism_enforced)() | Whether to refuse a render whose determinism perimeter has been breached. | ### an.determinism.AN_DETERMINISTIC_ENV_VAR *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'AN_DETERMINISTIC'* Read as an OFF switch, not an on switch — see the module docstring. ### an.determinism.CAPTURE_PAGE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'index.html'* The page the capture path must be on. `render.py` stages `preview.html` into every work dir and it carries seven clock calls, so “which page did the browser actually load” is a real question with a wrong answer available. ### an.determinism.capture_violations(report, , capture_page='index.html') Return one sentence per breach of the perimeter; empty means clean. Each sentence says what was observed, why it makes frames non-reproducible, and what to do about it — because the reader of this message is the person who just added the thing, and “determinism violation” alone tells them nothing. A missing key is reported rather than defaulted: a report that does not carry a field cannot testify that the field is fine, and silently reading `report.get("shared_ticker_started", False)` would turn a stale runtime into a clean bill of health. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> capture_violations({})[0].startswith("the determinism report is missing") True ``` ### an.determinism.determinism_enforced() Whether to refuse a render whose determinism perimeter has been breached. True unless [`AN_DETERMINISTIC_ENV_VAR`](_autosummary/an.determinism.html.md#an.determinism.AN_DETERMINISTIC_ENV_VAR) is explicitly falsey. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ```pycon >>> import os >>> os.environ.pop("AN_DETERMINISTIC", None) and None >>> determinism_enforced() True >>> os.environ["AN_DETERMINISTIC"] = "0" >>> determinism_enforced() False >>> del os.environ["AN_DETERMINISTIC"] ``` # _autosummary/an.engines.capture.html.md # an.engines.capture The capture loop: drive a session through every frame, resolve, write – for ANY engine. Moved out of the stage renderer (`an/adapters/cutout/render.py`’s `_capture_frames` and `_capture_frames_canvas`, an#247) and generalised over the session members of [`an.engines.protocol`](_autosummary/an.engines.protocol.html.md#module-an.engines.protocol). The algorithms are the ones the stage shipped, unchanged, because the decoded frames are the contract (the golden corpus and the canvas equivalence gate compare them): - **Sequential** (a session without `frames`): per frame, `frame(t)` for each instant; a frame of ONE instant at supersample 1 with no `resolve` member is written as the engine’s own bytes – nothing decoded, so **off is free** – and anything else goes through the resolve. - **Batched** (a session with `frames(requests)`): the requests go out in frame order, samples in the order given, at most `batch` frames and `batch_pixels` captured pixels per round trip (a frame whose instants alone exceed it is split over round trips and resolved once); the resolve runs on a small thread pool while the engine draws the next batch, with BACK-PRESSURE – at most `max_inflight` frames (and twice the pixel budget) wait on the pool, after which the loop blocks on the oldest before asking for more. **The resolve runs here, in the frame stage, before a file is written**: supersampling ([`an.media.supersample`](_autosummary/an.media.supersample.html.md#module-an.media.supersample), an exact block mean) and the open shutter ([`an.media.shutter`](_autosummary/an.media.shutter.html.md#module-an.media.shutter), an exact temporal mean). Nothing downstream reads a resolution off a file or averages anything; an ffmpeg `-vf scale` is refused for the reasons in `an-dev-render-pipeline` §2. A session’s own `resolve` member replaces the default resolve (the stage’s canvas session refuses non-opaque pixels there); the default is [`an.media.shutter.mean_png_bytes()`](_autosummary/an.media.shutter.html.md#an.media.shutter.mean_png_bytes). Two corruptions are silent unless refused, so both are refused: a dropped or reordered frame (every file is named by its frame number, and every frame `0..N-1` must exist on disk before the loop returns), and unbounded buffering (the bounds above). \*\*The bench’s `supersample` lever rebinds\*\* [`capture_frames()`](_autosummary/an.engines.capture.html.md#an.engines.capture.capture_frames) \*\*on this module\*\* to force the product’s own factor, so [`an.engines.frame_stage`](_autosummary/an.engines.frame_stage.html.md#module-an.engines.frame_stage) calls it as a module attribute, at call time. ### Module Attributes | [`DEFAULT_BATCH`](_autosummary/an.engines.capture.html.md#an.engines.capture.DEFAULT_BATCH) | Frames per round trip of a batched session. | |-------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------| | [`DEFAULT_ENCODE_WORKERS`](_autosummary/an.engines.capture.html.md#an.engines.capture.DEFAULT_ENCODE_WORKERS) | Threads resolving and encoding frames while the engine draws the next batch. | | [`DEFAULT_BATCH_PIXELS`](_autosummary/an.engines.capture.html.md#an.engines.capture.DEFAULT_BATCH_PIXELS) | a supersample counts k² times, an open shutter once per instant): at most this many per round trip, twice this many waiting on the pool. | | [`DEFAULT_MAX_INFLIGHT`](_autosummary/an.engines.capture.html.md#an.engines.capture.DEFAULT_MAX_INFLIGHT) | frames handed to the pool and not yet written. | ### Functions | [`capture_frames`](_autosummary/an.engines.capture.html.md#an.engines.capture.capture_frames)(session, requests, frames_dir, \*) | Write one PNG per request into `frames_dir`, resolved to the declared size. | |------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`default_resolve`](_autosummary/an.engines.capture.html.md#an.engines.capture.default_resolve)(samples, \*, frame, factor, size) | The core's resolve: spatially by `factor`, then the instants in time. | ### Exceptions | [`FrameStageError`](_autosummary/an.engines.capture.html.md#an.engines.capture.FrameStageError) | The frame stage could not produce a frame directory it can vouch for. | |--------------------------------------------------------------------|-------------------------------------------------------------------------| ### an.engines.capture.DEFAULT_BATCH *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 8* Frames per round trip of a batched session. Measured on the stage at 1920x1080 on an M1 Max: 67 ms/frame one frame per call, 46 at four, 46 at eight – the round trip is ~20 ms of fixed cost, amortised by the batch. ### an.engines.capture.DEFAULT_BATCH_PIXELS *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 4147200* a supersample counts k² times, an open shutter once per instant): at most this many per round trip, twice this many waiting on the pool. A frame COUNT bounds nothing when a frame is a k-times, many-sample, incompressible canvas (an#192 review: one reply overflowed the driver’s string limit and the render hung). * **Type:** The same two bounds in CAPTURED PIXELS (backbuffer pixels ### an.engines.capture.DEFAULT_ENCODE_WORKERS *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 2* Threads resolving and encoding frames while the engine draws the next batch. The stage’s decode/encode is ~60 ms/frame of Pillow at 1080p, the same order as the page’s own work, so it must overlap it. Two, not `cpu_count()`: a parallel render already runs one engine per shot. ### an.engines.capture.DEFAULT_MAX_INFLIGHT *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 16* frames handed to the pool and not yet written. * **Type:** BACK-PRESSURE ### *exception* an.engines.capture.FrameStageError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The frame stage could not produce a frame directory it can vouch for. A renderer built by `frame_stage_renderer(..., error=...)` re-raises it as its own typed error at its boundary. ### an.engines.capture.capture_frames(session, requests, frames_dir, , factor=1, size=None, batch=None, workers=None, max_inflight=None, batch_pixels=None) Write one PNG per request into `frames_dir`, resolved to the declared size. `session` is time-driven (`frame(t)`), optionally batched (`frames(requests)`), optionally with its own `resolve`. A state-driven session is adapted by the frame stage before it reaches here. `size`, when known, sets the pixel budget and is passed to the resolve. `None` for any tunable reads the module default at call time. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.engines.capture.default_resolve(samples, , frame, factor, size) The core’s resolve: spatially by `factor`, then the instants in time. One sample at factor 1 is returned as is – the engine’s own bytes. * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) # _autosummary/an.engines.conformance.html.md # an.engines.conformance Conformance of a TIME-driven engine against the timing kernel’s golden vectors. A time-driven engine evaluates the compiled channels itself (core study §2.7): `runtime.js` does, in a browser. Its pictures are only comparable with any other engine’s if the STATE it evaluated at `t` is the kernel’s, so a time-driven session exposes `state(t)` – the read-back – and this module holds it to `an/data/timing/timing_vectors.json`, the contract `an.timing` and `previz` both assert (ADR 0001 decision 10): numbers within the file’s tolerance, everything else exact, every sample of every case of the session’s property space. The engine supplies how to load a vector’s document; the check is the core’s. ```pycon >>> cases = vector_cases(space="stage.node") >>> len(cases) >= 10 and all(c["space"] == "stage.node" for c in cases) True >>> readback_mismatches(lambda t: {}, {"name": "n", "samples": [{"t": 0.0, "state": {}}]}) [] ``` ### Module Attributes | [`VECTORS_RESOURCE`](_autosummary/an.engines.conformance.html.md#an.engines.conformance.VECTORS_RESOURCE) | `(package, path inside it)` for [`importlib.resources`](https://docs.python.org/3/library/importlib.resources.html#module-importlib.resources). | |---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| ### Functions | [`as_contract_state`](_autosummary/an.engines.conformance.html.md#an.engines.conformance.as_contract_state)(state) | A state in the vectors' spelling: `"target:property"` keys. | |---------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`case_document`](_autosummary/an.engines.conformance.html.md#an.engines.conformance.case_document)(case) | The case's document, carrying its property space the way a compiled document does (an#287): `meta.entity_spaces` names the space for every entity the case animates and `meta.spaces` defines it, so an engine that reads only the DOCUMENT (`runtime.js` has no registry) evaluates the case in the case's space. | | [`conformance_report`](_autosummary/an.engines.conformance.html.md#an.engines.conformance.conformance_report)(open_case, cases) | Every mismatch over `cases`; `open_case(case)` is a context manager yielding a session loaded with the case's document. | | [`readback_mismatches`](_autosummary/an.engines.conformance.html.md#an.engines.conformance.readback_mismatches)(state_at, case) | `(case, t, expected, got)` for every sample whose read-back differs. | | [`vector_cases`](_autosummary/an.engines.conformance.html.md#an.engines.conformance.vector_cases)(\*[, space]) | The golden cases, optionally only those of one property space. | ### an.engines.conformance.VECTORS_RESOURCE *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= ('an.data', 'timing/timing_vectors.json')* `(package, path inside it)` for [`importlib.resources`](https://docs.python.org/3/library/importlib.resources.html#module-importlib.resources). * **Type:** Where the vectors ship ### an.engines.conformance.as_contract_state(state) A state in the vectors’ spelling: `"target:property"` keys. Accepts the kernel’s pose keys (`(target, property)` tuples) and the runtime’s (`"target::property"`). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> as_contract_state({("a", "x"): 1.0, "b::y": 2}) {'a:x': 1.0, 'b:y': 2} ``` ### an.engines.conformance.case_document(case) The case’s document, carrying its property space the way a compiled document does (an#287): `meta.entity_spaces` names the space for every entity the case animates and `meta.spaces` defines it, so an engine that reads only the DOCUMENT (`runtime.js` has no registry) evaluates the case in the case’s space. A case in the default space is returned as it is. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> case = {"space": {"name": "inline", "fields": []}, "document": { ... "timeline": {"duration": 1.0, "tracks": []}, "animations": {"m": { ... "duration": 1.0, "channels": [{"target": "view/a", "property": "x", ... "keyframes": [{"time": 0.0, "value": 0}]}]}}}} >>> meta = case_document(case)["meta"] >>> meta["entity_spaces"], meta["spaces"]["inline"]["fields"] ({'view': 'inline'}, []) >>> "meta" in case_document({"space": "stage.node", "document": case["document"]}) False ``` ### an.engines.conformance.conformance_report(open_case, cases) Every mismatch over `cases`; `open_case(case)` is a context manager yielding a session loaded with the case’s document. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.engines.conformance.readback_mismatches(state_at, case) `(case, t, expected, got)` for every sample whose read-back differs. `state_at` is a loaded session’s `state` (or anything with its shape). Compared with the contract’s own rule ([`an.timing.contract.values_close()`](_autosummary/an.timing.contract.html.md#an.timing.contract.values_close)). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.engines.conformance.vector_cases(, space=None) The golden cases, optionally only those of one property space. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] # _autosummary/an.engines.frame_stage.html.md # an.engines.frame_stage `frame_stage_renderer(engine)`: any seekable engine becomes a `Renderer`. The core owns everything around the engine, once, for every engine: 1. the knobs, validated before anything launches – ffmpeg present, the supersample factor ([`an.media.supersample.check_factor()`](_autosummary/an.media.supersample.html.md#an.media.supersample.check_factor)), the pixel format ([`an.media.mp4.check_pix_fmt()`](_autosummary/an.media.mp4.html.md#an.media.mp4.check_pix_fmt)), the engine’s own knobs (`Engine.check`), and the frame clock ([`an.media.shutter.check_frame_samples()`](_autosummary/an.media.shutter.html.md#an.media.shutter.check_frame_samples)); 2. the clock: `frame_count = max(1, round(duration * fps))`, frame `i` at `i / fps` unless `RenderContext.frame_samples` (built by [`an.frame_clock.FrameClock`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock)) says otherwise; 3. the shot’s workspace – `/shot_/` with a cleared `frames/`; 4. the capture loop ([`an.engines.capture`](_autosummary/an.engines.capture.html.md#module-an.engines.capture)): supersampling and the shutter resolved in the frame stage; 5. the sink: the frames muxed to the shot mp4 with the pinned argv, the shot’s dialogue laid under it ([`an.media.mp4.mux_shot()`](_autosummary/an.media.mp4.html.md#an.media.mp4.mux_shot)); 6. provenance: the core’s facts plus the session’s own (`provenance()`). The engine only loads the shot and draws instants ([`an.engines.protocol`](_autosummary/an.engines.protocol.html.md#module-an.engines.protocol)). A STATE-driven session is adapted here: the core evaluates its `timeline` with [`an.timing.timeline.evaluate_timeline()`](_autosummary/an.timing.timeline.html.md#an.timing.timeline.evaluate_timeline) (in the session’s `space` when it has one) and hands each state to `render`. Errors the core raises ([`FrameStageError`](_autosummary/an.engines.capture.html.md#an.engines.capture.FrameStageError), [`MediaError`](_autosummary/an.media.mp4.html.md#an.media.mp4.MediaError), [`UnseekableEngineError`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.UnseekableEngineError)) are re-raised as the renderer’s own `error` type at its boundary, message intact, so a cut-out render still fails with `CutoutRenderError`. ```pycon >>> from contextlib import contextmanager >>> class Card: ... name = "card" ... @contextmanager ... def open(self, job): ... yield self ... def frame(self, t): return b"" ... def state(self, t): return {} >>> r = frame_stage_renderer(Card(), renderers=("card", "title")) >>> r.name, r.supported_renderers ('card', ('card', 'title')) ``` ### Module Attributes | [`SHOT_WORKSPACE_PATTERN`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.SHOT_WORKSPACE_PATTERN) | A shot's scratch directory under `RenderContext.work_dir`. | |---------------------------------------------------------------------------|--------------------------------------------------------------| ### Functions | [`frame_stage_renderer`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.frame_stage_renderer)(engine, \*[, name, ...]) | Turn `engine` into a `Renderer`: the core's clock, capture loop, resolves and sinks. | |--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------| | [`require_engine`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.require_engine)(engine) | Refuse an object that is not an engine, saying what is missing. | | [`shot_workspace`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.shot_workspace)(work_dir, shot_id) | `/shot_`: the one per-shot scratch directory. | ### Classes | [`FrameStageRenderer`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.FrameStageRenderer)(engine[, name, ...]) | A `Renderer` that drives an [`Engine`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine) frame by frame. | |--------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------| | [`StateDrivenAdapter`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.StateDrivenAdapter)(session) | A state-driven session seen as a time-driven one: the core evaluates `at(t)`. | ### *class* an.engines.frame_stage.FrameStageRenderer(engine, name='', supported_renderers=(), error=, capture_options=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A `Renderer` that drives an [`Engine`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine) frame by frame. Build it with [`frame_stage_renderer()`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.frame_stage_renderer). Stateless across renders, so one instance serves every shot of a parallel render: each `render` opens its own session. #### capture_options *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]* Capture-loop tunables passed through to [`an.engines.capture.capture_frames()`](_autosummary/an.engines.capture.html.md#an.engines.capture.capture_frames) (`batch`, `workers`, `max_inflight`, `batch_pixels`); unset = its defaults. #### error The exception type raised at the boundary for every core error. alias of [`FrameStageError`](_autosummary/an.engines.capture.html.md#an.engines.capture.FrameStageError) #### probe_frames(shot, ctx, times) The film’s frames of `shot` showing at each of `times` (seconds), as PNG bytes. `an probe` (an#347): the session [`render()`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.FrameStageRenderer.render) opens (the same engine, state-driven adapter, supersample and frame clock) and the same [`capture_frames()`](_autosummary/an.engines.capture.html.md#an.engines.capture.capture_frames), asked only for the frames needed — so a probe frame IS the film’s frame, without the rest of the shot or the mux. Each instant is snapped to the frame showing then (`floor(t * fps)`, clamped to the shot). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)] #### render(shot, ctx) Render `shot` to mp4 through the engine; see the module docstring. * **Return type:** [`RenderResult`](_autosummary/an.adapters.html.md#an.adapters.RenderResult) #### supported_renderers *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ()* The `Shot.renderer` values this renderer claims (the ONE place it names them). ### an.engines.frame_stage.SHOT_WORKSPACE_PATTERN *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'shot_{shot_id}'* A shot’s scratch directory under `RenderContext.work_dir`. Kept from the stage renderer it came from, so the paths a render leaves behind (and that the bench and film assembly read) do not move. ### *class* an.engines.frame_stage.StateDrivenAdapter(session) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A state-driven session seen as a time-driven one: the core evaluates `at(t)`. `frame(t)` is `render(evaluate_timeline(timeline, t, space=space))` and `state(t)` is the evaluated state, so the capture loop and the conformance tests treat both drive modes alike. The session’s other members (`resolve`, `provenance`, …) are reached through attribute access. **Batched** (an#286): `frames(requests)` evaluates every instant here and hands the session the STATES, through its optional `render_states(states)` (one round trip per batch, the member a JS-bridged view engine implements), else `render` per state. A session’s own `frames` is never forwarded: it would take times and bypass `state`. **Adapted by drive mode** (an#286): `project(point, t)` and `bounds(t)` reach the session as `project(point, state)` and `bounds(state)` (the state-driven signature, previz’s `project(point, {state, ...})`), and exist only when the session has them, so [`describe()`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.describe) still reads capabilities from real members. #### frames(requests) One list of frames per request, a frame per instant, in order. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)]] ### an.engines.frame_stage.frame_stage_renderer(engine, \*, name=None, renderers=None, error=, capture_options=None) Turn `engine` into a `Renderer`: the core’s clock, capture loop, resolves and sinks. `name` defaults to the engine’s; `renderers` – the `Shot.renderer` values claimed – default to `(name,)`. `error` is the typed exception the renderer raises at its boundary for every core error. * **Return type:** [`FrameStageRenderer`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.FrameStageRenderer) ### an.engines.frame_stage.require_engine(engine) Refuse an object that is not an engine, saying what is missing. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> require_engine(object()) Traceback (most recent call last): ... TypeError: an Engine needs `name` and `open(job)`; object lacks: name, open ``` ### an.engines.frame_stage.shot_workspace(work_dir, shot_id) `/shot_`: the one per-shot scratch directory. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) # _autosummary/an.engines.html.md # an.engines Engines: seekable things the core drives frame by frame, and the renderer that drives them. Core (ADR 0001 decision 12; core study §2.7). No engine is core: the core holds the PROTOCOL and the frame stage, and an engine – the 2D stage runtime, a `previz` view behind a page, a `burns` crop over a still – lives in its own package and registers the renderer [`frame_stage_renderer()`](_autosummary/an.engines.html.md#an.engines.frame_stage_renderer) builds from it. - [`an.engines.protocol`](_autosummary/an.engines.protocol.html.md#module-an.engines.protocol) – `Engine` (a factory that opens a session per shot), the time-driven and state-driven session protocols, the declared live tier, and [`describe()`](_autosummary/an.engines.html.md#an.engines.describe), which reads a session’s tier, drive mode and features off the members it implements (never off a flag). - [`an.engines.capture`](_autosummary/an.engines.capture.html.md#module-an.engines.capture) – the capture loop, sequential or batched, with the frame stage’s resolves (supersample, shutter). - [`an.engines.frame_stage`](_autosummary/an.engines.frame_stage.html.md#module-an.engines.frame_stage) – [`frame_stage_renderer()`](_autosummary/an.engines.html.md#an.engines.frame_stage_renderer): an engine in, a `Renderer` out, using the core’s frame clock, capture loop, resolves and MP4 sink ([`an.media`](_autosummary/an.media.html.md#module-an.media)). ```pycon >>> from contextlib import contextmanager >>> class Blank: ... name = "blank" ... @contextmanager ... def open(self, job): ... yield self ... def frame(self, t): return b"" ... def state(self, t): return {} >>> describe(Blank()).drive, frame_stage_renderer(Blank()).name ('time', 'blank') ``` ### Functions | [`capture_frames`](_autosummary/an.engines.html.md#an.engines.capture_frames)(session, requests, frames_dir, \*) | Write one PNG per request into `frames_dir`, resolved to the declared size. | |------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------| | [`describe`](_autosummary/an.engines.html.md#an.engines.describe)(session) | The tier, drive mode and features a session (or a session class) offers. | | [`drive_mode`](_autosummary/an.engines.html.md#an.engines.drive_mode)(session) | `"time"`, `"state"`, or `None` for a session the frame stage cannot drive. | | [`frame_stage_renderer`](_autosummary/an.engines.html.md#an.engines.frame_stage_renderer)(engine, \*[, name, ...]) | Turn `engine` into a `Renderer`: the core's clock, capture loop, resolves and sinks. | | [`require_engine`](_autosummary/an.engines.html.md#an.engines.require_engine)(engine) | Refuse an object that is not an engine, saying what is missing. | | [`require_seekable`](_autosummary/an.engines.html.md#an.engines.require_seekable)(session) | The session's drive mode, or a refusal that says what to add. | | [`requests_as_dicts`](_autosummary/an.engines.html.md#an.engines.requests_as_dicts)(requests) | Requests as plain dicts, the shape a page or a subprocess takes. | | [`shot_workspace`](_autosummary/an.engines.html.md#an.engines.shot_workspace)(work_dir, shot_id) | `/shot_`: the one per-shot scratch directory. | ### Classes | [`Engine`](_autosummary/an.engines.html.md#an.engines.Engine)(\*args, \*\*kwargs) | A stateless factory of loaded, seekable sessions -- one per shot render. | |--------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------| | [`EngineProfile`](_autosummary/an.engines.html.md#an.engines.EngineProfile)(tier, drive, features) | What a session can do, read off its members. | | [`FrameJob`](_autosummary/an.engines.html.md#an.engines.FrameJob)(shot, ctx, workspace, frames_dir, ...) | What the frame stage asks of an engine for one shot. | | [`FrameRequest`](_autosummary/an.engines.html.md#an.engines.FrameRequest)(frame, times) | One output frame's instants, in the order they must be captured. | | [`FrameStageRenderer`](_autosummary/an.engines.html.md#an.engines.FrameStageRenderer)(engine[, name, ...]) | A `Renderer` that drives an [`Engine`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine) frame by frame. | | [`LiveEngine`](_autosummary/an.engines.html.md#an.engines.LiveEngine)(\*args, \*\*kwargs) | The live tier: apply, settle, capture in real time. | | [`StateDriven`](_autosummary/an.engines.html.md#an.engines.StateDriven)(\*args, \*\*kwargs) | A session the core hands states to. | | [`StateDrivenAdapter`](_autosummary/an.engines.html.md#an.engines.StateDrivenAdapter)(session) | A state-driven session seen as a time-driven one: the core evaluates `at(t)`. | | [`TimeDriven`](_autosummary/an.engines.html.md#an.engines.TimeDriven)(\*args, \*\*kwargs) | A session that evaluates the compiled channels itself. | ### Exceptions | [`FrameStageError`](_autosummary/an.engines.html.md#an.engines.FrameStageError) | The frame stage could not produce a frame directory it can vouch for. | |------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`UnseekableEngineError`](_autosummary/an.engines.html.md#an.engines.UnseekableEngineError) | A session that the frame stage cannot drive; the message says what to add. | ### *class* an.engines.Engine(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) A stateless factory of loaded, seekable sessions – one per shot render. #### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* The engine’s name (`"stage"`); also how provenance names it. #### open(job) Load `job.shot` and yield a session (see the module table). * **Return type:** [`AbstractContextManager`](https://docs.python.org/3/library/contextlib.html#contextlib.AbstractContextManager)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *class* an.engines.EngineProfile(tier, drive, features) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a session can do, read off its members. ### *class* an.engines.FrameJob(shot, ctx, workspace, frames_dir, total_frames, supersample, frame_samples=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What the frame stage asks of an engine for one shot. Built by the core, before [`Engine.open()`](_autosummary/an.engines.html.md#an.engines.Engine.open): every knob here is already validated, so an engine never re-derives the frame count or the factor. #### frame_samples *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), ...], ...] | [None](https://docs.python.org/3/builtins/constants.html#None)* Per frame, the instants to capture and average, or `None` for one instant at `i / fps`. #### requests() Every frame’s request, frame `i` at `i / fps` unless a clock says otherwise. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`FrameRequest`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.FrameRequest), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> from types import SimpleNamespace >>> job = FrameJob(None, SimpleNamespace(fps=4, resolution=(2, 2)), Path("."), ... Path("."), total_frames=3, supersample=1) >>> [r.times for r in job.requests()] [(0.0,), (0.25,), (0.5,)] ``` #### *property* size *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), [int](https://docs.python.org/3/builtins/functions.html#int)]* what every resolved frame must be. * **Type:** The DECLARED ([*width*](_autosummary/an.stage.paths.html.md#an.stage.paths.PathDescriptor.width), height) #### supersample *: [int](https://docs.python.org/3/builtins/functions.html#int)* the engine draws at `k` times the declared size, and the core resolves back to it. * **Type:** The validated supersample factor #### workspace *: [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path)* The shot’s own scratch directory (`/shot_`). The engine may stage files in it (the stage engine’s runtime copy); the core owns `frames/` and the delivered mp4 inside it. ### *class* an.engines.FrameRequest(frame, times) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One output frame’s instants, in the order they must be captured. One instant unless a frame clock opened the shutter (`RenderContext.frame_samples`). ### *exception* an.engines.FrameStageError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) The frame stage could not produce a frame directory it can vouch for. A renderer built by `frame_stage_renderer(..., error=...)` re-raises it as its own typed error at its boundary. ### *class* an.engines.FrameStageRenderer(engine, name='', supported_renderers=(), error=, capture_options=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A `Renderer` that drives an [`Engine`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine) frame by frame. Build it with [`frame_stage_renderer()`](_autosummary/an.engines.html.md#an.engines.frame_stage_renderer). Stateless across renders, so one instance serves every shot of a parallel render: each `render` opens its own session. #### capture_options *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]* Capture-loop tunables passed through to [`an.engines.capture.capture_frames()`](_autosummary/an.engines.capture.html.md#an.engines.capture.capture_frames) (`batch`, `workers`, `max_inflight`, `batch_pixels`); unset = its defaults. #### error alias of [`FrameStageError`](_autosummary/an.engines.capture.html.md#an.engines.capture.FrameStageError) #### probe_frames(shot, ctx, times) The film’s frames of `shot` showing at each of `times` (seconds), as PNG bytes. `an probe` (an#347): the session [`render()`](_autosummary/an.engines.html.md#an.engines.FrameStageRenderer.render) opens (the same engine, state-driven adapter, supersample and frame clock) and the same [`capture_frames()`](_autosummary/an.engines.capture.html.md#an.engines.capture.capture_frames), asked only for the frames needed — so a probe frame IS the film’s frame, without the rest of the shot or the mux. Each instant is snapped to the frame showing then (`floor(t * fps)`, clamped to the shot). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)] #### render(shot, ctx) Render `shot` to mp4 through the engine; see the module docstring. * **Return type:** [`RenderResult`](_autosummary/an.adapters.html.md#an.adapters.RenderResult) #### supported_renderers *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ()* The `Shot.renderer` values this renderer claims (the ONE place it names them). ### *class* an.engines.LiveEngine(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) The live tier: apply, settle, capture in real time. **Declared, not built.** Its recorder resamples to a constant rate (`walkthru`’s worked example); `frame_stage_renderer` does not drive it, and never falls back to it. ### *class* an.engines.StateDriven(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) A session the core hands states to. #### render(state) PNG bytes of `state` (`supersample` times the declared size). * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) #### timeline *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* The `an.timing` `Timeline` the core evaluates. ### *class* an.engines.StateDrivenAdapter(session) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A state-driven session seen as a time-driven one: the core evaluates `at(t)`. `frame(t)` is `render(evaluate_timeline(timeline, t, space=space))` and `state(t)` is the evaluated state, so the capture loop and the conformance tests treat both drive modes alike. The session’s other members (`resolve`, `provenance`, …) are reached through attribute access. **Batched** (an#286): `frames(requests)` evaluates every instant here and hands the session the STATES, through its optional `render_states(states)` (one round trip per batch, the member a JS-bridged view engine implements), else `render` per state. A session’s own `frames` is never forwarded: it would take times and bypass `state`. **Adapted by drive mode** (an#286): `project(point, t)` and `bounds(t)` reach the session as `project(point, state)` and `bounds(state)` (the state-driven signature, previz’s `project(point, {state, ...})`), and exist only when the session has them, so [`describe()`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.describe) still reads capabilities from real members. #### frames(requests) One list of frames per request, a frame per instant, in order. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)]] ### *class* an.engines.TimeDriven(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) A session that evaluates the compiled channels itself. #### frame(t) The scene at `t` as PNG bytes (`supersample` times the declared size). * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) #### state(t) The state the engine evaluated at `t`: a sparse pose, absent = at rest. * **Return type:** [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *exception* an.engines.UnseekableEngineError Bases: [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError) A session that the frame stage cannot drive; the message says what to add. ### an.engines.capture_frames(session, requests, frames_dir, , factor=1, size=None, batch=None, workers=None, max_inflight=None, batch_pixels=None) Write one PNG per request into `frames_dir`, resolved to the declared size. `session` is time-driven (`frame(t)`), optionally batched (`frames(requests)`), optionally with its own `resolve`. A state-driven session is adapted by the frame stage before it reaches here. `size`, when known, sets the pixel budget and is passed to the resolve. `None` for any tunable reads the module default at call time. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.engines.describe(session) The tier, drive mode and features a session (or a session class) offers. * **Return type:** [`EngineProfile`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.EngineProfile) ### an.engines.drive_mode(session) `"time"`, `"state"`, or `None` for a session the frame stage cannot drive. A session with both `frame` and `render` is time-driven: it evaluates its own document, and the core does not second-guess it. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.engines.frame_stage_renderer(engine, \*, name=None, renderers=None, error=, capture_options=None) Turn `engine` into a `Renderer`: the core’s clock, capture loop, resolves and sinks. `name` defaults to the engine’s; `renderers` – the `Shot.renderer` values claimed – default to `(name,)`. `error` is the typed exception the renderer raises at its boundary for every core error. * **Return type:** [`FrameStageRenderer`](_autosummary/an.engines.frame_stage.html.md#an.engines.frame_stage.FrameStageRenderer) ### an.engines.requests_as_dicts(requests) Requests as plain dicts, the shape a page or a subprocess takes. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.engines.require_engine(engine) Refuse an object that is not an engine, saying what is missing. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> require_engine(object()) Traceback (most recent call last): ... TypeError: an Engine needs `name` and `open(job)`; object lacks: name, open ``` ### an.engines.require_seekable(session) The session’s drive mode, or a refusal that says what to add. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> require_seekable(object()) Traceback (most recent call last): ... an.engines.protocol.UnseekableEngineError: this engine session cannot be captured: it has no frame(t) (time-driven), and no render(state) with a timeline (state-driven). Add frame(t) and state(t) if the engine evaluates the timeline itself, or timeline and render(state) if the core should evaluate it. ``` ### an.engines.shot_workspace(work_dir, shot_id) `/shot_`: the one per-shot scratch directory. * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### Modules | [`capture`](_autosummary/an.engines.capture.html.md#module-an.engines.capture) | The capture loop: drive a session through every frame, resolve, write -- for ANY engine. | |--------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------| | [`conformance`](_autosummary/an.engines.conformance.html.md#module-an.engines.conformance) | Conformance of a TIME-driven engine against the timing kernel's golden vectors. | | [`frame_stage`](_autosummary/an.engines.frame_stage.html.md#module-an.engines.frame_stage) | `frame_stage_renderer(engine)`: any seekable engine becomes a `Renderer`. | | [`protocol`](_autosummary/an.engines.protocol.html.md#module-an.engines.protocol) | The `Engine` protocol: a seekable thing that turns a time, or a state, into a frame. | # _autosummary/an.engines.protocol.html.md # an.engines.protocol The `Engine` protocol: a seekable thing that turns a time, or a state, into a frame. The second of the three renderer tiers (ADR 0001 decision 12; core study §2.7): 1. `Renderer` (`an.adapters._base`) – shot in, media file out. Every back-end is reachable through it; Manim lives there, whole-shot. 2. **\`\`Engine\`\`** (this module) – `previz`’s meaning of the word: something that can show the scene at any instant and hand over the pixels. The core turns any engine into a `Renderer` with [`an.engines.frame_stage_renderer()`](_autosummary/an.engines.html.md#an.engines.frame_stage_renderer), which owns the clock, the capture loop, supersampling, the shutter and the sinks, so an engine implements none of them. 3. `LiveEngine` – apply, settle, capture in real time (`walkthru`’s recorder). **Declared, not built.** **Capabilities are read from which members exist, never from a flag** (`previz`’s rule, ADR 0002 applied to engines), so a flag can never disagree with the code. [`describe()`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.describe) is the one place that reads them. An `Engine` is a stateless factory, safe to share across the threads of a parallel render. [`Engine.open()`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine.open) loads one shot and yields a **session**: the loaded, seekable view, whose members say what it can do. And on the `Engine` itself: `check(ctx)` validates the engine’s own knobs before anything launches (a typo must fail in microseconds, not after a browser started). ```pycon >>> class _Still: ... def frame(self, t): return b"png" ... def state(self, t): return {} >>> describe(_Still()) EngineProfile(tier='seekable', drive='time', features=frozenset({'readback'})) >>> class _Crop: ... timeline = None ... def render(self, state): return b"png" >>> describe(_Crop()).drive 'state' ``` ### Module Attributes | [`DRIVE_TIME`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.DRIVE_TIME) | who evaluates the timeline. | |------------------------------------------------------------------|-------------------------------------------------------------------| | [`TIER_SEEKABLE`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.TIER_SEEKABLE) | Tiers an engine can be on (the `Renderer` tier is not an engine). | | [`FEATURE_MEMBERS`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.FEATURE_MEMBERS) | Optional session member -> the feature it unlocks. | ### Functions | [`describe`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.describe)(session) | The tier, drive mode and features a session (or a session class) offers. | |------------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`drive_mode`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.drive_mode)(session) | `"time"`, `"state"`, or `None` for a session the frame stage cannot drive. | | [`require_seekable`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.require_seekable)(session) | The session's drive mode, or a refusal that says what to add. | | [`requests_as_dicts`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.requests_as_dicts)(requests) | Requests as plain dicts, the shape a page or a subprocess takes. | ### Classes | [`Engine`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine)(\*args, \*\*kwargs) | A stateless factory of loaded, seekable sessions -- one per shot render. | |--------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`EngineProfile`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.EngineProfile)(tier, drive, features) | What a session can do, read off its members. | | [`FrameJob`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.FrameJob)(shot, ctx, workspace, frames_dir, ...) | What the frame stage asks of an engine for one shot. | | [`FrameRequest`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.FrameRequest)(frame, times) | One output frame's instants, in the order they must be captured. | | [`LiveEngine`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.LiveEngine)(\*args, \*\*kwargs) | The live tier: apply, settle, capture in real time. | | [`StateDriven`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.StateDriven)(\*args, \*\*kwargs) | A session the core hands states to. | | [`TimeDriven`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.TimeDriven)(\*args, \*\*kwargs) | A session that evaluates the compiled channels itself. | ### Exceptions | [`UnseekableEngineError`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.UnseekableEngineError) | A session that the frame stage cannot drive; the message says what to add. | |--------------------------------------------------------------------------|------------------------------------------------------------------------------| ### an.engines.protocol.DRIVE_TIME *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'time'* who evaluates the timeline. * **Type:** Drive modes (core study §2.7) ### *class* an.engines.protocol.Engine(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) A stateless factory of loaded, seekable sessions – one per shot render. #### name *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* The engine’s name (`"stage"`); also how provenance names it. #### open(job) Load `job.shot` and yield a session (see the module table). * **Return type:** [`AbstractContextManager`](https://docs.python.org/3/library/contextlib.html#contextlib.AbstractContextManager)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *class* an.engines.protocol.EngineProfile(tier, drive, features) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a session can do, read off its members. ### an.engines.protocol.FEATURE_MEMBERS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'bounds': 'bounds', 'frame_with_alpha': 'alpha', 'frames': 'batch', 'project': 'project', 'provenance': 'provenance', 'render_states': 'batch', 'resolve': 'resolve', 'state': 'readback'}* Optional session member -> the feature it unlocks. The SSOT [`describe()`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.describe) reads; a new feature is a new row, never a flag on an engine. ### *class* an.engines.protocol.FrameJob(shot, ctx, workspace, frames_dir, total_frames, supersample, frame_samples=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What the frame stage asks of an engine for one shot. Built by the core, before [`Engine.open()`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.Engine.open): every knob here is already validated, so an engine never re-derives the frame count or the factor. #### frame_samples *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), ...], ...] | [None](https://docs.python.org/3/builtins/constants.html#None)* Per frame, the instants to capture and average, or `None` for one instant at `i / fps`. #### requests() Every frame’s request, frame `i` at `i / fps` unless a clock says otherwise. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`FrameRequest`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.FrameRequest), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> from types import SimpleNamespace >>> job = FrameJob(None, SimpleNamespace(fps=4, resolution=(2, 2)), Path("."), ... Path("."), total_frames=3, supersample=1) >>> [r.times for r in job.requests()] [(0.0,), (0.25,), (0.5,)] ``` #### *property* size *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[int](https://docs.python.org/3/builtins/functions.html#int), [int](https://docs.python.org/3/builtins/functions.html#int)]* what every resolved frame must be. * **Type:** The DECLARED ([*width*](_autosummary/an.stage.paths.html.md#an.stage.paths.PathDescriptor.width), height) #### supersample *: [int](https://docs.python.org/3/builtins/functions.html#int)* the engine draws at `k` times the declared size, and the core resolves back to it. * **Type:** The validated supersample factor #### workspace *: [Path](https://docs.python.org/3/library/pathlib.html#pathlib.Path)* The shot’s own scratch directory (`/shot_`). The engine may stage files in it (the stage engine’s runtime copy); the core owns `frames/` and the delivered mp4 inside it. ### *class* an.engines.protocol.FrameRequest(frame, times) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One output frame’s instants, in the order they must be captured. One instant unless a frame clock opened the shutter (`RenderContext.frame_samples`). ### *class* an.engines.protocol.LiveEngine(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) The live tier: apply, settle, capture in real time. **Declared, not built.** Its recorder resamples to a constant rate (`walkthru`’s worked example); `frame_stage_renderer` does not drive it, and never falls back to it. ### *class* an.engines.protocol.StateDriven(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) A session the core hands states to. #### render(state) PNG bytes of `state` (`supersample` times the declared size). * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) #### timeline *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* The `an.timing` `Timeline` the core evaluates. ### an.engines.protocol.TIER_SEEKABLE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'seekable'* Tiers an engine can be on (the `Renderer` tier is not an engine). ### *class* an.engines.protocol.TimeDriven(\*args, \*\*kwargs) Bases: [`Protocol`](https://docs.python.org/3/library/typing.html#typing.Protocol) A session that evaluates the compiled channels itself. #### frame(t) The scene at `t` as PNG bytes (`supersample` times the declared size). * **Return type:** [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) #### state(t) The state the engine evaluated at `t`: a sparse pose, absent = at rest. * **Return type:** [`Mapping`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *exception* an.engines.protocol.UnseekableEngineError Bases: [`TypeError`](https://docs.python.org/3/builtins/exceptions.html#TypeError) A session that the frame stage cannot drive; the message says what to add. ### an.engines.protocol.describe(session) The tier, drive mode and features a session (or a session class) offers. * **Return type:** [`EngineProfile`](_autosummary/an.engines.protocol.html.md#an.engines.protocol.EngineProfile) ### an.engines.protocol.drive_mode(session) `"time"`, `"state"`, or `None` for a session the frame stage cannot drive. A session with both `frame` and `render` is time-driven: it evaluates its own document, and the core does not second-guess it. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.engines.protocol.requests_as_dicts(requests) Requests as plain dicts, the shape a page or a subprocess takes. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.engines.protocol.require_seekable(session) The session’s drive mode, or a refusal that says what to add. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> require_seekable(object()) Traceback (most recent call last): ... an.engines.protocol.UnseekableEngineError: this engine session cannot be captured: it has no frame(t) (time-driven), and no render(state) with a timeline (state-driven). Add frame(t) and state(t) if the engine evaluates the timeline itself, or timeline and render(state) if the core should evaluate it. ``` # _autosummary/an.environments.html.md # an.environments Moved to [`an.stage.environments`](_autosummary/an.stage.environments.html.md#module-an.stage.environments) (an#247); this path is a LIVE alias of it. The 2D stage runtime is the first engine, outside the core’s import firewall (ADR 0001 decisions 5 and 14). Every name of the new module is reachable here, and rebinding one here (a bench lever, `monkeypatch`) rebinds it there, where the code runs (`an._shims.alias_module()`). # _autosummary/an.formats.html.md # an.formats Numbers as text: a declared subset of d3-format, for counters (an#342). A counter text block ([`an.stage.text.TextDescriptor`](_autosummary/an.stage.text.html.md#an.stage.text.TextDescriptor) `counter`) shows a number that moves; what it draws is a string, and this module is the one statement of how the number becomes the string. The format is a \*\*declared mini-language, not Python’s\*\* `str.format` (which allows attribute access, states no rounding and is not reproducible in a browser): one d3-format specifier in braces, with optional literal text around it. ```pycon >>> format_number(7, "Day {d}") 'Day 7' >>> format_number(1234567, "{,d}") '1,234,567' >>> format_number(21.456, "{.1f} °C") '21.5 °C' >>> format_number(0.256, "{.0%}") '26%' >>> format_number(1500, "{.2s}") '1.5k' ``` The subset, and what each specifier means (d3-format’s meaning, so a JavaScript consumer can reproduce it with `d3.format`): | `d` | an integer | |-------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `,d` | an integer with `,` between thousands | | `.Nf` | fixed point, `N` decimals | | `.N%` | times 100, fixed point, `N` decimals, then `%` | | `s` | `N` significant digits (`.Ns`; default 6) with an SI prefix
(`k`, `M`, `G`, …, `m`; `µ` and smaller are refused at
typesetting by a face that lacks the glyph) | **Rounding is to nearest, ties to even, on the float’s exact value** (Python’s own correctly rounded formatting): `2.5` → `2` and `3.5` → `4` under `d`; `0.125` → `0.12` under `.2f`. d3 rounds ties away from zero, so a JavaScript reproduction must round half to even to agree on exact ties (the frame grid rarely lands on one). Two further departures from d3’s defaults, both stated: the minus sign is `-` (U+002D), because the embedded face has no U+2212, and a value that rounds to zero never carries a sign (`-0.4` → `0`), which is d3’s own rule. ### Module Attributes | [`DFLT_SI_PRECISION`](_autosummary/an.formats.html.md#an.formats.DFLT_SI_PRECISION) | d3's default of 6 significant digits. | |----------------------------------------------------------------------|-----------------------------------------| ### Functions | [`parse_format`](_autosummary/an.formats.html.md#an.formats.parse_format)(fmt) | Parse `fmt`: literal text around exactly one `{specifier}`. | |----------------------------------------------------------------------------|---------------------------------------------------------------| | [`format_number`](_autosummary/an.formats.html.md#an.formats.format_number)(value, fmt) | `value` drawn as `fmt` says (see the module docstring). | ### Classes | [`NumberFormat`](_autosummary/an.formats.html.md#an.formats.NumberFormat)(prefix, type, precision, comma, ...) | A parsed format: literal `prefix`, the specifier, literal `suffix`. | |------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------| ### Exceptions | [`CounterFormatError`](_autosummary/an.formats.html.md#an.formats.CounterFormatError) | A counter `format` outside the declared subset. | |-----------------------------------------------------------------------|---------------------------------------------------| ### *exception* an.formats.CounterFormatError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A counter `format` outside the declared subset. ### an.formats.DFLT_SI_PRECISION *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 6* d3’s default of 6 significant digits. * **Type:** `s` with no precision ### *class* an.formats.NumberFormat(prefix, type, precision, comma, suffix) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A parsed format: literal `prefix`, the specifier, literal `suffix`. ### an.formats.format_number(value, fmt) `value` drawn as `fmt` says (see the module docstring). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> [format_number(v, "{d}") for v in (2.5, 3.5, -0.4, 29.5)] ['2', '4', '0', '30'] >>> format_number(-1234.5, "{,d}") '-1,234' ``` ### an.formats.parse_format(fmt) Parse `fmt`: literal text around exactly one `{specifier}`. * **Return type:** [`NumberFormat`](_autosummary/an.formats.html.md#an.formats.NumberFormat) ```pycon >>> parse_format("Day {d}").prefix 'Day ' >>> parse_format("{.3d}") Traceback (most recent call last): ... an.formats.CounterFormatError: counter format '{.3d}': `d` takes no precision (it is an integer); the subset is d, ,d, .Nf, .N%, s, .Ns ``` # _autosummary/an.frame_clock.html.md # an.frame_clock The frame clock: WHEN each output frame samples scene time. A render has always sampled frame `i` at exactly `i / fps` — one instant, on a perfect grid. A real camera does neither: its shutter stays open for part of the frame period (so a moving object smears), and its capture instants wander around the nominal grid (so the timestamp a frame carries is not quite when it was taken). Anything that wants to *measure* motion from video — the sub-frame impact estimators `an.impacts` exists to score — needs both, and needs to know exactly what was done. [`FrameClock`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock) is that model as data. [`FrameClock.frames()`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock.frames) returns one [`CapturedFrame`](_autosummary/an.frame_clock.html.md#an.frame_clock.CapturedFrame) per output frame, carrying the exposure interval and the instants integrated over it; [`FrameClock.sample_times()`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock.sample_times) is the projection the renderer consumes through `RenderContext.frame_samples`. One object feeds both the render and the ground truth, so the two cannot disagree about when a frame was taken. The default clock is the old behaviour exactly — no exposure, no jitter, one sample at `i / fps`: ```pycon >>> FrameClock(fps=4).sample_times(1.0) ((0.0,), (0.25,), (0.5,), (0.75,)) ``` A 180-degree shutter (`exposure=0.5`) integrates the first half of each frame period, sampled at the midpoints of `samples` equal sub-intervals: ```pycon >>> FrameClock(fps=4, exposure=0.5, samples=2).sample_times(0.5) ((0.03125, 0.09375), (0.28125, 0.34375)) >>> f = FrameClock(fps=4, exposure=0.5, samples=2).frames(0.5)[1] >>> (f.t_nominal, f.t_open, f.t_close, f.t_mid) (0.25, 0.25, 0.375, 0.3125) ``` Capture jitter moves each frame’s exposure as a unit, never out of order: ```pycon >>> clock = FrameClock(fps=30, jitter_sd=0.004, seed=7) >>> opens = [f.t_open for f in clock.frames(2.0)] >>> all(b > a for a, b in zip(opens, opens[1:])) True >>> clock.frames(2.0) == clock.frames(2.0) # seeded: the same clock twice True ``` ### Module Attributes | [`DEFAULT_EXPOSURE_SAMPLES`](_autosummary/an.frame_clock.html.md#an.frame_clock.DEFAULT_EXPOSURE_SAMPLES) | Sub-samples integrated per frame when the shutter is open and the caller did not say how many. | |-----------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| | [`MAX_JITTER_FRACTION`](_autosummary/an.frame_clock.html.md#an.frame_clock.MAX_JITTER_FRACTION) | A frame's capture offset is clamped to this fraction of the slack between one exposure closing and the next opening, on each side. | | [`MAX_REPORT_NOISE_FRACTION`](_autosummary/an.frame_clock.html.md#an.frame_clock.MAX_REPORT_NOISE_FRACTION) | Report noise is clamped to this fraction of the frame period, each side, so two neighbouring reported timestamps can never cross on a regular grid. | ### Functions | [`frame_count`](_autosummary/an.frame_clock.html.md#an.frame_clock.frame_count)(duration, fps) | Frames in a render of `duration` seconds — the renderer's own rule. | |-------------------------------------------------------------------------------|-----------------------------------------------------------------------| ### Classes | [`CapturedFrame`](_autosummary/an.frame_clock.html.md#an.frame_clock.CapturedFrame)(index, t_nominal, t_open, ...) | One output frame: when its exposure opened and closed, and what it saw. | |-------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | [`FrameClock`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock)([fps, exposure, samples, ...]) | A camera's timing, as data. | ### Exceptions | [`FrameClockError`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClockError) | A frame clock that cannot describe a camera. | |--------------------------------------------------------------------|------------------------------------------------| ### *class* an.frame_clock.CapturedFrame(index, t_nominal, t_open, t_close, samples, t_reported) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One output frame: when its exposure opened and closed, and what it saw. `t_nominal` is `index / fps` — what a constant-rate container (an mp4) says the frame’s time is. `samples` are the instants actually rendered and averaged into it; `t_mid` is the middle of the exposure, the single best instant to attribute a blurred frame to. `t_reported` is the timestamp a capture pipeline hands downstream: nominal or actual, per the clock’s `timestamps` setting. ### an.frame_clock.DEFAULT_EXPOSURE_SAMPLES *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 8* Sub-samples integrated per frame when the shutter is open and the caller did not say how many. Eight midpoint samples put the smear of an object crossing 100 px in one exposure at steps of ~12 px — continuous to a tracker, cheap to render (each sample is one screenshot). ### *class* an.frame_clock.FrameClock(fps=30.0, exposure=0.0, samples=None, jitter_sd=0.0, phase=0.0, timestamps='nominal', report_noise_sd=0.0, seed=0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A camera’s timing, as data. Every field defaults to the ideal camera. `fps`: nominal frame rate (need not be an integer: 29.97 is a camera). `exposure`: fraction of the frame period the shutter is open, in `[0, 1]`; 0 is an instantaneous sample, 0.5 a 180-degree shutter. `samples`: instants integrated per open exposure (midpoint rule); `None` means 1 when `exposure == 0` and [`DEFAULT_EXPOSURE_SAMPLES`](_autosummary/an.frame_clock.html.md#an.frame_clock.DEFAULT_EXPOSURE_SAMPLES) otherwise. `jitter_sd`: standard deviation, in seconds, of each frame’s CAPTURE offset from the nominal grid — the frame really is taken early or late. Gaussian, clamped at [`max_jitter`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock.max_jitter) so frames never overlap; a `jitter_sd` above half that clamp is refused rather than silently shrunk (at `exposure=1` there is no room for any). `phase`: seconds added to every capture instant — the camera clock’s sub-frame offset from scene time, in `(-1/fps, 1/fps)`. `timestamps`: the base of `CapturedFrame.t_reported` — `"nominal"` (`index / fps`, what a naive tick loop or an mp4 reports) or `"actual"` (`t_open`, what a capture API with real timestamps reports). `report_noise_sd`: Gaussian noise, in seconds, added to the REPORTED timestamp only — regular capture, noisy clock (a browser frame callback). Clamped at [`MAX_REPORT_NOISE_FRACTION`](_autosummary/an.frame_clock.html.md#an.frame_clock.MAX_REPORT_NOISE_FRACTION) of a frame period, with the same refuse-rather-than-shrink rule as `jitter_sd`, and reported timestamps must still increase: a real frame clock never runs backwards. `seed`: the random streams (capture jitter and report noise are independent draws from it). Every instant is clipped into `[0, duration]`, because a render cannot sample a scene outside its own timeline; the clipped values are what [`frames()`](_autosummary/an.frame_clock.html.md#an.frame_clock.FrameClock.frames) returns and what gets rendered. #### frames(duration) One [`CapturedFrame`](_autosummary/an.frame_clock.html.md#an.frame_clock.CapturedFrame) per output frame of a `duration` render. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`CapturedFrame`](_autosummary/an.frame_clock.html.md#an.frame_clock.CapturedFrame), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] #### *property* max_jitter *: [float](https://docs.python.org/3/builtins/functions.html#float)* The clamp on a frame’s capture offset, in seconds. ```pycon >>> round(FrameClock(fps=10, exposure=0.5).max_jitter, 9) 0.0245 ``` #### sample_times(duration) Per frame, the scene instants to render and average — the render seam. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)], [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] #### *property* samples_per_frame *: [int](https://docs.python.org/3/builtins/functions.html#int)* 1 for an instantaneous shutter. ```pycon >>> FrameClock().samples_per_frame, FrameClock(exposure=0.5).samples_per_frame (1, 8) ``` * **Type:** The resolved sample count ### *exception* an.frame_clock.FrameClockError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A frame clock that cannot describe a camera. ### an.frame_clock.MAX_JITTER_FRACTION *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.49* A frame’s capture offset is clamped to this fraction of the slack between one exposure closing and the next opening, on each side. Below one half, so two neighbouring frames can each move toward the other by the full clamp and still not overlap: the clock never reorders frames, whatever `jitter_sd` is. ### an.frame_clock.MAX_REPORT_NOISE_FRACTION *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.24* Report noise is clamped to this fraction of the frame period, each side, so two neighbouring reported timestamps can never cross on a regular grid. ### an.frame_clock.frame_count(duration, fps) Frames in a render of `duration` seconds — the renderer’s own rule. * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ```pycon >>> frame_count(2.0, 30), frame_count(0.01, 30) (60, 1) ``` # _autosummary/an.genres.html.md # an.genres Genres: what a kind of animation adds to the core, declared as one object. ADR 0001 decisions 2-4 and the core study §2.15. A **genre** (cut-out animation, data visualisation, mathematical explainers, …) extends the core by *registration*, never by editing a core `if kind == …` chain. It is one plain, declarative [`Genre`](_autosummary/an.genres.html.md#an.genres.Genre) object — the shape `shaping` uses (“a new genre is one file”) — listing what it registers: - **action kinds** ([`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind)): a model, how it occupies time, how `scene.md` spells it; - **entity kinds** ([`EntityKind`](_autosummary/an.genres.html.md#an.genres.EntityKind)), each naming the property space its nodes live in, plus any new **property spaces** and **field kinds** for the timing kernel ([`an.timing`](_autosummary/an.timing.html.md#module-an.timing)); - **semantic checks** ([`SemanticCheck`](_autosummary/an.genres.html.md#an.genres.SemanticCheck)) that `an validate` runs; - **md sugar** ([`DialogueSugar`](_autosummary/an.genres.html.md#an.genres.DialogueSugar)) on `scene.md` dialogue lines; - **capabilities** and **analysers** ([`an.capabilities`](_autosummary/an.capabilities.html.md#module-an.capabilities), ADR 0002): the capability names its methods require and the derivation of what its assets afford; - **vocabulary** entries — presets, methods, IR-field notes — and **aspects** with their default chains ([`an.semantic`](_autosummary/an.semantic.html.md#module-an.semantic), ADR 0003). Because the object is plain data, a genre is \*\*inspectable before it is loaded\*\*: [`available()`](_autosummary/an.genres.html.md#an.genres.available) reads every installed genre’s declaration without registering anything, which is how an unregistered kind’s error can name the package that provides it. **Discovery is explicit, never at import time** (decision 3). Importing `an` registers no genre. [`load()`](_autosummary/an.genres.html.md#an.genres.load) reads the `an.genres` entry point group and registers each genre it finds; `an.load(project)`, the `an` CLI and (later) the MCP entry call it, and anyone can. A package declares its genre as: ```default [project.entry-points."an.genres"] cutout_animation = "cutan.genre:CUTOUT" ``` [`register_genre()`](_autosummary/an.genres.html.md#an.genres.register_genre) installs a genre object directly (a test, a notebook, a genre defined in the same process). ```pycon >>> from an.genres import Genre, register_genre, installed, without_genres >>> with without_genres(): ... installed() () >>> demo = Genre("demo_genre", title="Demo") >>> with without_genres(): ... _ = register_genre(demo) ... installed() ('demo_genre',) ``` ### Module Attributes | [`ENTRY_POINT_GROUP`](_autosummary/an.genres.html.md#an.genres.ENTRY_POINT_GROUP) | The entry-point group a genre package declares its [`Genre`](_autosummary/an.genres.html.md#an.genres.Genre) under. | |-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------| | [`API_LEVEL`](_autosummary/an.genres.html.md#an.genres.API_LEVEL) | every hook, registry field and moved path a genre package may rely on. | | [`IN_DISTRIBUTION_GENRES`](_autosummary/an.genres.html.md#an.genres.IN_DISTRIBUTION_GENRES) | Genres the `an` distribution itself ships, as entry-point values. | ### Functions | [`require_api_level`](_autosummary/an.genres.html.md#an.genres.require_api_level)(level, \*, package) | Refuse, with an upgrade hint, when this `an` is older than `package` needs. | |---------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`hook_modules`](_autosummary/an.genres.html.md#an.genres.hook_modules)(\*[, exclude_owner]) | The modules whose code the genres' registered hooks run, sorted and unique. | | [`register_service`](_autosummary/an.genres.html.md#an.genres.register_service)(name, target, \*[, owner, ...]) | Register a named service a genre offers the core (an#225). | | [`require_service`](_autosummary/an.genres.html.md#an.genres.require_service)(name, \*[, what, extra]) | The registered service `name`; a typed error naming the install when absent. | | [`service`](_autosummary/an.genres.html.md#an.genres.service)(name[, default]) | The registered service `name`, resolved, or `default` when none is. | | [`services`](_autosummary/an.genres.html.md#an.genres.services)(prefix) | `{name without the prefix: resolved service}` for every service under `prefix`. | | [`action_kind`](_autosummary/an.genres.html.md#an.genres.action_kind)(name) | The registered kind called `name`, or `None`. | | [`action_kind_names`](_autosummary/an.genres.html.md#an.genres.action_kind_names)(\*[, owner]) | Registered action-kind names in registration order; `owner`'s only when given. | | [`available`](_autosummary/an.genres.html.md#an.genres.available)(\*[, entry_points, builtin]) | Every discoverable genre's declaration, by name — read, never registered. | | `entity_kind`(name) | | | `entity_kind_names`(\*[, owner]) | | | [`entity_space_resolver`](_autosummary/an.genres.html.md#an.genres.entity_space_resolver)(entities, \*[, default]) | `target -> PropertySpace`: the space its ENTITY's kind declares. | | [`discovered_entry_points`](_autosummary/an.genres.html.md#an.genres.discovered_entry_points)(\*[, entry_points, ...]) | The in-distribution genres (`builtin`; none since the cut-out genre moved to `cutan`, an#225) merged with `entry_points` (default: the installed ones), de-duplicated by name — the in-distribution declaration first. | | [`genre_entry_points`](_autosummary/an.genres.html.md#an.genres.genre_entry_points)(\*[, group]) | The installed `an.genres` entry points (nothing is imported). | | [`genres_declaring`](_autosummary/an.genres.html.md#an.genres.genres_declaring)(test) | The installed genres (loaded or not) whose declaration passes `test`. | | [`installed`](_autosummary/an.genres.html.md#an.genres.installed)() | The names of the genres registered in this process, in registration order. | | [`genre_library`](_autosummary/an.genres.html.md#an.genres.genre_library)(name, \*[, default]) | The package whose data root holds genre `name`'s library and projects. | | `installed_genre`(name) | | | [`load`](_autosummary/an.genres.html.md#an.genres.load)(\*[, entry_points, builtin]) | Register every discoverable genre. | | [`providers_of`](_autosummary/an.genres.html.md#an.genres.providers_of)(kind, \*[, registry]) | The installed genres (loaded or not) that declare `kind` in `registry` (a key of [`Genre.provides()`](_autosummary/an.genres.html.md#an.genres.Genre.provides)). | | [`register_genre`](_autosummary/an.genres.html.md#an.genres.register_genre)(genre, \*[, replace, ...]) | Register everything `genre` declares, owned by `genre.name`. | | [`without_genres`](_autosummary/an.genres.html.md#an.genres.without_genres)() | Run a block with no genre registered (the core alone), then restore. | ### Classes | [`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind)(name, model[, duration, flatten, ...]) | One kind of action: its model, how it occupies time, how `scene.md` spells it. | |------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`CompilePass`](_autosummary/an.genres.html.md#an.genres.CompilePass)(name, run[, order, compiler, ...]) | One step a genre adds to an engine's COMPILER (shot -> compiled document). | | [`RuntimeScript`](_autosummary/an.genres.html.md#an.genres.RuntimeScript)(name, source[, engine, ...]) | JavaScript a genre adds to an engine's RUNTIME (an#247; ADR 0001 decision 4, second batch): for the stage, code that registers visual kinds with `window.anRegisterVisual(kind, make)` -- how the cut-out mouth and eye leave `runtime.js` for `cutan` (P8). | | [`SwapDeclaration`](_autosummary/an.genres.html.md#an.genres.SwapDeclaration)(sets[, descriptor, ...]) | What one entity's descriptor declares for the stage compiler's swap vocabulary. | | [`DialogueSugar`](_autosummary/an.genres.html.md#an.genres.DialogueSugar)(name, opener, field, parse, format) | `scene.md` sugar on a dialogue line: one bracket pair, one `Dialogue` field (and, declared in `fields`, the parameters it may carry). | | [`EntityKind`](_autosummary/an.genres.html.md#an.genres.EntityKind)(name[, space, store, ...]) | One kind of entity (`AssetRef.kind`): what its nodes' properties are. | | [`Genre`](_autosummary/an.genres.html.md#an.genres.Genre)(name[, title, description, package, ...]) | A genre: one plain, declarative object listing what it registers. | | [`SemanticCheck`](_autosummary/an.genres.html.md#an.genres.SemanticCheck)(name, run[, stage, order, ...]) | One semantic-validation check: `run(ctx)` adds findings to `ctx.report`. | ### Exceptions | [`GenreAPILevelError`](_autosummary/an.genres.html.md#an.genres.GenreAPILevelError) | A genre package needs a newer `an` than the one installed. | |-----------------------------------------------------------------------------------------------|------------------------------------------------------------------------| | [`ServiceMissingError`](_autosummary/an.genres.html.md#an.genres.ServiceMissingError) | The core asked a genre for a service nobody registered. | | [`GenreError`](_autosummary/an.genres.html.md#an.genres.GenreError) | A genre declaration is malformed, or its entry point does not resolve. | | [`RegistryError`](_autosummary/an.genres.html.md#an.genres.RegistryError) | A registration is malformed or collides with one already made. | | [`UnregisteredKindError`](_autosummary/an.genres.html.md#an.genres.UnregisteredKindError)(what, name, \*[, ...]) | A document names a kind no loaded genre registered. | ### an.genres.API_LEVEL *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 6* every hook, registry field and moved path a genre package may rely on. Bumped by each change a genre needs (the P8 seam PRs and each move to `cutan`, an#225), never decremented. A genre states the lowest level it needs with [`require_api_level()`](_autosummary/an.genres.html.md#an.genres.require_api_level), which is how “the genre declares the lowest `an` it supports” (ADR 0001 decision 8) is said without a version pin: `an`’s version is assigned by CI at merge, so no PR can name the release it ships in. A genre package must also run against an `an` older than this constant: it reads `getattr(an.genres, "API_LEVEL", 0)` before calling [`require_api_level()`](_autosummary/an.genres.html.md#an.genres.require_api_level), and raises its own typed error when it is missing. Levels (one line each; `tests/test_genre_gate.py` holds the list complete): 1 = moved-module shims (`an._shims.moved_to_package`) and this check (an#296, P8 B0a). 2 = the cut-out genre’s move (an#225): `Genre.services`, `ActionKind.lowering`, > `EntityKind.swap_declaration`, `an.stage.rig`. 3 = the public rig builder (an#338): `an.stage.rig.build_rig_subtree`, `rig_origin`, : `RigDocument` (`origin`), `omit_unset_rig_fields`, `an.stage.compile.note_raster_rig`. 4 = the bones’ rest pose (an#339): `an.stage.rig.register_rest_pose_migration`, : `rig_rest_problems`, `RigDocument.rest_rotation`. 5 = nested chains (an#340): `build_rig_subtree(skip_slots=)`, `slot_parent_chain`, : `slot_node_paths`, `rig_problems`, `rig_affordances`, `RigError`, `rig.hierarchy`. 6 = the rest pose’s protection said aloud (an#407): `an.stage.rig.rest_pose_protection`. * **Type:** The level of the genre-facing API this `an` provides ### *class* an.genres.ActionKind(name, model, duration=None, flatten=None, children=None, read_md=None, write_md=None, md_start=True, description='', version='1', lowering=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One kind of action: its model, how it occupies time, how `scene.md` spells it. - `model` validates a document’s action of this kind. A genre’s model subclasses [`an.ir.schema.ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction); the core’s are the static members of the schema’s union. - `duration` is a LEAF’s natural length; a leaf flattens to one `FlatAction` on `[t, t + duration]` and advances a `sequence` by it. - `flatten` replaces that default for kinds that place themselves differently (`set` does not advance the cursor) or that hold children (`sequence`): `flatten(action, t, ctx) -> new cursor`, where `ctx` is [`an.ir.compose.FlattenContext`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlattenContext). - `children` lists a composite’s child actions, so generic walkers (validation) reach every leaf without knowing the kind. - `read_md` / `write_md` are the `scene.md` `yaml actions` hooks: `read_md(item, index=i) -> action` (`start:` already removed when `md_start`) and `write_md(action) -> dict` (without `start`). A kind with no `read_md` has no `scene.md` form. #### lowering *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* How the STAGE compiler turns an action of this kind into clips, for a kind that is not a plain tween or set (the cut-out `play`): an object with `extent_resolver(vocab, *, products)`, `expand(flat_list, *, vocab, fps, step_hz, default_easing, resolutions, products)`, `view_of(entity_swaps, vocab, *, duration)` and `clip(action, *, anim_id, vocab, fps, view)` – see [`an.stage.compile.ActionLowering`](_autosummary/an.stage.compile.html.md#an.stage.compile.ActionLowering). `None`: the compiler has nothing kind-specific to do. (an#225: this is how the compiler stops naming `play`.) #### md_start *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* Does `start:` in `scene.md` wrap this kind in `sequence(delay(start), …)`? #### version *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '1'* bump when what an action of this kind compiles to changes for the same fields, so the shots that use it re-render visibly ([`an.semantic`](_autosummary/an.semantic.html.md#module-an.semantic) folds it into the shot digest). * **Type:** The kind’s vocabulary version (ADR 0003) ### *class* an.genres.CompilePass(name, run, order=0.0, compiler='stage', builds=None, description='', replace=False) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One step a genre adds to an engine’s COMPILER (shot -> compiled document). A compiler (`compiler`: today `"stage"`, [`an.stage.compile`](_autosummary/an.stage.compile.html.md#module-an.stage.compile)) runs its own passes plus every registered one, in `order`. A pass with `builds` set is an ENTITY BUILDER instead: the compiler’s scene pass calls it for each entity of that kind (the cut-out genre’s `rig` builds a `character`); builders with a lower `order` build all their entities first (the stage’s backdrop before the cast), equal orders in entity order. `run` is the callable, or `"module:function"`, resolved on first use – so a genre is inspectable ([`an.genres.available()`](_autosummary/an.genres.html.md#an.genres.available)) without importing the engine its passes target. What `run` receives is the compiler’s business (the stage hands a pass its `CompileState`, a builder the entity and the scene being built); the core never calls it. #### replace *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* Explicitly take the place of the ENGINE’s own pass of this name (or its builder for `builds`). Without it a name or kind the engine already has is refused when the compiler runs; with it the replacement is recorded in the compiled document (review of an#270, S3). #### resolve() The callable `run` names. * **Return type:** [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> CompilePass("p", "math:sqrt").resolve()(4.0) 2.0 ``` ### *class* an.genres.DialogueSugar(name, opener, field, parse, format, description='', fields=()) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) `scene.md` sugar on a dialogue line: one bracket pair, one `Dialogue` field (and, declared in `fields`, the parameters it may carry). `parse(content) -> value` turns what is between the brackets into the field’s value (raise `ValueError(why)` to refuse it); `format(line) -> str | None` is the inverse (the content, without brackets, or `None` when the line carries none). The cut-out genre’s `[emotion]` is one. A sugar that also sets other `Dialogue` fields (`[angry 0.4]`: the emotion and its `emotion_intensity`, an#253) names them in `fields`; its `parse` then returns `{field name: value}` over `field` and any of `fields`, and `format` writes them back. #### values(content) `{Dialogue field: value}` for the bracket `content` (`parse`, checked against what the sugar declares). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.genres.ENTRY_POINT_GROUP *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'an.genres'* The entry-point group a genre package declares its [`Genre`](_autosummary/an.genres.html.md#an.genres.Genre) under. ### *class* an.genres.EntityKind(name, space=None, store=None, description='', version='1', swap_declaration=None, descriptor_kind=None, placeholder_on_missing=False, swap_checks=None, specimen=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One kind of entity (`AssetRef.kind`): what its nodes’ properties are. `space` names the registered [`an.timing.spaces.PropertySpace`](_autosummary/an.timing.spaces.html.md#an.timing.spaces.PropertySpace) its nodes’ properties live in (`None`: the entity has no animatable nodes, as a voice); `store` is the project-mall store its `ref` keys into. #### descriptor_kind *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The `kind` tag of the descriptor document `store` holds for this kind (`"CharacterDescriptor"`): what makes the validator treat the entity as a rig whose declared asset sets it can check (an#246). #### placeholder_on_missing *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* A missing `ref` is NOT an error because the compiler draws a placeholder instead; the genre reports it with its own (warning) check. #### specimen *: [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* a short shot showing one entity of this kind on its own, the one `ref` casts — what `an library sheet` draws for a version of it (an#347). `None`: the sheet shows a labelled placeholder. * **Type:** `(ref: AssetRef) -> Shot` #### swap_checks *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* an object with `missing_set_hint(prop) -> str` (appended to “names no declared asset set”) and `whole_entity(action, desc, prop, keys, entity_id, *, where, report, art_exists) -> bool` (judge a swap on the entity ITSELF; `True` when handled). `None`: the generic per-node rule only. * **Type:** Extra swap-reference checks for this kind #### swap_declaration *: [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[Any](https://docs.python.org/3/library/typing.html#typing.Any), [Any](https://docs.python.org/3/library/typing.html#typing.Any)], [SwapDeclaration](_autosummary/an.genres.registry.html.md#an.genres.registry.SwapDeclaration) | [None](https://docs.python.org/3/builtins/constants.html#None)] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* what the entity’s descriptor declares for the stage compiler’s swap vocabulary (an#87). `None`: the kind declares nothing (its built nodes’ sets ARE its declaration). * **Type:** `(entity, mall) -> SwapDeclaration | None` #### version *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '1'* The kind’s vocabulary version (ADR 0003), as [`ActionKind.version`](_autosummary/an.genres.html.md#an.genres.ActionKind.version). ### *class* an.genres.Genre(name, title='', description='', package='', library='', action_kinds=(), entity_kinds=(), spaces=(), field_kinds=(), checks=(), dialogue_sugar=(), capabilities=(), analysers=(), vocabulary=(), aspects=(), compile_passes=(), runtime_scripts=(), services=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A genre: one plain, declarative object listing what it registers. `name` is the genre’s persisted slug (`cutout_animation`); it is also the owner of every entry it registers. `package` names the distribution that ships it, for error messages. Every collection defaults to empty, so a later phase adds a field (compile passes, vocabulary, capabilities) without touching any genre that does not use it. `spaces` are [`an.timing.spaces.PropertySpace`](_autosummary/an.timing.spaces.html.md#an.timing.spaces.PropertySpace) objects and `field_kinds` are `(name, factory)` pairs for [`an.timing.kinds.register_kind()`](_autosummary/an.timing.kinds.html.md#an.timing.kinds.register_kind). `capabilities` are [`an.capabilities.Capability`](_autosummary/an.capabilities.html.md#an.capabilities.Capability) objects, `analysers` [`an.capabilities.Analyser`](_autosummary/an.capabilities.html.md#an.capabilities.Analyser) objects, `vocabulary` [`an.semantic.Entry`](_autosummary/an.semantic.html.md#an.semantic.Entry) objects (methods included) and `aspects` [`an.semantic.Aspect`](_autosummary/an.semantic.html.md#an.semantic.Aspect) objects; registering the genre checks the whole ([`an.semantic.check_registry()`](_autosummary/an.semantic.html.md#an.semantic.check_registry)): every aspect’s chain ends in a method that requires nothing, and every requirement names a registered capability. `library` names the package whose data root holds the genre’s asset library and its projects (`~/.local/share/`, ADR 0005, plan §1 decision 7); empty means the core’s (`an`). It is not `package`: the distribution that ships a genre and the root its data lives under can differ (the cut-out genre ships inside `an` today, while its library is already `cutan`’s). The core never names a genre’s library itself — a project made in a genre asks the genre ([`genre_library()`](_autosummary/an.genres.html.md#an.genres.genre_library)). #### compile_passes *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[CompilePass](_autosummary/an.genres.registry.html.md#an.genres.registry.CompilePass), ...]* *= ()* Steps the genre adds to an engine’s compiler, and builders for its entity kinds ([`CompilePass`](_autosummary/an.genres.html.md#an.genres.CompilePass); an#247). #### provides() What this genre registers, by registry, as names — without registering it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)]] ```pycon >>> Genre("g", action_kinds=()).provides()["action kinds"] () ``` #### runtime_scripts *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[RuntimeScript](_autosummary/an.genres.registry.html.md#an.genres.registry.RuntimeScript), ...]* *= ()* its visual kinds ([`RuntimeScript`](_autosummary/an.genres.html.md#an.genres.RuntimeScript); an#247). * **Type:** Code the genre adds to an engine’s runtime #### services *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [object](https://docs.python.org/3/builtins/functions.html#object)]* `{name: object or "module:attr"}` the genre offers the core by name ([`register_service()`](_autosummary/an.genres.html.md#an.genres.register_service); an#225): the CLI namespaces it adds (`cli.`), its lip-sync providers (`lipsync.`), and the other places the core asks “is there a genre that does this?”. ### *exception* an.genres.GenreAPILevelError Bases: [`GenreError`](_autosummary/an.genres.html.md#an.genres.GenreError), [`ImportError`](https://docs.python.org/3/builtins/exceptions.html#ImportError) A genre package needs a newer `an` than the one installed. ### *exception* an.genres.GenreError Bases: [`RegistryError`](_autosummary/an.genres.registry.html.md#an.genres.registry.RegistryError) A genre declaration is malformed, or its entry point does not resolve. ### an.genres.IN_DISTRIBUTION_GENRES *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)], ...]* *= ()* Genres the `an` distribution itself ships, as entry-point values. They are found by [`load()`](_autosummary/an.genres.html.md#an.genres.load) WITHOUT relying on installed metadata: an editable install made before the `an.genres` group existed never refreshes its `dist-info`, and a missing entry point must never silently drop a genre that ships in the same distribution as the core (review-244 S1). Still explicit discovery (only [`load()`](_autosummary/an.genres.html.md#an.genres.load) reads it, never an import). Every genre is external now: the cut-out genre moved to `cutan` (an#225) and comes through the `an.genres` entry point alone. ### *exception* an.genres.RegistryError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A registration is malformed or collides with one already made. ### *class* an.genres.RuntimeScript(name, source, engine='stage', description='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) JavaScript a genre adds to an engine’s RUNTIME (an#247; ADR 0001 decision 4, second batch): for the stage, code that registers visual kinds with `window.anRegisterVisual(kind, make)` – how the cut-out mouth and eye leave `runtime.js` for `cutan` (P8). `source` is `"package:relative/path.js"`, read with [`importlib.resources`](https://docs.python.org/3/library/importlib.resources.html#module-importlib.resources) when the engine stages its runtime, so it ships in the genre’s wheel. The staged code is part of the shot cache’s key. #### code() The script’s code (UTF-8). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> RuntimeScript("x", "an.stage.runtime:extensions.js").code().startswith("//") True ``` ### *class* an.genres.SemanticCheck(name, run, stage='shot', order=0.0, description='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One semantic-validation check: `run(ctx)` adds findings to `ctx.report`. `ctx` is [`an.ir.validate.ValidationContext`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationContext); a `shot` check is called once per shot with `ctx.shot` set. Within a stage, checks run by `order` (then registration order), so a genre’s check lands exactly where it belongs in the report. ### *exception* an.genres.ServiceMissingError Bases: [`RegistryError`](_autosummary/an.genres.registry.html.md#an.genres.registry.RegistryError), [`ImportError`](https://docs.python.org/3/builtins/exceptions.html#ImportError) The core asked a genre for a service nobody registered. ### *class* an.genres.SwapDeclaration(sets, descriptor=None, art_exists=None, scale=1.0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What one entity’s descriptor declares for the stage compiler’s swap vocabulary. `sets` is `{set name: {KEY: attachment name}}` as declared; `descriptor` is the (migrated) document the declaration came from, kept for the kind’s own lowering; `art_exists` answers `rel_path -> art on disk` (`None` when the store cannot say); `scale` is the factor from the entity’s view box to scene pixels. ### *exception* an.genres.UnregisteredKindError(what, name, , known=(), providers=(), where='') Bases: [`RegistryError`](_autosummary/an.genres.registry.html.md#an.genres.registry.RegistryError) A document names a kind no loaded genre registered. The message names the installed genres that *could* provide it (read from their declarations, which are inspectable without loading them), so the fix is one line: `an.genres.load()`, or installing the package named. ### an.genres.action_kind(name) The registered kind called `name`, or `None`. * **Return type:** [`ActionKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.ActionKind) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.genres.action_kind_names(, owner=None) Registered action-kind names in registration order; `owner`’s only when given. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.available(, entry_points=None, builtin=True) Every discoverable genre’s declaration, by name — read, never registered. The in-distribution genres plus the entry points ([`discovered_entry_points()`](_autosummary/an.genres.html.md#an.genres.discovered_entry_points)). A genre whose entry point does not import is left out (its error is what [`load()`](_autosummary/an.genres.html.md#an.genres.load) raises). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Genre`](_autosummary/an.genres.html.md#an.genres.Genre)] ### an.genres.discovered_entry_points(, entry_points=None, builtin=True) The in-distribution genres (`builtin`; none since the cut-out genre moved to `cutan`, an#225) merged with `entry_points` (default: the installed ones), de-duplicated by name — the in-distribution declaration first. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`EntryPoint`](https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.EntryPoint), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> [ep.name for ep in discovered_entry_points(entry_points=())] [] ``` ### an.genres.entity_space_resolver(entities, , default=None) `target -> PropertySpace`: the space its ENTITY’s kind declares. The ONE policy for “what are this target’s properties” (review-244 S7): `an validate`’s generic target check and the compiler’s keyframe check both use it. A target’s entity is its first path segment; a target with no entity (the stage camera’s `root`), or an entity whose kind is unregistered or declares no space, gets `default` — the timing default [`an.timing.spaces.DFLT_TIMELINE_SPACE`](_autosummary/an.timing.spaces.html.md#an.timing.spaces.DFLT_TIMELINE_SPACE) when `None`. The default EVALUATOR agrees since an#245: the stage’s compiled document records each entity whose kind declares another space (`meta.entity_spaces`), and `timeline_from_compiled` resolves by it. ```pycon >>> from an.ir.schema import AssetRef >>> space_of = entity_space_resolver([AssetRef(kind="prop", id="lamp", store="props", ref="l")]) >>> space_of("lamp/shade").name, space_of("root").name ('stage.node', 'stage.node') ``` ### an.genres.genre_entry_points(, group='an.genres') The installed `an.genres` entry points (nothing is imported). * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`EntryPoint`](https://docs.python.org/3/library/importlib.metadata.html#importlib.metadata.EntryPoint), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.genre_library(name, , default='an') The package whose data root holds genre `name`’s library and projects. `default` (the core package) for no genre, an unknown one, or a genre that declares none. Reads the genres installed in this process (call [`load()`](_autosummary/an.genres.html.md#an.genres.load) first, as every entry point does). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> genre_library(None) 'an' ``` ### an.genres.genres_declaring(test) The installed genres (loaded or not) whose declaration passes `test`. Each is named as `genre (package)`. Reading declarations imports the genre modules but registers nothing. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.hook_modules(, exclude_owner='an') The modules whose code the genres’ registered hooks run, sorted and unique. Compile passes, lowerings, entity hooks, checks, services and runtime scripts of every owner but `exclude_owner` (the core’s own are walked from the renderer already). The shot cache’s code key starts its walk here for the packages outside `an`, so a change to a genre’s code changes the key (an#294): the genre is reached by REGISTRATION, not by an import from `an`. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> isinstance(hook_modules(), tuple) True ``` ### an.genres.installed() The names of the genres registered in this process, in registration order. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.load(, entry_points=None, builtin=True) Register every discoverable genre. Idempotent. Discoverable: the genres the `an` distribution ships ([`IN_DISTRIBUTION_GENRES`](_autosummary/an.genres.html.md#an.genres.IN_DISTRIBUTION_GENRES), unless `builtin=False`) and the `an.genres` entry points (`entry_points` replaces the installed ones — tests, a host that curates). Returns the names of the genres registered after the call. Never called at import time: the CLI, `an.load(project)` and the MCP entry call it, so a document naming a genre’s kind validates to that kind’s model. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.providers_of(kind, , registry='action kinds') The installed genres (loaded or not) that declare `kind` in `registry` (a key of [`Genre.provides()`](_autosummary/an.genres.html.md#an.genres.Genre.provides)). Used by the unregistered-kind errors. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.register_genre(genre, , replace=False, check_capabilities=True) Register everything `genre` declares, owned by `genre.name`. Idempotent for the same object: registering a genre that is already installed is a no-op, so [`load()`](_autosummary/an.genres.html.md#an.genres.load) can be called from every entry point. A different object under an installed name raises unless `replace`. All or nothing: a registration that fails part-way leaves no trace. `check_capabilities=False` defers the “every requirement names a registered capability” check to the caller ([`load()`](_autosummary/an.genres.html.md#an.genres.load) runs it once all genres are in, so a genre extending another loads in any order). * **Return type:** [`Genre`](_autosummary/an.genres.html.md#an.genres.Genre) ### an.genres.register_service(name, target, , owner='an', replace=False) Register a named service a genre offers the core (an#225). The seam for the places where the core needs a genre’s code only when that genre is installed: a CLI namespace (`cli.character`), a provider factory (`lipsync.offline`), a licence lookup. `target` is the object itself or `"module:attr"` (imported on first use, so declaring a service imports no engine). The names a genre may use are the core’s contract, listed with their callers in `misc/docs/architecture_as_built.md`. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.genres.require_api_level(level, , package) Refuse, with an upgrade hint, when this `an` is older than `package` needs. A genre package calls it at import (`require_api_level(3, package="cutan")`). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> require_api_level(1, package="demo") >>> try: ... require_api_level(API_LEVEL + 1, package="demo") ... except GenreAPILevelError as e: ... print(str(e).startswith(f"demo needs an.genres API level {API_LEVEL + 1}")) True ``` ### an.genres.require_service(name, , what='', extra='cutout') The registered service `name`; a typed error naming the install when absent. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.genres.service(name, default=None) The registered service `name`, resolved, or `default` when none is. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> service("no.such.service") is None True ``` ### an.genres.services(prefix) `{name without the prefix: resolved service}` for every service under `prefix`. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> services("no.such.") {} ``` ### an.genres.without_genres() Run a block with no genre registered (the core alone), then restore. * **Return type:** [`Iterator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)[[`None`](https://docs.python.org/3/builtins/constants.html#None)] ```pycon >>> with without_genres(): ... action_kind("play") is None True ``` ### Modules | [`registry`](_autosummary/an.genres.registry.html.md#module-an.genres.registry) | The core's open registries: action kinds, entity kinds, semantic checks, md sugar, compile passes. | |---------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------| # _autosummary/an.genres.registry.html.md # an.genres.registry The core’s open registries: action kinds, entity kinds, semantic checks, md sugar, compile passes. ADR 0001 decision 2 (“the IR is open at the type level; genres register, never edit”) and decision 4 (the first batch of registries). Each registry is a plain name-keyed table with an **owner** per entry, so the core can tell its own entries from a genre’s (the timing contract does the same, review-237 S3), and a test can take every genre out and put it back ([`snapshot()`](_autosummary/an.genres.registry.html.md#an.genres.registry.snapshot) / `restore()`). This module imports nothing from `an.ir`: the schema consults it while it validates (a document’s `kind: play` is looked up here), so it must sit below the schema in the import graph. That is also why an entry holds its model class and hooks as plain values: the registry never needs to know what they are. ```pycon >>> isinstance(action_kind("tween"), ActionKind) # core kinds register on import of the IR True >>> "play" in action_kind_names(owner=CORE_OWNER) # a genre's kind is never the core's False ``` ### Module Attributes | [`CORE_OWNER`](_autosummary/an.genres.registry.html.md#an.genres.registry.CORE_OWNER) | The owner of every entry the core registers itself. | |--------------------------------------------------------------------|--------------------------------------------------------------------| | [`DurationHook`](_autosummary/an.genres.registry.html.md#an.genres.registry.DurationHook) | the natural length of a leaf. | | [`CheckStage`](_autosummary/an.genres.registry.html.md#an.genres.registry.CheckStage) | once before the shots, once per shot, once after them. | | [`DIALOGUE_BRACKETS`](_autosummary/an.genres.registry.html.md#an.genres.registry.DIALOGUE_BRACKETS) | The bracket pairs a GENRE may claim on a `scene.md` dialogue line. | ### Functions | [`action_kind`](_autosummary/an.genres.registry.html.md#an.genres.registry.action_kind)(name) | The registered kind called `name`, or `None`. | |----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| | [`action_kind_names`](_autosummary/an.genres.registry.html.md#an.genres.registry.action_kind_names)(\*[, owner]) | Registered action-kind names in registration order; `owner`'s only when given. | | `action_kind_owner`(name) | | | `check_names`(\*[, owner]) | | | [`check_owner`](_autosummary/an.genres.registry.html.md#an.genres.registry.check_owner)(name) | Who registered the check `name` (`CORE_OWNER` for the core's), or `None`. | | [`checks`](_autosummary/an.genres.registry.html.md#an.genres.registry.checks)(stage) | The registered checks of `stage`, in run order (`order`, then registration). | | `compile_pass_names`(\*[, owner]) | | | [`compile_pass_owner`](_autosummary/an.genres.registry.html.md#an.genres.registry.compile_pass_owner)(name) | Who registered the compile pass `name` (a genre's name), or `None`. | | [`compile_passes`](_autosummary/an.genres.registry.html.md#an.genres.registry.compile_passes)(compiler) | The registered passes of `compiler` (builders excluded), in run order. | | [`dialogue_sugar`](_autosummary/an.genres.registry.html.md#an.genres.registry.dialogue_sugar)(opener) | The sugar registered for the bracket `opener`, or `None`. | | `dialogue_sugars`() | | | [`entity_builders`](_autosummary/an.genres.registry.html.md#an.genres.registry.entity_builders)(compiler) | `{entity kind: builder}` registered for `compiler`. | | `entity_kind`(name) | | | `entity_kind_names`(\*[, owner]) | | | [`hook_modules`](_autosummary/an.genres.registry.html.md#an.genres.registry.hook_modules)(\*[, exclude_owner]) | The modules whose code the genres' registered hooks run, sorted and unique. | | [`owners`](_autosummary/an.genres.registry.html.md#an.genres.registry.owners)() | Every owner with at least one entry, the core first. | | [`register_action_kind`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_action_kind)(kind, \*[, owner, replace]) | Register an action kind. | | [`register_check`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_check)(check, \*[, owner, replace]) | Register a semantic-validation check (run by `an.ir.validate.validate_semantic`). | | [`register_compile_pass`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_compile_pass)(compile_pass, \*[, ...]) | Register a compile pass (or an entity builder) under its name. | | [`register_dialogue_sugar`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_dialogue_sugar)(sugar, \*[, owner, ...]) | Register `scene.md` dialogue sugar. | | [`register_entity_kind`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_entity_kind)(kind, \*[, owner, replace]) | Register an entity kind (a value `AssetRef.kind` may take). | | [`register_runtime_script`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_runtime_script)(script, \*[, owner, ...]) | Register runtime code for an engine (a genre's visual kinds). | | [`register_service`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_service)(name, target, \*[, owner, ...]) | Register a named service a genre offers the core (an#225). | | [`require_service`](_autosummary/an.genres.registry.html.md#an.genres.registry.require_service)(name, \*[, what, extra]) | The registered service `name`; a typed error naming the install when absent. | | `restore`(state) | | | [`runtime_scripts`](_autosummary/an.genres.registry.html.md#an.genres.registry.runtime_scripts)(engine) | The scripts registered for `engine`, by name (a stable order). | | [`service`](_autosummary/an.genres.registry.html.md#an.genres.registry.service)(name[, default]) | The registered service `name`, resolved, or `default` when none is. | | [`services`](_autosummary/an.genres.registry.html.md#an.genres.registry.services)(prefix) | `{name without the prefix: resolved service}` for every service under `prefix`. | | [`snapshot`](_autosummary/an.genres.registry.html.md#an.genres.registry.snapshot)() | The state of every table, for `restore()`. | | [`unregister_owner`](_autosummary/an.genres.registry.html.md#an.genres.registry.unregister_owner)(owner) | Remove every entry `owner` registered, from every table. | ### Classes | [`ActionKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.ActionKind)(name, model[, duration, flatten, ...]) | One kind of action: its model, how it occupies time, how `scene.md` spells it. | |------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`CompilePass`](_autosummary/an.genres.registry.html.md#an.genres.registry.CompilePass)(name, run[, order, compiler, ...]) | One step a genre adds to an engine's COMPILER (shot -> compiled document). | | [`DialogueSugar`](_autosummary/an.genres.registry.html.md#an.genres.registry.DialogueSugar)(name, opener, field, parse, format) | `scene.md` sugar on a dialogue line: one bracket pair, one `Dialogue` field (and, declared in `fields`, the parameters it may carry). | | [`EntityKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.EntityKind)(name[, space, store, ...]) | One kind of entity (`AssetRef.kind`): what its nodes' properties are. | | [`RuntimeScript`](_autosummary/an.genres.registry.html.md#an.genres.registry.RuntimeScript)(name, source[, engine, ...]) | JavaScript a genre adds to an engine's RUNTIME (an#247; ADR 0001 decision 4, second batch): for the stage, code that registers visual kinds with `window.anRegisterVisual(kind, make)` -- how the cut-out mouth and eye leave `runtime.js` for `cutan` (P8). | | [`SemanticCheck`](_autosummary/an.genres.registry.html.md#an.genres.registry.SemanticCheck)(name, run[, stage, order, ...]) | One semantic-validation check: `run(ctx)` adds findings to `ctx.report`. | | [`SwapDeclaration`](_autosummary/an.genres.registry.html.md#an.genres.registry.SwapDeclaration)(sets[, descriptor, ...]) | What one entity's descriptor declares for the stage compiler's swap vocabulary. | ### Exceptions | [`RegistryError`](_autosummary/an.genres.registry.html.md#an.genres.registry.RegistryError) | A registration is malformed or collides with one already made. | |-----------------------------------------------------------------------------------------------|------------------------------------------------------------------| | [`ServiceMissingError`](_autosummary/an.genres.registry.html.md#an.genres.registry.ServiceMissingError) | The core asked a genre for a service nobody registered. | | [`UnregisteredKindError`](_autosummary/an.genres.registry.html.md#an.genres.registry.UnregisteredKindError)(what, name, \*[, ...]) | A document names a kind no loaded genre registered. | ### *class* an.genres.registry.ActionKind(name, model, duration=None, flatten=None, children=None, read_md=None, write_md=None, md_start=True, description='', version='1', lowering=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One kind of action: its model, how it occupies time, how `scene.md` spells it. - `model` validates a document’s action of this kind. A genre’s model subclasses [`an.ir.schema.ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction); the core’s are the static members of the schema’s union. - `duration` is a LEAF’s natural length; a leaf flattens to one `FlatAction` on `[t, t + duration]` and advances a `sequence` by it. - `flatten` replaces that default for kinds that place themselves differently (`set` does not advance the cursor) or that hold children (`sequence`): `flatten(action, t, ctx) -> new cursor`, where `ctx` is [`an.ir.compose.FlattenContext`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlattenContext). - `children` lists a composite’s child actions, so generic walkers (validation) reach every leaf without knowing the kind. - `read_md` / `write_md` are the `scene.md` `yaml actions` hooks: `read_md(item, index=i) -> action` (`start:` already removed when `md_start`) and `write_md(action) -> dict` (without `start`). A kind with no `read_md` has no `scene.md` form. #### lowering *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* How the STAGE compiler turns an action of this kind into clips, for a kind that is not a plain tween or set (the cut-out `play`): an object with `extent_resolver(vocab, *, products)`, `expand(flat_list, *, vocab, fps, step_hz, default_easing, resolutions, products)`, `view_of(entity_swaps, vocab, *, duration)` and `clip(action, *, anim_id, vocab, fps, view)` – see [`an.stage.compile.ActionLowering`](_autosummary/an.stage.compile.html.md#an.stage.compile.ActionLowering). `None`: the compiler has nothing kind-specific to do. (an#225: this is how the compiler stops naming `play`.) #### md_start *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= True* Does `start:` in `scene.md` wrap this kind in `sequence(delay(start), …)`? #### version *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '1'* bump when what an action of this kind compiles to changes for the same fields, so the shots that use it re-render visibly ([`an.semantic`](_autosummary/an.semantic.html.md#module-an.semantic) folds it into the shot digest). * **Type:** The kind’s vocabulary version (ADR 0003) ### an.genres.registry.CORE_OWNER *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'an'* The owner of every entry the core registers itself. A genre registers under its own name (`an.genres.Genre.name`). ### an.genres.registry.CheckStage once before the shots, once per shot, once after them. * **Type:** When a check runs alias of [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)[‘scene’, ‘shot’, ‘finish’] ### *class* an.genres.registry.CompilePass(name, run, order=0.0, compiler='stage', builds=None, description='', replace=False) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One step a genre adds to an engine’s COMPILER (shot -> compiled document). A compiler (`compiler`: today `"stage"`, [`an.stage.compile`](_autosummary/an.stage.compile.html.md#module-an.stage.compile)) runs its own passes plus every registered one, in `order`. A pass with `builds` set is an ENTITY BUILDER instead: the compiler’s scene pass calls it for each entity of that kind (the cut-out genre’s `rig` builds a `character`); builders with a lower `order` build all their entities first (the stage’s backdrop before the cast), equal orders in entity order. `run` is the callable, or `"module:function"`, resolved on first use – so a genre is inspectable ([`an.genres.available()`](_autosummary/an.genres.html.md#an.genres.available)) without importing the engine its passes target. What `run` receives is the compiler’s business (the stage hands a pass its `CompileState`, a builder the entity and the scene being built); the core never calls it. #### replace *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* Explicitly take the place of the ENGINE’s own pass of this name (or its builder for `builds`). Without it a name or kind the engine already has is refused when the compiler runs; with it the replacement is recorded in the compiled document (review of an#270, S3). #### resolve() The callable `run` names. * **Return type:** [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> CompilePass("p", "math:sqrt").resolve()(4.0) 2.0 ``` ### an.genres.registry.DIALOGUE_BRACKETS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'[': ']'}* The bracket pairs a GENRE may claim on a `scene.md` dialogue line. The line grammar has three: `(…)` (timing) and `{…}` (delivery direction) are the core’s own and never registered; `[…]` is the one left for sugar. ### *class* an.genres.registry.DialogueSugar(name, opener, field, parse, format, description='', fields=()) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) `scene.md` sugar on a dialogue line: one bracket pair, one `Dialogue` field (and, declared in `fields`, the parameters it may carry). `parse(content) -> value` turns what is between the brackets into the field’s value (raise `ValueError(why)` to refuse it); `format(line) -> str | None` is the inverse (the content, without brackets, or `None` when the line carries none). The cut-out genre’s `[emotion]` is one. A sugar that also sets other `Dialogue` fields (`[angry 0.4]`: the emotion and its `emotion_intensity`, an#253) names them in `fields`; its `parse` then returns `{field name: value}` over `field` and any of `fields`, and `format` writes them back. #### values(content) `{Dialogue field: value}` for the bracket `content` (`parse`, checked against what the sugar declares). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.genres.registry.DurationHook the natural length of a leaf. `extent` is the caller’s per-call resolver for a leaf that has no explicit duration (the compiler and `an validate` pass one bound to the entity’s descriptor), or `None`. * **Type:** `(action, extent) -> seconds` alias of [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)], [`float`](https://docs.python.org/3/builtins/functions.html#float)] ### *class* an.genres.registry.EntityKind(name, space=None, store=None, description='', version='1', swap_declaration=None, descriptor_kind=None, placeholder_on_missing=False, swap_checks=None, specimen=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One kind of entity (`AssetRef.kind`): what its nodes’ properties are. `space` names the registered [`an.timing.spaces.PropertySpace`](_autosummary/an.timing.spaces.html.md#an.timing.spaces.PropertySpace) its nodes’ properties live in (`None`: the entity has no animatable nodes, as a voice); `store` is the project-mall store its `ref` keys into. #### descriptor_kind *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The `kind` tag of the descriptor document `store` holds for this kind (`"CharacterDescriptor"`): what makes the validator treat the entity as a rig whose declared asset sets it can check (an#246). #### placeholder_on_missing *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* *= False* A missing `ref` is NOT an error because the compiler draws a placeholder instead; the genre reports it with its own (warning) check. #### specimen *: [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[Any](https://docs.python.org/3/library/typing.html#typing.Any)], [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* a short shot showing one entity of this kind on its own, the one `ref` casts — what `an library sheet` draws for a version of it (an#347). `None`: the sheet shows a labelled placeholder. * **Type:** `(ref: AssetRef) -> Shot` #### swap_checks *: [Any](https://docs.python.org/3/library/typing.html#typing.Any)* *= None* an object with `missing_set_hint(prop) -> str` (appended to “names no declared asset set”) and `whole_entity(action, desc, prop, keys, entity_id, *, where, report, art_exists) -> bool` (judge a swap on the entity ITSELF; `True` when handled). `None`: the generic per-node rule only. * **Type:** Extra swap-reference checks for this kind #### swap_declaration *: [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[Any](https://docs.python.org/3/library/typing.html#typing.Any), [Any](https://docs.python.org/3/library/typing.html#typing.Any)], [SwapDeclaration](_autosummary/an.genres.registry.html.md#an.genres.registry.SwapDeclaration) | [None](https://docs.python.org/3/builtins/constants.html#None)] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* what the entity’s descriptor declares for the stage compiler’s swap vocabulary (an#87). `None`: the kind declares nothing (its built nodes’ sets ARE its declaration). * **Type:** `(entity, mall) -> SwapDeclaration | None` #### version *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= '1'* The kind’s vocabulary version (ADR 0003), as [`ActionKind.version`](_autosummary/an.genres.registry.html.md#an.genres.registry.ActionKind.version). ### *exception* an.genres.registry.RegistryError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A registration is malformed or collides with one already made. ### *class* an.genres.registry.RuntimeScript(name, source, engine='stage', description='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) JavaScript a genre adds to an engine’s RUNTIME (an#247; ADR 0001 decision 4, second batch): for the stage, code that registers visual kinds with `window.anRegisterVisual(kind, make)` – how the cut-out mouth and eye leave `runtime.js` for `cutan` (P8). `source` is `"package:relative/path.js"`, read with [`importlib.resources`](https://docs.python.org/3/library/importlib.resources.html#module-importlib.resources) when the engine stages its runtime, so it ships in the genre’s wheel. The staged code is part of the shot cache’s key. #### code() The script’s code (UTF-8). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> RuntimeScript("x", "an.stage.runtime:extensions.js").code().startswith("//") True ``` ### *class* an.genres.registry.SemanticCheck(name, run, stage='shot', order=0.0, description='') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One semantic-validation check: `run(ctx)` adds findings to `ctx.report`. `ctx` is [`an.ir.validate.ValidationContext`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationContext); a `shot` check is called once per shot with `ctx.shot` set. Within a stage, checks run by `order` (then registration order), so a genre’s check lands exactly where it belongs in the report. ### *exception* an.genres.registry.ServiceMissingError Bases: [`RegistryError`](_autosummary/an.genres.registry.html.md#an.genres.registry.RegistryError), [`ImportError`](https://docs.python.org/3/builtins/exceptions.html#ImportError) The core asked a genre for a service nobody registered. ### *class* an.genres.registry.SwapDeclaration(sets, descriptor=None, art_exists=None, scale=1.0) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What one entity’s descriptor declares for the stage compiler’s swap vocabulary. `sets` is `{set name: {KEY: attachment name}}` as declared; `descriptor` is the (migrated) document the declaration came from, kept for the kind’s own lowering; `art_exists` answers `rel_path -> art on disk` (`None` when the store cannot say); `scale` is the factor from the entity’s view box to scene pixels. ### *exception* an.genres.registry.UnregisteredKindError(what, name, , known=(), providers=(), where='') Bases: [`RegistryError`](_autosummary/an.genres.registry.html.md#an.genres.registry.RegistryError) A document names a kind no loaded genre registered. The message names the installed genres that *could* provide it (read from their declarations, which are inspectable without loading them), so the fix is one line: `an.genres.load()`, or installing the package named. ### an.genres.registry.action_kind(name) The registered kind called `name`, or `None`. * **Return type:** [`ActionKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.ActionKind) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.genres.registry.action_kind_names(, owner=None) Registered action-kind names in registration order; `owner`’s only when given. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.registry.check_owner(name) Who registered the check `name` (`CORE_OWNER` for the core’s), or `None`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.genres.registry.checks(stage) The registered checks of `stage`, in run order (`order`, then registration). * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`SemanticCheck`](_autosummary/an.genres.registry.html.md#an.genres.registry.SemanticCheck), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.registry.compile_pass_owner(name) Who registered the compile pass `name` (a genre’s name), or `None`. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.genres.registry.compile_passes(compiler) The registered passes of `compiler` (builders excluded), in run order. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`CompilePass`](_autosummary/an.genres.registry.html.md#an.genres.registry.CompilePass), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.registry.dialogue_sugar(opener) The sugar registered for the bracket `opener`, or `None`. * **Return type:** [`DialogueSugar`](_autosummary/an.genres.registry.html.md#an.genres.registry.DialogueSugar) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.genres.registry.entity_builders(compiler) `{entity kind: builder}` registered for `compiler`. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`CompilePass`](_autosummary/an.genres.registry.html.md#an.genres.registry.CompilePass)] ### an.genres.registry.hook_modules(, exclude_owner='an') The modules whose code the genres’ registered hooks run, sorted and unique. Compile passes, lowerings, entity hooks, checks, services and runtime scripts of every owner but `exclude_owner` (the core’s own are walked from the renderer already). The shot cache’s code key starts its walk here for the packages outside `an`, so a change to a genre’s code changes the key (an#294): the genre is reached by REGISTRATION, not by an import from `an`. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ```pycon >>> isinstance(hook_modules(), tuple) True ``` ### an.genres.registry.owners() Every owner with at least one entry, the core first. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.registry.register_action_kind(kind, , owner='an', replace=False) Register an action kind. Its model’s `kind` must default to its name. * **Return type:** [`ActionKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.ActionKind) ```pycon >>> from pydantic import BaseModel >>> class Bad(BaseModel): ... kind: str = "other" >>> register_action_kind(ActionKind("wave", Bad), owner="demo") Traceback (most recent call last): ... an.genres.registry.RegistryError: action kind 'wave': ... ``` ### an.genres.registry.register_check(check, , owner='an', replace=False) Register a semantic-validation check (run by `an.ir.validate.validate_semantic`). * **Return type:** [`SemanticCheck`](_autosummary/an.genres.registry.html.md#an.genres.registry.SemanticCheck) ### an.genres.registry.register_compile_pass(compile_pass, , owner='an', replace=False) Register a compile pass (or an entity builder) under its name. * **Return type:** [`CompilePass`](_autosummary/an.genres.registry.html.md#an.genres.registry.CompilePass) ### an.genres.registry.register_dialogue_sugar(sugar, , owner='an', replace=False) Register `scene.md` dialogue sugar. One sugar per bracket pair. * **Return type:** [`DialogueSugar`](_autosummary/an.genres.registry.html.md#an.genres.registry.DialogueSugar) ### an.genres.registry.register_entity_kind(kind, , owner='an', replace=False) Register an entity kind (a value `AssetRef.kind` may take). * **Return type:** [`EntityKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.EntityKind) ### an.genres.registry.register_runtime_script(script, , owner='an', replace=False) Register runtime code for an engine (a genre’s visual kinds). * **Return type:** [`RuntimeScript`](_autosummary/an.genres.registry.html.md#an.genres.registry.RuntimeScript) ### an.genres.registry.register_service(name, target, , owner='an', replace=False) Register a named service a genre offers the core (an#225). The seam for the places where the core needs a genre’s code only when that genre is installed: a CLI namespace (`cli.character`), a provider factory (`lipsync.offline`), a licence lookup. `target` is the object itself or `"module:attr"` (imported on first use, so declaring a service imports no engine). The names a genre may use are the core’s contract, listed with their callers in `misc/docs/architecture_as_built.md`. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.genres.registry.require_service(name, , what='', extra='cutout') The registered service `name`; a typed error naming the install when absent. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.genres.registry.runtime_scripts(engine) The scripts registered for `engine`, by name (a stable order). * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`RuntimeScript`](_autosummary/an.genres.registry.html.md#an.genres.registry.RuntimeScript), [`...`](https://docs.python.org/3/builtins/constants.html#Ellipsis)] ### an.genres.registry.service(name, default=None) The registered service `name`, resolved, or `default` when none is. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> service("no.such.service") is None True ``` ### an.genres.registry.services(prefix) `{name without the prefix: resolved service}` for every service under `prefix`. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> services("no.such.") {} ``` ### an.genres.registry.snapshot() The state of every table, for `restore()`. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple) ### an.genres.registry.unregister_owner(owner) Remove every entry `owner` registered, from every table. * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) # _autosummary/an.html.md # an an — AI-driven structured animation. Public API surface (curated). See `an.ir` for the Scene IR, `an.adapters` for renderer plumbing, `an.audio` for TTS/lip-sync protocols, `an.verify` for verification, and `an.stores` for the project mall. ```pycon >>> import an >>> 'SceneIR' in an.__all__ True ``` ### Functions | [`set_`](_autosummary/an.html.md#an.set_)(target, property, value, \*[, at]) | Discrete property set at time `at` (relative to its enclosing scope). | |---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | [`tween`](_autosummary/an.html.md#an.tween)(target, property, to, duration, \*[, ...]) | Animate a property from `from_` (or its current value) to `to`. | | [`sequence`](_autosummary/an.html.md#an.sequence)(\*actions) | Run children one after the other. | | [`parallel`](_autosummary/an.html.md#an.parallel)(\*actions) | Run all children at once. | | [`stagger`](_autosummary/an.html.md#an.stagger)(lag, \*actions) | Start each action `lag` seconds after the previous one STARTS. | | [`crowd`](_autosummary/an.html.md#an.crowd)(id, \*, ref, count[, kind, store, ...]) | `count` entities of one asset (`kind`/`store`/`ref`) placed in `area`. | | [`fan_out`](_autosummary/an.html.md#an.fan_out)(action, members, \*[, crowd_id]) | A copy of `action` per member, its targets moved from the crowd to the member. | | [`delay`](_autosummary/an.html.md#an.delay)(duration) | An empty span that consumes time. | | [`loop`](_autosummary/an.html.md#an.loop)(action, count) | Repeat `action` `count` times. | | [`flatten`](_autosummary/an.html.md#an.flatten)(action, \*[, start, play_extent]) | Walk a composition tree, emitting leaf actions with absolute times. | | [`validate_schema`](_autosummary/an.html.md#an.validate_schema)(doc) | Validate that `doc` (dict, JSON string, or SceneIR) conforms to the schema. | | [`validate_semantic`](_autosummary/an.html.md#an.validate_semantic)(scene, \*[, ...]) | Cross-field semantic checks. | | [`markdown_to_ir`](_autosummary/an.html.md#an.markdown_to_ir)(md_text) | Parse the structured Markdown form of a scene into a SceneIR. | | [`ir_to_markdown`](_autosummary/an.html.md#an.ir_to_markdown)(scene) | Render a SceneIR back into the structured Markdown form. | | [`init`](_autosummary/an.html.md#an.init)(project_dir, \*[, name, force]) | Create a fresh an project at `project_dir`. | | [`load`](_autosummary/an.html.md#an.load)(project_dir, \*[, check_kinds]) | Load an existing project. | | [`save`](_autosummary/an.html.md#an.save)(project) | Persist a Project's current scene back to disk (md + json). | | [`build_project_mall`](_autosummary/an.html.md#an.build_project_mall)(project_dir, \*[, ensure]) | Build the standard project mall over `project_dir`. | | [`check_requirements`](_autosummary/an.html.md#an.check_requirements)() | Return a per-tool status dict. | ### Classes | [`SceneIR`](_autosummary/an.html.md#an.SceneIR)(\*\*data) | Top-level Scene IR document. | |---------------------------------------------------------------------------------|----------------------------------------------------------| | [`Meta`](_autosummary/an.html.md#an.Meta)(\*\*data) | Scene metadata. | | [`AssetRef`](_autosummary/an.html.md#an.AssetRef)(\*\*data) | Reference to an entry in a project store. | | [`Shot`](_autosummary/an.html.md#an.Shot)(\*\*data) | A single rendered unit. | | [`Dialogue`](_autosummary/an.html.md#an.Dialogue)(\*\*data) | One line of spoken dialogue. | | [`Camera`](_autosummary/an.html.md#an.Camera)(\*\*data) | Camera state for a shot: a named move, or explicit keys. | | [`Resolution`](_autosummary/an.html.md#an.Resolution)(\*\*data) | Pixel dimensions of the rendered output. | | [`FlatAction`](_autosummary/an.html.md#an.FlatAction)(start, end, action) | A leaf action with its absolute start and end times. | | [`Project`](_autosummary/an.html.md#an.Project)(root, mall, scene) | A loaded an project: directory + mall + current scene. | ### *class* an.AssetRef(\*\*data) Bases: `_IRModel` Reference to an entry in a project store. The IR never inlines large assets. Instead it references them by store name + key, so the same character/voice/environment is reusable across scenes. `overrides` lets a single shot tweak presentation without forking the asset. ```pycon >>> AssetRef(kind="character", id="maya", store="characters", ref="maya-v1").id 'maya' ``` #### kind *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* it selected nothing (the compiler skipped it, nothing read the styles store) and the name belonged to the renderer selector. Art direction arrives as a StylePack (#112). A `str` in the schema, not a `Literal` (ADR 0001 decision 2): the values are the REGISTERED entity kinds ([`an.genres`](_autosummary/an.genres.html.md#module-an.genres)) — the core’s `environment`, `prop` and `voice`, a genre’s `character` — and `an validate` checks it against that registry, naming the genre that provides an unregistered one. * **Type:** `"style"` was retired in an#106 #### library *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The asset-library version this entry was checked out from (ADR 0005 decision 8): `"[:]@"`, e.g. `"cutan:character.alice-reiniger@v003"` (grammar: [`an.library.ids.parse_ref()`](_autosummary/an.library.ids.html.md#an.library.ids.parse_ref), a pinned version required: `vNNN` or `sha256:`, never `latest`). `None` — the default, and every document written before the library existed — means the asset is the project’s own. Today the strategy is check-out, so `ref` still names the project-store key the compiler reads and this field is the pin beside it; live reference resolves it instead, later. Additive and omit-when-unset, like `stage`: an unset `library` leaves no trace in a dump, so no stored scene changes and no schema version moves. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### stage *: [StagePlacement](_autosummary/an.ir.schema.html.md#an.ir.schema.StagePlacement) | [None](https://docs.python.org/3/builtins/constants.html#None)* Where on the stage this entity stands. `None` — the default and what every existing document has — means “wherever the layout puts it”, which for characters is the evenly-spaced row the compiler computes. **Additive by construction, and hash-free by construction**: the contract hashes the COMPILED document, and an `AssetRef` never reaches it. So this field can grow without retiring a single ledger row. ### *class* an.Camera(\*\*data) Bases: `_CameraShakes` Camera state for a shot: a named move, or explicit keys. ```pycon >>> Camera(move="push_in").move 'push_in' >>> Camera(keys=[CameraKey(at=0.0), CameraKey(at=2.0, x=-200.0)]).keys[1].x -200.0 ``` **One code path, two front doors** — the shape the dialogue `[emotion]` sugar already uses. A named `move` desugars to a key list; `keys` is that list written out. Setting both raises, because a scene that says two things about the same camera has no reading that is not a guess. `keys` defaults to `None`, not `[]`, and that too is load-bearing: the markdown writer dumps the camera with `exclude_none=True`, which KEEPS empty lists — an empty default would write `keys: []` into every camera block it regenerates. `position`, `target` and `focal_length` were removed in an#109. They were written into every `scene.md` this package ever generated and read by nothing; a registered migration drops them. #### keys *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[CameraKey](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraKey)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The explicit door. `None` = use `move`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### move *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* A named preset — sugar for `keys`. The cutout renderer’s vocabulary is `an.stage.compile.CAMERA_MOVES`; validate and the compiler are pinned to the same table by test, because a move that validates and then raises is the failure `_check_renderable` exists to prevent. ### *class* an.Dialogue(\*\*data) Bases: `_IRModel` One line of spoken dialogue. `start` and `duration` are None until the audio pipeline runs (TTS gives us a real duration); the pipeline stamps them then, deriving `start` from the author’s `pause` / `at` ([`planned_start()`](_autosummary/an.html.md#an.Dialogue.planned_start)). #### at *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Where this line starts, in SHOT seconds, whatever came before it — `(at 3.0)` in `scene.md`. `start` is what the audio pipeline DERIVES from `at`/`pause` on every pass; these two are what the author wrote (an#187). #### direction *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None)* How the line is DELIVERED — cues such as `["excited"]` or `["sighs", "annoyed"]`, `{excited}` in `scene.md` (an#209). A TTS model that takes inline audio tags (ElevenLabs v3/v4) receives them as `[excited] Hi!`; others ignore them. Never part of `text`, so captions and lip-sync alignment never see a cue. #### emotion_intensity *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* `maya [angry 0.4]: …` in `scene.md`, a typed parameter on the (b-name) emotion. `None` is full strength, and is omitted from JSON. * **Type:** How strongly `emotion` shows, 0..1 (an#253) #### leveled *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict) | [None](https://docs.python.org/3/builtins/constants.html#None)* , “gain_db”: }\`\` when `audio_ref` is the leveled audio. `None` — unleveled — is omitted from JSON. * **Type:** Stamped by voice leveling (an#315) * **Type:** ``` `` ``` {“source” #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### pause *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Seconds of silence before this line, after the previous line’s speech ends (the shot start, for the first line) — `(pause 1.5)` in `scene.md`. #### planned_start(cursor) Where this line starts, given the previous line ends at `cursor`. The one rule the audio pipeline stamps into `start` and `an validate` lays lines out by: `at` if set, else `cursor + pause`. A `start` on a line never synthesized (no `audio_ref`) was authored — the spelling of `at` before an#187 — and counts as one; a synthesized line’s `start` is the pipeline’s own stamp, re-derived here. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> Dialogue(speaker="a", text="bye", pause=1.5).planned_start(0.8) 2.3 >>> Dialogue(speaker="a", text="bye", at=4.0).planned_start(0.8) 4.0 >>> Dialogue(speaker="a", text="bye").planned_start(0.8) 0.8 ``` #### spoken *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* seconds from the line’s start to the end of its AUDIBLE speech — its take’s own trailing silence left out — stamped with `duration` from the line’s audio. The next line’s `pause` counts from here (a line with no pause still follows the whole take). `None` (silent audio, a line its voice’s `trim_silence` already cut to the tail the author keeps, a line stamped before an#397) counts from the end of `duration`, as before. Never written to JSON: it is read off the line’s stored audio on every pass (the audio pipeline, and a render that skips synthesis), so `scene.json` and its fixtures do not change. * **Type:** DERIVED (an#397) #### word_timings *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[WordTimingIR](_autosummary/an.ir.schema.html.md#an.ir.schema.WordTimingIR)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The provider’s word timings, line-relative; `None` when the provider has none (offline, Rhubarb) or the line was stamped before an#96. ### *class* an.FlatAction(start, end, action) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A leaf action with its absolute start and end times. The flat-form list is the canonical representation passed to renderers and verifiers. Composition nodes (sequence/parallel/delay/loop) do not appear in the flat form — they’re collapsed into time offsets. ### *class* an.Meta(\*\*data) Bases: `_IRModel` Scene metadata. #### captions *: [Captions](_autosummary/an.ir.schema.html.md#an.ir.schema.Captions) | [None](https://docs.python.org/3/builtins/constants.html#None)* Captions from the dialogue’s word timings (`Captions`, an#175); `None` — the default — is none, omitted from JSON like `style_pack`. #### closing_transition *: [Transition](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) | [None](https://docs.python.org/3/builtins/constants.html#None)* a `fade` to its `color` over its `duration`, on the last shot’s last frames (the film’s length is unchanged, and its final frame is the colour; the sound fades with it). `None` (or a `cut`) ends on the last frame as drawn. A dissolve has nothing to dissolve into, so it is refused. * **Type:** How the film ENDS (an#389) #### default_easing *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)] | [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[float](https://docs.python.org/3/builtins/functions.html#float)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The easing every authored `tween` that names none is drawn with (an#166) — `"linear"` for a snappy South Park cadence, an overshooting cubic-Bezier for a bouncy one. Precedence is \*\*tween > this > the built-in `"ease_in_out"``** (:meth:`TweenAction.resolved_easing`). ``None` — the default and what every existing document has — changes nothing, and is omitted from JSON like `style_pack`, so no committed scene and no compiled document moves. It reaches authored tweens ONLY: a motion preset writes its own easings, the camera’s named moves supply theirs, and blinks, `play` clips and swap channels have none to inherit. There is no per-shot override yet — style is a scene’s. #### default_renderer *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* a registered renderer’s name. * **Type:** Like [`Shot.renderer`](_autosummary/an.html.md#an.Shot.renderer) #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### sounds *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[SoundCue](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)]* Sound cues in FILM time — a music bed, an ambience under every shot (`SoundCue`). Empty, the default, is no sound layer at all. #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Stepped timing for AUTHORED TWEENS, in pose updates per second; `None` (the default) leaves every tween smooth. At 30 fps, `15` is “on twos” and `10` “on threes” — the character-animation practice Spider-Verse made famous (characters on twos, simulation on ones). The camera is exempt by construction, as are swap channels (already stepped by format), compiled blinks and `play` clips: only `tween` curves are resampled — sample-and-hold of the eased curve on a SHOT-wide grid (every tween in a shot shares it; it restarts at a cut), not a retiming into holds and fast transitions. A tween’s own START and END are always pose changes too, so a tween that begins or ends off-grid changes pose on that frame as well as on the grid (a `set` at an off-grid `at` likewise lands where it was authored). A shot’s own `step_hz` overrides this. Must be positive (schema) and `<= fps` (validate + compile), an#89. #### style_pack *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The `StylePack` in the project’s `styles` store this scene is drawn under, by key. `None` — the default and what every existing document has — leaves every colour exactly where it is, which is why adding this moved no corpus hash (an#112). A pack changes what the COMPILER decides: the character palette, the leg and pupil colours, the environment presets’ sky and ground — and SVG art whose descriptor tags its colours by role (`colour_roles`, written by `an character new`). Untagged art is never inferred (inferring a role from a pixel is what produced an#99’s wrong-tone lid); a rig a pack cannot reach is WARNED about by name at compile. #### voice_loudness *: [VoiceLoudness](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness) | [None](https://docs.python.org/3/builtins/constants.html#None)* One loudness for every voice (`VoiceLoudness`, an#315); `None` — the default — levels nothing, and is omitted from JSON. ### *class* an.Project(root, mall, scene) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A loaded an project: directory + mall + current scene. ### *class* an.Resolution(\*\*data) Bases: `_IRModel` Pixel dimensions of the rendered output. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.SceneIR(\*\*data) Bases: `_IRModel` Top-level Scene IR document. The SSOT. A document is portable, diffable, and renderer-agnostic. Persisted as JSON at `ir/scene.json` inside an an project. ```pycon >>> from an.base import SCHEMA_VERSION >>> doc = SceneIR(meta=Meta(title="Hello")) >>> doc.version == SCHEMA_VERSION True >>> round_tripped = SceneIR.model_validate_json(doc.model_dump_json()) >>> round_tripped.meta.title 'Hello' ``` #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.Shot(\*\*data) Bases: `_IRModel` A single rendered unit. A scene is a sequence of shots. A shot’s `renderer` selects the backend that draws it. Every renderer must accept the same Shot fields; renderer-specific options go under `options`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### policy *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None)* per aspect, the methods it prefers in order, over the style pack’s (`StylePack.policy`) and under an author’s request — `{"locomotion": ["loco.glide"]}`. `None`: the style’s. * **Type:** This shot’s **policy** (an#348) #### renderer *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Which RENDERER draws this shot — not art direction. The field was called `style` until an#106, colliding with the styles store (which holds art direction) and with `AssetRef(kind="style")`; one word for two meanings is how a scene came to declare a “style” that selected a renderer while the thing that actually styles it went unread. A `str` in the schema (ADR 0001 decision 2): any name a renderer registered (`an.adapters.register_renderer`), checked by `an validate`. `cutout` stays the persisted default (decision 9). #### sounds *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[SoundCue](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)]* Sound cues in SHOT-local time (`SoundCue`). #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Per-shot override of [`Meta.step_hz`](_autosummary/an.html.md#an.Meta.step_hz) (`None` = inherit). #### transition *: [Transition](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) | [None](https://docs.python.org/3/builtins/constants.html#None)* How this shot is entered (`Transition`); `None` is a hard cut. ### an.build_project_mall(project_dir, , ensure=False, \*\*overrides) Build the standard project mall over `project_dir`. Pass `ensure=True` to create the per-store directories on disk if they don’t exist. Pass keyword overrides to swap in alternate stores (e.g. an in-memory `dict` for tests). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`MutableMapping`](https://docs.python.org/3/library/typing.html#typing.MutableMapping)] ### an.check_requirements() Return a per-tool status dict. The CLI subcommand `an check` pretty-prints this. Programmatic callers can inspect the dict directly. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)] ### an.crowd(id, , ref, count, kind='prop', store=None, layout='grid', area=(-480.0, -60.0, 480.0, 240.0), scale=1.0, scale_jitter=0.0, jitter=0.0, seed=0) `count` entities of one asset (`kind`/`store`/`ref`) placed in `area`. id: the crowd’s name; member `k` is `_` (`member_id()`) ref: the asset every member draws count: how many (at least 1) kind: the entity kind (`prop`, or a genre’s, such as `character`) store: the store the asset lives in (default: the kind’s registered store) layout: `grid` (rows filled from the back), `row` or `scatter` area: `(x0, y0, x1, y1)` in scene pixels about the stage centre; a > member’s stage point stands inside it scale: every member’s stage scale scale_jitter: each member’s scale varies by up to this fraction (`0.1`: ±10%) jitter: each grid or row member moves by up to this fraction of its cell seed: the scatter and the jitters are drawn from it ```pycon >>> [m.stage.at for m in crowd("line", ref="dot", count=3, layout="row", area=(0, 0, 300, 100))] [(50.0, 50.0), (150.0, 50.0), (250.0, 50.0)] >>> crowd("x", ref="dot", count=0) Traceback (most recent call last): ... ValueError: a crowd needs at least one member; got count=0 ``` * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`AssetRef`](_autosummary/an.ir.schema.html.md#an.ir.schema.AssetRef)] ### an.delay(duration) An empty span that consumes time. Useful inside `sequence`. * **Return type:** [`DelayAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.DelayAction) ### an.fan_out(action, members, , crowd_id=None) A copy of `action` per member, its targets moved from the crowd to the member. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] action: any action, leaf or composite; every target naming the crowd : (`army`, or a node of it, `army/arm_l`) is rewritten members: the crowd’s members (`AssetRef` s or ids), in order crowd_id: the crowd’s name (default: read off the first member’s id, > `army_0` -> `army`) Pair it with [`an.ir.compose.stagger()`](_autosummary/an.ir.compose.html.md#an.ir.compose.stagger) for a ripple through the ranks, or [`parallel()`](_autosummary/an.ir.compose.html.md#an.ir.compose.parallel) for the crowd moving as one. ```pycon >>> from an.ir.compose import tween >>> [a.target for a in fan_out(tween("army/arm_l", "rotation", to=1.0, duration=0.5), ["army_0", "army_1"])] ['army_0/arm_l', 'army_1/arm_l'] ``` ### an.flatten(action, , start=0.0, play_extent=None) Walk a composition tree, emitting leaf actions with absolute times. A `play` without `duration` advances a `sequence` by `play_extent` (default `default_play_extent()`): its natural length, or zero for a looping animation, which runs to the shot end. Delays are absorbed into the timeline (they don’t appear in the output). Loops are unrolled by simple repetition — appropriate at v0.1; the cutout runtime can re-roll for efficiency later. Every node is dispatched through its registered kind ([`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind)), so a genre’s kind flattens without an edit here; a node whose kind nobody registered raises, naming the genre that provides it, and an `ExtensionAction` read before its genre loaded is validated by the registered model on the way through. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`FlatAction`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlatAction)] ### an.init(project_dir, , name=None, force=False) Create a fresh an project at `project_dir`. Idempotent unless the directory already contains a non-empty `scene.md`; pass `force=True` to overwrite. Returns the absolute project root. The project’s `.gitignore` gains `PROJECT_GITIGNORE` (lines it lacks). * **Return type:** [`Path`](https://docs.python.org/3/library/pathlib.html#pathlib.Path) ### an.ir_to_markdown(scene) Render a SceneIR back into the structured Markdown form. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> from an.ir.schema import SceneIR, Meta, Shot >>> scene = SceneIR(meta=Meta(title="Demo", duration=5.0), ... timeline=[Shot(id="s1", renderer="cutout", duration=5.0)]) >>> md = ir_to_markdown(scene) >>> "# Demo" in md True >>> "## Shot s1 (cutout)" in md True ``` This writes the WHOLE document in the writer’s own formatting, and keeps no prose but `meta.notes`. Updating an existing `scene.md` goes through `merge_markdown()`, which keeps the author’s text wherever the content did not change. ### an.load(project_dir, , check_kinds=True) Load an existing project. Reconciles scene.md / ir/scene.json first. Registers the installed genres first ([`an.genres.load()`](_autosummary/an.genres.html.md#an.genres.load), ADR 0001 decision 3: discovery is explicit, and loading a project is one of the places it happens), so the scene’s genre kinds — the cut-out genre’s `play`, `expression` and `character` — read as their own models. Then refuses a scene that names an action kind, entity kind or renderer nothing registered ([`an.ir.validate.require_registered_kinds()`](_autosummary/an.ir.validate.html.md#an.ir.validate.require_registered_kinds)): the schema holds those as `str` (ADR 0001 decision 2), so without this a typo’d `kind: enviroment` would load and render silently without its backdrop. `check_kinds=False` is for `an validate`, which reports them as findings instead. * **Return type:** [`Project`](_autosummary/an.project.html.md#an.project.Project) ### an.loop(action, count) Repeat `action` `count` times. * **Return type:** [`LoopAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.LoopAction) ### an.markdown_to_ir(md_text) Parse the structured Markdown form of a scene into a SceneIR. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ```pycon >>> md = '''# Demo ... ... ```yaml meta ... title: Demo ... duration: 5 ... ``` ... ... ## Shot s1 (cutout) ... ... ```yaml shot ... duration: 5 ... ``` ... ... ```dialogue ... charlie: hi ... ``` ... ''' >>> scene = markdown_to_ir(md) >>> scene.meta.title 'Demo' >>> scene.timeline[0].id 's1' >>> scene.timeline[0].dialogue[0].text 'hi' ``` ### an.parallel(\*actions) Run all children at once. Total duration = max of child durations. * **Return type:** [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction) ### an.save(project) Persist a Project’s current scene back to disk (md + json). * **Return type:** [`None`](https://docs.python.org/3/builtins/constants.html#None) ### an.sequence(\*actions) Run children one after the other. Total duration = sum of child durations. * **Return type:** [`SequenceAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SequenceAction) ### an.set_(target, property, value, , at=0.0) Discrete property set at time `at` (relative to its enclosing scope). * **Return type:** [`SetAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SetAction) ### an.stagger(lag, \*actions) Start each action `lag` seconds after the previous one STARTS. The **stagger** (Manim’s `LaggedStart`, `previz`’s compose, a crowd entering one by one): the children run in parallel, the `i`-th delayed by `i * lag`. It is authoring sugar, not a new kind — it builds the `parallel` of `sequence(delay(i * lag), action)` it means, so the scene document, `scene.md` and every renderer see only core kinds. Total duration: the latest child’s end. `scene.md` holds it verbatim (a `kind: parallel` entry), so it round-trips. (`an.stage.text.reveal_units` — `an.stage.text.stagger` before an#241 — is the text-block preset: a LIST of per-unit actions with holds, not a combinator.) * **Return type:** [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction) ```pycon >>> flat = flatten(stagger(0.25, tween("a", "x", to=1.0, duration=1.0), ... tween("b", "x", to=1.0, duration=1.0), ... tween("c", "x", to=1.0, duration=1.0))) >>> [(f.action.target, f.start, f.end) for f in flat] [('a', 0.0, 1.0), ('b', 0.25, 1.25), ('c', 0.5, 1.5)] >>> duration_of(stagger(0.5, delay(1.0), delay(1.0))) 1.5 >>> stagger(0.1).children [] >>> stagger(-1.0, delay(1.0)) Traceback (most recent call last): ... ValueError: stagger lag must be >= 0, got -1.0 ``` ### an.tween(target, property, to, duration, , from_=None, easing=INHERIT) Animate a property from `from_` (or its current value) to `to`. `easing` left out inherits the scene’s `meta.default_easing` (else `"ease_in_out"`); naming one — `"ease_in_out"` included — pins it. * **Return type:** [`TweenAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.TweenAction) ```pycon >>> "easing" in tween("a", "x", to=1.0, duration=1.0).model_fields_set False >>> tween("a", "x", to=1.0, duration=1.0, easing="linear").easing 'linear' ``` ### an.validate_schema(doc) Validate that `doc` (dict, JSON string, or SceneIR) conforms to the schema. * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) ```pycon >>> validate_schema({"meta": {"title": "x"}, "timeline": []}).passed True >>> r = validate_schema({"meta": {"title": "x"}, "timeline": [{"id": "s", "duration": "not-a-number"}]}) >>> r.passed False ``` ### an.validate_semantic(scene, , available_voices=None, available_characters=None, available_props=None, available_environments=None, available_sounds=None, available_library_lock=None, available_styles=None, only=None, fps=None) Cross-field semantic checks. Pass live stores in for cross-store checks. Both `available_voices` and `available_characters` accept any mapping; `available_props` is the same thing for `kind="prop"` entities (an#108), and `available_environments` lets the flat-pan warning read a stage’s planes (an#111) — without it a prop’s swaps are reported as having no descriptor, which is validate refusing what compile accepts. Voices are consulted via `__contains__` only; characters additionally via `__getitem__` (the swap-reference and `play` checks read descriptor dicts, an#87 / an#7). Pass `None` to skip those checks — and know that skipping them is what it sounds like: a `play` or a swap the compiler will refuse passes silently without the store (the CLI, `an validate`, always passes it). `available_styles` is the project’s `styles` store: a check reads the StylePack the scene names (`meta.style_pack`) from `ctx.stores["styles"]` (a style’s `policy`, an#348). `available_library_lock` is the project’s asset-library lockfile (`mall["library_lock"]`): with it, every scene `library:` pin is checked against the lockfile (`warning` on disagreement) and every pinned check-out against its library version (`info` when it has been edited). The checks are a REGISTRY ([`an.genres.registry.register_check()`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_check)): the core’s own register below, a genre’s when it is loaded (the cut-out genre’s `play`, `expression`, turn and view checks), and they run in stages — `scene`, then `shot` once per shot, then `finish` — each by its `order`. An action or entity kind no loaded genre registered is one error naming the genre that provides it; checks that would trip over it skip that shot rather than crash. `only` runs just the registered checks of those names (what `an render` does after synthesis, `post_synthesis_findings()`); `fps` is the one the film is assembled at when it is not the scene’s (`an render --fps`), which decides how long a dissolve’s overlap is. * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) ### Modules | [`adapters`](_autosummary/an.adapters.html.md#module-an.adapters) | Renderer adapters — facades over backends (the stage, Manim, Remotion, whiteboard). | |----------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------| | [`assemble`](_autosummary/an.assemble.html.md#module-an.assemble) | Film assembly: rendered shots → one film, with transitions and a sound layer. | | [`audio`](_autosummary/an.audio.html.md#module-an.audio) | Audio pipeline — TTS and lip-sync providers + orchestration. | | [`base`](_autosummary/an.base.html.md#module-an.base) | Core types, constants, and re-exports for an. | | [`bench`](_autosummary/an.bench.html.md#module-an.bench) | `an bench` — render a fixed corpus, compute a metrics panel, write one ledger row. | | [`build`](_autosummary/an.build.html.md#module-an.build) | Incremental re-processing: content-addressed build stages (ADR 0004). | | [`capabilities`](_autosummary/an.capabilities.html.md#module-an.capabilities) | Capabilities: what an asset, an engine or the environment affords, and the one matcher. | | [`captions`](_autosummary/an.captions.html.md#module-an.captions) | Captions from the word timings the audio pipeline already computes (an#175). | | [`conftest`](_autosummary/an.conftest.html.md#module-an.conftest) | Collection rules for the package's own doctests. | | [`credits`](_autosummary/an.credits.html.md#module-an.credits) | What a rendered video owes, and to whom. | | [`data`](_autosummary/an.data.html.md#module-an.data) | Bundled non-Python resources (cutout JS runtime, etc.). | | [`determinism`](_autosummary/an.determinism.html.md#module-an.determinism) | The determinism perimeter: what must stay true for a render to be reproducible. | | [`engines`](_autosummary/an.engines.html.md#module-an.engines) | Engines: seekable things the core drives frame by frame, and the renderer that drives them. | | [`environments`](_autosummary/an.environments.html.md#module-an.environments) | Moved to [`an.stage.environments`](_autosummary/an.stage.environments.html.md#module-an.stage.environments) (an#247); this path is a LIVE alias of it. | | [`formats`](_autosummary/an.formats.html.md#module-an.formats) | Numbers as text: a declared subset of d3-format, for counters (an#342). | | [`frame_clock`](_autosummary/an.frame_clock.html.md#module-an.frame_clock) | The frame clock: WHEN each output frame samples scene time. | | [`genres`](_autosummary/an.genres.html.md#module-an.genres) | Genres: what a kind of animation adds to the core, declared as one object. | | [`ir`](_autosummary/an.ir.html.md#module-an.ir) | Scene IR — the single source of truth for a scene. | | [`iterate`](_autosummary/an.iterate.html.md#module-an.iterate) | Iterative edit loop — free-text instruction → IR patch via Claude → re-render. | | [`library`](_autosummary/an.library.html.md#module-an.library) | The asset library: reusable assets that outlive their videos (ADR 0005). | | [`live_api`](_autosummary/an.live_api.html.md#module-an.live_api) | The one switch that says "yes, this run may spend money". | | [`mcp`](_autosummary/an.mcp.html.md#module-an.mcp) | The `an` MCP server: a curated, generated surface over the vocabulary and the capability registry. | | [`measurements`](_autosummary/an.measurements.html.md#module-an.measurements) | Measured durations: shots whose renderer, not their author, decides their length. | | [`media`](_autosummary/an.media.html.md#module-an.media) | Frames to deliverables, engine-independent: the frame stage's resolves and the sinks. | | [`motion`](_autosummary/an.motion.html.md#module-an.motion) | Motion presets: a named vocabulary of moves, as authoring macros. | | [`orchestrate`](_autosummary/an.orchestrate.html.md#module-an.orchestrate) | Orchestrator: validate → audio → render → verify. | | [`paint`](_autosummary/an.paint.html.md#module-an.paint) | Paint: what fills a shape when one flat colour is not enough -- a gradient. | | [`paths`](_autosummary/an.paths.html.md#module-an.paths) | Moved to [`an.stage.paths`](_autosummary/an.stage.paths.html.md#module-an.stage.paths) (an#247); this path is a LIVE alias of it. | | [`preview`](_autosummary/an.preview.html.md#module-an.preview) | Moved to [`an.stage.preview`](_autosummary/an.stage.preview.html.md#module-an.stage.preview) (an#247); this path is a LIVE alias of it. | | [`probe`](_autosummary/an.probe.html.md#module-an.probe) | `an probe`: a shot's frame at chosen instants, through the very path `render` draws it (an#347). | | [`project`](_autosummary/an.project.html.md#module-an.project) | Project init/load/save — the on-disk anatomy of an an project. | | [`props`](_autosummary/an.props.html.md#module-an.props) | Moved to [`an.stage.props`](_autosummary/an.stage.props.html.md#module-an.stage.props) (an#247); this path is a LIVE alias of it. | | [`props_cli`](_autosummary/an.props_cli.html.md#module-an.props_cli) | `an props …` — a prop's asset folder from the shell (an#340). | | [`raster`](_autosummary/an.raster.html.md#module-an.raster) | Moved to [`an.stage.raster`](_autosummary/an.stage.raster.html.md#module-an.stage.raster) (an#247); this path is a LIVE alias of it. | | [`render`](_autosummary/an.render.html.md#module-an.render) | Project-level rendering: per-shot mp4 → final composited mp4 via ffmpeg concat. | | [`semantic`](_autosummary/an.semantic.html.md#module-an.semantic) | The semantic layer: one versioned vocabulary registry, methods, aspects and the matcher. | | [`sound_anchors`](_autosummary/an.sound_anchors.html.md#module-an.sound_anchors) | Sound cues timed by the picture (an#317): `at: {when: , reaches: {y: px}}` and `until:`. | | [`sound_fetch`](_autosummary/an.sound_fetch.html.md#module-an.sound_fetch) | Add a sound from a URL, with its provenance and the cut taken (an#318). | | [`sounds`](_autosummary/an.sounds.html.md#module-an.sounds) | Sound assets: what the sound layer plays, where it came from, and a synthesizer. | | [`sounds_cli`](_autosummary/an.sounds_cli.html.md#module-an.sounds_cli) | `an sounds …`: the project's sounds store from the shell (an#318). | | [`stage`](_autosummary/an.stage.html.md#module-an.stage) | The 2D stage: the default engine, shipped with `an` but outside the core (an#247). | | [`stores`](_autosummary/an.stores.html.md#module-an.stores) | Project mall: a dict of dol-backed `MutableMapping` stores. | | [`styles`](_autosummary/an.styles.html.md#module-an.styles) | StylePack: art direction as a document, and the first reader the styles store has had. | | [`text`](_autosummary/an.text.html.md#module-an.text) | Moved to [`an.stage.text`](_autosummary/an.stage.text.html.md#module-an.stage.text) (an#247); this path is a LIVE alias of it. | | [`timing`](_autosummary/an.timing.html.md#module-an.timing) | The timing kernel: what is on screen at time `t`, as a pure function. | | [`tools`](_autosummary/an.tools.html.md#module-an.tools) | User-facing utility functions, plus the SSOT list for CLI dispatch. | | [`util`](_autosummary/an.util.html.md#module-an.util) | Internal helpers: file I/O, hashing, time arithmetic, light path utilities. | | [`verify`](_autosummary/an.verify.html.md#module-an.verify) | Verification protocol — same interface for human, lint, vision-LM, MoVer. | # _autosummary/an.ir.assets.html.md # an.ir.assets Where a third-party asset came from, and what its licence obliges. `an` composes work it did not create — avatar art from a generator, stock images, fonts, commissioned SVG — into a video its user ships. A licence defect is the only failure in this package that reaches *backwards* through completed work: a video shipped with an unattributed CC BY asset cannot be un-shipped, whereas every rendering bug can be fixed forward. Until now there was nowhere to record any of it. The character descriptor’s `metadata` dict carried a comment saying it *could* hold a licence; nothing ever put one there. ### Why the field names look borrowed They are. The rights fields are spelled exactly as `illustration.ImageResult` spells them — `license`, `license_url`, `attribution`, `source_page_url`, `author`, `author_url`, `cacheable`, `provider`, `id`, `url` — because `illustration` is the federation’s image-retrieval package and its results are the most likely thing to become an `AssetSource`. Identical names mean the adapter is a dict copy rather than a rename table, and a rename table is where a field quietly stops being carried. `tests/` pins this literally. That is the precedent `artful` already set for shared vocabulary across packages that must not depend on each other. Two fields are `an`’s own, because `ImageResult` has no equivalent: - `sha256` — the digest of the bytes as they entered the project. A licence attached to a URL is a licence attached to whatever that URL serves *today*; attached to a digest, it stays attached to the thing that was actually used. - `cost_usd` — what acquiring it cost, if anything. **\`None\` means unknown, never free.** That is the federation’s rule for costs and it matters here for the same reason it matters in a plan: a `0.0` that means “we did not check” reads as “this was free” to every consumer downstream. ### The long-term home This is a local definition of something three packages need — `illustration` retrieves third-party images, `an` composes them, `reelee` ships the result — and that is the signature of a missing federation primitive rather than three missing local fields. It is proposed upstream as `lacing.Artifact.rights` (lacing#34). `Artifact` is frozen and holds real deployed data, so that change needs a registered migration and a coordinated release; until it lands, this mirror is what keeps `an` from shipping unattributed work in the meantime. ### Module Attributes | [`PRIVATE_STUDY`](_autosummary/an.ir.assets.html.md#an.ir.assets.PRIVATE_STUDY) | The recognised code for material its owner has not licensed at all — frames or art carved out of a film, a show, a book — that a user may study privately but must not publish (an#211). | |---------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`PUBLIC_DOMAIN`](_autosummary/an.ir.assets.html.md#an.ir.assets.PUBLIC_DOMAIN) | The recognised code for the public domain — no rights to clear, nothing owed (an#211). | | [`LicenseClass`](_autosummary/an.ir.assets.html.md#an.ir.assets.LicenseClass) | What a licence means for shipping the video it ends up in. | | [`PROVIDER_TERMS_RESTRICTIONS`](_autosummary/an.ir.assets.html.md#an.ir.assets.PROVIDER_TERMS_RESTRICTIONS) | the words a credits report prints beside it. | | [`ATTRIBUTION_REQUIRING_LICENSES`](_autosummary/an.ir.assets.html.md#an.ir.assets.ATTRIBUTION_REQUIRING_LICENSES) | Licence codes that oblige the *user of the output* to credit someone. | | [`NONCOMMERCIAL_LICENSES`](_autosummary/an.ir.assets.html.md#an.ir.assets.NONCOMMERCIAL_LICENSES) | Licence codes for NON-COMMERCIAL use only, each owing a credit too (an#373): Creative Commons' NC family. | | [`NONCOMMERCIAL_RESTRICTION`](_autosummary/an.ir.assets.html.md#an.ir.assets.NONCOMMERCIAL_RESTRICTION) | What a `noncommercial` licence restricts, printed wherever one is listed (a provider's own terms say it in their own words instead). | ### Functions | [`provider_terms_restriction`](_autosummary/an.ir.assets.html.md#an.ir.assets.provider_terms_restriction)(source) | The restriction a provider-terms licence carries beyond its class, if any. | |---------------------------------------------------------------------------------------|---------------------------------------------------------------------------------| | [`license_class`](_autosummary/an.ir.assets.html.md#an.ir.assets.license_class)(source) | What this asset's licence means for shipping the video (an#211). | | [`license_restriction`](_autosummary/an.ir.assets.html.md#an.ir.assets.license_restriction)(source) | What a licence restricts beyond its class's credit, for a report line (an#373). | | [`normalise_license`](_autosummary/an.ir.assets.html.md#an.ir.assets.normalise_license)(code) | A licence code folded to lowercase words joined by `-`. | | [`requires_attribution`](_autosummary/an.ir.assets.html.md#an.ir.assets.requires_attribution)(source) | Whether shipping this asset obliges the user to credit someone. | ### Classes | [`AssetSource`](_autosummary/an.ir.assets.html.md#an.ir.assets.AssetSource)(\*\*data) | Provenance and rights for one third-party asset. | |--------------------------------------------------------------------------|----------------------------------------------------| ### an.ir.assets.ATTRIBUTION_REQUIRING_LICENSES *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'by', 'by-sa', 'cc-by', 'cc-by-4.0', 'cc-by-nd', 'cc-by-sa', 'cc-by-sa-4.0'})* Licence codes that oblige the *user of the output* to credit someone. Matched case-insensitively against the licence code. Deliberately a small, explicit set rather than a pattern: “does this oblige me” is a question with a legal answer, and a regex that guesses is worse than a list that admits what it does not know. An unrecognised licence is reported as UNKNOWN, which is not the same as “no obligation”. ### *class* an.ir.assets.AssetSource(\*\*data) Bases: `BaseModel` Provenance and rights for one third-party asset. ```pycon >>> s = AssetSource(provider="dicebear", id="lorelei/amy", license="cc0-1.0") >>> requires_attribution(s) False >>> s = AssetSource(provider="dicebear", id="adventurer/amy", license="cc-by-4.0") >>> requires_attribution(s) True ``` #### cacheable *: [bool](https://docs.python.org/3/builtins/functions.html#bool) | [None](https://docs.python.org/3/builtins/constants.html#None)* `False` — they do not (the Freesound API keeps every sound by reference), and no store takes them; `None` — not recorded, which is not a yes (an#332, as `lacing.Rights`); `True` — they do. * **Type:** Whether the terms let the bytes be KEPT (stored, cached) #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow'}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### an.ir.assets.LicenseClass What a licence means for shipping the video it ends up in. - `attribution` — shippable, with a credit that MUST be displayed; - `free` — shippable, nothing owed (public domain, CC0, MIT-shaped); - `noncommercial` — shippable in a personal or private video, with its credit displayed, but NOT for commercial use (a monetised, sponsored or client video): CC BY-NC and its variants, the ElevenLabs free plan (an#373); - `private` — NOT shippable: all rights reserved, private study only; - `unknown` — not classified, which is not the same as free. alias of [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)[‘attribution’, ‘free’, ‘noncommercial’, ‘private’, ‘unknown’] ### an.ir.assets.NONCOMMERCIAL_LICENSES *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'by-nc', 'by-nc-nd', 'by-nc-sa', 'cc-by-nc', 'cc-by-nc-nd', 'cc-by-nc-sa'})* Licence codes for NON-COMMERCIAL use only, each owing a credit too (an#373): Creative Commons’ NC family. Matched like [`ATTRIBUTION_REQUIRING_LICENSES`](_autosummary/an.ir.assets.html.md#an.ir.assets.ATTRIBUTION_REQUIRING_LICENSES) (a trailing version counts as its family: `cc-by-nc-sa-4.0`). ### an.ir.assets.NONCOMMERCIAL_RESTRICTION *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'non-commercial use only (no monetised, sponsored or client video); credit owed'* What a `noncommercial` licence restricts, printed wherever one is listed (a provider’s own terms say it in their own words instead). ### an.ir.assets.PRIVATE_STUDY *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'all-rights-reserved-private-study'* The recognised code for material its owner has not licensed at all — frames or art carved out of a film, a show, a book — that a user may study privately but must not publish (an#211). Any code that normalises to one starting with `all-rights-reserved` or `private-study` is this class, so `"All rights reserved - private study only"` is recognised too. ### an.ir.assets.PROVIDER_TERMS_RESTRICTIONS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= {'elevenlabs-free-plan': 'ElevenLabs free plan: non-commercial use only, and the video must credit ElevenLabs (elevenlabs.io)', 'stability-community': "Stability AI Community License: the licence ends once you (with affiliates) make over USD 1,000,000 a year (then an Enterprise licence is needed), and use must follow Stability's acceptable use policy"}* the words a credits report prints beside it. * **Type:** What a provider-terms code restricts beyond its class, by code ### an.ir.assets.PUBLIC_DOMAIN *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'public-domain'* The recognised code for the public domain — no rights to clear, nothing owed (an#211). `pd`, `pd-us`, `pdm-1.0`, `public-domain`, `cc-pdm-1.0` and `cc0-*` are all this class. ### an.ir.assets.license_class(source) What this asset’s licence means for shipping the video (an#211). * **Return type:** [`Literal`](https://docs.python.org/3/library/typing.html#typing.Literal)[`'attribution'`, `'free'`, `'noncommercial'`, `'private'`, `'unknown'`] ```pycon >>> license_class(AssetSource(provider="p", license="pd")) 'free' >>> license_class(AssetSource(provider="p", license="all-rights-reserved")) 'private' >>> license_class(AssetSource(provider="p", license="cc-by-4.0")) 'attribution' >>> license_class(AssetSource(provider="freesound", license="cc-by-nc-4.0")) 'noncommercial' >>> license_class(AssetSource(provider="p", license="bespoke")) 'unknown' ``` A provider’s terms count for what that provider made (`PROVIDER_TERMS`): ```pycon >>> license_class(AssetSource(provider="elevenlabs", license="elevenlabs-paid-plan")) 'free' >>> license_class(AssetSource(provider="openai", license="elevenlabs-paid-plan")) 'unknown' ``` ### an.ir.assets.license_restriction(source) What a licence restricts beyond its class’s credit, for a report line (an#373). * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> license_restriction(AssetSource(provider="freesound", license="cc-by-nc-4.0"))[:24] 'non-commercial use only ' >>> license_restriction(AssetSource(provider="p", license="cc-by-4.0")) is None True ``` ### an.ir.assets.normalise_license(code) A licence code folded to lowercase words joined by `-`. Free text is what people actually write in a licence field, so the classifier reads through punctuation and spacing: * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> normalise_license("All rights reserved - private study only; never publish") 'all-rights-reserved-private-study-only-never-publish' >>> normalise_license(" CC-BY-4.0 ") 'cc-by-4-0' ``` ### an.ir.assets.provider_terms_restriction(source) The restriction a provider-terms licence carries beyond its class, if any. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> provider_terms_restriction(AssetSource(provider="elevenlabs", license="elevenlabs-free-plan"))[:21] 'ElevenLabs free plan:' >>> provider_terms_restriction(AssetSource(provider="openai", license="elevenlabs-free-plan")) is None True ``` ### an.ir.assets.requires_attribution(source) Whether shipping this asset obliges the user to credit someone. Returns `None` for an unrecognised or absent licence: “we do not know” is a distinct answer from “no”, and collapsing them is how an obligation gets silently dropped. Private-study material (all rights reserved) also answers `None` here — the question is not whom to credit but that it may not ship at all; [`license_class()`](_autosummary/an.ir.assets.html.md#an.ir.assets.license_class) says so (`"private"`). * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) | [`None`](https://docs.python.org/3/builtins/constants.html#None) # _autosummary/an.ir.camera.html.md # an.ir.camera Camera semantics: the named moves, and the one resolver that expands them. This module exists because the alternative was two hand-maintained tables. The compiler owned `CAMERA_MOVES` and `an.ir.validate` owned a frozenset of the same names, reconciled by a test — which works, and is not what “a move that validates cannot then raise” means. It means *one table*. It lives under `an/ir/` rather than in the cutout adapter because the IR layer must not import an adapter, and validate is in the IR layer. The camera is IR semantics anyway: `Camera`/`CameraKey` are schema models, and a renderer that cannot honour a move says so through `can_render`, not by keeping its own vocabulary. The geometry it encodes, verified numerically against the vendored PixiJS composition: `root.pivot` IS a 2D camera, because PixiJS composes `world = position + M·(local − pivot)` and the runtime indexes the centre container as `root`. `+x` moves the CAMERA right, which moves content left. ### Module Attributes | [`PAN_FRACTION`](_autosummary/an.ir.camera.html.md#an.ir.camera.PAN_FRACTION) | How far a pan travels, as a fraction of the canvas width (a tilt uses the same fraction of the height). | |-----------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------| | [`CAMERA_MOVES`](_autosummary/an.ir.camera.html.md#an.ir.camera.CAMERA_MOVES) | The named moves, as KEY LISTS. | ### Functions | [`camera_keys`](_autosummary/an.ir.camera.html.md#an.ir.camera.camera_keys)(shot, \*, width, height) | The shot's camera as an explicit key list — the ONE resolver. | |------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | [`camera_shake_offsets`](_autosummary/an.ir.camera.html.md#an.ir.camera.camera_shake_offsets)(shot, \*, width, height) | The shot's camera shakes as `(time, dx, dy)` screen offsets — the ONE resolver (an#429). | ### Exceptions | [`CameraError`](_autosummary/an.ir.camera.html.md#an.ir.camera.CameraError) | A camera that cannot be resolved into keys. | |----------------------------------------------------------------|-----------------------------------------------| ### an.ir.camera.CAMERA_MOVES *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Callable](https://docs.python.org/3/library/typing.html#typing.Callable)[[[float](https://docs.python.org/3/builtins/functions.html#float)], [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[CameraKey](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraKey)]]]* *= {'hold': >, 'pan_left': >, 'pan_right': >, 'pull_out': >, 'push_in': >, 'tilt_down': >, 'tilt_up': >, 'zoom_in': >, 'zoom_out': >}* The named moves, as KEY LISTS. `move` is sugar over `keys` — one code path, two front doors. The five zoom moves must desugar to **exactly** the document they produced before an#109, which is more specific than “a scale tween”: two animations named `__camera___scale_x`/`_scale_y`, one channel each targeting `root`, keyframes `[(0.0, s0, "ease_in_out"), (duration, s1, null)]`, on two tracks rooted at `"__camera__"`, and **no pivot channels**. The emitter emits only the channels that actually vary, which is what makes that true rather than merely intended — and what keeps every camera scene’s contract hash where it was. ### *exception* an.ir.camera.CameraError Bases: [`ValueError`](https://docs.python.org/3/builtins/exceptions.html#ValueError) A camera that cannot be resolved into keys. A plain `ValueError` subclass so the IR layer can raise it without knowing about any renderer; the cutout compiler re-raises it as a `CutoutCompileError` at its own boundary. ### an.ir.camera.PAN_FRACTION *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.3333333333333333* How far a pan travels, as a fraction of the canvas width (a tilt uses the same fraction of the height). A third of the frame is a legible move at any resolution and is the one number a named pan has to choose; an author who wants a different distance writes `keys` and says so. ### an.ir.camera.camera_keys(shot, , width, height) The shot’s camera as an explicit key list — the ONE resolver. `move` and `keys` are two front doors on one path. \*\*Validate calls this and so does the compiler\*\*, which is what makes “a move that validates cannot then raise” true by construction rather than by two tables agreeing — the arrangement it replaced (an#109 review, H-1). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`CameraKey`](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraKey)] ```pycon >>> from an.ir.schema import Camera, Shot >>> push = Shot(id="s", renderer="cutout", duration=2.0, camera=Camera(move="push_in")) >>> [(k.at, k.zoom) for k in camera_keys(push, width=320, height=240)] [(0.0, 1.0), (2.0, 1.25)] >>> pan = Shot(id="s", renderer="cutout", duration=2.0, camera=Camera(move="pan_left")) >>> [(k.at, round(k.x, 3)) for k in camera_keys(pan, width=320, height=240)] [(0.0, 0.0), (2.0, -106.667)] ``` ### an.ir.camera.camera_shake_offsets(shot, , width, height) The shot’s camera shakes as `(time, dx, dy)` screen offsets — the ONE resolver (an#429). Empty when the shot has none. Each shake is at rest (`0, 0`) at its start and its end; between, the frame jumps `frequency` times a second to a seeded offset of at most `amplitude` × the frame height, scaled down linearly to rest when `decay`. Validate and the compiler both call this, so a shake that validates cannot then raise (as with [`camera_keys()`](_autosummary/an.ir.camera.html.md#an.ir.camera.camera_keys)). * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float), [`float`](https://docs.python.org/3/builtins/functions.html#float)]] ```pycon >>> from an.ir.schema import Camera, CameraShake, Shot >>> s = Shot(id="s", duration=2.0, camera=Camera(shake=[CameraShake(at=1.0, duration=0.25, frequency=8)])) >>> [(t, round(dx, 2), round(dy, 2)) for t, dx, dy in camera_shake_offsets(s, width=1280, height=720)] [(1.0, 0.0, 0.0), (1.125, 3.72, 2.79), (1.25, 0.0, 0.0)] ``` # _autosummary/an.ir.compose.html.md # an.ir.compose Composition combinators for authoring action trees, plus a flattener. The composition tree is the *authoring* form. The flat list of ``` ` ``` FlatAction\`s with absolute start times is the *canonical* form that gets verified, cached, and rendered. Both forms round-trip through the schema; the flat form is what tooling reasons about. ```pycon >>> from an.ir.compose import sequence, parallel, tween, delay, flatten >>> action = sequence( ... tween("charlie/torso", "rotation", to=10.0, duration=1.0), ... delay(0.5), ... tween("charlie/torso", "rotation", to=0.0, duration=1.0), ... ) >>> flat = flatten(action) >>> [round(f.start, 3) for f in flat] [0.0, 1.5] >>> [round(f.end, 3) for f in flat] [1.0, 2.5] >>> action2 = parallel( ... tween("a", "x", to=1.0, duration=2.0), ... tween("b", "y", to=1.0, duration=3.0), ... ) >>> flat2 = flatten(action2) >>> [(round(f.start, 2), round(f.end, 2)) for f in flat2] [(0.0, 2.0), (0.0, 3.0)] ``` ### Module Attributes | [`INHERIT`](_autosummary/an.ir.compose.html.md#an.ir.compose.INHERIT) | `tween(..., easing=INHERIT)` — the default — leaves the easing UNSET, so the scene's `meta.default_easing` applies, else `"ease_in_out"` (an#166). | |-------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------| | [`PlayExtent`](_autosummary/an.ir.compose.html.md#an.ir.compose.PlayExtent) | `PlayAction -> seconds` a play WITHOUT an explicit `duration` occupies in a `sequence`. | ### Functions | [`delay`](_autosummary/an.ir.compose.html.md#an.ir.compose.delay)(duration) | An empty span that consumes time. | |---------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`duration_of`](_autosummary/an.ir.compose.html.md#an.ir.compose.duration_of)(action, \*[, play_extent]) | Compute the total duration of an action tree without evaluating it. | | [`flatten`](_autosummary/an.ir.compose.html.md#an.ir.compose.flatten)(action, \*[, start, play_extent]) | Walk a composition tree, emitting leaf actions with absolute times. | | [`iter_actions`](_autosummary/an.ir.compose.html.md#an.ir.compose.iter_actions)(action) | `action` and every action under it, depth first (composites through their kind's `children` hook). | | [`kind_of`](_autosummary/an.ir.compose.html.md#an.ir.compose.kind_of)(action) | The registered [`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind) that governs `action`. | | [`loop`](_autosummary/an.ir.compose.html.md#an.ir.compose.loop)(action, count) | Repeat `action` `count` times. | | [`map_leaves`](_autosummary/an.ir.compose.html.md#an.ir.compose.map_leaves)(action, fn) | `action` with every LEAF replaced by `fn(leaf)`, composites rebuilt around them (whatever field a composite keeps its children in: its kind's `children` hook says which values are children, the model's fields say where they live, so `loop.child` and a genre's composite are reached). | | [`parallel`](_autosummary/an.ir.compose.html.md#an.ir.compose.parallel)(\*actions) | Run all children at once. | | [`resolve_action`](_autosummary/an.ir.compose.html.md#an.ir.compose.resolve_action)(action) | `action` as its registered model (an `ExtensionAction` left open by a document read before its genre loaded is validated now). | | [`sequence`](_autosummary/an.ir.compose.html.md#an.ir.compose.sequence)(\*actions) | Run children one after the other. | | [`set_`](_autosummary/an.ir.compose.html.md#an.ir.compose.set_)(target, property, value, \*[, at]) | Discrete property set at time `at` (relative to its enclosing scope). | | [`stagger`](_autosummary/an.ir.compose.html.md#an.ir.compose.stagger)(lag, \*actions) | Start each action `lag` seconds after the previous one STARTS. | | [`tween`](_autosummary/an.ir.compose.html.md#an.ir.compose.tween)(target, property, to, duration, \*[, ...]) | Animate a property from `from_` (or its current value) to `to`. | ### Classes | [`FlatAction`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlatAction)(start, end, action) | A leaf action with its absolute start and end times. | |-----------------------------------------------------------------------------------|-------------------------------------------------------------------------| | [`FlattenContext`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlattenContext)(out[, extent]) | What a kind's `flatten` hook gets: where to put leaves, how to recurse. | ### *class* an.ir.compose.FlatAction(start, end, action) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A leaf action with its absolute start and end times. The flat-form list is the canonical representation passed to renderers and verifiers. Composition nodes (sequence/parallel/delay/loop) do not appear in the flat form — they’re collapsed into time offsets. ### *class* an.ir.compose.FlattenContext(out, extent=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a kind’s `flatten` hook gets: where to put leaves, how to recurse. `extent` is the caller’s extent resolver ([`PlayExtent`](_autosummary/an.ir.compose.html.md#an.ir.compose.PlayExtent)), passed on to every leaf’s `duration` hook. #### flatten(action, t) Flatten `action` starting at `t`; return the new cursor. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ### an.ir.compose.INHERIT *= INHERIT* `tween(..., easing=INHERIT)` — the default — leaves the easing UNSET, so the scene’s `meta.default_easing` applies, else `"ease_in_out"` (an#166). A sentinel rather than `None` because `None` already means linear. ### an.ir.compose.PlayExtent `PlayAction -> seconds` a play WITHOUT an explicit `duration` occupies in a `sequence`. The default is `default_play_extent()`; the compiler and `an validate` pass one bound to the entity’s descriptor. Generically, it is the caller’s **extent resolver**: it is handed to every leaf kind’s `duration` hook ([`an.genres.ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind)), and the kinds that have an open-ended length (the cut-out genre’s `play`) consult it. alias of [`Callable`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)], [`float`](https://docs.python.org/3/builtins/functions.html#float)] ### an.ir.compose.delay(duration) An empty span that consumes time. Useful inside `sequence`. * **Return type:** [`DelayAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.DelayAction) ### an.ir.compose.duration_of(action, , play_extent=None) Compute the total duration of an action tree without evaluating it. `play_extent` resolves a duration-less `play` (see [`PlayExtent`](_autosummary/an.ir.compose.html.md#an.ir.compose.PlayExtent)). * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> duration_of(tween("a", "x", to=1.0, duration=2.0)) 2.0 >>> duration_of(sequence(delay(0.5), tween("a", "x", to=1.0, duration=1.5))) 2.0 >>> duration_of(parallel(delay(0.5), delay(2.5))) 2.5 >>> duration_of(loop(delay(0.25), 4)) 1.0 >>> duration_of(set_("a", "x", 1.0)) 0.0 ``` ### an.ir.compose.flatten(action, , start=0.0, play_extent=None) Walk a composition tree, emitting leaf actions with absolute times. A `play` without `duration` advances a `sequence` by `play_extent` (default `default_play_extent()`): its natural length, or zero for a looping animation, which runs to the shot end. Delays are absorbed into the timeline (they don’t appear in the output). Loops are unrolled by simple repetition — appropriate at v0.1; the cutout runtime can re-roll for efficiency later. Every node is dispatched through its registered kind ([`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind)), so a genre’s kind flattens without an edit here; a node whose kind nobody registered raises, naming the genre that provides it, and an `ExtensionAction` read before its genre loaded is validated by the registered model on the way through. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`FlatAction`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlatAction)] ### an.ir.compose.iter_actions(action) `action` and every action under it, depth first (composites through their kind’s `children` hook). Unregistered kinds are yielded, not raised: a validator walks with this to REPORT them. ```pycon >>> [a.kind for a in iter_actions(sequence(delay(1.0), loop(delay(0.5), 2)))] ['sequence', 'delay', 'loop', 'delay'] ``` ### an.ir.compose.kind_of(action) The registered [`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind) that governs `action`. Raises [`UnregisteredKindError`](_autosummary/an.genres.html.md#an.genres.UnregisteredKindError), naming the genre that provides it, for a kind nobody registered. * **Return type:** [`ActionKind`](_autosummary/an.genres.registry.html.md#an.genres.registry.ActionKind) ```pycon >>> kind_of(delay(1.0)).name 'delay' ``` ### an.ir.compose.loop(action, count) Repeat `action` `count` times. * **Return type:** [`LoopAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.LoopAction) ### an.ir.compose.map_leaves(action, fn) `action` with every LEAF replaced by `fn(leaf)`, composites rebuilt around them (whatever field a composite keeps its children in: its kind’s `children` hook says which values are children, the model’s fields say where they live, so `loop.child` and a genre’s composite are reached). * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> act = sequence(delay(1.0), loop(set_("a", "x", 1.0), 2)) >>> renamed = map_leaves(act, lambda a: a.model_copy(update={"target": "b"}) if a.kind == "set" else a) >>> [a.target for a in iter_actions(renamed) if a.kind == "set"] ['b'] ``` ### an.ir.compose.parallel(\*actions) Run all children at once. Total duration = max of child durations. * **Return type:** [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction) ### an.ir.compose.resolve_action(action) `action` as its registered model (an `ExtensionAction` left open by a document read before its genre loaded is validated now). * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ```pycon >>> resolve_action(delay(0.5)).duration 0.5 ``` ### an.ir.compose.sequence(\*actions) Run children one after the other. Total duration = sum of child durations. * **Return type:** [`SequenceAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SequenceAction) ### an.ir.compose.set_(target, property, value, , at=0.0) Discrete property set at time `at` (relative to its enclosing scope). * **Return type:** [`SetAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SetAction) ### an.ir.compose.stagger(lag, \*actions) Start each action `lag` seconds after the previous one STARTS. The **stagger** (Manim’s `LaggedStart`, `previz`’s compose, a crowd entering one by one): the children run in parallel, the `i`-th delayed by `i * lag`. It is authoring sugar, not a new kind — it builds the `parallel` of `sequence(delay(i * lag), action)` it means, so the scene document, `scene.md` and every renderer see only core kinds. Total duration: the latest child’s end. `scene.md` holds it verbatim (a `kind: parallel` entry), so it round-trips. (`an.stage.text.reveal_units` — `an.stage.text.stagger` before an#241 — is the text-block preset: a LIST of per-unit actions with holds, not a combinator.) * **Return type:** [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction) ```pycon >>> flat = flatten(stagger(0.25, tween("a", "x", to=1.0, duration=1.0), ... tween("b", "x", to=1.0, duration=1.0), ... tween("c", "x", to=1.0, duration=1.0))) >>> [(f.action.target, f.start, f.end) for f in flat] [('a', 0.0, 1.0), ('b', 0.25, 1.25), ('c', 0.5, 1.5)] >>> duration_of(stagger(0.5, delay(1.0), delay(1.0))) 1.5 >>> stagger(0.1).children [] >>> stagger(-1.0, delay(1.0)) Traceback (most recent call last): ... ValueError: stagger lag must be >= 0, got -1.0 ``` ### an.ir.compose.tween(target, property, to, duration, , from_=None, easing=INHERIT) Animate a property from `from_` (or its current value) to `to`. `easing` left out inherits the scene’s `meta.default_easing` (else `"ease_in_out"`); naming one — `"ease_in_out"` included — pins it. * **Return type:** [`TweenAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.TweenAction) ```pycon >>> "easing" in tween("a", "x", to=1.0, duration=1.0).model_fields_set False >>> tween("a", "x", to=1.0, duration=1.0, easing="linear").easing 'linear' ``` # _autosummary/an.ir.html.md # an.ir Scene IR — the single source of truth for a scene. Three layers, per the architectural spec: - **Narrative** (`scene.md`) — human Markdown with structured fenced blocks. - **Scene Graph** (`ir/scene.json`) — Pydantic-validated JSON. The SSOT. - **Render Code** — generated per-backend, disposable. This subpackage owns layer 2 (the Pydantic schema), the Markdown↔JSON sync that keeps layer 1 and layer 2 in lock-step, the validators (schema + semantic), the version migration registry, and the composition combinators that flatten authoring-time DSL to canonical-form actions. ### Functions | [`set_`](_autosummary/an.ir.html.md#an.ir.set_)(target, property, value, \*[, at]) | Discrete property set at time `at` (relative to its enclosing scope). | |---------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------| | [`tween`](_autosummary/an.ir.html.md#an.ir.tween)(target, property, to, duration, \*[, ...]) | Animate a property from `from_` (or its current value) to `to`. | | [`sequence`](_autosummary/an.ir.html.md#an.ir.sequence)(\*actions) | Run children one after the other. | | [`parallel`](_autosummary/an.ir.html.md#an.ir.parallel)(\*actions) | Run all children at once. | | [`stagger`](_autosummary/an.ir.html.md#an.ir.stagger)(lag, \*actions) | Start each action `lag` seconds after the previous one STARTS. | | [`crowd`](_autosummary/an.ir.html.md#an.ir.crowd)(id, \*, ref, count[, kind, store, ...]) | `count` entities of one asset (`kind`/`store`/`ref`) placed in `area`. | | [`fan_out`](_autosummary/an.ir.html.md#an.ir.fan_out)(action, members, \*[, crowd_id]) | A copy of `action` per member, its targets moved from the crowd to the member. | | [`delay`](_autosummary/an.ir.html.md#an.ir.delay)(duration) | An empty span that consumes time. | | [`loop`](_autosummary/an.ir.html.md#an.ir.loop)(action, count) | Repeat `action` `count` times. | | [`flatten`](_autosummary/an.ir.html.md#an.ir.flatten)(action, \*[, start, play_extent]) | Walk a composition tree, emitting leaf actions with absolute times. | | [`validate_schema`](_autosummary/an.ir.html.md#an.ir.validate_schema)(doc) | Validate that `doc` (dict, JSON string, or SceneIR) conforms to the schema. | | [`validate_semantic`](_autosummary/an.ir.html.md#an.ir.validate_semantic)(scene, \*[, ...]) | Cross-field semantic checks. | | [`migrate`](_autosummary/an.ir.html.md#an.ir.migrate)(doc[, target_version, kind]) | Migrate a document to `target_version` (default: its kind's current). | | [`register_migration`](_autosummary/an.ir.html.md#an.ir.register_migration)(kind, from_version, ...) | Decorator: register a migration for one kind in `MIGRATIONS`. | | [`register_kind`](_autosummary/an.ir.html.md#an.ir.register_kind)(kind) | Register a document kind. | | [`kind_of`](_autosummary/an.ir.html.md#an.ir.kind_of)(doc, \*[, kind]) | Resolve a document's kind, by explicit name or from its `kind` tag. | | [`markdown_to_ir`](_autosummary/an.ir.html.md#an.ir.markdown_to_ir)(md_text) | Parse the structured Markdown form of a scene into a SceneIR. | | [`ir_to_markdown`](_autosummary/an.ir.html.md#an.ir.ir_to_markdown)(scene) | Render a SceneIR back into the structured Markdown form. | | [`sync`](_autosummary/an.ir.html.md#an.ir.sync)(project_dir) | Reconcile `scene.md` and `ir/scene.json` inside a project directory. | ### Classes | [`SceneIR`](_autosummary/an.ir.html.md#an.ir.SceneIR)(\*\*data) | Top-level Scene IR document. | |----------------------------------------------------------------------------------------------------|----------------------------------------------------------| | [`Meta`](_autosummary/an.ir.html.md#an.ir.Meta)(\*\*data) | Scene metadata. | | [`AssetRef`](_autosummary/an.ir.html.md#an.ir.AssetRef)(\*\*data) | Reference to an entry in a project store. | | [`Shot`](_autosummary/an.ir.html.md#an.ir.Shot)(\*\*data) | A single rendered unit. | | [`Dialogue`](_autosummary/an.ir.html.md#an.ir.Dialogue)(\*\*data) | One line of spoken dialogue. | | [`Camera`](_autosummary/an.ir.html.md#an.ir.Camera)(\*\*data) | Camera state for a shot: a named move, or explicit keys. | | [`Resolution`](_autosummary/an.ir.html.md#an.ir.Resolution)(\*\*data) | Pixel dimensions of the rendered output. | | [`FlatAction`](_autosummary/an.ir.html.md#an.ir.FlatAction)(start, end, action) | A leaf action with its absolute start and end times. | | [`ValidationReport`](_autosummary/an.ir.html.md#an.ir.ValidationReport)([passed, findings]) | Result of running one or more validators. | | [`ValidationFinding`](_autosummary/an.ir.html.md#an.ir.ValidationFinding)(severity, ir_path, description) | A single validation issue with a path into the IR. | | [`DocumentKind`](_autosummary/an.ir.html.md#an.ir.DocumentKind)(name, version_field, ...) | A schema-versioned document kind. | ### *class* an.ir.AssetRef(\*\*data) Bases: `_IRModel` Reference to an entry in a project store. The IR never inlines large assets. Instead it references them by store name + key, so the same character/voice/environment is reusable across scenes. `overrides` lets a single shot tweak presentation without forking the asset. ```pycon >>> AssetRef(kind="character", id="maya", store="characters", ref="maya-v1").id 'maya' ``` #### kind *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* it selected nothing (the compiler skipped it, nothing read the styles store) and the name belonged to the renderer selector. Art direction arrives as a StylePack (#112). A `str` in the schema, not a `Literal` (ADR 0001 decision 2): the values are the REGISTERED entity kinds ([`an.genres`](_autosummary/an.genres.html.md#module-an.genres)) — the core’s `environment`, `prop` and `voice`, a genre’s `character` — and `an validate` checks it against that registry, naming the genre that provides an unregistered one. * **Type:** `"style"` was retired in an#106 #### library *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The asset-library version this entry was checked out from (ADR 0005 decision 8): `"[:]@"`, e.g. `"cutan:character.alice-reiniger@v003"` (grammar: [`an.library.ids.parse_ref()`](_autosummary/an.library.ids.html.md#an.library.ids.parse_ref), a pinned version required: `vNNN` or `sha256:`, never `latest`). `None` — the default, and every document written before the library existed — means the asset is the project’s own. Today the strategy is check-out, so `ref` still names the project-store key the compiler reads and this field is the pin beside it; live reference resolves it instead, later. Additive and omit-when-unset, like `stage`: an unset `library` leaves no trace in a dump, so no stored scene changes and no schema version moves. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### stage *: [StagePlacement](_autosummary/an.ir.schema.html.md#an.ir.schema.StagePlacement) | [None](https://docs.python.org/3/builtins/constants.html#None)* Where on the stage this entity stands. `None` — the default and what every existing document has — means “wherever the layout puts it”, which for characters is the evenly-spaced row the compiler computes. **Additive by construction, and hash-free by construction**: the contract hashes the COMPILED document, and an `AssetRef` never reaches it. So this field can grow without retiring a single ledger row. ### *class* an.ir.Camera(\*\*data) Bases: `_CameraShakes` Camera state for a shot: a named move, or explicit keys. ```pycon >>> Camera(move="push_in").move 'push_in' >>> Camera(keys=[CameraKey(at=0.0), CameraKey(at=2.0, x=-200.0)]).keys[1].x -200.0 ``` **One code path, two front doors** — the shape the dialogue `[emotion]` sugar already uses. A named `move` desugars to a key list; `keys` is that list written out. Setting both raises, because a scene that says two things about the same camera has no reading that is not a guess. `keys` defaults to `None`, not `[]`, and that too is load-bearing: the markdown writer dumps the camera with `exclude_none=True`, which KEEPS empty lists — an empty default would write `keys: []` into every camera block it regenerates. `position`, `target` and `focal_length` were removed in an#109. They were written into every `scene.md` this package ever generated and read by nothing; a registered migration drops them. #### keys *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[CameraKey](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraKey)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The explicit door. `None` = use `move`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### move *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* A named preset — sugar for `keys`. The cutout renderer’s vocabulary is `an.stage.compile.CAMERA_MOVES`; validate and the compiler are pinned to the same table by test, because a move that validates and then raises is the failure `_check_renderable` exists to prevent. ### *class* an.ir.Dialogue(\*\*data) Bases: `_IRModel` One line of spoken dialogue. `start` and `duration` are None until the audio pipeline runs (TTS gives us a real duration); the pipeline stamps them then, deriving `start` from the author’s `pause` / `at` ([`planned_start()`](_autosummary/an.ir.html.md#an.ir.Dialogue.planned_start)). #### at *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Where this line starts, in SHOT seconds, whatever came before it — `(at 3.0)` in `scene.md`. `start` is what the audio pipeline DERIVES from `at`/`pause` on every pass; these two are what the author wrote (an#187). #### direction *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None)* How the line is DELIVERED — cues such as `["excited"]` or `["sighs", "annoyed"]`, `{excited}` in `scene.md` (an#209). A TTS model that takes inline audio tags (ElevenLabs v3/v4) receives them as `[excited] Hi!`; others ignore them. Never part of `text`, so captions and lip-sync alignment never see a cue. #### emotion_intensity *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* `maya [angry 0.4]: …` in `scene.md`, a typed parameter on the (b-name) emotion. `None` is full strength, and is omitted from JSON. * **Type:** How strongly `emotion` shows, 0..1 (an#253) #### leveled *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict) | [None](https://docs.python.org/3/builtins/constants.html#None)* , “gain_db”: }\`\` when `audio_ref` is the leveled audio. `None` — unleveled — is omitted from JSON. * **Type:** Stamped by voice leveling (an#315) * **Type:** ``` `` ``` {“source” #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### pause *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Seconds of silence before this line, after the previous line’s speech ends (the shot start, for the first line) — `(pause 1.5)` in `scene.md`. #### planned_start(cursor) Where this line starts, given the previous line ends at `cursor`. The one rule the audio pipeline stamps into `start` and `an validate` lays lines out by: `at` if set, else `cursor + pause`. A `start` on a line never synthesized (no `audio_ref`) was authored — the spelling of `at` before an#187 — and counts as one; a synthesized line’s `start` is the pipeline’s own stamp, re-derived here. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> Dialogue(speaker="a", text="bye", pause=1.5).planned_start(0.8) 2.3 >>> Dialogue(speaker="a", text="bye", at=4.0).planned_start(0.8) 4.0 >>> Dialogue(speaker="a", text="bye").planned_start(0.8) 0.8 ``` #### spoken *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* seconds from the line’s start to the end of its AUDIBLE speech — its take’s own trailing silence left out — stamped with `duration` from the line’s audio. The next line’s `pause` counts from here (a line with no pause still follows the whole take). `None` (silent audio, a line its voice’s `trim_silence` already cut to the tail the author keeps, a line stamped before an#397) counts from the end of `duration`, as before. Never written to JSON: it is read off the line’s stored audio on every pass (the audio pipeline, and a render that skips synthesis), so `scene.json` and its fixtures do not change. * **Type:** DERIVED (an#397) #### word_timings *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[WordTimingIR](_autosummary/an.ir.schema.html.md#an.ir.schema.WordTimingIR)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The provider’s word timings, line-relative; `None` when the provider has none (offline, Rhubarb) or the line was stamped before an#96. ### *class* an.ir.DocumentKind(name, version_field, current_version) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A schema-versioned document kind. `version_field` differs between kinds (`version` for the scene IR, `schema_version` for the character descriptor), which is exactly why a migrator cannot simply reach for `doc["version"]`. #### version_of(doc) The document’s declared version, defaulting to this build’s. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ### *class* an.ir.FlatAction(start, end, action) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A leaf action with its absolute start and end times. The flat-form list is the canonical representation passed to renderers and verifiers. Composition nodes (sequence/parallel/delay/loop) do not appear in the flat form — they’re collapsed into time offsets. ### *class* an.ir.Meta(\*\*data) Bases: `_IRModel` Scene metadata. #### captions *: [Captions](_autosummary/an.ir.schema.html.md#an.ir.schema.Captions) | [None](https://docs.python.org/3/builtins/constants.html#None)* Captions from the dialogue’s word timings (`Captions`, an#175); `None` — the default — is none, omitted from JSON like `style_pack`. #### closing_transition *: [Transition](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) | [None](https://docs.python.org/3/builtins/constants.html#None)* a `fade` to its `color` over its `duration`, on the last shot’s last frames (the film’s length is unchanged, and its final frame is the colour; the sound fades with it). `None` (or a `cut`) ends on the last frame as drawn. A dissolve has nothing to dissolve into, so it is refused. * **Type:** How the film ENDS (an#389) #### default_easing *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)] | [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[float](https://docs.python.org/3/builtins/functions.html#float)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The easing every authored `tween` that names none is drawn with (an#166) — `"linear"` for a snappy South Park cadence, an overshooting cubic-Bezier for a bouncy one. Precedence is \*\*tween > this > the built-in `"ease_in_out"``** (:meth:`TweenAction.resolved_easing`). ``None` — the default and what every existing document has — changes nothing, and is omitted from JSON like `style_pack`, so no committed scene and no compiled document moves. It reaches authored tweens ONLY: a motion preset writes its own easings, the camera’s named moves supply theirs, and blinks, `play` clips and swap channels have none to inherit. There is no per-shot override yet — style is a scene’s. #### default_renderer *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* a registered renderer’s name. * **Type:** Like [`Shot.renderer`](_autosummary/an.ir.html.md#an.ir.Shot.renderer) #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### sounds *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[SoundCue](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)]* Sound cues in FILM time — a music bed, an ambience under every shot (`SoundCue`). Empty, the default, is no sound layer at all. #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Stepped timing for AUTHORED TWEENS, in pose updates per second; `None` (the default) leaves every tween smooth. At 30 fps, `15` is “on twos” and `10` “on threes” — the character-animation practice Spider-Verse made famous (characters on twos, simulation on ones). The camera is exempt by construction, as are swap channels (already stepped by format), compiled blinks and `play` clips: only `tween` curves are resampled — sample-and-hold of the eased curve on a SHOT-wide grid (every tween in a shot shares it; it restarts at a cut), not a retiming into holds and fast transitions. A tween’s own START and END are always pose changes too, so a tween that begins or ends off-grid changes pose on that frame as well as on the grid (a `set` at an off-grid `at` likewise lands where it was authored). A shot’s own `step_hz` overrides this. Must be positive (schema) and `<= fps` (validate + compile), an#89. #### style_pack *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The `StylePack` in the project’s `styles` store this scene is drawn under, by key. `None` — the default and what every existing document has — leaves every colour exactly where it is, which is why adding this moved no corpus hash (an#112). A pack changes what the COMPILER decides: the character palette, the leg and pupil colours, the environment presets’ sky and ground — and SVG art whose descriptor tags its colours by role (`colour_roles`, written by `an character new`). Untagged art is never inferred (inferring a role from a pixel is what produced an#99’s wrong-tone lid); a rig a pack cannot reach is WARNED about by name at compile. #### voice_loudness *: [VoiceLoudness](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness) | [None](https://docs.python.org/3/builtins/constants.html#None)* One loudness for every voice (`VoiceLoudness`, an#315); `None` — the default — levels nothing, and is omitted from JSON. ### *class* an.ir.Resolution(\*\*data) Bases: `_IRModel` Pixel dimensions of the rendered output. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.SceneIR(\*\*data) Bases: `_IRModel` Top-level Scene IR document. The SSOT. A document is portable, diffable, and renderer-agnostic. Persisted as JSON at `ir/scene.json` inside an an project. ```pycon >>> from an.base import SCHEMA_VERSION >>> doc = SceneIR(meta=Meta(title="Hello")) >>> doc.version == SCHEMA_VERSION True >>> round_tripped = SceneIR.model_validate_json(doc.model_dump_json()) >>> round_tripped.meta.title 'Hello' ``` #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.Shot(\*\*data) Bases: `_IRModel` A single rendered unit. A scene is a sequence of shots. A shot’s `renderer` selects the backend that draws it. Every renderer must accept the same Shot fields; renderer-specific options go under `options`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### policy *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None)* per aspect, the methods it prefers in order, over the style pack’s (`StylePack.policy`) and under an author’s request — `{"locomotion": ["loco.glide"]}`. `None`: the style’s. * **Type:** This shot’s **policy** (an#348) #### renderer *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Which RENDERER draws this shot — not art direction. The field was called `style` until an#106, colliding with the styles store (which holds art direction) and with `AssetRef(kind="style")`; one word for two meanings is how a scene came to declare a “style” that selected a renderer while the thing that actually styles it went unread. A `str` in the schema (ADR 0001 decision 2): any name a renderer registered (`an.adapters.register_renderer`), checked by `an validate`. `cutout` stays the persisted default (decision 9). #### sounds *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[SoundCue](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)]* Sound cues in SHOT-local time (`SoundCue`). #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Per-shot override of [`Meta.step_hz`](_autosummary/an.ir.html.md#an.ir.Meta.step_hz) (`None` = inherit). #### transition *: [Transition](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) | [None](https://docs.python.org/3/builtins/constants.html#None)* How this shot is entered (`Transition`); `None` is a hard cut. ### *class* an.ir.ValidationFinding(severity, ir_path, description, location=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A single validation issue with a path into the IR. #### location *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* `":"` when the thing to fix is an opaque source a shot runs (a Manim scene file, an#279) rather than the IR; `None` otherwise. ### *class* an.ir.ValidationReport(passed=True, findings=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Result of running one or more validators. `passed` is True iff there are no error-severity findings. ### an.ir.crowd(id, , ref, count, kind='prop', store=None, layout='grid', area=(-480.0, -60.0, 480.0, 240.0), scale=1.0, scale_jitter=0.0, jitter=0.0, seed=0) `count` entities of one asset (`kind`/`store`/`ref`) placed in `area`. id: the crowd’s name; member `k` is `_` (`member_id()`) ref: the asset every member draws count: how many (at least 1) kind: the entity kind (`prop`, or a genre’s, such as `character`) store: the store the asset lives in (default: the kind’s registered store) layout: `grid` (rows filled from the back), `row` or `scatter` area: `(x0, y0, x1, y1)` in scene pixels about the stage centre; a > member’s stage point stands inside it scale: every member’s stage scale scale_jitter: each member’s scale varies by up to this fraction (`0.1`: ±10%) jitter: each grid or row member moves by up to this fraction of its cell seed: the scatter and the jitters are drawn from it ```pycon >>> [m.stage.at for m in crowd("line", ref="dot", count=3, layout="row", area=(0, 0, 300, 100))] [(50.0, 50.0), (150.0, 50.0), (250.0, 50.0)] >>> crowd("x", ref="dot", count=0) Traceback (most recent call last): ... ValueError: a crowd needs at least one member; got count=0 ``` * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`AssetRef`](_autosummary/an.ir.schema.html.md#an.ir.schema.AssetRef)] ### an.ir.delay(duration) An empty span that consumes time. Useful inside `sequence`. * **Return type:** [`DelayAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.DelayAction) ### an.ir.fan_out(action, members, , crowd_id=None) A copy of `action` per member, its targets moved from the crowd to the member. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] action: any action, leaf or composite; every target naming the crowd : (`army`, or a node of it, `army/arm_l`) is rewritten members: the crowd’s members (`AssetRef` s or ids), in order crowd_id: the crowd’s name (default: read off the first member’s id, > `army_0` -> `army`) Pair it with [`an.ir.compose.stagger()`](_autosummary/an.ir.compose.html.md#an.ir.compose.stagger) for a ripple through the ranks, or [`parallel()`](_autosummary/an.ir.compose.html.md#an.ir.compose.parallel) for the crowd moving as one. ```pycon >>> from an.ir.compose import tween >>> [a.target for a in fan_out(tween("army/arm_l", "rotation", to=1.0, duration=0.5), ["army_0", "army_1"])] ['army_0/arm_l', 'army_1/arm_l'] ``` ### an.ir.flatten(action, , start=0.0, play_extent=None) Walk a composition tree, emitting leaf actions with absolute times. A `play` without `duration` advances a `sequence` by `play_extent` (default `default_play_extent()`): its natural length, or zero for a looping animation, which runs to the shot end. Delays are absorbed into the timeline (they don’t appear in the output). Loops are unrolled by simple repetition — appropriate at v0.1; the cutout runtime can re-roll for efficiency later. Every node is dispatched through its registered kind ([`ActionKind`](_autosummary/an.genres.html.md#an.genres.ActionKind)), so a genre’s kind flattens without an edit here; a node whose kind nobody registered raises, naming the genre that provides it, and an `ExtensionAction` read before its genre loaded is validated by the registered model on the way through. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`FlatAction`](_autosummary/an.ir.compose.html.md#an.ir.compose.FlatAction)] ### an.ir.ir_to_markdown(scene) Render a SceneIR back into the structured Markdown form. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> from an.ir.schema import SceneIR, Meta, Shot >>> scene = SceneIR(meta=Meta(title="Demo", duration=5.0), ... timeline=[Shot(id="s1", renderer="cutout", duration=5.0)]) >>> md = ir_to_markdown(scene) >>> "# Demo" in md True >>> "## Shot s1 (cutout)" in md True ``` This writes the WHOLE document in the writer’s own formatting, and keeps no prose but `meta.notes`. Updating an existing `scene.md` goes through `merge_markdown()`, which keeps the author’s text wherever the content did not change. ### an.ir.kind_of(doc, , kind=None) Resolve a document’s kind, by explicit name or from its `kind` tag. Raises `ValueError` for an unregistered kind rather than guessing — a document whose kind nobody declared has no known version field, so any answer would be a fabrication. * **Return type:** [`DocumentKind`](_autosummary/an.ir.html.md#an.ir.DocumentKind) ### an.ir.loop(action, count) Repeat `action` `count` times. * **Return type:** [`LoopAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.LoopAction) ### an.ir.markdown_to_ir(md_text) Parse the structured Markdown form of a scene into a SceneIR. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ```pycon >>> md = '''# Demo ... ... ```yaml meta ... title: Demo ... duration: 5 ... ``` ... ... ## Shot s1 (cutout) ... ... ```yaml shot ... duration: 5 ... ``` ... ... ```dialogue ... charlie: hi ... ``` ... ''' >>> scene = markdown_to_ir(md) >>> scene.meta.title 'Demo' >>> scene.timeline[0].id 's1' >>> scene.timeline[0].dialogue[0].text 'hi' ``` ### an.ir.migrate(doc, target_version=None, , kind=None) Migrate a document to `target_version` (default: its kind’s current). Walks the migration registry one step at a time, considering only the migrations registered for this document’s kind. Raises `ValueError` if no path exists between the source and target versions. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> from an.base import SCHEMA_VERSION >>> migrate({"version": SCHEMA_VERSION, "kind": "SceneIR"})["version"] == SCHEMA_VERSION True >>> migrate({"version": "0.1.0", "kind": "SceneIR"})["version"] == SCHEMA_VERSION True ``` ### an.ir.parallel(\*actions) Run all children at once. Total duration = max of child durations. * **Return type:** [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction) ### an.ir.register_kind(kind) Register a document kind. Returns it, so callers can bind the result. * **Return type:** [`DocumentKind`](_autosummary/an.ir.html.md#an.ir.DocumentKind) ### an.ir.register_migration(kind, from_version, to_version) Decorator: register a migration for one kind in `MIGRATIONS`. Registered against the throwaway `Widget` kind from the module docstring, deliberately: this registry is process-wide, so a doctest that registered a step for a REAL kind would leave a second path through the ladder for every test that ran afterwards — which is exactly what happened once, and it presented as one unrelated test failing only in a full run (an#106). * **Return type:** [`Callable`](https://docs.python.org/3/library/typing.html#typing.Callable)[[[`Callable`](https://docs.python.org/3/library/typing.html#typing.Callable)[[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]]], [`Callable`](https://docs.python.org/3/library/typing.html#typing.Callable)[[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]]] ```pycon >>> @register_migration("Widget", "1.0", "2.0") ... def _bump(doc): ... doc["widget_version"] = "2.0" ... return doc >>> ("Widget", "1.0", "2.0") in MIGRATIONS True ``` ### an.ir.sequence(\*actions) Run children one after the other. Total duration = sum of child durations. * **Return type:** [`SequenceAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SequenceAction) ### an.ir.set_(target, property, value, , at=0.0) Discrete property set at time `at` (relative to its enclosing scope). * **Return type:** [`SetAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SetAction) ### an.ir.stagger(lag, \*actions) Start each action `lag` seconds after the previous one STARTS. The **stagger** (Manim’s `LaggedStart`, `previz`’s compose, a crowd entering one by one): the children run in parallel, the `i`-th delayed by `i * lag`. It is authoring sugar, not a new kind — it builds the `parallel` of `sequence(delay(i * lag), action)` it means, so the scene document, `scene.md` and every renderer see only core kinds. Total duration: the latest child’s end. `scene.md` holds it verbatim (a `kind: parallel` entry), so it round-trips. (`an.stage.text.reveal_units` — `an.stage.text.stagger` before an#241 — is the text-block preset: a LIST of per-unit actions with holds, not a combinator.) * **Return type:** [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction) ```pycon >>> flat = flatten(stagger(0.25, tween("a", "x", to=1.0, duration=1.0), ... tween("b", "x", to=1.0, duration=1.0), ... tween("c", "x", to=1.0, duration=1.0))) >>> [(f.action.target, f.start, f.end) for f in flat] [('a', 0.0, 1.0), ('b', 0.25, 1.25), ('c', 0.5, 1.5)] >>> duration_of(stagger(0.5, delay(1.0), delay(1.0))) 1.5 >>> stagger(0.1).children [] >>> stagger(-1.0, delay(1.0)) Traceback (most recent call last): ... ValueError: stagger lag must be >= 0, got -1.0 ``` ### an.ir.sync(project_dir) Reconcile `scene.md` and `ir/scene.json` inside a project directory. Strategy in v0.1: Markdown is the human SSOT; if both exist, the JSON is regenerated from the Markdown unless mtimes show JSON is newer (which the user is told never to do — but we warn instead of silently overwriting). * **Return type:** `SyncResult` ### an.ir.tween(target, property, to, duration, , from_=None, easing=INHERIT) Animate a property from `from_` (or its current value) to `to`. `easing` left out inherits the scene’s `meta.default_easing` (else `"ease_in_out"`); naming one — `"ease_in_out"` included — pins it. * **Return type:** [`TweenAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.TweenAction) ```pycon >>> "easing" in tween("a", "x", to=1.0, duration=1.0).model_fields_set False >>> tween("a", "x", to=1.0, duration=1.0, easing="linear").easing 'linear' ``` ### an.ir.validate_schema(doc) Validate that `doc` (dict, JSON string, or SceneIR) conforms to the schema. * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) ```pycon >>> validate_schema({"meta": {"title": "x"}, "timeline": []}).passed True >>> r = validate_schema({"meta": {"title": "x"}, "timeline": [{"id": "s", "duration": "not-a-number"}]}) >>> r.passed False ``` ### an.ir.validate_semantic(scene, , available_voices=None, available_characters=None, available_props=None, available_environments=None, available_sounds=None, available_library_lock=None, available_styles=None, only=None, fps=None) Cross-field semantic checks. Pass live stores in for cross-store checks. Both `available_voices` and `available_characters` accept any mapping; `available_props` is the same thing for `kind="prop"` entities (an#108), and `available_environments` lets the flat-pan warning read a stage’s planes (an#111) — without it a prop’s swaps are reported as having no descriptor, which is validate refusing what compile accepts. Voices are consulted via `__contains__` only; characters additionally via `__getitem__` (the swap-reference and `play` checks read descriptor dicts, an#87 / an#7). Pass `None` to skip those checks — and know that skipping them is what it sounds like: a `play` or a swap the compiler will refuse passes silently without the store (the CLI, `an validate`, always passes it). `available_styles` is the project’s `styles` store: a check reads the StylePack the scene names (`meta.style_pack`) from `ctx.stores["styles"]` (a style’s `policy`, an#348). `available_library_lock` is the project’s asset-library lockfile (`mall["library_lock"]`): with it, every scene `library:` pin is checked against the lockfile (`warning` on disagreement) and every pinned check-out against its library version (`info` when it has been edited). The checks are a REGISTRY ([`an.genres.registry.register_check()`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_check)): the core’s own register below, a genre’s when it is loaded (the cut-out genre’s `play`, `expression`, turn and view checks), and they run in stages — `scene`, then `shot` once per shot, then `finish` — each by its `order`. An action or entity kind no loaded genre registered is one error naming the genre that provides it; checks that would trip over it skip that shot rather than crash. `only` runs just the registered checks of those names (what `an render` does after synthesis, `post_synthesis_findings()`); `fps` is the one the film is assembled at when it is not the scene’s (`an render --fps`), which decides how long a dissolve’s overlap is. * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) ### Modules | [`assets`](_autosummary/an.ir.assets.html.md#module-an.ir.assets) | Where a third-party asset came from, and what its licence obliges. | |---------------------------------------------------------------------------------|----------------------------------------------------------------------------| | [`camera`](_autosummary/an.ir.camera.html.md#module-an.ir.camera) | Camera semantics: the named moves, and the one resolver that expands them. | | [`compose`](_autosummary/an.ir.compose.html.md#module-an.ir.compose) | Composition combinators for authoring action trees, plus a flattener. | | [`schema`](_autosummary/an.ir.schema.html.md#module-an.ir.schema) | Pydantic v2 models for the Scene IR. | | [`validate`](_autosummary/an.ir.validate.html.md#module-an.ir.validate) | Schema and semantic validation for SceneIR documents. | # _autosummary/an.ir.schema.html.md # an.ir.schema Pydantic v2 models for the Scene IR. Design principles (locked in from the architectural plan): - **Renderer-agnostic.** No cutout-specific or Manim-specific fields here. Backend adapters compile shots into their own internal formats. This module only knows what every shot has in common. - **Versioned envelope.** Every IR document carries `version` and `compatible_version`. Migrations live in `an.ir.migrate`. - **Forward-compatible reads.** Top-level model has `extra="allow"` so a future field doesn’t crash an older reader. - \*\*Open `Action` union\*\* (ADR 0001 decision 2). The union holds the core kinds (`set`, `tween`, `sequence`, `parallel`, `delay`, `loop`) and ONE open member, [`ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction), which a callable discriminator selects for any other `kind`. A genre registers its kinds ([`an.genres`](_autosummary/an.genres.html.md#module-an.genres)); a document’s `kind: play` then validates to the registered model, and before registration it stays an `ExtensionAction` that round-trips untouched and that validate, flatten and the compiler refuse by name. The union is never rebuilt at registration. - **Time in seconds (float).** Always. Doctest: ```pycon >>> from an.ir.schema import SceneIR, Meta, Shot >>> scene = SceneIR( ... meta=Meta(title="Park Bench", duration=45.0), ... timeline=[Shot(id="s1", renderer="cutout", duration=45.0)], ... ) >>> from an.base import SCHEMA_VERSION >>> scene.version == SCHEMA_VERSION True >>> scene.kind 'SceneIR' >>> scene.timeline[0].renderer 'cutout' ``` ### Module Attributes | [`DFLT_SHAKE_DURATION`](_autosummary/an.ir.schema.html.md#an.ir.schema.DFLT_SHAKE_DURATION) | how long a jolt lasts, how far the frame jumps (a fraction of the frame HEIGHT, so it reads the same at any resolution: 0.015 is about 11 px at 720p), and how many times a second it jumps. | |----------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`CORE_ACTION_KINDS`](_autosummary/an.ir.schema.html.md#an.ir.schema.CORE_ACTION_KINDS) | The `kind` of every action the core defines (the static union members). | | [`EXTENSION_TAG`](_autosummary/an.ir.schema.html.md#an.ir.schema.EXTENSION_TAG) | The union tag of the open member. | | [`Action`](_autosummary/an.ir.schema.html.md#an.ir.schema.Action) | the core kinds plus [`ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction) for any other `kind` (a registered genre kind validates to its own model through it). | | [`DEFAULT_CAPTION_MAX_CHARS`](_autosummary/an.ir.schema.html.md#an.ir.schema.DEFAULT_CAPTION_MAX_CHARS) | the broadcast convention (BBC / Netflix timed-text guidance: 42 characters, two lines). | | [`DEFAULT_CAPTION_SIZE`](_autosummary/an.ir.schema.html.md#an.ir.schema.DEFAULT_CAPTION_SIZE) | Caption type size as a fraction of frame height — a little under the title default, as captions are read while something else is watched. | | [`STAGE_NODE_SPACE`](_autosummary/an.ir.schema.html.md#an.ir.schema.STAGE_NODE_SPACE) | The property space a 2D stage engine's node lives in ([`an.timing.spaces`](_autosummary/an.timing.spaces.html.md#module-an.timing.spaces)). | | [`SPECIMEN_DURATION`](_autosummary/an.ir.schema.html.md#an.ir.schema.SPECIMEN_DURATION) | How long a specimen shot runs (`an library sheet` draws its first frame). | | [`SPECIMEN_SHOT_ID`](_autosummary/an.ir.schema.html.md#an.ir.schema.SPECIMEN_SHOT_ID) | The id of a specimen shot. | ### Functions | [`resolve_step_hz`](_autosummary/an.ir.schema.html.md#an.ir.schema.resolve_step_hz)(shot, scene_step_hz) | The stepped-timing policy `shot` renders under: its own `step_hz` when it declares one, else the scene's, else `None` (smooth). | |----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | [`stage_specimen`](_autosummary/an.ir.schema.html.md#an.ir.schema.stage_specimen)(ref) | A short shot showing the one stage entity `ref` casts, on its own (an#347). | | [`unregistered_action_kind`](_autosummary/an.ir.schema.html.md#an.ir.schema.unregistered_action_kind)(kind, \*[, where]) | The error for an action `kind` no loaded genre registered. | ### Classes | [`AssetRef`](_autosummary/an.ir.schema.html.md#an.ir.schema.AssetRef)(\*\*data) | Reference to an entry in a project store. | |----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`Camera`](_autosummary/an.ir.schema.html.md#an.ir.schema.Camera)(\*\*data) | Camera state for a shot: a named move, or explicit keys. | | [`CameraFollow`](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraFollow)(\*\*data) | A camera that follows an entity (an#445): the frame keeps `target` where it stood at the shot's start. | | [`CameraKey`](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraKey)(\*\*data) | One camera pose at one time — the explicit door behind the named moves. | | [`CameraShake`](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraShake)(\*\*data) | A jolt of the frame inside a shot (an#429): seeded screen-space jitter. | | [`Captions`](_autosummary/an.ir.schema.html.md#an.ir.schema.Captions)(\*\*data) | Captions for the whole film, built from the dialogue's word timings. | | [`CueAnchor`](_autosummary/an.ir.schema.html.md#an.ir.schema.CueAnchor)(\*\*data) | A sound cue's time, taken from the picture (an#317): when a node reaches a frame row or column. | | [`CueUntil`](_autosummary/an.ir.schema.html.md#an.ir.schema.CueUntil)(\*\*data) | Where a sound cue ends: at another cue's start, plus `offset` (an#317). | | [`DelayAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.DelayAction)(\*\*data) | Composition: an empty span that consumes time. | | [`Dialogue`](_autosummary/an.ir.schema.html.md#an.ir.schema.Dialogue)(\*\*data) | One line of spoken dialogue. | | [`ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction)(\*\*data) | An action of a kind the core does not define: the IR's one open member. | | [`LoopAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.LoopAction)(\*\*data) | Composition: repeat `child` `count` times. | | [`Meta`](_autosummary/an.ir.schema.html.md#an.ir.schema.Meta)(\*\*data) | Scene metadata. | | [`Narration`](_autosummary/an.ir.schema.html.md#an.ir.schema.Narration)(\*\*data) | Off-screen narration. | | [`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction)(\*\*data) | Composition: run all children simultaneously starting at the same time. | | [`Resolution`](_autosummary/an.ir.schema.html.md#an.ir.schema.Resolution)(\*\*data) | Pixel dimensions of the rendered output. | | [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR)(\*\*data) | Top-level Scene IR document. | | [`SequenceAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SequenceAction)(\*\*data) | Composition: run children one after the other. | | [`SetAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SetAction)(\*\*data) | Set a property to a value at a specific time. | | [`Shot`](_autosummary/an.ir.schema.html.md#an.ir.schema.Shot)(\*\*data) | A single rendered unit. | | [`SoundCue`](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)(\*\*data) | One sound placed on the timeline: an SFX hit, an ambience, a music bed. | | [`StagePlacement`](_autosummary/an.ir.schema.html.md#an.ir.schema.StagePlacement)(\*\*data) | Where an entity stands on the stage, and how big it is. | | [`Transition`](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition)(\*\*data) | How a shot is ENTERED — from the previous shot, or (for the first shot) from nothing. | | [`TweenAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.TweenAction)(\*\*data) | Animate a property from a start value to an end value over a duration. | | [`VisemeKeyframe`](_autosummary/an.ir.schema.html.md#an.ir.schema.VisemeKeyframe)(\*\*data) | A single mouth-shape keyframe in a viseme track. | | [`VisemeTrack`](_autosummary/an.ir.schema.html.md#an.ir.schema.VisemeTrack)(\*\*data) | Aligned viseme track produced by the lip-sync stage. | | [`VoiceLoudness`](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness)(\*\*data) | One loudness for every voice of the film (an#315). | | [`WordTimingIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.WordTimingIR)(\*\*data) | One word of a line and when it was spoken, in seconds from the line's start (like [`VisemeKeyframe`](_autosummary/an.ir.schema.html.md#an.ir.schema.VisemeKeyframe), never absolute). | ### an.ir.schema.Action the core kinds plus [`ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction) for any other `kind` (a registered genre kind validates to its own model through it). `SerializeAsAny` makes a typed genre instance (a `PlayAction`) serialize with its own fields rather than the open member’s. * **Type:** Every action alias of `Annotated`[`Annotated`[[`SetAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SetAction), `Tag`(tag=set)] | `Annotated`[[`TweenAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.TweenAction), `Tag`(tag=tween)] | `Annotated`[[`SequenceAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.SequenceAction), `Tag`(tag=sequence)] | `Annotated`[[`ParallelAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ParallelAction), `Tag`(tag=parallel)] | `Annotated`[[`DelayAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.DelayAction), `Tag`(tag=delay)] | `Annotated`[[`LoopAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.LoopAction), `Tag`(tag=loop)] | `Annotated`[[`ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction), `SerializeAsAny`(), `Tag`(tag=extension)], `Discriminator`(discriminator=`_action_tag`, custom_error_type=[`None`](https://docs.python.org/3/builtins/constants.html#None), custom_error_message=[`None`](https://docs.python.org/3/builtins/constants.html#None), custom_error_context=[`None`](https://docs.python.org/3/builtins/constants.html#None))] ### *class* an.ir.schema.AssetRef(\*\*data) Bases: `_IRModel` Reference to an entry in a project store. The IR never inlines large assets. Instead it references them by store name + key, so the same character/voice/environment is reusable across scenes. `overrides` lets a single shot tweak presentation without forking the asset. ```pycon >>> AssetRef(kind="character", id="maya", store="characters", ref="maya-v1").id 'maya' ``` #### kind *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* it selected nothing (the compiler skipped it, nothing read the styles store) and the name belonged to the renderer selector. Art direction arrives as a StylePack (#112). A `str` in the schema, not a `Literal` (ADR 0001 decision 2): the values are the REGISTERED entity kinds ([`an.genres`](_autosummary/an.genres.html.md#module-an.genres)) — the core’s `environment`, `prop` and `voice`, a genre’s `character` — and `an validate` checks it against that registry, naming the genre that provides an unregistered one. * **Type:** `"style"` was retired in an#106 #### library *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The asset-library version this entry was checked out from (ADR 0005 decision 8): `"[:]@"`, e.g. `"cutan:character.alice-reiniger@v003"` (grammar: [`an.library.ids.parse_ref()`](_autosummary/an.library.ids.html.md#an.library.ids.parse_ref), a pinned version required: `vNNN` or `sha256:`, never `latest`). `None` — the default, and every document written before the library existed — means the asset is the project’s own. Today the strategy is check-out, so `ref` still names the project-store key the compiler reads and this field is the pin beside it; live reference resolves it instead, later. Additive and omit-when-unset, like `stage`: an unset `library` leaves no trace in a dump, so no stored scene changes and no schema version moves. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### stage *: [StagePlacement](_autosummary/an.ir.schema.html.md#an.ir.schema.StagePlacement) | [None](https://docs.python.org/3/builtins/constants.html#None)* Where on the stage this entity stands. `None` — the default and what every existing document has — means “wherever the layout puts it”, which for characters is the evenly-spaced row the compiler computes. **Additive by construction, and hash-free by construction**: the contract hashes the COMPILED document, and an `AssetRef` never reaches it. So this field can grow without retiring a single ledger row. ### an.ir.schema.CORE_ACTION_KINDS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('set', 'tween', 'sequence', 'parallel', 'delay', 'loop')* The `kind` of every action the core defines (the static union members). ### *class* an.ir.schema.Camera(\*\*data) Bases: `_CameraShakes` Camera state for a shot: a named move, or explicit keys. ```pycon >>> Camera(move="push_in").move 'push_in' >>> Camera(keys=[CameraKey(at=0.0), CameraKey(at=2.0, x=-200.0)]).keys[1].x -200.0 ``` **One code path, two front doors** — the shape the dialogue `[emotion]` sugar already uses. A named `move` desugars to a key list; `keys` is that list written out. Setting both raises, because a scene that says two things about the same camera has no reading that is not a guess. `keys` defaults to `None`, not `[]`, and that too is load-bearing: the markdown writer dumps the camera with `exclude_none=True`, which KEEPS empty lists — an empty default would write `keys: []` into every camera block it regenerates. `position`, `target` and `focal_length` were removed in an#109. They were written into every `scene.md` this package ever generated and read by nothing; a registered migration drops them. #### keys *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[CameraKey](_autosummary/an.ir.schema.html.md#an.ir.schema.CameraKey)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The explicit door. `None` = use `move`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### move *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* A named preset — sugar for `keys`. The cutout renderer’s vocabulary is `an.stage.compile.CAMERA_MOVES`; validate and the compiler are pinned to the same table by test, because a move that validates and then raises is the failure `_check_renderable` exists to prevent. ### *class* an.ir.schema.CameraFollow(\*\*data) Bases: `_IRModel` A camera that follows an entity (an#445): the frame keeps `target` where it stood at the shot’s start. ```pycon >>> CameraFollow(target="bob").axes 'x' ``` `target` is an entity id or one of its nodes (`bob/head`); `axes` is which way the camera tracks it (`x`: a side-scrolling walk, `xy`: both). Resolved at compile time from the compiled motion (the target’s position at every frame), so planes parallax with it like any camera move. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.CameraKey(\*\*data) Bases: `_IRModel` One camera pose at one time — the explicit door behind the named moves. ```pycon >>> CameraKey(at=1.0, x=-160.0, zoom=1.25).x -160.0 ``` **Sign convention**, stated because every surveyed tool disagrees: `+x` moves the CAMERA right, which moves the content left. `zoom` is on-screen magnification, so `1.25` means “everything 25% bigger”, and it composes through the pivot — a push-in during a pan zooms toward what the camera is looking at rather than toward a fixed frame centre. `rotation` is camera roll in radians. `easing` defaults to **\`None\`, not \`”ease_in_out”\`**, and that is not a style choice: today’s emitter puts `"ease_in_out"` on the first keyframe and `null` on the terminal one, so a per-key default of `"ease_in_out"` would put it on both and move every camera scene’s contract hash. The named moves supply the easing they have always supplied. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### rotation *: [float](https://docs.python.org/3/builtins/functions.html#float)* Camera roll, radians. #### x *: [float](https://docs.python.org/3/builtins/functions.html#float)* Camera position in scene pixels. `+x` moves the camera right. #### zoom *: [float](https://docs.python.org/3/builtins/functions.html#float)* On-screen magnification. Must be > 0 — a zero or negative zoom is not a camera, and the compiler would emit a degenerate root scale. ### *class* an.ir.schema.CameraShake(\*\*data) Bases: `_IRModel` A jolt of the frame inside a shot (an#429): seeded screen-space jitter. ```pycon >>> CameraShake(at=1.0).duration 0.4 ``` Layered on whatever the camera does (a `move`, `keys`, or nothing): the pan and zoom are the root’s pivot and scale, a shake is its screen position, so the two add without either knowing the other. The jitter is deterministic (`seed`) and, with `decay`, falls linearly to rest by the end; the frame is exactly at rest before `at` and after it. #### amplitude *: [float](https://docs.python.org/3/builtins/functions.html#float)* How far the frame jumps at most, as a fraction of the frame height. #### at *: [float](https://docs.python.org/3/builtins/functions.html#float)* When the jolt starts, in shot seconds. #### decay *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* Fall linearly to rest over the duration (an impact); off, it holds its amplitude to the end (a rumble). #### duration *: [float](https://docs.python.org/3/builtins/functions.html#float)* How long it lasts. #### frequency *: [float](https://docs.python.org/3/builtins/functions.html#float)* Jumps per second. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### seed *: [int](https://docs.python.org/3/builtins/functions.html#int)* the same seed draws the same jolt on every machine. * **Type:** Which jitter ### *class* an.ir.schema.Captions(\*\*data) Bases: `_IRModel` Captions for the whole film, built from the dialogue’s word timings. Present = on; `meta.captions` unset (the default) is no captions and no trace in any document. One cue list ([`an.captions.caption_pages()`](_autosummary/an.captions.html.md#an.captions.caption_pages)) feeds BOTH outputs, so the picture and the sidecar cannot disagree: - `burn`: each page is drawn as an overlay text block (camera-immune, placed at `anchor` in the title-safe area), shown for exactly the frames the sidecar says; - `sidecar`: a SubRip `.srt` written through the `captions` store, next to the delivered mp4, in FILM time (a dissolve shortens the film, and every later cue moves with it). ```pycon >>> Captions().max_chars, Captions().anchor (42, 'bottom') >>> Captions(highlight="#ffcc00").highlight '#ffcc00' ``` #### anchor *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* One of tituli’s nine title-safe anchors. #### font *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* `None` = the embedded face; else an ABSOLUTE font file path, or one relative to the project directory. #### highlight *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* the word being spoken is drawn in this colour (karaoke); `None` draws every word in `color`. * **Type:** `#rrggbb` #### max_chars *: [int](https://docs.python.org/3/builtins/functions.html#int)* Line breaks are made HERE, by character count, and written into both the burned block and the sidecar — the same lines in both. 42 fits the title-safe width of a 16:9 or 4:3 frame at the default size; a square or portrait frame needs fewer (about 32 at 1:1) or a smaller `size` — a line that does not fit is REFUSED before the render, never clipped. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### strict *: [bool](https://docs.python.org/3/builtins/functions.html#bool)* A line with no word timings is captioned with its words spread evenly over its duration, with a warning; `strict` makes that an error. ### *class* an.ir.schema.CueAnchor(\*\*data) Bases: `_IRModel` A sound cue’s time, taken from the picture (an#317): when a node reaches a frame row or column. `when` is a node path in a stage shot (`crawl/line_7`: a text block’s unit, a prop, a plane); `reaches` is `{"y": px}` or `{"x": px}` in the frame’s pixels (0 at the top or left), crossed in either direction by the node’s on-screen centre — the camera, parallax and a crawl’s tilt included. Resolved when the film is laid out, never written back into the scene: a layout change moves the sound with the picture. `offset` is added after. `shot` names the shot to look in, for a cue in `meta.sounds` (default: the first shot that has the node). ```pycon >>> CueAnchor(when="crawl/line_7", reaches={"y": 840}).axis ('y', 840.0) ``` #### *property* axis *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [float](https://docs.python.org/3/builtins/functions.html#float)]* `(axis, pixels)`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.CueUntil(\*\*data) Bases: `_IRModel` Where a sound cue ends: at another cue’s start, plus `offset` (an#317). `cue` is the `sound` key of a cue in the same list (the shot’s, or `meta.sounds`); the first such cue is meant. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### an.ir.schema.DEFAULT_CAPTION_MAX_CHARS *: [int](https://docs.python.org/3/builtins/functions.html#int)* *= 42* the broadcast convention (BBC / Netflix timed-text guidance: 42 characters, two lines). * **Type:** Characters per caption line and lines per caption page ### an.ir.schema.DEFAULT_CAPTION_SIZE *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.05* Caption type size as a fraction of frame height — a little under the title default, as captions are read while something else is watched. ### an.ir.schema.DFLT_SHAKE_DURATION *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.4* how long a jolt lasts, how far the frame jumps (a fraction of the frame HEIGHT, so it reads the same at any resolution: 0.015 is about 11 px at 720p), and how many times a second it jumps. Art direction, chosen to read as an impact rather than a tremor. * **Type:** A camera shake’s defaults (an#429) ### *class* an.ir.schema.DelayAction(\*\*data) Bases: `_ActionBase` Composition: an empty span that consumes time. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.Dialogue(\*\*data) Bases: `_IRModel` One line of spoken dialogue. `start` and `duration` are None until the audio pipeline runs (TTS gives us a real duration); the pipeline stamps them then, deriving `start` from the author’s `pause` / `at` ([`planned_start()`](_autosummary/an.ir.schema.html.md#an.ir.schema.Dialogue.planned_start)). #### at *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Where this line starts, in SHOT seconds, whatever came before it — `(at 3.0)` in `scene.md`. `start` is what the audio pipeline DERIVES from `at`/`pause` on every pass; these two are what the author wrote (an#187). #### direction *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] | [None](https://docs.python.org/3/builtins/constants.html#None)* How the line is DELIVERED — cues such as `["excited"]` or `["sighs", "annoyed"]`, `{excited}` in `scene.md` (an#209). A TTS model that takes inline audio tags (ElevenLabs v3/v4) receives them as `[excited] Hi!`; others ignore them. Never part of `text`, so captions and lip-sync alignment never see a cue. #### emotion_intensity *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* `maya [angry 0.4]: …` in `scene.md`, a typed parameter on the (b-name) emotion. `None` is full strength, and is omitted from JSON. * **Type:** How strongly `emotion` shows, 0..1 (an#253) #### leveled *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict) | [None](https://docs.python.org/3/builtins/constants.html#None)* , “gain_db”: }\`\` when `audio_ref` is the leveled audio. `None` — unleveled — is omitted from JSON. * **Type:** Stamped by voice leveling (an#315) * **Type:** ``` `` ``` {“source” #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### pause *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Seconds of silence before this line, after the previous line’s speech ends (the shot start, for the first line) — `(pause 1.5)` in `scene.md`. #### planned_start(cursor) Where this line starts, given the previous line ends at `cursor`. The one rule the audio pipeline stamps into `start` and `an validate` lays lines out by: `at` if set, else `cursor + pause`. A `start` on a line never synthesized (no `audio_ref`) was authored — the spelling of `at` before an#187 — and counts as one; a synthesized line’s `start` is the pipeline’s own stamp, re-derived here. * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) ```pycon >>> Dialogue(speaker="a", text="bye", pause=1.5).planned_start(0.8) 2.3 >>> Dialogue(speaker="a", text="bye", at=4.0).planned_start(0.8) 4.0 >>> Dialogue(speaker="a", text="bye").planned_start(0.8) 0.8 ``` #### spoken *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* seconds from the line’s start to the end of its AUDIBLE speech — its take’s own trailing silence left out — stamped with `duration` from the line’s audio. The next line’s `pause` counts from here (a line with no pause still follows the whole take). `None` (silent audio, a line its voice’s `trim_silence` already cut to the tail the author keeps, a line stamped before an#397) counts from the end of `duration`, as before. Never written to JSON: it is read off the line’s stored audio on every pass (the audio pipeline, and a render that skips synthesis), so `scene.json` and its fixtures do not change. * **Type:** DERIVED (an#397) #### word_timings *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[WordTimingIR](_autosummary/an.ir.schema.html.md#an.ir.schema.WordTimingIR)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The provider’s word timings, line-relative; `None` when the provider has none (offline, Rhubarb) or the line was stamped before an#96. ### an.ir.schema.EXTENSION_TAG *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'extension'* The union tag of the open member. ### *class* an.ir.schema.ExtensionAction(\*\*data) Bases: `_ActionBase` An action of a kind the core does not define: the IR’s one open member. The schema’s `Action` union selects this for any `kind` other than the core’s (ADR 0001 decision 2). When a genre has REGISTERED that kind ([`an.genres.registry.register_action_kind()`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_action_kind)), validating a document yields the registered model instead — a `PlayAction` for `kind: play` — so code downstream sees typed actions. Before registration the action stays an `ExtensionAction`: its fields are kept as extras and round-trip byte for byte, and [`resolved()`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction.resolved) (called by `flatten`, `an validate` and the compiler) refuses it naming the genre that provides it. Every genre’s action model subclasses this, which is what lets a typed instance sit in the union and serialize with its own fields. ```pycon >>> ExtensionAction(kind="wave", target="flag").model_dump() {'name': None, 'kind': 'wave', 'target': 'flag'} ``` #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### resolved(, strict=True) This action as its registered model. A typed instance is returned as is. A bare `ExtensionAction` is validated by the model its kind registered — or, unregistered, raises [`UnregisteredKindError`](_autosummary/an.genres.registry.html.md#an.genres.registry.UnregisteredKindError) (`strict`) or comes back unchanged (`strict=False`). * **Return type:** [`ExtensionAction`](_autosummary/an.ir.schema.html.md#an.ir.schema.ExtensionAction) ### *class* an.ir.schema.LoopAction(\*\*data) Bases: `_ActionBase` Composition: repeat `child` `count` times. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.Meta(\*\*data) Bases: `_IRModel` Scene metadata. #### captions *: [Captions](_autosummary/an.ir.schema.html.md#an.ir.schema.Captions) | [None](https://docs.python.org/3/builtins/constants.html#None)* Captions from the dialogue’s word timings ([`Captions`](_autosummary/an.ir.schema.html.md#an.ir.schema.Captions), an#175); `None` — the default — is none, omitted from JSON like `style_pack`. #### closing_transition *: [Transition](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) | [None](https://docs.python.org/3/builtins/constants.html#None)* a `fade` to its `color` over its `duration`, on the last shot’s last frames (the film’s length is unchanged, and its final frame is the colour; the sound fades with it). `None` (or a `cut`) ends on the last frame as drawn. A dissolve has nothing to dissolve into, so it is refused. * **Type:** How the film ENDS (an#389) #### default_easing *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)] | [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[float](https://docs.python.org/3/builtins/functions.html#float)] | [None](https://docs.python.org/3/builtins/constants.html#None)* The easing every authored `tween` that names none is drawn with (an#166) — `"linear"` for a snappy South Park cadence, an overshooting cubic-Bezier for a bouncy one. Precedence is \*\*tween > this > the built-in `"ease_in_out"``** (:meth:`TweenAction.resolved_easing`). ``None` — the default and what every existing document has — changes nothing, and is omitted from JSON like `style_pack`, so no committed scene and no compiled document moves. It reaches authored tweens ONLY: a motion preset writes its own easings, the camera’s named moves supply theirs, and blinks, `play` clips and swap channels have none to inherit. There is no per-shot override yet — style is a scene’s. #### default_renderer *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* a registered renderer’s name. * **Type:** Like [`Shot.renderer`](_autosummary/an.ir.schema.html.md#an.ir.schema.Shot.renderer) #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### sounds *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[SoundCue](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)]* Sound cues in FILM time — a music bed, an ambience under every shot ([`SoundCue`](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)). Empty, the default, is no sound layer at all. #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Stepped timing for AUTHORED TWEENS, in pose updates per second; `None` (the default) leaves every tween smooth. At 30 fps, `15` is “on twos” and `10` “on threes” — the character-animation practice Spider-Verse made famous (characters on twos, simulation on ones). The camera is exempt by construction, as are swap channels (already stepped by format), compiled blinks and `play` clips: only `tween` curves are resampled — sample-and-hold of the eased curve on a SHOT-wide grid (every tween in a shot shares it; it restarts at a cut), not a retiming into holds and fast transitions. A tween’s own START and END are always pose changes too, so a tween that begins or ends off-grid changes pose on that frame as well as on the grid (a `set` at an off-grid `at` likewise lands where it was authored). A shot’s own `step_hz` overrides this. Must be positive (schema) and `<= fps` (validate + compile), an#89. #### style_pack *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* The `StylePack` in the project’s `styles` store this scene is drawn under, by key. `None` — the default and what every existing document has — leaves every colour exactly where it is, which is why adding this moved no corpus hash (an#112). A pack changes what the COMPILER decides: the character palette, the leg and pupil colours, the environment presets’ sky and ground — and SVG art whose descriptor tags its colours by role (`colour_roles`, written by `an character new`). Untagged art is never inferred (inferring a role from a pixel is what produced an#99’s wrong-tone lid); a rig a pack cannot reach is WARNED about by name at compile. #### voice_loudness *: [VoiceLoudness](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness) | [None](https://docs.python.org/3/builtins/constants.html#None)* One loudness for every voice ([`VoiceLoudness`](_autosummary/an.ir.schema.html.md#an.ir.schema.VoiceLoudness), an#315); `None` — the default — levels nothing, and is omitted from JSON. ### *class* an.ir.schema.Narration(\*\*data) Bases: `_IRModel` Off-screen narration. Same shape as Dialogue minus the speaker pin. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.ParallelAction(\*\*data) Bases: `_ActionBase` Composition: run all children simultaneously starting at the same time. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.Resolution(\*\*data) Bases: `_IRModel` Pixel dimensions of the rendered output. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### an.ir.schema.SPECIMEN_DURATION *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.5* How long a specimen shot runs (`an library sheet` draws its first frame). ### an.ir.schema.SPECIMEN_SHOT_ID *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'specimen'* The id of a specimen shot. ### an.ir.schema.STAGE_NODE_SPACE *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* *= 'stage.node'* The property space a 2D stage engine’s node lives in ([`an.timing.spaces`](_autosummary/an.timing.spaces.html.md#module-an.timing.spaces)). ### *class* an.ir.schema.SceneIR(\*\*data) Bases: `_IRModel` Top-level Scene IR document. The SSOT. A document is portable, diffable, and renderer-agnostic. Persisted as JSON at `ir/scene.json` inside an an project. ```pycon >>> from an.base import SCHEMA_VERSION >>> doc = SceneIR(meta=Meta(title="Hello")) >>> doc.version == SCHEMA_VERSION True >>> round_tripped = SceneIR.model_validate_json(doc.model_dump_json()) >>> round_tripped.meta.title 'Hello' ``` #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.SequenceAction(\*\*data) Bases: `_ActionBase` Composition: run children one after the other. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.SetAction(\*\*data) Bases: `_ActionBase` Set a property to a value at a specific time. Discrete, no tween. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.Shot(\*\*data) Bases: `_IRModel` A single rendered unit. A scene is a sequence of shots. A shot’s `renderer` selects the backend that draws it. Every renderer must accept the same Shot fields; renderer-specific options go under `options`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### policy *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None)* per aspect, the methods it prefers in order, over the style pack’s (`StylePack.policy`) and under an author’s request — `{"locomotion": ["loco.glide"]}`. `None`: the style’s. * **Type:** This shot’s **policy** (an#348) #### renderer *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* Which RENDERER draws this shot — not art direction. The field was called `style` until an#106, colliding with the styles store (which holds art direction) and with `AssetRef(kind="style")`; one word for two meanings is how a scene came to declare a “style” that selected a renderer while the thing that actually styles it went unread. A `str` in the schema (ADR 0001 decision 2): any name a renderer registered (`an.adapters.register_renderer`), checked by `an validate`. `cutout` stays the persisted default (decision 9). #### sounds *: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[SoundCue](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)]* Sound cues in SHOT-local time ([`SoundCue`](_autosummary/an.ir.schema.html.md#an.ir.schema.SoundCue)). #### step_hz *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Per-shot override of [`Meta.step_hz`](_autosummary/an.ir.schema.html.md#an.ir.schema.Meta.step_hz) (`None` = inherit). #### transition *: [Transition](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition) | [None](https://docs.python.org/3/builtins/constants.html#None)* How this shot is entered ([`Transition`](_autosummary/an.ir.schema.html.md#an.ir.schema.Transition)); `None` is a hard cut. ### *class* an.ir.schema.SoundCue(\*\*data) Bases: `_IRModel` One sound placed on the timeline: an SFX hit, an ambience, a music bed. `sound` is a key in the project’s `sounds` store (`an.sounds`), where the bytes and their licence live — the IR never inlines audio. `at` is seconds from the start of whatever holds the cue: a shot’s `sounds` are SHOT-local (they move with the shot, across transitions and re-orderings), `meta.sounds` are FILM time (a music bed under the whole thing). ```pycon >>> SoundCue(sound="hit", at=1.2).gain_db 0.0 >>> SoundCue(sound="bed", loop=True, duck_db=-12).duck_db -12.0 ``` #### at *: [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[float](https://docs.python.org/3/builtins/functions.html#float), FieldInfo(annotation=NoneType, required=True, metadata=[Ge(ge=0)])] | [CueAnchor](_autosummary/an.ir.schema.html.md#an.ir.schema.CueAnchor)* Seconds, or a [`CueAnchor`](_autosummary/an.ir.schema.html.md#an.ir.schema.CueAnchor) resolved from the picture when the film is laid out (an#317). #### duck_db *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* Attenuation, in dB, while any dialogue line plays; `None` never ducks. A music bed usually wants `DEFAULT_DUCK_DB`; an SFX hit wants none. #### duration *: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None)* the asset’s own length, or — when `loop` — to the end of its shot (shot cue) or of the film (meta cue). * **Type:** How long it plays. `None` #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### until *: [CueUntil](_autosummary/an.ir.schema.html.md#an.ir.schema.CueUntil) | [None](https://docs.python.org/3/builtins/constants.html#None)* Ends the cue at another cue’s start ([`CueUntil`](_autosummary/an.ir.schema.html.md#an.ir.schema.CueUntil)), instead of a fixed `duration`. ### *class* an.ir.schema.StagePlacement(\*\*data) Bases: `_IRModel` Where an entity stands on the stage, and how big it is. ```pycon >>> StagePlacement(at=(120.0, -40.0), scale=0.5).at (120.0, -40.0) >>> StagePlacement().at is None True ``` `at` is in SCENE pixels relative to the stage centre — the same space the compiler already places characters in — so an author reads it off the same ruler as a camera pivot. `scale` multiplies the rig’s own uniform scale. **\`after\` landed in an#344** (a studio set’s sky disc between a sky plane and a holed wall plate): it names the anchor the entity is drawn right after. `depth` is still not a field: an entity takes the depth of the plane it is placed after. The paragraphs below are the record of why both were deferred, kept because `depth`’s reason still holds. \*\*Deliberately only two fields, and the reason has been re-stated because the first one expired.\*\* #108 sketched `depth` and `after` as well, deferred on the grounds that they belong to a stage vocabulary that had not arrived. It arrived the same day: #109 landed the translating camera and #110 landed plane environments, and nothing revisited this paragraph — a deferral citing a *condition* outlives the condition silently, which is why the reason below cites a state instead (an#126). The current reason is simply that \*\*nothing reads them and nothing has asked to.\*\* Shipping either now would put a knob in the schema that a scene can set, that renders identically, and that says nothing — which is worse than an absent one, and is the same defect `an.styles.UNREACHABLE_ROLES` refuses by construction on the other side of the compiler. What each would cost, so the next reader does not re-derive it: - `depth` would place a prop on a parallax plane, which means parenting the prop into that plane’s subtree — and `_track_root_of` makes entity identity the first path segment, so every animation target on that prop changes shape. - `after` would order a prop against planes, which is `characters_after`’s problem a second time; that one needed the environment and character builders interleaved before any ordering could be expressed at all. Neither is hard. Both are unmotivated, and an unmotivated knob in a versioned schema is a migration you owe later for a feature nobody used. #### after *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* an environment plane (`"set/skyline"`) or another placed entity (`"grid"`). `None` = the default band, where the environment’s `characters_after` cuts. A plane’s parallax carries an entity placed after it; an entity placed after an entity rides the default depth. * **Type:** What this entity is drawn immediately after (an#344) #### at *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[float](https://docs.python.org/3/builtins/functions.html#float), FieldInfo(annotation=NoneType, required=True, metadata=[AllowInfNan(allow_inf_nan=False)])], [Annotated](https://docs.python.org/3/library/typing.html#typing.Annotated)[[float](https://docs.python.org/3/builtins/functions.html#float), FieldInfo(annotation=NoneType, required=True, metadata=[AllowInfNan(allow_inf_nan=False)])]] | [None](https://docs.python.org/3/builtins/constants.html#None)* `(x, y)` in scene pixels from the stage centre. `None` = default layout. `allow_inf_nan=False` on both fields, and it is not pedantry: pydantic serializes `inf` and `nan` to JSON **null**, and re-validating that JSON raises — so a scene file written with either is corrupt one way, and the author finds out on the next load rather than at the edit that did it (an#108 review, M-1). `gt=0` already refuses `scale=0` and `scale=-1`; it does not refuse `inf`. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### scale *: [float](https://docs.python.org/3/builtins/functions.html#float)* Uniform scale multiplier on the built rig. `1.0` = the rig’s own size. ### *class* an.ir.schema.Transition(\*\*data) Bases: `_IRModel` How a shot is ENTERED — from the previous shot, or (for the first shot) from nothing. ```pycon >>> Transition(kind="dissolve", duration=0.5).duration 0.5 >>> Transition(kind="fade").color '#000000' ``` - `cut` — the default, and what a shot with no `transition` means. - `fade` — through `color`: the previous shot’s last `duration / 2` fades to the colour and this shot’s first `duration / 2` fades up from it. On the FIRST shot the whole `duration` is a fade up from the colour. **Holds the film’s length**: nothing overlaps. - `dissolve` — the previous shot’s last `duration` seconds and this shot’s first `duration` seconds are seen through each other. \*\*The film gets `duration` shorter\*\* than the sum of its shots: both shots play in full, overlapped (the editor’s convention — the overlapped seconds are each shot’s “handle”). Dialogue stays in sync with its own shot’s picture; audio from both shots is heard in the overlap. Not allowed on the first shot. - `wipe` — overlaps like a dissolve, but a hard edge sweeps across the frame in `direction` (the way the edge travels: `left` brings this shot in from the right), this shot on the side it has passed (an#390). The edge stands where a dissolve’s mix would: `(j + 1) / (k + 1)` of the way across on overlap frame `j` of `k`. Not on the first shot. #### direction *: [Literal](https://docs.python.org/3/library/typing.html#typing.Literal)['left', 'right', 'up', 'down']* A `wipe`’s direction; omitted from a dump for every other kind. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.TweenAction(\*\*data) Bases: `_ActionBase` Animate a property from a start value to an end value over a duration. #### easing *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float), [float](https://docs.python.org/3/builtins/functions.html#float)] | [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[float](https://docs.python.org/3/builtins/functions.html#float)] | [None](https://docs.python.org/3/builtins/constants.html#None)* a tween that does not name an easing takes the scene’s [`Meta.default_easing`](_autosummary/an.ir.schema.html.md#an.ir.schema.Meta.default_easing), and only when that is unset too the built-in `"ease_in_out"` this default spells. “Unset” is `"easing" not in model_fields_set` — the default stays the literal so every reader of `.easing` still sees the curve a scene without a default draws — and the serializer below omits an unset easing, so the distinction survives `scene.json`. `None` is an explicit LINEAR ramp (the evaluators’ reading of a null easing), not “unset”. * **Type:** The curve. \*\*Unset is not the same as ``` `` ``` ”ease_in_out” ``` `` ``` \*\* (an#166) #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### resolved_easing(default=None) The easing this tween draws with under a scene default of `default` — the ONE statement of the precedence \*\*tween > scene (`Meta.default_easing`) > built-in ``` `` ``` ”ease_in_out” ``` `` ``` \*\* (an#166). ```pycon >>> TweenAction(target="a", property="x", to_value=1).resolved_easing("linear") 'linear' >>> TweenAction(target="a", property="x", to_value=1, easing="ease_in_out").resolved_easing("linear") 'ease_in_out' >>> TweenAction(target="a", property="x", to_value=1).resolved_easing(None) 'ease_in_out' ``` * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### *class* an.ir.schema.VisemeKeyframe(\*\*data) Bases: `_IRModel` A single mouth-shape keyframe in a viseme track. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.VisemeTrack(\*\*data) Bases: `_IRModel` Aligned viseme track produced by the lip-sync stage. Optional in P1. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.ir.schema.VoiceLoudness(\*\*data) Bases: `_IRModel` One loudness for every voice of the film (an#315). TTS voices arrive at very different levels (a 19 dB spread measured on one episode). Set, the render levels each voice: its integrated loudness over ALL its lines (EBU R128), one gain to `target_lufs` (plus the voice document’s `loudness_offset_db`), peaks held at `peak_db` dBFS by a lookahead limiter — derived audio, content-keyed, never re-synthesised ([`an.audio.loudness`](_autosummary/an.audio.loudness.html.md#module-an.audio.loudness)). Unset, the default, levels nothing. ```pycon >>> VoiceLoudness().target_lufs, VoiceLoudness().peak_db (-16.0, -1.5) >>> VoiceLoudness.model_validate(-20).target_lufs # a bare number is the target -20.0 ``` #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. #### peak_db *: [float](https://docs.python.org/3/builtins/functions.html#float)* The highest a sample may reach after the gain, dBFS. #### target_lufs *: [float](https://docs.python.org/3/builtins/functions.html#float)* speech for the web; -23: EBU R128 broadcast). * **Type:** The level every voice is brought to, LUFS (-16 ### *class* an.ir.schema.WordTimingIR(\*\*data) Bases: `_IRModel` One word of a line and when it was spoken, in seconds from the line’s start (like [`VisemeKeyframe`](_autosummary/an.ir.schema.html.md#an.ir.schema.VisemeKeyframe), never absolute). Stamped by the audio pipeline from the provider’s word timings when it has them (an#96); JSON only — `scene.md` never carries it, the way it never carries visemes. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {'extra': 'allow', 'populate_by_name': True}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### an.ir.schema.resolve_step_hz(shot, scene_step_hz) The stepped-timing policy `shot` renders under: its own `step_hz` when it declares one, else the scene’s, else `None` (smooth). The ONE statement of the shot-over-scene rule — the cutout renderer, the preview and the project renderer all call it (an#89 review: three copies). * **Return type:** [`float`](https://docs.python.org/3/builtins/functions.html#float) | [`None`](https://docs.python.org/3/builtins/constants.html#None) ```pycon >>> resolve_step_hz(Shot(id="s", step_hz=10.0), 15.0) 10.0 >>> resolve_step_hz(Shot(id="s"), 15.0) 15.0 >>> resolve_step_hz(Shot(id="s"), None) is None True ``` ### an.ir.schema.stage_specimen(ref) A short shot showing the one stage entity `ref` casts, on its own (an#347). * **Return type:** [`Shot`](_autosummary/an.ir.schema.html.md#an.ir.schema.Shot) ```pycon >>> stage_specimen(AssetRef(kind="prop", id="lamp", store="props", ref="lamp")).entities[0].id 'lamp' ``` ### an.ir.schema.unregistered_action_kind(kind, , where='') The error for an action `kind` no loaded genre registered. It names the installed genres whose declaration provides the kind, read without loading them ([`an.genres.providers_of()`](_autosummary/an.genres.html.md#an.genres.providers_of)). * **Return type:** [`Exception`](https://docs.python.org/3/builtins/exceptions.html#Exception) # _autosummary/an.ir.validate.html.md # an.ir.validate Schema and semantic validation for SceneIR documents. Two layers, called separately so callers can pick how strict to be: - `validate_schema` — Pydantic validation only. Wrong types, missing required fields, malformed JSON. - `validate_semantic` — cross-field checks. Unknown asset references, zero-duration shots, voice refs missing from a voices store. Layout-overlap checks (boxes off-screen, text behind sprites) live in `an.verify.layout`, not here, because they need a render context. ### Module Attributes | [`RETIRED_KEYS`](_autosummary/an.ir.validate.html.md#an.ir.validate.RETIRED_KEYS) | Keys an#106 retired, and what to write instead. | |-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`RETIRED_CAMERA_KEYS`](_autosummary/an.ir.validate.html.md#an.ir.validate.RETIRED_CAMERA_KEYS) | an#109's removed camera fields. | | [`CUT_CONTINUITY_PROPS`](_autosummary/an.ir.validate.html.md#an.ir.validate.CUT_CONTINUITY_PROPS) | position in scene px, and the size of its scale (its SIGN is facing, which the genre's view continuity check says, an#203). | | [`CUT_CONTINUITY_TOLERANCE`](_autosummary/an.ir.validate.html.md#an.ir.validate.CUT_CONTINUITY_TOLERANCE) | a pixel, or a hundredth of the scale. | | [`DIALOGUE_OVERRUN_TOLERANCE_S`](_autosummary/an.ir.validate.html.md#an.ir.validate.DIALOGUE_OVERRUN_TOLERANCE_S) | a frame at 60 fps. | | [`POST_SYNTHESIS_CHECKS`](_autosummary/an.ir.validate.html.md#an.ir.validate.POST_SYNTHESIS_CHECKS) | The registered checks whose answer depends on what synthesis produced — a line's real length, hence where it starts and ends — and that `an render` therefore runs again AFTER the audio pipeline, on the timing it will mux ([`post_synthesis_findings()`](_autosummary/an.ir.validate.html.md#an.ir.validate.post_synthesis_findings) runs exactly these, by name, through the registry). | ### Functions | [`counter_block_ids`](_autosummary/an.ir.validate.html.md#an.ir.validate.counter_block_ids)(shot, stores) | The ids of `shot`'s counter text blocks (an#342): the only targets a `value` is authored on in the core. | |----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [`post_synthesis_findings`](_autosummary/an.ir.validate.html.md#an.ir.validate.post_synthesis_findings)(scene, \*[, fps, checks]) | `(check, finding)` for each finding the synthesized timing gives. | | [`registered_kind_problems`](_autosummary/an.ir.validate.html.md#an.ir.validate.registered_kind_problems)(scene) | The findings of the three registry checks alone — every action kind, entity kind and renderer the scene names must be registered — without the rest of `validate_semantic` (no stores, no rig builds; cheap). | | [`require_registered_kinds`](_autosummary/an.ir.validate.html.md#an.ir.validate.require_registered_kinds)(scene, \*[, where]) | `scene`, or [`UnregisteredInSceneError`](_autosummary/an.ir.validate.html.md#an.ir.validate.UnregisteredInSceneError) naming every action kind, entity kind and renderer it uses that is not registered. | | [`rig_stores`](_autosummary/an.ir.validate.html.md#an.ir.validate.rig_stores)() | `{entity kind: (mall store, descriptor kind)}` for every kind that has a rig. | | [`shot_dialogue_overruns`](_autosummary/an.ir.validate.html.md#an.ir.validate.shot_dialogue_overruns)(shot, \*[, ...]) | `(k, message)` for each line of `shot` that ends past the shot's end. | | [`validate_schema`](_autosummary/an.ir.validate.html.md#an.ir.validate.validate_schema)(doc) | Validate that `doc` (dict, JSON string, or SceneIR) conforms to the schema. | | [`validate_semantic`](_autosummary/an.ir.validate.html.md#an.ir.validate.validate_semantic)(scene, \*[, ...]) | Cross-field semantic checks. | ### Classes | [`ValidationContext`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationContext)(scene, report, stores[, ...]) | What a registered semantic check ([`an.genres.SemanticCheck`](_autosummary/an.genres.html.md#an.genres.SemanticCheck)) reads. | |----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | [`ValidationFinding`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationFinding)(severity, ir_path, description) | A single validation issue with a path into the IR. | | [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport)([passed, findings]) | Result of running one or more validators. | ### Exceptions | [`UnregisteredInSceneError`](_autosummary/an.ir.validate.html.md#an.ir.validate.UnregisteredInSceneError)(findings, \*[, where]) | A scene names kinds or renderers nothing registered: refused at load. | |----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------| ### an.ir.validate.CUT_CONTINUITY_PROPS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('x', 'y', 'scale_x', 'scale_y')* position in scene px, and the size of its scale (its SIGN is facing, which the genre’s view continuity check says, an#203). * **Type:** What an entity’s placement across a cut is compared on (an#394) ### an.ir.validate.CUT_CONTINUITY_TOLERANCE *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [float](https://docs.python.org/3/builtins/functions.html#float)]* *= {'scale_x': 0.01, 'scale_y': 0.01, 'x': 1.0, 'y': 1.0}* a pixel, or a hundredth of the scale. * **Type:** How far a value may move across a cut and still be “the same” ### an.ir.validate.DIALOGUE_OVERRUN_TOLERANCE_S *: [float](https://docs.python.org/3/builtins/functions.html#float)* *= 0.016666666666666666* a frame at 60 fps. * **Type:** Slack before a line counts as running past its shot ### an.ir.validate.POST_SYNTHESIS_CHECKS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ('dialogue_fits', 'dialogue_in_dissolve', 'cutout.hidden_mouth_while_speaking')* The registered checks whose answer depends on what synthesis produced — a line’s real length, hence where it starts and ends — and that `an render` therefore runs again AFTER the audio pipeline, on the timing it will mux ([`post_synthesis_findings()`](_autosummary/an.ir.validate.html.md#an.ir.validate.post_synthesis_findings) runs exactly these, by name, through the registry). A check added later that reads `Dialogue.duration` or `start` belongs here; `tests/test_render_findings.py` lists the ones that do. ### an.ir.validate.RETIRED_CAMERA_KEYS *: [frozenset](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]* *= frozenset({'focal_length', 'position', 'target'})* an#109’s removed camera fields. A WARNING, not an error, and the difference is the harm: a surviving `style` silently picks the wrong RENDERER, while these three selected nothing — they described a 3D camera this package never had. What is left is dead weight in a file, so it is worth saying and not worth failing over. Reported at all because the migration cannot reach them: a document already at the current version is never migrated again, so a camera block that came through a sync between the version bump and this check keeps them forever as `extra="allow"` extras, and nothing else looks. ### an.ir.validate.RETIRED_KEYS *: [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [str](https://docs.python.org/3/builtins/stdtypes.html#str)]]* *= {'meta': {'default_style': 'default_renderer'}, 'shot': {'style': 'renderer'}}* Keys an#106 retired, and what to write instead. `SceneIR`’s models are `extra="allow"` (deliberately — forward compatibility), so a document that still carries one of these validates cleanly and renders with the DEFAULT renderer. The migration rewrites stored 0.1.x documents, but nothing rewrites a document that is already 0.2.0: an agent patch, a hand edit, or a caller passing `style=` to `Shot(...)` all produce a permanently dead key that no later migration will touch. So it is caught here, at ERROR, by name. ### *exception* an.ir.validate.UnregisteredInSceneError(findings, , where='') Bases: [`UnregisteredKindError`](_autosummary/an.genres.registry.html.md#an.genres.registry.UnregisteredKindError) A scene names kinds or renderers nothing registered: refused at load. Raised by [`require_registered_kinds()`](_autosummary/an.ir.validate.html.md#an.ir.validate.require_registered_kinds) — what `an.load(project)` (and so `an render`) runs, so a typo’d `kind:` or `renderer:` can no longer render silently wrong now that the schema holds them as `str` (review-244 S2). `findings` keeps each one with its IR path. ### *class* an.ir.validate.ValidationContext(scene, report, stores, voices=None, characters=None, sounds=None, library_lock=None, shot=None, index=None, memo=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a registered semantic check ([`an.genres.SemanticCheck`](_autosummary/an.genres.html.md#an.genres.SemanticCheck)) reads. `stores` holds only the stores actually supplied, keyed by MALL name (an absent one means its checks did not RUN — never that what it holds is missing). `shot` and `index` are set while the `shot` stage runs. `memo` is shared by every check of one `validate_semantic` call, so two checks that need the same derived fact compute it once ([`cached()`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationContext.cached)). #### cached(key, compute) `compute()`, once per `key` per validation. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) #### library_lock *: [Mapping](https://docs.python.org/3/library/typing.html#typing.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* The project’s asset-library lockfile (`mall["library_lock"]`, an#240); `None` means the pin checks did not run. #### *property* path *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* The IR path of the current shot (`timeline/`). ### *class* an.ir.validate.ValidationFinding(severity, ir_path, description, location=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A single validation issue with a path into the IR. #### location *: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [None](https://docs.python.org/3/builtins/constants.html#None)* `":"` when the thing to fix is an opaque source a shot runs (a Manim scene file, an#279) rather than the IR; `None` otherwise. ### *class* an.ir.validate.ValidationReport(passed=True, findings=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Result of running one or more validators. `passed` is True iff there are no error-severity findings. ### an.ir.validate.counter_block_ids(shot, stores) The ids of `shot`’s counter text blocks (an#342): the only targets a `value` is authored on in the core. Empty without the props store. * **Return type:** [`frozenset`](https://docs.python.org/3/builtins/stdtypes.html#frozenset)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ### an.ir.validate.post_synthesis_findings(scene, , fps=None, checks=('dialogue_fits', 'dialogue_in_dissolve', 'cutout.hidden_mouth_while_speaking'), \*\*stores) `(check, finding)` for each finding the synthesized timing gives. The SAME registered checks `an validate` runs, selected by name ([`POST_SYNTHESIS_CHECKS`](_autosummary/an.ir.validate.html.md#an.ir.validate.POST_SYNTHESIS_CHECKS)): dialogue past its shot’s end, a speaker overlapping themself, a line heard during a dissolve, a line spoken while the speaker’s view hides its mouth. `an render` calls this once the audio pipeline has stamped every line’s real `duration`, so what `an validate` could only estimate is reported exactly, at the moment it becomes known (an#254). `fps` is the render’s (it decides the dissolve overlaps); default the scene’s. `stores` are [`validate_semantic()`](_autosummary/an.ir.validate.html.md#an.ir.validate.validate_semantic)’s `available_*` keywords. A check no loaded genre registered is skipped. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`ValidationFinding`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationFinding)]] ### an.ir.validate.registered_kind_problems(scene) The findings of the three registry checks alone — every action kind, entity kind and renderer the scene names must be registered — without the rest of `validate_semantic` (no stores, no rig builds; cheap). * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) ### an.ir.validate.require_registered_kinds(scene, , where='') `scene`, or [`UnregisteredInSceneError`](_autosummary/an.ir.validate.html.md#an.ir.validate.UnregisteredInSceneError) naming every action kind, entity kind and renderer it uses that is not registered. * **Return type:** [`SceneIR`](_autosummary/an.ir.schema.html.md#an.ir.schema.SceneIR) ### an.ir.validate.rig_stores() `{entity kind: (mall store, descriptor kind)}` for every kind that has a rig. The core’s own (`prop`) plus the kinds genres register with a `descriptor_kind` (the cut-out genre’s `character`): derived from the registry, not a table the core edits (an#246). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> rig_stores()["prop"] ('props', 'PropDescriptor') ``` ### an.ir.validate.shot_dialogue_overruns(shot, , effects_of=None, synthesized_only=False, tolerance_s=0.016666666666666666) `(k, message)` for each line of `shot` that ends past the shot’s end. The ONE overrun check: `an validate` runs it, the audio pipeline runs it after synthesis ([`an.audio.pipeline.dialogue_overruns()`](_autosummary/an.audio.pipeline.html.md#an.audio.pipeline.dialogue_overruns)), and `an render` reports it from the rendered timing ([`post_synthesis_findings()`](_autosummary/an.ir.validate.html.md#an.ir.validate.post_synthesis_findings)). The audio is cut at the shot end (each shot’s mix is trimmed to its duration), and the lines play back to back, so a shot shortened below its dialogue loses the tail of it — silently, until now (an e2e run shrank an 8.2 s shot holding 7.1 s of speech to 3.0 s and `an validate` said nothing). What is known depends on when this runs. After the audio pipeline, a line carries its real `duration` and the check is exact. Before it, the duration is the offline voice’s estimate ([`an.audio.offline_tts.estimate_speech_duration()`](_autosummary/an.audio.offline_tts.html.md#an.audio.offline_tts.estimate_speech_duration) over the voice’s `tempo` — exactly what an offline render will give, and an under-estimate for a real voice). Either way the lines are laid out by the pipeline’s own rule, [`an.ir.schema.Dialogue.planned_start()`](_autosummary/an.ir.schema.html.md#an.ir.schema.Dialogue.planned_start) — back to back from the shot start, shifted by each line’s `pause` or pinned by its `at` (an#187) — so a pause edited after synthesis is judged where it will play, not where the stale stamp says. `effects_of` ( ``` `` ``` line -> \`\` its voice’s normalised effects) supplies the tempo, and — for a synthesized line whose voice does not trim — the fix of trimming the silence a real voice pads a line with. ```pycon >>> from an.ir.schema import Dialogue, Shot >>> shot = Shot(id="s", duration=1.0, dialogue=[ ... Dialogue(speaker="a", text="hi", start=0.2, duration=1.3, audio_ref="k")]) >>> [(k, m[:44]) for k, m in shot_dialogue_overruns(shot)] [(0, 'line 0 (a) ends at 1.30s as synthesized, pas')] ``` * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`int`](https://docs.python.org/3/builtins/functions.html#int), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ### an.ir.validate.validate_schema(doc) Validate that `doc` (dict, JSON string, or SceneIR) conforms to the schema. * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) ```pycon >>> validate_schema({"meta": {"title": "x"}, "timeline": []}).passed True >>> r = validate_schema({"meta": {"title": "x"}, "timeline": [{"id": "s", "duration": "not-a-number"}]}) >>> r.passed False ``` ### an.ir.validate.validate_semantic(scene, , available_voices=None, available_characters=None, available_props=None, available_environments=None, available_sounds=None, available_library_lock=None, available_styles=None, only=None, fps=None) Cross-field semantic checks. Pass live stores in for cross-store checks. Both `available_voices` and `available_characters` accept any mapping; `available_props` is the same thing for `kind="prop"` entities (an#108), and `available_environments` lets the flat-pan warning read a stage’s planes (an#111) — without it a prop’s swaps are reported as having no descriptor, which is validate refusing what compile accepts. Voices are consulted via `__contains__` only; characters additionally via `__getitem__` (the swap-reference and `play` checks read descriptor dicts, an#87 / an#7). Pass `None` to skip those checks — and know that skipping them is what it sounds like: a `play` or a swap the compiler will refuse passes silently without the store (the CLI, `an validate`, always passes it). `available_styles` is the project’s `styles` store: a check reads the StylePack the scene names (`meta.style_pack`) from `ctx.stores["styles"]` (a style’s `policy`, an#348). `available_library_lock` is the project’s asset-library lockfile (`mall["library_lock"]`): with it, every scene `library:` pin is checked against the lockfile (`warning` on disagreement) and every pinned check-out against its library version (`info` when it has been edited). The checks are a REGISTRY ([`an.genres.registry.register_check()`](_autosummary/an.genres.registry.html.md#an.genres.registry.register_check)): the core’s own register below, a genre’s when it is loaded (the cut-out genre’s `play`, `expression`, turn and view checks), and they run in stages — `scene`, then `shot` once per shot, then `finish` — each by its `order`. An action or entity kind no loaded genre registered is one error naming the genre that provides it; checks that would trip over it skip that shot rather than crash. `only` runs just the registered checks of those names (what `an render` does after synthesis, [`post_synthesis_findings()`](_autosummary/an.ir.validate.html.md#an.ir.validate.post_synthesis_findings)); `fps` is the one the film is assembled at when it is not the scene’s (`an render --fps`), which decides how long a dissolve’s overlap is. * **Return type:** [`ValidationReport`](_autosummary/an.ir.validate.html.md#an.ir.validate.ValidationReport) # _autosummary/an.iterate.html.md # an.iterate Iterative edit loop — free-text instruction → IR patch via Claude → re-render. Phase 10. The spec’s signature user story: > > “I say ‘make Maya’s laugh longer and warmer.’ Claude Code edits the IR, > > re-renders just the affected shot, and shows me the diff. I approve.” This module turns a free-text instruction into a structured set of patches on the SceneIR JSON tree, validates them, applies them, persists, and (optionally) re-renders. The vision LM is Claude Opus 4.7 with adaptive thinking; `messages.parse()` + a Pydantic schema guarantees the patches are valid JSON of the expected shape. Path syntax for patches: slash-delimited JSON-pointer-style. List indices are integers. Examples: > “meta/title” > “timeline/0/duration” > “timeline/1/dialogue/0/text” > “timeline/1/dialogue/0/emotion” Patch operations: > {“op”: “set”, “path”: “…”, “value”: …} # replace (or create) value > {“op”: “append”, “path”: “…”, “value”: …} # append to a list > {“op”: “delete”, “path”: “…”} # remove an entry The orchestrator records each iteration in `mall["decisions"]` so the agent can review what changed across runs. ### Functions | [`iterate`](_autosummary/an.iterate.html.md#an.iterate.iterate)(project_dir, instruction, \*[, ...]) | Apply a free-text instruction to the scene at `project_dir`. | |-------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------| | [`system_prompt`](_autosummary/an.iterate.html.md#an.iterate.system_prompt)() | The `an iterate` system prompt: the protocol around the generated vocabulary. | ### Classes | [`IterateResponse`](_autosummary/an.iterate.html.md#an.iterate.IterateResponse)(\*\*data) | Structured reply from Claude for a single iterate() call. | |--------------------------------------------------------------------------------------------------|-------------------------------------------------------------| | [`IterateResult`](_autosummary/an.iterate.html.md#an.iterate.IterateResult)([success, summary, patches, ...]) | Outcome of an iterate() call. | | [`Patch`](_autosummary/an.iterate.html.md#an.iterate.Patch)(\*\*data) | A single mutation against the SceneIR JSON tree. | ### Exceptions | [`IterateError`](_autosummary/an.iterate.html.md#an.iterate.IterateError) | Raised when an iterate call cannot apply its proposed patches. | |-----------------------------------------------------------------|------------------------------------------------------------------| ### *exception* an.iterate.IterateError Bases: [`RuntimeError`](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) Raised when an iterate call cannot apply its proposed patches. ### *class* an.iterate.IterateResponse(\*\*data) Bases: `BaseModel` Structured reply from Claude for a single iterate() call. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### *class* an.iterate.IterateResult(success=True, summary='', patches=, affected_shots=, new_scene=None, validation=None, error=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Outcome of an iterate() call. ### *class* an.iterate.Patch(\*\*data) Bases: `BaseModel` A single mutation against the SceneIR JSON tree. #### model_config *: [ClassVar](https://docs.python.org/3/library/typing.html#typing.ClassVar)[ConfigDict]* *= {}* Configuration for the model, should be a dictionary conforming to [`ConfigDict`][pydantic.config.ConfigDict]. ### an.iterate.iterate(project_dir, instruction, , apply=True, model='claude-opus-4-7', max_tokens=4096) Apply a free-text instruction to the scene at `project_dir`. Steps: > 1. Load the project. > 2. Send the current scene + the instruction to Claude. > 3. Parse the structured patch response. > 4. Apply patches to a deep-copied IR; validate. > 5. If valid and `apply=True`, persist to mall[“scenes”][“main”] and > append to mall[“decisions”]. The caller is responsible for re-rendering: `an render` then re-renders exactly the shots whose content changed, found by digest (the shot cache, ADR 0004) — `IterateResult.affected_shots` is the model’s account of which those are, for the reader, not the mechanism. * **Return type:** [`IterateResult`](_autosummary/an.iterate.html.md#an.iterate.IterateResult) ### an.iterate.system_prompt() The `an iterate` system prompt: the protocol around the generated vocabulary. Loads the installed genres first (their presets and methods are part of the vocabulary). Stable for a given registry, so it caches as well as the hand-written one did. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> text = system_prompt() >>> "walk" in text and "Rules:" in text True ``` # _autosummary/an.library.affordances.html.md # an.library.affordances Affordances for the library: the capability registry, re-exported from [`an.capabilities`](_autosummary/an.capabilities.html.md#module-an.capabilities). P5 seeded ADR 0002’s `affordances(asset)` here; P7 moved the tables and the matcher to the core registry, [`an.capabilities`](_autosummary/an.capabilities.html.md#module-an.capabilities), and this module now re-exports the SAME objects (`ANALYSERS is an.capabilities.ANALYSERS`), so the library’s facets and `find(…, near=True)` and the compiler’s method choice are one derivation and one matcher, never two. The character analyser is the cut-out genre’s: it registers through `an.genres.cutout.CUTOUT` (its `capabilities` and `analysers` fields) when the genres load, which the library’s entry points do ([`an.library.api.publish()`](_autosummary/an.library.api.html.md#an.library.api.publish), [`an.library.api.find()`](_autosummary/an.library.api.html.md#an.library.api.find)). ```pycon >>> import an.capabilities >>> ANALYSERS is an.capabilities.ANALYSERS and CAPABILITIES is an.capabilities.CAPABILITIES True >>> afford = {"swap.view": {"keys": ["front", "side"]}, "limbs.legs": {}} >>> matches(afford, "swap.view:side"), matches(afford, "swap.view:back"), matches(afford, "limbs.legs") (True, False, True) ``` ### Functions | [`analyse`](_autosummary/an.library.affordances.html.md#an.library.affordances.analyse)(kind, doc[, art]) | `(profile, analysers)` of one subject: its capabilities and the analyser versions used. | |----------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| | [`capability_of`](_autosummary/an.library.affordances.html.md#an.library.affordances.capability_of)(query) | `(capability, key)` of a query term (the library's `find` form). | | [`current_affordances`](_autosummary/an.library.affordances.html.md#an.library.affordances.current_affordances)(kind, doc, art, \*, ...) | The stored snapshot when its analyser version is current, else a fresh derivation. | | [`matches`](_autosummary/an.library.affordances.html.md#an.library.affordances.matches)(profile, term) | Whether `profile` (or the subject of `term` in a `Subjects`) meets `term`. | | [`missing`](_autosummary/an.library.affordances.html.md#an.library.affordances.missing)(profile, requires) | The requirement terms `profile` does not meet, spelled, in the order asked. | | [`register_analyser`](_autosummary/an.library.affordances.html.md#an.library.affordances.register_analyser)(kind, \*[, version, ...]) | Register an analyser. | | [`register_capability`](_autosummary/an.library.affordances.html.md#an.library.affordances.register_capability)(name, \*[, description, ...]) | Register a capability (or a [`Capability`](_autosummary/an.library.affordances.html.md#an.library.affordances.Capability)). | | [`remedy_for`](_autosummary/an.library.affordances.html.md#an.library.affordances.remedy_for)(term) | What would add the capability a requirement term asks for. | ### Classes | [`Analyser`](_autosummary/an.library.affordances.html.md#an.library.affordances.Analyser)(kind, version, derive[, subject, ...]) | The derivation of one kind's profile, versioned. | |----------------------------------------------------------------------------------------------------|----------------------------------------------------------------------| | [`Capability`](_autosummary/an.library.affordances.html.md#an.library.affordances.Capability)(name, description, remedy[, ...]) | A registered capability: its name, what it means, and how to add it. | ### *class* an.library.affordances.Analyser(kind, version, derive, subject='asset', declares=(), overrides=None) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) The derivation of one kind’s profile, versioned. `kind` is an asset kind (`character`) or a subject that has one analyser (`engine`, `environment`). Bump `version` whenever the output can change for the same input: snapshots made under the old one are then recomputed on read. The version is NOT a compile input (consult §5): the derived profile is, so touching an analyser without changing its output re-renders nothing. #### declares *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ()* The document’s declared facts the derivation honours instead of deriving (`rest_view`, `face_overlay`) or reads as a request (`gait`): reported by `describe_asset` (ADR 0002 decision 2). #### overrides *: [Callable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Callable)[[[Any](https://docs.python.org/3/library/typing.html#typing.Any), [Mapping](https://docs.python.org/3/library/collections.abc.html#collections.abc.Mapping)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), [Any](https://docs.python.org/3/library/typing.html#typing.Any)]], [Iterable](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterable)[[str](https://docs.python.org/3/builtins/stdtypes.html#str)]] | [None](https://docs.python.org/3/builtins/constants.html#None)* *= None* `(doc, art) -> declared field names` the derivation USED as overrides that do not show on an afforded capability’s params: a declared fact that REMOVES a capability (a character’s `occluded`, an#381). Those on an afforded capability are already in its `overrides` param. `None`: none beyond those. Reporting only: it changes no profile, so adding it does not bump `version`. ### *class* an.library.affordances.Capability(name, description, remedy, subject='asset', command=None, version='1') Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) A registered capability: its name, what it means, and how to add it. `command` is the CLI that adds it, when one exists (`an character add-views`); `version` bumps when the *meaning* of the name changes (a persisted name is never redefined in place). #### to_json() The capability as the generated docs and the MCP surface list it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### an.library.affordances.analyse(kind, doc, art=None) `(profile, analysers)` of one subject: its capabilities and the analyser versions used. A kind with no registered analyser affords nothing *derived* and records no analyser — an honest empty answer, not a guess. * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]], [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ```pycon >>> analyse("no-such-kind", {}) ({}, {}) ``` ### an.library.affordances.capability_of(query) `(capability, key)` of a query term (the library’s `find` form). * **Return type:** [`tuple`](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) | [`None`](https://docs.python.org/3/builtins/constants.html#None)] ```pycon >>> capability_of("swap.view:side"), capability_of("limbs.legs") (('swap.view', 'side'), ('limbs.legs', None)) ``` ### an.library.affordances.current_affordances(kind, doc, art, , stored, stored_analysers) The stored snapshot when its analyser version is current, else a fresh derivation. Affordances are derived data, so recomputing them is always safe; trusting a snapshot made by an older analyser is what would make a facet lie. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.library.affordances.matches(profile, term) Whether `profile` (or the subject of `term` in a `Subjects`) meets `term`. * **Return type:** [`bool`](https://docs.python.org/3/builtins/functions.html#bool) ### an.library.affordances.missing(profile, requires) The requirement terms `profile` does not meet, spelled, in the order asked. THE matcher (ADR 0002 decision 4): `why_not`, `applicable`, `resolve` and the library’s `find(…, near=True)` all call it. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> missing({}, ["env.ffmpeg"]), missing(Subjects(environment={"env.ffmpeg": {}}), ["env.ffmpeg"]) (['env.ffmpeg'], []) ``` ### an.library.affordances.register_analyser(kind, , version='', subject='asset', owner='an') Register an analyser. Two forms. `register_analyser(Analyser(...), owner=...)` registers the object and returns it (a genre’s `analysers` field goes this way). With a `kind` string it is a decorator: `@register_analyser("character", version="0.1.0")` registers the decorated derivation. * **Return type:** [`Any`](https://docs.python.org/3/library/typing.html#typing.Any) ### an.library.affordances.register_capability(name, , description='', remedy='', subject='asset', command=None, version='1', owner='an') Register a capability (or a [`Capability`](_autosummary/an.library.affordances.html.md#an.library.affordances.Capability)). Returns it. Re-registering the same definition is a no-op; a different definition under a name another owner holds raises, because capability names are persisted and two meanings for one name would make a stored facet lie. * **Return type:** [`Capability`](_autosummary/an.capabilities.html.md#an.capabilities.Capability) ```pycon >>> cap = register_capability("demo.thing", description="a thing", remedy="add one", owner="demo") >>> CAPABILITIES["demo.thing"] is cap True >>> _ = drop_owner("demo") ``` ### an.library.affordances.remedy_for(term) What would add the capability a requirement term asks for. * **Return type:** [`str`](https://docs.python.org/3/builtins/stdtypes.html#str) ```pycon >>> remedy_for("no.such.capability") 'no registered capability no.such.capability; see vocabulary() for the known names' ``` # _autosummary/an.library.api.html.md # an.library.api The library’s verbs: `publish`, `find`, `vocabulary`, `show`, `promote`, `retire`. Plain functions over [`Library`](_autosummary/an.library.federation.html.md#an.library.federation.Library) objects (pillar 8: the functions are the API; the `an library …` CLI and, later, MCP are thin projections of them). Writes take the one owning library; reads take a library or a search path ([`search_path()`](_autosummary/an.library.federation.html.md#an.library.federation.search_path)). Check-out lives in [`an.library.checkout`](_autosummary/an.library.html.md#an.library.checkout). The documents they write (ADR 0005 decision 4, design §4): - a **record** per asset — identity and curation, mutable: `id`, `kind`, `title`, `family`, `head`, `status` (`retired` hides it from `find`: [`retire()`](_autosummary/an.library.api.html.md#an.library.api.retire)), its append-only `status_history`, `facets` (`style`, `origin`), `tags`; - a **label** per relabel of a version’s unchanged content (an#307) — append-only, keyed by the hash of what it says: the source, who and why, and the rights it gave the version; a version’s rights read its labels; - a **version** per publish — immutable: the descriptor `doc` verbatim, its `files` as `dol.content.ContentRef` s, the asset-level `source`, `derived_from`, the derived `affordances` with the `analysers` that made them, the rolled-up `rights`, the `art` facet, and `manifest_sha256` — the **version identity**: the hash of `doc`, the files’ hashes, `source` and `derived_from`. It is not a content key (lineage changes it, and a checked-out copy can be edited after it is pinned); nothing should cache on it as one. Publishing what the head already is makes no new version. **Rights are recomputed, not trusted.** The stored `rights` block is a cache of [`effective_rights()`](_autosummary/an.library.api.html.md#an.library.api.effective_rights), which rolls up — most restrictive wins — the asset-level source, the descriptor’s own source, every part’s, and recursively every version the asset derives from. `promote` and `find(rights=…)` recompute it. ### Module Attributes | [`LIBRARY_ERRORS`](_autosummary/an.library.api.html.md#an.library.api.LIBRARY_ERRORS) | the CLI prints these as a sentence and exits non-zero. | |-------------------------------------------------------------------|----------------------------------------------------------| ### Functions | [`effective_rights`](_autosummary/an.library.api.html.md#an.library.api.effective_rights)(libraries, version, \*[, ...]) | The rights of a version, recomputed from its sources, its lineage and its bytes. | |-----------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------| | [`find`](_autosummary/an.library.api.html.md#an.library.api.find)(libraries, \*[, kind, style, affords, ...]) | Assets matching every facet given (AND across facets, OR within one facet's values). | | [`promote`](_autosummary/an.library.api.html.md#an.library.api.promote)(libraries, ref, \*[, to, as_id, ...]) | Copy one version into another library — by default the core `an` library. | | [`publish`](_autosummary/an.library.api.html.md#an.library.api.publish)(library, asset_id, doc[, files, ...]) | Publish `doc` and its `files` as the next version of `asset_id` in `library`. | | [`publish_dir`](_autosummary/an.library.api.html.md#an.library.api.publish_dir)(library, folder, asset_id, \*\*kwargs) | Publish an asset folder as it sits in a project store (`assets/characters/alice/`). | | [`reindex`](_autosummary/an.library.api.html.md#an.library.api.reindex)(library, \*[, search]) | Rebuild `library`'s floor index from its versions. | | [`retire`](_autosummary/an.library.api.html.md#an.library.api.retire)(library, asset_id, \*, by, reason) | Retire an asset id: recorded, hidden from `find` by default, never deleted. | | [`scan_index`](_autosummary/an.library.api.html.md#an.library.api.scan_index)(library) | Every asset's head version in `library`, read from the stores. | | [`set_status`](_autosummary/an.library.api.html.md#an.library.api.set_status)(library, asset_id, status, \*, by, ...) | Set an asset's curation status, recording who and why; return the record. | | [`show`](_autosummary/an.library.api.html.md#an.library.api.show)(libraries, ref) | The record, the resolved version, its recomputed rights and the list of versions. | | [`unknown_advice`](_autosummary/an.library.api.html.md#an.library.api.unknown_advice)(libraries, version, \*[, ...]) | What would answer each `unknown` contributor of a version — one sentence per kind. | | [`version_labels`](_autosummary/an.library.api.html.md#an.library.api.version_labels)(library, version) | The labels recorded on a stored version since it was published, oldest first. | | [`version_sources`](_autosummary/an.library.api.html.md#an.library.api.version_sources)(libraries, version, \*[, ...]) | Every labelled source a version's rights depend on — its own, its lineage, its bytes. | | [`vocabulary`](_autosummary/an.library.api.html.md#an.library.api.vocabulary)(libraries, \*[, index]) | Every facet with its values and counts, and the registered capabilities. | ### Classes | [`FindResult`](_autosummary/an.library.api.html.md#an.library.api.FindResult)(hits, near, counts) | Hits, near misses (with `near=True`), and per-facet value counts over the hits. | |----------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------| | [`Hit`](_autosummary/an.library.api.html.md#an.library.api.Hit)(library, asset_id, version, score[, ...]) | One asset that answers a query — or nearly does (`missing` non-empty). | | [`IndexEntry`](_autosummary/an.library.api.html.md#an.library.api.IndexEntry)(library, asset_id, version, kind, ...) | One asset's head version, as the index sees it. | | [`PublishResult`](_autosummary/an.library.api.html.md#an.library.api.PublishResult)(ref, manifest_sha256, created, ...) | What a publish did: the version it names, and whether it made one. | ### Exceptions | [`CheckoutError`](_autosummary/an.library.api.html.md#an.library.api.CheckoutError) | A version cannot be materialised into this project as asked. | |------------------------------------------------------------------------|----------------------------------------------------------------------------------| | [`IntegrityError`](_autosummary/an.library.api.html.md#an.library.api.IntegrityError) | Stored bytes, paths or a stored manifest do not match what was recorded. | | [`LibraryError`](_autosummary/an.library.api.html.md#an.library.api.LibraryError) | A library operation refused, with a sentence saying why and what to do. | | [`LibraryIndexWarning`](_autosummary/an.library.api.html.md#an.library.api.LibraryIndexWarning) | A record or version could not be read; the index skipped it. | | [`PlaceholderRigWarning`](_autosummary/an.library.api.html.md#an.library.api.PlaceholderRigWarning) | A character published with no rig: the compiler would draw only its placeholder. | ### *exception* an.library.api.CheckoutError Bases: [`LibraryError`](_autosummary/an.library.api.html.md#an.library.api.LibraryError) A version cannot be materialised into this project as asked. ### *class* an.library.api.FindResult(hits, near, counts) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) Hits, near misses (with `near=True`), and per-facet value counts over the hits. #### to_dict() A JSON-ready view. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *class* an.library.api.Hit(library, asset_id, version, score, title=None, license_class='unknown', missing=, remedies=, federated=False) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One asset that answers a query — or nearly does (`missing` non-empty). #### *property* ref *: [str](https://docs.python.org/3/builtins/stdtypes.html#str)* namespaced when the search spanned several libraries. * **Type:** The reference to pin #### to_dict() A JSON-ready view (CLI `--json`, MCP). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ### *class* an.library.api.IndexEntry(library, asset_id, version, kind, record, rights, affordances, art, document=) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) One asset’s head version, as the index sees it. #### affordance_terms() Every query term this entry satisfies: `cap` and each `cap:key`. * **Return type:** [`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] #### facet_values() Every facet’s values for this entry (the AND/OR matcher’s input). * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`set`](https://docs.python.org/3/builtins/stdtypes.html#set)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)]] ### *exception* an.library.api.IntegrityError Bases: [`LibraryError`](_autosummary/an.library.api.html.md#an.library.api.LibraryError) Stored bytes, paths or a stored manifest do not match what was recorded. ### an.library.api.LIBRARY_ERRORS *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[type](https://docs.python.org/3/builtins/functions.html#type)[[BaseException](https://docs.python.org/3/builtins/exceptions.html#BaseException)], ...]* *= (, , , , , , )* the CLI prints these as a sentence and exits non-zero. * **Type:** Every error a library verb raises for a caller’s mistake (not a bug) ### *exception* an.library.api.LibraryError Bases: [`Exception`](https://docs.python.org/3/builtins/exceptions.html#Exception) A library operation refused, with a sentence saying why and what to do. ### *exception* an.library.api.LibraryIndexWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) A record or version could not be read; the index skipped it. ### *exception* an.library.api.PlaceholderRigWarning Bases: [`UserWarning`](https://docs.python.org/3/builtins/exceptions.html#UserWarning) A character published with no rig: the compiler would draw only its placeholder. ### *class* an.library.api.PublishResult(ref, manifest_sha256, created, rights, affordances, advice=(), conflicts=()) Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object) What a publish did: the version it names, and whether it made one. #### advice *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), ...]* *= ()* what would answer each kind of gap, one sentence each ([`unknown_advice()`](_autosummary/an.library.api.html.md#an.library.api.unknown_advice)). * **Type:** For an `unknown` result #### conflicts *: [tuple](https://docs.python.org/3/builtins/stdtypes.html#tuple)[RightsConflict, ...]* *= ()* statements freer than what binds their bytes, kept beside the stricter one that binds. * **Type:** The rights conflicts the version records (an#357) ### an.library.api.effective_rights(libraries, version, \*, floor=, owner=None, rule=None) The rights of a version, recomputed from its sources, its lineage and its bytes. owner: the library holding `version` (see [`version_sources()`](_autosummary/an.library.api.html.md#an.library.api.version_sources)) rule: a `_PerFileRule` to share with the caller (one per operation) * **Return type:** [`Rights`](_autosummary/an.library.rights.html.md#an.library.rights.Rights) ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> _ = publish(lib, "prop.vase", {"name": "vase"}, ... source={"provider": "film", "license": "all-rights-reserved"}) >>> effective_rights(lib, read_version(lib, "prop.vase", "v001"), owner=lib).license_class 'private' ``` ### an.library.api.find(libraries, \*, kind=None, style=None, affords=None, rights='any', family=None, origin=None, status=None, tags=None, art=None, near=False, index=) Assets matching every facet given (AND across facets, OR within one facet’s values). * **Return type:** [`FindResult`](_autosummary/an.library.api.html.md#an.library.api.FindResult) affords: capabilities the asset must ALL have — `limbs.legs`, or : `swap.view:side` for a capability with a given key. Each capability is its own boolean facet, so a list of them is AND, as across facets. An unregistered name raises, naming the close ones rights: `any` (default — study renders are legitimate), `publishable` : (`free` + `attribution` + `noncommercial`), `commercial` (`free` + `attribution`: what a commercial video may use, an#373), or licence classes. Rights are recomputed from each version’s sources and lineage, not read from its cache status: curation statuses; an asset whose status is hidden : (`HIDDEN_STATUSES`: `retired`) is offered only when its status is asked for by name near: also return assets that pass every other facet but miss some : capabilities, or are curated for another style than asked, each with what is missing and the remedy that would add it (a style mismatch is listed as `style:`, remedied by restyling: an#271) index: the index to read (default: a scan of the stores) ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> _ = publish(lib, "prop.lamp", {"name": "lamp"}, style=["reiniger", "gilliam"]) >>> [h.ref for h in find(lib, kind="prop", style="gilliam")] ['prop.lamp@v001'] >>> len(find(lib, kind="prop", rights="publishable")) # no source: unknown 0 ``` ### an.library.api.promote(libraries, ref, , to=None, as_id=None, allow_restricted=False, strict_assets=False) Copy one version into another library — by default the core `an` library. An asset made in a genre’s library and reused across genres is promoted to the core (plan §1 decision 7). The copy is a new version in the target, derived from the source version, with the record’s curation carried over. - A `private` or `unknown` version is refused unless `allow_restricted=True`: private-study material never leaves its library by default (ADR 0005 decision 10). The rights checked are recomputed from the version’s sources and lineage, and the stricter of those and the stored ones wins. - If the target already has an asset with this id that does not derive from the one promoted (another character that happens to share the id), it is refused: promoting would make it a new version of an unrelated asset. `as_id` promotes under another id. - `strict_assets`: refuse a copy that would record a rights conflict ([`publish()`](_autosummary/an.library.api.html.md#an.library.api.publish)’s, an#357), instead of recording it. * **Return type:** [`PublishResult`](_autosummary/an.library.api.html.md#an.library.api.PublishResult) ### an.library.api.publish(library, asset_id, doc, files=None, \*, source=None, relicense=None, relabel=None, derived_from=(), title=None, family=None, style=None, origin=None, status=None, tags=None, replace_curation=False, note=None, expect_head=, search=None, carry_source=True, license_parts=None, file_sources=None, strict_assets=False) Publish `doc` and its `files` as the next version of `asset_id` in `library`. library: the owning library (writes never go to a search path) asset_id: `.`; the kind must be registered doc: the descriptor — the existing document `an` already versions > (`CharacterDescriptor`, …), as a model or its JSON dict, stored verbatim files: the asset’s files, by the relative paths the descriptor uses : (`parts/head.svg`) — stored once each in the content-addressed blobs source: provenance declared for the asset as a whole. It contributes BESIDE : the descriptor’s own `source` (the most restrictive wins), never instead of it. With no `source`, and a descriptor declaring nothing or exactly what the head’s declared, the source of the previous version carries forward (`carry_source`) — for the bytes it was declared on only: a file changed or added since is recorded as `unlabelled` on the version and is `unknown`. Later versions inherit that gap through `previous` even when they pass `source=`; `relabel` (or a relicence) answers it. With no source at all the version is `unknown` — recorded and visible, not refused relicense: `{"by": who, "reason": why}` — the ONLY way to relax rights. : Rights attach to the bytes and the lineage: a new version inherits the version it follows (`previous`), every version it derives from, and every version holding the same file bytes, and may only be more restrictive than they are — a cc0 in the descriptor or in `source=` never relabels private art. A relicence makes `source` (required) the whole statement, records who and why on the version (and in its manifest and reasons), and covers these bytes for later versions relabel: `{"by": who, "reason": why}` beside an explicit `source=` : (required) — a first statement about bytes NOBODY labelled (an#263): the gaps of this asset’s own version chain (files an earlier version recorded `unlabelled`, files no person’s source spoke for, an earlier version with no source at all) are answered with `source`, and so is another asset’s silence about a file the chain held once and this version no longer holds (an#307). It relaxes no statement anyone made: a private (or any) licence, a per-part source, a version this one derives from, and every other asset’s statement about bytes this version holds still bind. On content that changed, recorded on the new version, in its manifest and in its reasons; on UNCHANGED content, recorded on the head in the append-only `labels` store ([`version_labels()`](_autosummary/an.library.api.html.md#an.library.api.version_labels)) and no version is minted (an#307) derived_from: library references this version derives from (an earlier version, : the original of a recolour); each must resolve, and its rights are inherited. A descriptor checked out of a library derives from its origin by default title, family, style, origin, status, tags: curation, stored on the record; : given again with unchanged content they update the record and make no version. `style` and `tags` add to what is there, or replace it with `replace_curation=True` note: what changed, stored on the version expect_head: guard against publishing into an asset you did not mean: > `None` — the id must be new; `"vNNN"` — the head must be that version search: further libraries where `derived_from` references resolve (the : owning library is always searched first) license_parts: `{glob: source}` — a per-file statement for every stored : path a glob matches (`match_license_parts()`: `*` stays in one folder, `**` crosses folders, case-exact; a glob matching nothing, two globs disagreeing on a path, or a near miss refuse), each pinned to the file’s digest (an#345). Needs an asset-level `source` (given or carried): the files no glob names are stated with the version’s label computed WITHOUT these statements. A per-file statement never relaxes what the bytes already carry — the per-part source of the same file, the same bytes at another path, and every earlier statement of this asset’s chain or of a version it derives from about them: a looser one is kept and recorded as a rights conflict, the stricter binding (an#357), unless `relicense` records who and why (the relicence then lists the digests it covers, and a per-file statement stricter than it keeps binding). At a later publish a statement is carried for its file while the bytes are unchanged; a file changed since is recorded `unlabelled` file_sources: `{path: source}` — the same, by exact stored path (what a : stored version holds; [`promote()`](_autosummary/an.library.api.html.md#an.library.api.promote) passes it) strict_assets: refuse a publish that would record a rights conflict : (`RightsConflict`: a per-part or per-file statement freer than what binds its bytes) instead of recording it with a `RightsConflictWarning` (an#357: inform, don’t block, by default) ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> doc = {"name": "lamp", "source": {"provider": "me", "license": "cc0-1.0"}} >>> r = publish(lib, "prop.lamp", doc, {"parts/lamp.svg": b""}, style="reiniger") >>> str(r.ref), r.created, r.rights.license_class ('an:prop.lamp@v001', True, 'free') >>> publish(lib, "prop.lamp", doc, {"parts/lamp.svg": b""}).created False ``` * **Return type:** [`PublishResult`](_autosummary/an.library.api.html.md#an.library.api.PublishResult) ### an.library.api.publish_dir(library, folder, asset_id, \*\*kwargs) Publish an asset folder as it sits in a project store (`assets/characters/alice/`). The descriptor is the kind’s descriptor file (`character.json`); every other file under the folder is published as one of the asset’s files, so a check-out reproduces the folder — except operating-system clutter (`.DS_Store`, hidden files, `Thumbs.db`: `an.stores._common.is_os_junk()`) that the descriptor does not name — a part it names is published whatever its file is called (review-288 S2). Keyword arguments go to [`publish()`](_autosummary/an.library.api.html.md#an.library.api.publish). * **Return type:** [`PublishResult`](_autosummary/an.library.api.html.md#an.library.api.PublishResult) ### an.library.api.reindex(library, , search=None) Rebuild `library`’s floor index from its versions. Returns the number of blobs indexed. Lineage resolves through `search` and then every library on this machine ([`an.library.floor.machine_libraries()`](_autosummary/an.library.floor.html.md#an.library.floor.machine_libraries)), so a promoted copy’s parent in a genre’s library is read without being named (an#361). The index is derived data: rebuilding it is always safe, and the way to repair a library whose index was lost or written by an older `an`. It also (re-)registers the library’s root in the machine registry ([`an.library.registry`](_autosummary/an.library.registry.html.md#module-an.library.registry)), so a library made at a custom root before the registry existed becomes visible to every other library’s rights floor. `reindex_changes()` says first what a rebuild would change. The new index is computed in full first, then written over the old one entry by entry, and only then are stale entries removed: a crash midway leaves old and new statements side by side, never an empty floor (an#249 R4-N4). * **Return type:** [`int`](https://docs.python.org/3/builtins/functions.html#int) ### an.library.api.retire(library, asset_id, , by, reason) Retire an asset id: recorded, hidden from `find` by default, never deleted. Its versions stay readable — a project pinned to one still checks it out and validates — and its rights statements still bind the floor (retiring is curation, not a relabel). `find(status="retired")` lists it; a publish into it is refused unless it passes `status=` to revive it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> _ = publish(lib, "prop.dead", {"name": "dead"}) >>> _ = retire(lib, "prop.dead", by="me", reason="superseded") >>> len(find(lib)), [h.asset_id for h in find(lib, status="retired")] (0, ['prop.dead']) ``` ### an.library.api.scan_index(library) Every asset’s head version in `library`, read from the stores. Affordances snapshotted by an older analyser are recomputed, not trusted. A record or version that cannot be read (a damaged file) is skipped with a [`LibraryIndexWarning`](_autosummary/an.library.api.html.md#an.library.api.LibraryIndexWarning) naming it, so one bad entry never blinds every search. * **Return type:** [`Iterator`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Iterator)[[`IndexEntry`](_autosummary/an.library.api.html.md#an.library.api.IndexEntry)] ### an.library.api.set_status(library, asset_id, status, , by, reason) Set an asset’s curation status, recording who and why; return the record. The record’s `status_history` is appended to, never rewritten, and no version is touched: a project pinned to one keeps reading it. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> _ = publish(lib, "prop.lamp", {"name": "lamp"}) >>> set_status(lib, "prop.lamp", "approved", by="me", reason="looks right")["status"] 'approved' ``` ### an.library.api.show(libraries, ref) The record, the resolved version, its recomputed rights and the list of versions. * **Return type:** [`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)] ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> _ = publish(lib, "prop.lamp", {"name": "lamp"}, title="A lamp") >>> s = show(lib, "prop.lamp") >>> s["ref"], s["record"]["title"], s["versions"] ('an:prop.lamp@v001', 'A lamp', ['v001']) ``` ### an.library.api.unknown_advice(libraries, version, \*, owner=None, floor=) What would answer each `unknown` contributor of a version — one sentence per kind. The advice a refusal prints, so it names what works for THESE gaps (an#307): a gap of the asset’s own chain takes a relabel; a gap of a version it derives from is labelled there; another asset’s silence about bytes this version still holds is answered by labelling THAT asset (a relabel here cannot speak for another asset), or by dropping the file; and anything stated (a licence nobody recognises, an unverified stamp, a parent not on the path) relaxes only by a relicence. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str)] ```pycon >>> lib = open_library("an", records={}, versions={}, blobs={}) >>> r = publish(lib, "prop.vase", {"name": "vase"}) >>> r.rights.license_class, "--relabel-by" in r.advice[0] ('unknown', True) ``` ### an.library.api.version_labels(library, version) The labels recorded on a stored version since it was published, oldest first. A relabel of a version’s UNCHANGED content is recorded on that version, in the library’s append-only `labels` store, instead of minting a new version (an#307). A label counts only for the very version it was made on: its `manifest` must be this version’s (a same-named library’s other `x@v001` never inherits it). An unreadable label is skipped with a [`LibraryIndexWarning`](_autosummary/an.library.api.html.md#an.library.api.LibraryIndexWarning); skipping one can only leave the version stricter. * **Return type:** [`list`](https://docs.python.org/3/builtins/stdtypes.html#list)[[`dict`](https://docs.python.org/3/builtins/stdtypes.html#dict)[[`str`](https://docs.python.org/3/builtins/stdtypes.html#str), [`Any`](https://docs.python.org/3/library/typing.html#typing.Any)]] ### an.library.api.version_sources(libraries, version, \*, floor=, owner=None, per_file=True, rule=None) Every labelled source a version’s rights depend on — its own, its lineage, its bytes. - its own ([`an.library.rights.sources_in()`](_autosummary/an.library.rights.html.md#an.library.rights.sources_in): asset-level, descriptor, parts); - the version it follows (`previous`) and each `derived_from` version, recursively, labelled ` >