framerudiments 0.1.4__tar.gz → 0.2.0__tar.gz

{framerudiments-0.1.4/src/framerudiments.egg-info → framerudiments-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.1.4
+Version: 0.2.0
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -29,6 +29,19 @@ FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
 from one traceable timeline. It is the offline Python renderer in the
 [DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
 
+**0.2.0** accepts source-bound StemLab BPM/first-beat readings through
+`clock.beat_alignment`. Procedural motion follows the fractional beat phase
+after excerpt/repeat mapping. Audio, lyric/cue timestamps and captured
+recordings retain their original source clock. See [beat alignment](docs/beat-alignment.md).
+
+![Actual encoded FrameRudiments 0.2.0 synthetic example with original and aligned movement side by side, source-timed captions and recorded bands](docs/media/beat-alignment.png)
+
+[Play the four-second demonstration](docs/media/beat-alignment.mp4): original
+120 BPM clicks start at 0.125 seconds; the right movement uses the -16 pip
+reading. Text and recorded bands keep source time. This synthetic example
+demonstrates clock composition; it does not establish song-analysis accuracy.
+[Encoded-frame verification and hashes](docs/media/beat-alignment-evidence.json).
+
 It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
 the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
 Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,

{framerudiments-0.1.4 → framerudiments-0.2.0}/README.md

@@ -4,6 +4,19 @@ FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
 from one traceable timeline. It is the offline Python renderer in the
 [DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
 
+**0.2.0** accepts source-bound StemLab BPM/first-beat readings through
+`clock.beat_alignment`. Procedural motion follows the fractional beat phase
+after excerpt/repeat mapping. Audio, lyric/cue timestamps and captured
+recordings retain their original source clock. See [beat alignment](docs/beat-alignment.md).
+
+![Actual encoded FrameRudiments 0.2.0 synthetic example with original and aligned movement side by side, source-timed captions and recorded bands](docs/media/beat-alignment.png)
+
+[Play the four-second demonstration](docs/media/beat-alignment.mp4): original
+120 BPM clicks start at 0.125 seconds; the right movement uses the -16 pip
+reading. Text and recorded bands keep source time. This synthetic example
+demonstrates clock composition; it does not establish song-analysis accuracy.
+[Encoded-frame verification and hashes](docs/media/beat-alignment-evidence.json).
+
 It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
 the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
 Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,

framerudiments-0.2.0/docs/beat-alignment.md

@@ -0,0 +1,56 @@
+# Beat alignment from saved StemLab evidence
+
+![Actual FrameRudiments 0.2.0 encoded example: original and aligned native movement with source-time captions and recorded bands](media/beat-alignment.png)
+
+[Play the four-second example](media/beat-alignment.mp4). Original synthetic
+120 BPM clicks begin at 0.125 seconds. The left native bounce shows the original
+grid; the right follows the -16 pip reading. The bands retain their recording
+clock. Text changes at the original LRC times: “Signals into motion” at 0,
+“Words into light” at 1.25, “Keep the clock in sight” at 2.50, then clears at
+3.75 seconds. The synthetic text is a caption fixture, not sung lyrics.
+[Encoded verification, source identity and hashes](media/beat-alignment-evidence.json).
+
+Generate a source-bound reading from saved StemLab evidence, reviewing canonical,
+combined, fitted and half/double-time interpretations and individual detectors:
+
+```sh
+stemlab beat-offset RESULTS --output NEW --audio EXACT-MASTER.wav \
+  --alignment-analysis consensus --alignment-bpm-basis combined_fit
+```
+
+Use `canonical` only when canonical BPM has an established authority. Retain the
+full comparison report; a good beat-grid fit is not a listening or downbeat
+confirmation. A normal half-time reading does not mean a detector failed.
+
+Pin the resulting file exactly as every other project input:
+
+```json
+"clock": {
+  "authority": "Reviewed StemLab consensus constant-grid fit",
+  "status": "estimated",
+  "phase_status": "estimated",
+  "beat_alignment": {"path": "beat-alignment.json", "sha256": "EXACT_FILE_SHA256"}
+}
+```
+
+The adapter validates the master SHA-256, source sample rate/frame bounds,
+64-pip units, detector/report identities and exact rational clock equation.
+An explicit BPM must agree. Do not also supply `origin` or `beat_grid`; the
+reading owns this clock. An estimated BPM cannot become `confirmed` through
+project metadata, and phase authority stays separate.
+
+The existing BeatClock uses the first source beat as its origin. At that instant
+the procedural clock is pip zero; before it, pips can be negative. Excerpts and
+repeats map source time first and apply phase once. Keep the original master,
+LRC, CUE and captured recording clocks unchanged. A recording's captured beat
+zero and integer samples remain authoritative, including Fourier dimensions.
+
+Missing, mismatched or poor evidence remains a review hold. A constant-grid
+reading is not proof that a variable-tempo song fits one BPM. Existing projects
+without a reading retain their explicit clock and report unverified phase when
+no phase status was supplied.
+
+Reproduce the actual fixture with `python examples/beat-alignment/generate.py
+NEW-DIRECTORY --font /path/to/font.ttf`, then use normal `plan`, `preflight` and
+`render` commands. Keep technical encoded QA separate from attended listening,
+creative approval and any platform publication.

framerudiments-0.2.0/docs/media/beat-alignment-evidence.json

@@ -0,0 +1,173 @@
+{
+  "context": "Actual FrameRudiments 0.2.0 encoded synthetic clock-composition example",
+  "frames": 240,
+  "fps": 60,
+  "dimensions": [
+    360,
+    640
+  ],
+  "duration_seconds": 4,
+  "source_audio_sha256": "83e47effac0c8cf6c6c8c70f3babec9b55f61fcea0ba1a97822528e85b8ffe8c",
+  "first_beat_seconds": 0.125,
+  "offset_pips": -16,
+  "pips_per_beat": 64,
+  "screenshot_frame": 75,
+  "screenshot_source_seconds": 1.25,
+  "verification": {
+    "probe": {
+      "streams": [
+        {
+          "index": 0,
+          "codec_name": "h264",
+          "codec_long_name": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
+          "profile": "High",
+          "codec_type": "video",
+          "codec_tag_string": "avc1",
+          "codec_tag": "0x31637661",
+          "mime_codec_string": "avc1.64001f",
+          "width": 360,
+          "height": 640,
+          "coded_width": 368,
+          "coded_height": 640,
+          "has_b_frames": 2,
+          "pix_fmt": "yuv420p",
+          "level": 31,
+          "color_range": "tv",
+          "color_space": "bt709",
+          "chroma_location": "left",
+          "field_order": "progressive",
+          "refs": 4,
+          "is_avc": "true",
+          "nal_length_size": "4",
+          "id": "0x1",
+          "r_frame_rate": "60/1",
+          "avg_frame_rate": "60/1",
+          "time_base": "1/15360",
+          "start_pts": 0,
+          "start_time": "0.000000",
+          "duration_ts": 61440,
+          "duration": "4.000000",
+          "bit_rate": "108766",
+          "bits_per_raw_sample": "8",
+          "nb_frames": "240",
+          "nb_read_frames": "240",
+          "extradata_size": 49,
+          "disposition": {
+            "default": 1,
+            "dub": 0,
+            "original": 0,
+            "comment": 0,
+            "lyrics": 0,
+            "karaoke": 0,
+            "forced": 0,
+            "hearing_impaired": 0,
+            "visual_impaired": 0,
+            "clean_effects": 0,
+            "attached_pic": 0,
+            "timed_thumbnails": 0,
+            "non_diegetic": 0,
+            "captions": 0,
+            "descriptions": 0,
+            "metadata": 0,
+            "dependent": 0,
+            "still_image": 0,
+            "multilayer": 0
+          },
+          "tags": {
+            "language": "und",
+            "handler_name": "VideoHandler",
+            "encoder": "Lavc63.1.101 libx264"
+          }
+        },
+        {
+          "index": 1,
+          "codec_name": "aac",
+          "codec_long_name": "AAC (Advanced Audio Coding)",
+          "profile": "LC",
+          "codec_type": "audio",
+          "codec_tag_string": "mp4a",
+          "codec_tag": "0x6134706d",
+          "mime_codec_string": "mp4a.40.2",
+          "sample_fmt": "fltp",
+          "sample_rate": "48000",
+          "channels": 2,
+          "channel_layout": "stereo",
+          "bits_per_sample": 0,
+          "initial_padding": 1024,
+          "id": "0x2",
+          "r_frame_rate": "0/0",
+          "avg_frame_rate": "0/0",
+          "time_base": "1/48000",
+          "start_pts": 0,
+          "start_time": "0.000000",
+          "duration_ts": 192000,
+          "duration": "4.000000",
+          "bit_rate": "35574",
+          "nb_frames": "189",
+          "nb_read_frames": "188",
+          "extradata_size": 5,
+          "disposition": {
+            "default": 1,
+            "dub": 0,
+            "original": 0,
+            "comment": 0,
+            "lyrics": 0,
+            "karaoke": 0,
+            "forced": 0,
+            "hearing_impaired": 0,
+            "visual_impaired": 0,
+            "clean_effects": 0,
+            "attached_pic": 0,
+            "timed_thumbnails": 0,
+            "non_diegetic": 0,
+            "captions": 0,
+            "descriptions": 0,
+            "metadata": 0,
+            "dependent": 0,
+            "still_image": 0,
+            "multilayer": 0
+          },
+          "tags": {
+            "language": "und",
+            "handler_name": "SoundHandler"
+          }
+        }
+      ],
+      "format": {
+        "nb_streams": 2,
+        "nb_programs": 0,
+        "nb_stream_groups": 0,
+        "format_name": "mov,mp4,m4a,3gp,3g2,mj2",
+        "format_long_name": "QuickTime / MOV",
+        "start_time": "0.000000",
+        "duration": "4.000000",
+        "size": "79895",
+        "bit_rate": "159790",
+        "probe_score": 100,
+        "tags": {
+          "major_brand": "isom",
+          "minor_version": "512",
+          "compatible_brands": "isomiso2avc1mp41",
+          "encoder": "Lavf63.1.101"
+        }
+      }
+    },
+    "full_decode": "passed",
+    "decoded_timestamps": "CFR from zero; all frames checked",
+    "audio_duration_error_seconds": 0.0,
+    "mp4_atoms": [
+      "ftyp",
+      "moov",
+      "free",
+      "mdat"
+    ],
+    "listening_approved": false,
+    "platform_safe_zone_verified": false
+  },
+  "description": "Left: original pip-zero movement. Right: source-bound aligned movement. Bottom: captured recording keeps source clock. Text changes at original LRC timestamps. Soundtrack: original synthetic clicks.",
+  "limits": "Synthetic score, not detector accuracy, canonical-song authority or attended listening approval. Generated illustration omitted because actual rendered output demonstrates the composition.",
+  "files": {
+    "beat-alignment.mp4": "7e8a62a67fcc2967540121bd848263d2eff2bea02ca77e0b01f3be2966d45ccb",
+    "beat-alignment.png": "1755f09c51382cf04adbe0b18ce702036807e8b595633cc10cd116bfb9c5f88a"
+  }
+}

{framerudiments-0.1.4 → framerudiments-0.2.0}/docs/project-format.md

@@ -11,7 +11,7 @@ the inputs are checked again before and after a render.
 | `purpose` | `short` (120 ms endpoint fades by default), `visualiser`, or `canvas` (no fades by default). |
 | `width`, `height`, `fps`, `fps_reason` | Even dimensions, fps defaults to 60; other rates need a reason. No platform compliance is inferred. |
 | `audio` | `source` file reference, verified `sample_rate`, start-inclusive `start_sample`, end-exclusive `end_sample`, optional positive integer `repeats` and `fade_seconds`. |
-| `clock` | `bpm` or `beat_grid` file reference; `authority`, `status` (`confirmed`, `estimated`, `synthetic`), optional `origin` in source seconds and `phase_status`. |
+| `clock` | `bpm`, `beat_grid` or source-bound `beat_alignment` file reference; `authority`, `status` (`confirmed`, `estimated`, `synthetic`), optional `origin` in source seconds and `phase_status`. A reading owns its BPM/origin and cannot be combined with `beat_grid` or `origin`. |
 | `font` | Pinned TTF/OTF file for authored text. |
 | `lyrics`, `cues` | Separate LRC references; `.cue` files are also supported for structural cues. |
 | `canonical_lyrics` | Optional pinned plain text whose performed nonempty lines must exactly match the LRC. Bracketed structural lines in this comparison file are excluded. |
@@ -30,6 +30,13 @@ control their appearance. `mapping` amplitudes are `dx`, `dy`, `rotation`
 and `scale_axis` select index 0,1,2 of the motion projection. Defaults are
 0,1,2,2 respectively. Set `y_axis: 0` to map a one-dimensional bounce vertically.
 
+![Actual encoded original/aligned clock example: captions and recorded bands retain source time](media/beat-alignment.png)
+
+[Watch the synthetic clock example](media/beat-alignment.mp4) and follow the
+[source-bound alignment setup](beat-alignment.md). Its first click at 0.125
+seconds maps to pip zero; the screenshot is encoded frame 75 at source 1.25
+seconds. [Verification and media hashes](media/beat-alignment-evidence.json).
+
 Atlas configuration is `{columns, rows, count, cycle_ticks, phase_beats?}`.
 The atlas must divide into exact cells. One beat is 16 ticks; cycle ticks are
 explicitly authored rather than silently quantised. Cycles use a continuous

{framerudiments-0.1.4 → framerudiments-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "framerudiments"
-version = "0.1.4"
+version = "0.2.0"
 description = "Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence."
 requires-python = ">=3.11"
 readme = "README.md"

{framerudiments-0.1.4 → framerudiments-0.2.0}/src/framerudiments/__init__.py

@@ -1,5 +1,5 @@
 """Offline frame composition on a traceable musical clock."""
-__version__ = "0.1.4"
+__version__ = "0.2.0"
 
 from .project import Project
 from .render import render, preflight

framerudiments-0.2.0/src/framerudiments/beat_alignment.py

@@ -0,0 +1,57 @@
+"""Validate a source-bound StemLab clock handoff; no detector or DSP implementation."""
+
+from fractions import Fraction
+import math
+from pathlib import Path
+import re
+
+from .io import read_json
+
+
+def beat_alignment(path, source_sha256, sample_rate, end_sample):
+    path = Path(path)
+    if path.stat().st_size > 16384:
+        raise ValueError("Beat alignment exceeds 16 KiB")
+    reading = read_json(path)
+    if (
+        reading.get("schema") != "stemlab.beat-alignment.v1"
+        or reading.get("pips_per_beat") != 64
+        or reading.get("canonical_first_beat_pip") != 0
+        or reading.get("source_sha256") != source_sha256
+    ):
+        raise ValueError("Beat alignment requires the exact audio master and 64-pip contract")
+    for key in ("source_sha256", "evidence_sha256", "report_sha256"):
+        if not isinstance(reading.get(key), str) or not re.fullmatch("[a-f0-9]{64}", reading[key]):
+            raise ValueError("Beat alignment needs source, detector and report SHA-256 identities")
+    for key in ("analysis_id", "bpm_basis"):
+        if not isinstance(reading.get(key), str) or not re.fullmatch("[a-zA-Z0-9_.-]{1,128}", reading[key]):
+            raise ValueError("Beat alignment needs an explicit analysis and BPM basis")
+    exact = []
+    for key in ("exact_bpm", "first_beat_exact_seconds", "exact_offset_pips"):
+        value = reading.get(key)
+        if not isinstance(value, str) or not re.fullmatch(r"-?\d{1,80}(?:/[1-9]\d{0,79})?", value):
+            raise ValueError("Beat alignment requires bounded exact rational clock values")
+        exact.append(Fraction(value))
+    tempo, first, offset = exact
+    if not 20 <= tempo <= 400 or not 0 <= first <= 86400 or first * tempo * 64 / 60 + offset != 0:
+        raise ValueError("Beat alignment must map the first source beat to pip zero")
+    for key, value in zip(("bpm", "first_beat_seconds", "offset_pips"), exact):
+        actual = reading.get(key)
+        if type(actual) not in (int, float) or not math.isfinite(actual) or abs(actual - float(value)) > 1e-7:
+            raise ValueError("Exact and numeric beat alignment values disagree")
+    audio = reading.get("source_audio") or {}
+    if (
+        reading.get("source_audio_verified") is not True
+        or audio.get("sample_rate") != sample_rate
+        or type(audio.get("num_frames")) is not int
+        or audio["num_frames"] < end_sample
+        or first >= Fraction(audio["num_frames"], sample_rate)
+    ):
+        raise ValueError("Beat alignment source sample rate/frame bounds disagree with the project")
+    if reading.get("bpm_status") not in {"canonical", "estimated"} or reading.get("phase_status") not in {
+        "estimated",
+        "confirmed",
+        "synthetic",
+    }:
+        raise ValueError("Beat alignment must retain BPM and phase authority separately")
+    return reading

{framerudiments-0.1.4 → framerudiments-0.2.0}/src/framerudiments/project.py

@@ -6,6 +6,7 @@ from pathlib import Path
 from .io import read_json, file_ref, fields, integer, number, sha256
 from .timeline import BeatClock, parse_lrc, parse_cue, frame_ledger
 from .stemlab import beat_grid, selected_loop
+from .beat_alignment import beat_alignment
 
 
 class Project:
@@ -58,11 +59,25 @@ class Project:
         self.fade = number(self.audio.get("fade_seconds", .12 if self.purpose == "short" else 0),
                            "fade seconds", minimum=0, maximum=float(self.duration) / 2)
         cfg = data["clock"]
-        fields(cfg, {"bpm", "origin", "authority", "status", "phase_status", "beat_grid"}, "clock")
+        fields(cfg, {"bpm", "origin", "authority", "status", "phase_status", "beat_grid", "beat_alignment"}, "clock")
         if not cfg.get("authority") or cfg.get("status") not in {"confirmed", "estimated", "synthetic"}:
             raise ValueError("Clock needs authority and confirmed/estimated/synthetic status")
-        grid = beat_grid(self.ref(cfg["beat_grid"])["path"]) if "beat_grid" in cfg else None
-        self.clock = BeatClock(bpm=cfg.get("bpm"), origin=cfg.get("origin", 0), beats=grid)
+        self.alignment = None
+        if "beat_alignment" in cfg:
+            if "beat_grid" in cfg or "origin" in cfg:
+                raise ValueError('beat_alignment cannot be combined with a separate beat grid or origin')
+            ref = self.ref(cfg['beat_alignment'])
+            self.alignment = beat_alignment(ref['path'], self.audio_ref['sha256'], self.sample_rate, self.end_sample)
+            if 'bpm' in cfg and abs(number(cfg['bpm'], 'BPM')-self.alignment['bpm']) > 1e-8:
+                raise ValueError('Explicit BPM conflicts with the beat alignment reading')
+            if self.alignment['bpm_status'] == 'estimated' and cfg['status'] != 'estimated':
+                raise ValueError('An estimated alignment BPM cannot be promoted to confirmed or synthetic')
+            if 'phase_status' in cfg and cfg['phase_status'] != self.alignment['phase_status']:
+                raise ValueError('Project phase authority conflicts with the saved reading')
+            self.clock = BeatClock(bpm=self.alignment['bpm'], origin=self.alignment['first_beat_seconds'])
+        else:
+            grid = beat_grid(self.ref(cfg["beat_grid"])["path"]) if "beat_grid" in cfg else None
+            self.clock = BeatClock(bpm=cfg.get("bpm"), origin=cfg.get("origin", 0), beats=grid)
         self.font_ref = self.ref(data["font"]) if "font" in data else None
         if (data.get("lyrics") or data.get("identity")) and not self.font_ref:
             raise ValueError("Pin an explicit font for all authored text")
@@ -119,6 +134,8 @@ class Project:
                     repeats=self.repeats, duration_seconds=float(self.duration),
                     video_duration_seconds=self.frame_count / self.fps,
                     frame_rounding="nearest, ties toward positive infinity; stable source ordering",
-                    clock=self.data["clock"], endpoint_fade_seconds=self.fade, endpoint_fade_curve="qsin",
+                    clock={**self.data['clock'], 'alignment': self.alignment,
+                           'phase_status': self.alignment['phase_status'] if self.alignment else self.data['clock'].get('phase_status', 'unverified')},
+                    endpoint_fade_seconds=self.fade, endpoint_fade_curve="qsin",
                     lyrics=self.lyrics, cues=self.cues, stemlab_loop=self.loop, effects=self.data.get("effects", []), inputs=self.inputs,
                     state="prepared; perceptual review pending")

{framerudiments-0.1.4 → framerudiments-0.2.0/src/framerudiments.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: framerudiments
-Version: 0.1.4
+Version: 0.2.0
 Summary: Deterministic Shorts and lyric visualisers using DanceRudiments and StemLab evidence.
 Author: Kieran Simkin
 License-Expression: MIT
@@ -29,6 +29,19 @@ FrameRudiments renders Shorts, Canvas-style clips and full lyric visualisers
 from one traceable timeline. It is the offline Python renderer in the
 [DanceFlow ecosystem](https://kieransimkin.co.uk/danceflow/).
 
+**0.2.0** accepts source-bound StemLab BPM/first-beat readings through
+`clock.beat_alignment`. Procedural motion follows the fractional beat phase
+after excerpt/repeat mapping. Audio, lyric/cue timestamps and captured
+recordings retain their original source clock. See [beat alignment](docs/beat-alignment.md).
+
+![Actual encoded FrameRudiments 0.2.0 synthetic example with original and aligned movement side by side, source-timed captions and recorded bands](docs/media/beat-alignment.png)
+
+[Play the four-second demonstration](docs/media/beat-alignment.mp4): original
+120 BPM clicks start at 0.125 seconds; the right movement uses the -16 pip
+reading. Text and recorded bands keep source time. This synthetic example
+demonstrates clock composition; it does not establish song-analysis accuracy.
+[Encoded-frame verification and hashes](docs/media/beat-alignment-evidence.json).
+
 It consolidates the shared Python/Pillow/FFmpeg mechanisms developed across
 the existing Gilt Trip, Blame Putin, Clay, Paper Dreams, Free Danny Tommo,
 Silly Sausage Britain and Moderate or Good renderers. Release-specific artwork,

{framerudiments-0.1.4 → framerudiments-0.2.0}/src/framerudiments.egg-info/SOURCES.txt

@@ -3,12 +3,16 @@ LICENSE
 MANIFEST.in
 README.md
 pyproject.toml
+docs/beat-alignment.md
 docs/extraction.md
 docs/project-format.md
 docs/rudiment-renderers.md
 docs/spectrum.md
 docs/visualisers.md
 docs/workflow-media.md
+docs/media/beat-alignment-evidence.json
+docs/media/beat-alignment.mp4
+docs/media/beat-alignment.png
 docs/media/demo-transcript.md
 docs/media/effects-pipeline.svg
 docs/media/full-frame-comparison.png
@@ -18,6 +22,7 @@ integration/test_visualisers_gpu.py
 src/framerudiments/__init__.py
 src/framerudiments/__main__.py
 src/framerudiments/atlas.py
+src/framerudiments/beat_alignment.py
 src/framerudiments/choreography.py
 src/framerudiments/cli.py
 src/framerudiments/compositor.py
@@ -54,6 +59,7 @@ src/framerudiments/visualiser_assets/kaleidoscope.milk
 src/framerudiments/visualiser_assets/package-lock.json
 src/framerudiments/visualiser_assets/package.json
 tests/test_adapters.py
+tests/test_beat_alignment.py
 tests/test_extracted_helpers.py
 tests/test_flight.py
 tests/test_lyrics.py

framerudiments-0.2.0/tests/test_beat_alignment.py

@@ -0,0 +1,144 @@
+import copy
+import wave
+
+import pytest
+
+from framerudiments.io import sha256, write_json
+from framerudiments.project import Project
+from framerudiments.timeline import parse_lrc
+
+
+def fixture(tmp_path):
+    audio = tmp_path / "master.wav"
+    with wave.open(str(audio), "wb") as stream:
+        stream.setparams((1, 2, 48000, 0, "NONE", "not compressed"))
+        stream.writeframes(b"\0\0" * 48000 * 4)
+    reading = dict(
+        schema="stemlab.beat-alignment.v1",
+        source_sha256=sha256(audio),
+        source_audio_verified=True,
+        source_audio=dict(sample_rate=48000, num_frames=192000),
+        bpm=120,
+        exact_bpm="120",
+        bpm_basis="combined_fit",
+        bpm_status="estimated",
+        phase_status="estimated",
+        analysis_id="consensus",
+        evidence_sha256="b" * 64,
+        report_sha256="c" * 64,
+        first_beat_seconds=0.125,
+        first_beat_exact_seconds="1/8",
+        offset_pips=-16,
+        exact_offset_pips="-16",
+        pips_per_beat=64,
+        canonical_first_beat_pip=0,
+    )
+    path = tmp_path / "alignment.json"
+    write_json(path, reading)
+    data = dict(
+        schema="framerudiments.project.v1",
+        purpose="canvas",
+        width=180,
+        height=320,
+        fps=60,
+        audio=dict(
+            source=dict(path="master.wav", sha256=sha256(audio)),
+            sample_rate=48000,
+            start_sample=0,
+            end_sample=192000,
+            fade_seconds=0,
+        ),
+        clock=dict(
+            authority="Synthetic source-bound test reading",
+            status="estimated",
+            beat_alignment=dict(path="alignment.json", sha256=sha256(path)),
+        ),
+        layers=[],
+        background=dict(colour="#101b2e"),
+    )
+    return data, reading, path
+
+
+def test_first_beat_and_negative_prebeat_pips_preserve_source_timing(tmp_path):
+    data, reading, path = fixture(tmp_path)
+    project = Project(data, tmp_path)
+    assert project.clock.pip_at(0.125) == 0
+    assert project.clock.pip_at(0) == -16
+    assert project.clock.pip_at(0.625) == 64
+    assert project.source_time(0) == 0
+    assert project.summary()["clock"]["alignment"]["report_sha256"] == "c" * 64
+    assert project.summary()["clock"]["phase_status"] == "estimated"
+    lyrics = tmp_path / "lyrics.lrc"
+    lyrics.write_text("[00:00.125]Unshifted words\n[00:01.125]Later words\n", encoding="utf-8")
+    ledger = project.ledger(parse_lrc(lyrics))
+    assert [r["frame"] for r in ledger if r["text"]] == [8, 68]
+    assert next(r for r in ledger if r["text"])["source_seconds"] == 0.125
+    baseline = copy.deepcopy(data)
+    baseline["clock"] = dict(bpm=120, authority="Original source clock", status="estimated")
+    assert ledger == Project(baseline, tmp_path).ledger(parse_lrc(lyrics))
+
+
+def test_excerpt_and_repeat_mapping_precedes_alignment_once(tmp_path):
+    data, _, _ = fixture(tmp_path)
+    data["audio"].update(start_sample=30000, end_sample=78000, repeats=2)
+    project = Project(data, tmp_path)
+    assert project.source_time(0) == 0.625
+    assert project.clock.pip_at(project.source_time(0)) == 64
+    assert project.clock.pip_at(project.source_time(60)) == 64
+    assert project.continuous_beat(60) == pytest.approx(project.continuous_beat(0) + 2)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [
+        {"source_sha256": "a" * 64},
+        {"exact_offset_pips": "-15"},
+        {"source_audio_verified": False},
+        {"first_beat_seconds": 4},
+        {"phase_status": "automatic"},
+        {"exact_bpm": "1e999"},
+    ],
+)
+def test_conflicting_readings_are_rejected(tmp_path, change):
+    data, reading, path = fixture(tmp_path)
+    reading.update(change)
+    write_json(path, reading)
+    data["clock"]["beat_alignment"]["sha256"] = sha256(path)
+    with pytest.raises(ValueError):
+        Project(data, tmp_path)
+
+
+@pytest.mark.parametrize(
+    "change",
+    [{"origin": 0}, {"beat_grid": {}}, {"bpm": 145}, {"status": "confirmed"}, {"phase_status": "confirmed"}],
+)
+def test_no_double_origin_or_authority_promotion(tmp_path, change):
+    data, _, _ = fixture(tmp_path)
+    data["clock"].update(change)
+    with pytest.raises(ValueError):
+        Project(data, tmp_path)
+
+
+def test_recording_clock_and_source_sample_bounds_remain_independent(tmp_path):
+    from dancerudiments_authoring.recording import Recording, RecordingClock, write_recording
+    from framerudiments.motion import Motion
+
+    data, _, _ = fixture(tmp_path)
+    project = Project(data, tmp_path)
+    recording = Recording(
+        "source_capture",
+        ("level",),
+        tuple((i / 511,) for i in range(512)),
+        RecordingClock(120, "synthetic source capture", "confirmed", 0, "supplied", 0),
+    )
+    path = tmp_path / "recording.json"
+    write_recording(path, recording)
+    motion = Motion(
+        dict(kind="recording", file=dict(path=str(path), sha256=sha256(path))), tmp_path, project.clock
+    )
+    assert motion.sample(0.5)[0] == pytest.approx(64 / 511)
+    assert project.clock.pip_at(0.5) == 48
+    wrong = copy.deepcopy(data)
+    wrong["audio"]["end_sample"] = 192001
+    with pytest.raises(ValueError, match="frame bounds"):
+        Project(wrong, tmp_path)