dancerudiments 0.2.4__tar.gz → 0.3.0__tar.gz

{dancerudiments-0.2.4 → dancerudiments-0.3.0}/.gitattributes

@@ -30,3 +30,10 @@ harness/beats.json text eol=lf
 # Keep original DanceFlow artwork byte-identical across platform packages.
 **/branding/*.svg text eol=lf
 **/branding/*.png binary
+
+# Recording WASM provenance hashes the actual C++ source bytes. Do not let
+# core.autocrlf turn these into CRLF on Windows; do not weaken the SHA tests.
+tools/recording_wasm.cpp text eol=lf
+include/dancerudiments/recording_view.hpp text eol=lf
+python/dancerudiments_authoring/harness_assets/recording.wasm.json text eol=lf
+python/dancerudiments_authoring/harness_assets/recording.wasm.b64 text eol=lf

dancerudiments-0.3.0/.github/workflows/recordings.yml

@@ -0,0 +1,55 @@
+name: Recording harness and native compatibility
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  recording-harness:
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    env:
+      DANCERUDIMENTS_REQUIRE_NATIVE: '1'
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.13'
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - name: Build and install actual native/authoring package
+        run: |
+          python -m pip install . playwright
+          python -m playwright install --with-deps chromium
+      - name: Check committed sampler/source hashes and shared package APIs
+        run: |
+          python -m unittest discover -s tests/python -p test_recording.py -v
+          python -m unittest discover -s tests/python -p test_harness_display.py -v
+      - name: Check unchanged beat-player contracts after moving shared assets
+        run: node --test tests/typescript/beat-player.test.js
+      - name: Rebuild the generic native recording accessor
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y clang lld
+          python tools/build_recording_wasm.py
+      - name: Native C++ recording and existing-pattern regressions
+        run: |
+          cmake -S . -B build-recordings -DCMAKE_BUILD_TYPE=Release
+          cmake --build build-recordings --parallel 2
+          ctest --test-dir build-recordings --output-on-failure
+      - name: Verify a freshly built recording page with real local-file loading
+        env:
+          PYTHONPATH: python
+        run: python tools/test_recording_harness.py recording-harness/index.html --make-fixture --screenshot recording-comparison.png
+      - uses: actions/upload-artifact@v6
+        if: always()
+        with:
+          name: native-recording-harness
+          path: |
+            recording-harness/
+            recording-comparison.png
+            recording-comparison-bars.png
+          if-no-files-found: warn

dancerudiments-0.3.0/AGENTS.md

@@ -0,0 +1,25 @@
+# Agent instructions for DanceRudiments
+
+- Read README.md, docs/ and the binding examples. Check the native catalogue, integer-pip timing, compositions and the C++, Python, WASM and C# bindings before adding a pattern or adapter.
+- Use the relevant existing capabilities as fully as the task warrants. Always look for a useful improvement to this tool. Fix a reusable gap here rather than copying its engine or carrying a private workaround; record why no change is justified when that is the result.
+- Submit improvements as PRs to https://github.com/kieransimkin/DanceRudiments/pulls. Never leave a completed reusable improvement only in a local fork. Keep changes focused and preserve the tool's identity and compatibility contracts.
+- Add relevant regression coverage, documentation and a reproducible example when behaviour changes. Use tools/release_version.py and tools/check_release_version.py. Run the native and relevant binding tests from .github/workflows/ before packaging.
+- Keep credentials, account data, private media and rights records out of source, fixtures, logs and packages. Use synthetic fixtures or explicitly authorised public examples and preserve their provenance/licences.
+- Use [CONTRIBUTING.md](CONTRIBUTING.md) for review. Maintainers publish accepted, validated improvements as a fresh matching GitHub release and verify configured registry destinations. Preserve existing tags and release assets; publication and deployment remain subject to applicable authorisation.
+- Website: https://kieransimkin.co.uk/danceflow/
+
+## Keep README documentation current
+
+- Whenever a feature is added or changed, update the relevant README.md in the same change to reflect the resulting behaviour. This applies to every feature addition or modification, including APIs, commands, configuration, defaults, integrations and removals.
+- Update affected feature descriptions, usage instructions, options, examples and limitations. For tools or packages with their own README.md, update that README as well as the repository README when its overview or usage is affected.
+- Check the README against the implemented and verified behaviour before committing, opening or merging a PR, publishing a release or handing off the work. A feature change is incomplete until its README documentation is current; a changelog or other documentation does not replace this requirement.
+
+## Released viewers and coordinated CI/CD
+
+- Read [docs/released-viewers.md](docs/released-viewers.md) before changing dependency, build or release behaviour. The sibling layout is `DanceRudiments/`, `react-timeline-sequence/`, and `stemlab/` under one parent.
+- Release the two companions first (React Timeline Sequence, then DanceRudiments), verify their configured publication workflows and public registries, then synchronize/rebuild/test/release StemLab. A merge or tag alone is not a verified release.
+- StemLab must target the **latest stable official releases**. No unreleased main commit, mutable development override, local `file:` archive or vendor package may substitute for a missing release. Latest is resolved before the build and locked to exact published versions, release commits and registry hashes for that run; fail visibly on stale or incompatible dependencies rather than falling back silently.
+- Use the canonical `stemlab/scripts/Release-DanceFlow.ps1` coordinator from the shared parent directory. Preview first; `-Execute` explicitly performs scoped commits, normal pushes and fresh tags; `-Resume` must preserve source identities and existing tags/assets. Never force-push, move release tags, commit unrelated work, bypass failed checks or change approvals/protections/credentials to manufacture a pass.
+- Update this repository's README.md and AGENTS.md in the same change whenever release policy, dependency rules, automation, commands, controls or validation change. Keep relevant package/feature READMEs current too. A separate guide or changelog does not replace the root README update.
+- Preserve the master-plus-drums/percussion beat-routing contract, 64-pips-per-beat native recording clock, per-dimension bars and combined waveform/spectrogram lanes. New UI features must be supplied by released shared APIs and genuinely rebuilt frontend assets, not copied engines or marker strings.
+- Distinguish source CI, package publication, full-song inference, browser/audio QA, artifact packaging, actual Pages deployment and live URL/audio verification. Keep all four Arcadians pages together; do not report unexecuted, skipped or older-commit checks as success. CI playback evidence is not subjective listening QA.

{dancerudiments-0.2.4 → dancerudiments-0.3.0}/CMakeLists.txt

@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.20)
-project(DanceRudiments VERSION 0.2.4
+project(DanceRudiments VERSION 0.3.0
   DESCRIPTION "Deterministic rhythmic position functions for DanceFlow. Music: https://kieransimkin.co.uk/my-songs/"
   HOMEPAGE_URL "https://kieransimkin.co.uk/my-songs/"
   LANGUAGES CXX)
@@ -59,6 +59,9 @@ endif()
 
 if(DANCERUDIMENTS_BUILD_TESTS)
   enable_testing()
+  add_executable(dancerudiments_recording_tests tests/cpp/test_recording.cpp)
+  target_link_libraries(dancerudiments_recording_tests PRIVATE DanceRudiments::DanceRudiments)
+  add_test(NAME dancerudiments_recordings COMMAND dancerudiments_recording_tests)
   add_executable(dancerudiments_tests tests/cpp/test_main.cpp)
   target_link_libraries(dancerudiments_tests PRIVATE DanceRudiments::DanceRudiments)
   add_test(NAME dancerudiments_cpp COMMAND dancerudiments_tests)

{dancerudiments-0.2.4 → dancerudiments-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dancerudiments
-Version: 0.2.4
+Version: 0.3.0
 Summary: Deterministic rhythmic position functions with C++, Python, TypeScript/WASM and C# bindings. https://kieransimkin.co.uk/my-songs/
 Author: Kieran Simkin
 License-Expression: MIT AND BSD-3-Clause AND CC0-1.0 AND CC-BY-4.0
@@ -42,7 +42,9 @@ Project website: [https://kieransimkin.co.uk/danceflow/](https://kieransimkin.co
 
 ## ▶ Try the pattern visualizer
 
-**[Download the self-contained visualizer — HTML](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)**
+**[▶ Open the movement visualiser](https://kieransimkin.github.io/DanceRudiments/)**
+
+[Download the self-contained HTML for offline use](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)
 
 Save the file and open it in a browser. **No install, server, CDN, soundfont or
 separate WASM file is required.** The complete 1,731-movement catalogue includes a
@@ -59,13 +61,13 @@ The downloadable file is the checked-in snapshot; the **Pattern visualizer**
 workflow also rebuilds a fresh version from every pushed native catalogue.
 [Beat player, rebuilding, release downloads and optional live hosting](docs/midi-harness.md).
 
-[![Four Amen-based movements compared in the real self-contained visualizer](https://raw.githubusercontent.com/kieransimkin/DanceRudiments/main/docs/images/visualizer-amen-desktop.png)](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)
+[![Four Amen-based movements compared in the real self-contained visualizer](https://raw.githubusercontent.com/kieransimkin/DanceRudiments/main/docs/images/visualizer-amen-desktop.png)](https://kieransimkin.github.io/DanceRudiments/)
 
 *Captured from the running C++/WebAssembly visualizer at beat 2.75. Audio was not started during this screenshot.*
 
 
 
-DanceRudiments is a C++17 library of deterministic rhythmic position functions. One integer pip is `1/64` of a beat. Built-in and custom patterns each keep their own loop period. Every sampler wraps positive or negative input into its own loop before sampling.
+DanceRudiments is a C++17 library of deterministic rhythmic position functions. One integer pip is `1/64` of a beat. Built-in and custom patterns each keep their own loop period. Every legacy pattern sampler wraps positive or negative input into its own loop before sampling.
 
 Outputs are dimensionless offsets, normally in `[-1, 1]`. The caller chooses pixels, CSS units, metres, or another scale. There is deliberately no time interpolation in the public API: renderers advance with integer pips and get one exact sample per pip.
 
@@ -105,6 +107,33 @@ python tools/build_default_catalogue.py --check
 The release workflow builds the complete native catalogue demo plus an offline,
 audio-enabled 68-rhythm / 16-mapping comparison page. All live motion comes from C++/WASM.
 
+## BPM-synchronised N-dimensional recordings and comparison harness
+
+The additive `dancerudiments.recording` format stores **any number of named
+float64 dimensions** at **64 pips per beat**, with a mandatory BPM estimate or
+confirmed value and separate beat-phase provenance. `SampledRecording` provides
+native non-looping C++/Python playback, including captures beyond the old
+65,535-pip loop length; existing XYZ patterns and their wrapping rules are unchanged.
+
+```python
+from dancerudiments_authoring import load_recording
+from dancerudiments_authoring.harness import build_recording_harness
+r = load_recording("output/recordings/audio_recording.json")
+values = r.to_native().sample(r.clock.start_pip)  # every dimension, real C++
+build_recording_harness([r], "output/index.html")
+```
+
+The exported page uses **the same packaged visualizer assets as catalogue/release
+pages**, with native WASM sampling, shared transport, four-card comparison and
+review import/export. Recording mode adds arbitrary-axis X/Y/Z selection, locked
+BPM/origin and non-looping completion. The tiny generic WASM sampler is bundled;
+no compiler or CDN is needed at export time. StemLab's `record-rudiment` and
+`generate-batch` produce individual or varied stem/filter combinations using this
+API without copying it. Music is not bundled unless explicitly requested.
+
+See **[recording format, harness, native API and compatibility](docs/recordings.md)**.
+Build the updated source to use this unreleased API; earlier releases lack it.
+
 ## Curve and event authoring
 
 The optional **Python authoring tools** compile LFOs, segmented curves, sampled
@@ -170,7 +199,7 @@ another movement implementation. The examples below are checked into
 | TypeScript / JavaScript | `catalogue` (an array, not a function) | `sample(name, pip)` after `bindNative()` | `info.periodPips` | Call the custom bank's `dispose()` |
 
 **One beat is 64 pips.** Supply a signed 32-bit integer, not milliseconds or a
-floating-point beat number. Every sampler wraps negative as well as positive
+floating-point beat number. Every legacy pattern sampler wraps negative as well as positive
 positions into its own loop. Offsets are `{x, y, z}`, dimensionless and bounded to
 `[-1, 1]`; choose the pixel/metre scale in your application. There is no automatic
 interpolation, BPM detection or audio playback inside a binding.
@@ -548,3 +577,56 @@ Apply an output to a bounded subject. DanceRudiments changes position only; it m
 ## Troubleshooting history
 
 See [build and release troubleshooting](docs/troubleshooting.md) for prior failures, causes and fixes.
+
+### Switch the shared visualizer between trajectories and bars
+
+Use **Movement view → X–Y plot / Bar graph**. Bar view uses the same native
+C++/WebAssembly sample and the existing clock, shows **every dimension** as a
+separate signed bar, and keeps comparison cards on one common scale. Switching
+views does not interrupt playback or change the underlying recording. The
+selection is local to your browser; long dimension sets scroll horizontally.
+This applies to catalogue/release pages and recording harnesses exported by
+StemLab. Rebuild old generated pages to include the control. See
+[recording visualizer controls](docs/recordings.md#trajectory-or-all-dimension-bars).
+
+
+## Coordinated releases and latest-release dependencies
+
+Keep `DanceRudiments`, `react-timeline-sequence`, and `stemlab` as sibling
+checkouts. The release order is **React Timeline Sequence → DanceRudiments →
+StemLab**: publish and verify the companions before updating the consuming app.
+StemLab must use their **latest stable official releases**, not an unreleased
+commit, sibling source package or vendored npm archive. Each build records exact
+released versions/commits/integrity after latest-release resolution so all its
+jobs use the same bytes; CI fails clearly when that snapshot is stale.
+
+From the parent folder, preview and then explicitly execute:
+
+```powershell
+.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot .
+.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot . -Execute
+```
+
+For the first migration use the same commands with
+`.\release-kit\Release-DanceFlow.ps1` after extracting the complete kit. It
+applies the three repository patches, updates versions, performs scoped commits
+and normal pushes, waits for exact-commit CI, then creates **new** release tags.
+The existing GitHub Actions workflows publish packages; no protection rules,
+credentials, old tags or assets are changed. The initial expected next-minor
+versions are only a preview proposal, never a claim that they are published.
+
+Use Node.js 24, Python 3.11+, PowerShell 5.1+, Git and authenticated GitHub CLI.
+Required main/registry/Pages jobs must pass; missing approvals and partial
+publication are blockers, not success. The default script releases all three
+projects, is opt-in via `-Execute`, and supports a saved exact-source `-Resume`
+session. A changed checkout or pre-commit build failure requires review rather
+than an automatic stash/reset or guessed recovery.
+
+StemLab's helper updates npm manifests/lock, optional native dependency minimum,
+release/build metadata and the genuinely rebuilt JS/CSS together. Its daily
+release-update workflow proposes subsequent updates by PR without auto-merging.
+A tagged StemLab release generates all four Arcadians pages and validates actual
+Pages deployment, live HTML and seekable audio. Do not start a duplicate manual
+Arcadians analysis during that tagged build. Read
+**[the full release, resume, verification and troubleshooting guide](docs/released-viewers.md)**
+before running it. Keep this README and AGENTS.md synchronized with future changes.

{dancerudiments-0.2.4 → dancerudiments-0.3.0}/README.md

@@ -24,7 +24,9 @@ Project website: [https://kieransimkin.co.uk/danceflow/](https://kieransimkin.co
 
 ## ▶ Try the pattern visualizer
 
-**[Download the self-contained visualizer — HTML](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)**
+**[▶ Open the movement visualiser](https://kieransimkin.github.io/DanceRudiments/)**
+
+[Download the self-contained HTML for offline use](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)
 
 Save the file and open it in a browser. **No install, server, CDN, soundfont or
 separate WASM file is required.** The complete 1,731-movement catalogue includes a
@@ -41,13 +43,13 @@ The downloadable file is the checked-in snapshot; the **Pattern visualizer**
 workflow also rebuilds a fresh version from every pushed native catalogue.
 [Beat player, rebuilding, release downloads and optional live hosting](docs/midi-harness.md).
 
-[![Four Amen-based movements compared in the real self-contained visualizer](https://raw.githubusercontent.com/kieransimkin/DanceRudiments/main/docs/images/visualizer-amen-desktop.png)](https://github.com/kieransimkin/DanceRudiments/raw/refs/heads/main/harness/index.html)
+[![Four Amen-based movements compared in the real self-contained visualizer](https://raw.githubusercontent.com/kieransimkin/DanceRudiments/main/docs/images/visualizer-amen-desktop.png)](https://kieransimkin.github.io/DanceRudiments/)
 
 *Captured from the running C++/WebAssembly visualizer at beat 2.75. Audio was not started during this screenshot.*
 
 
 
-DanceRudiments is a C++17 library of deterministic rhythmic position functions. One integer pip is `1/64` of a beat. Built-in and custom patterns each keep their own loop period. Every sampler wraps positive or negative input into its own loop before sampling.
+DanceRudiments is a C++17 library of deterministic rhythmic position functions. One integer pip is `1/64` of a beat. Built-in and custom patterns each keep their own loop period. Every legacy pattern sampler wraps positive or negative input into its own loop before sampling.
 
 Outputs are dimensionless offsets, normally in `[-1, 1]`. The caller chooses pixels, CSS units, metres, or another scale. There is deliberately no time interpolation in the public API: renderers advance with integer pips and get one exact sample per pip.
 
@@ -87,6 +89,33 @@ python tools/build_default_catalogue.py --check
 The release workflow builds the complete native catalogue demo plus an offline,
 audio-enabled 68-rhythm / 16-mapping comparison page. All live motion comes from C++/WASM.
 
+## BPM-synchronised N-dimensional recordings and comparison harness
+
+The additive `dancerudiments.recording` format stores **any number of named
+float64 dimensions** at **64 pips per beat**, with a mandatory BPM estimate or
+confirmed value and separate beat-phase provenance. `SampledRecording` provides
+native non-looping C++/Python playback, including captures beyond the old
+65,535-pip loop length; existing XYZ patterns and their wrapping rules are unchanged.
+
+```python
+from dancerudiments_authoring import load_recording
+from dancerudiments_authoring.harness import build_recording_harness
+r = load_recording("output/recordings/audio_recording.json")
+values = r.to_native().sample(r.clock.start_pip)  # every dimension, real C++
+build_recording_harness([r], "output/index.html")
+```
+
+The exported page uses **the same packaged visualizer assets as catalogue/release
+pages**, with native WASM sampling, shared transport, four-card comparison and
+review import/export. Recording mode adds arbitrary-axis X/Y/Z selection, locked
+BPM/origin and non-looping completion. The tiny generic WASM sampler is bundled;
+no compiler or CDN is needed at export time. StemLab's `record-rudiment` and
+`generate-batch` produce individual or varied stem/filter combinations using this
+API without copying it. Music is not bundled unless explicitly requested.
+
+See **[recording format, harness, native API and compatibility](docs/recordings.md)**.
+Build the updated source to use this unreleased API; earlier releases lack it.
+
 ## Curve and event authoring
 
 The optional **Python authoring tools** compile LFOs, segmented curves, sampled
@@ -152,7 +181,7 @@ another movement implementation. The examples below are checked into
 | TypeScript / JavaScript | `catalogue` (an array, not a function) | `sample(name, pip)` after `bindNative()` | `info.periodPips` | Call the custom bank's `dispose()` |
 
 **One beat is 64 pips.** Supply a signed 32-bit integer, not milliseconds or a
-floating-point beat number. Every sampler wraps negative as well as positive
+floating-point beat number. Every legacy pattern sampler wraps negative as well as positive
 positions into its own loop. Offsets are `{x, y, z}`, dimensionless and bounded to
 `[-1, 1]`; choose the pixel/metre scale in your application. There is no automatic
 interpolation, BPM detection or audio playback inside a binding.
@@ -530,3 +559,56 @@ Apply an output to a bounded subject. DanceRudiments changes position only; it m
 ## Troubleshooting history
 
 See [build and release troubleshooting](docs/troubleshooting.md) for prior failures, causes and fixes.
+
+### Switch the shared visualizer between trajectories and bars
+
+Use **Movement view → X–Y plot / Bar graph**. Bar view uses the same native
+C++/WebAssembly sample and the existing clock, shows **every dimension** as a
+separate signed bar, and keeps comparison cards on one common scale. Switching
+views does not interrupt playback or change the underlying recording. The
+selection is local to your browser; long dimension sets scroll horizontally.
+This applies to catalogue/release pages and recording harnesses exported by
+StemLab. Rebuild old generated pages to include the control. See
+[recording visualizer controls](docs/recordings.md#trajectory-or-all-dimension-bars).
+
+
+## Coordinated releases and latest-release dependencies
+
+Keep `DanceRudiments`, `react-timeline-sequence`, and `stemlab` as sibling
+checkouts. The release order is **React Timeline Sequence → DanceRudiments →
+StemLab**: publish and verify the companions before updating the consuming app.
+StemLab must use their **latest stable official releases**, not an unreleased
+commit, sibling source package or vendored npm archive. Each build records exact
+released versions/commits/integrity after latest-release resolution so all its
+jobs use the same bytes; CI fails clearly when that snapshot is stale.
+
+From the parent folder, preview and then explicitly execute:
+
+```powershell
+.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot .
+.\stemlab\scripts\Release-DanceFlow.ps1 -ProjectsRoot . -Execute
+```
+
+For the first migration use the same commands with
+`.\release-kit\Release-DanceFlow.ps1` after extracting the complete kit. It
+applies the three repository patches, updates versions, performs scoped commits
+and normal pushes, waits for exact-commit CI, then creates **new** release tags.
+The existing GitHub Actions workflows publish packages; no protection rules,
+credentials, old tags or assets are changed. The initial expected next-minor
+versions are only a preview proposal, never a claim that they are published.
+
+Use Node.js 24, Python 3.11+, PowerShell 5.1+, Git and authenticated GitHub CLI.
+Required main/registry/Pages jobs must pass; missing approvals and partial
+publication are blockers, not success. The default script releases all three
+projects, is opt-in via `-Execute`, and supports a saved exact-source `-Resume`
+session. A changed checkout or pre-commit build failure requires review rather
+than an automatic stash/reset or guessed recovery.
+
+StemLab's helper updates npm manifests/lock, optional native dependency minimum,
+release/build metadata and the genuinely rebuilt JS/CSS together. Its daily
+release-update workflow proposes subsequent updates by PR without auto-merging.
+A tagged StemLab release generates all four Arcadians pages and validates actual
+Pages deployment, live HTML and seekable audio. Do not start a duplicate manual
+Arcadians analysis during that tagged build. Read
+**[the full release, resume, verification and troubleshooting guide](docs/released-viewers.md)**
+before running it. Keep this README and AGENTS.md synchronized with future changes.

{dancerudiments-0.2.4 → dancerudiments-0.3.0}/bindings/csharp/DanceRudiments/DanceRudiments.csproj

@@ -2,7 +2,7 @@
   <!-- Kieran Simkin / DanceFlow: https://kieransimkin.co.uk/my-songs/ -->
   <PropertyGroup>
     <TargetFramework>net8.0</TargetFramework>
-    <Version>0.2.4</Version>
+    <Version>0.3.0</Version>
     <PackageId>DanceRudiments</PackageId>
     <Authors>Kieran Simkin</Authors>
     <Description>Deterministic rhythmic position functions with native C# bindings. Music: https://kieransimkin.co.uk/my-songs/</Description>

{dancerudiments-0.2.4 → dancerudiments-0.3.0}/bindings/python/module.cpp

@@ -3,6 +3,7 @@
 #include <utility>
 #include "dancerudiments/dance_rudiments.hpp"
 #include "dancerudiments/sampled_pattern.hpp"
+#include "dancerudiments/recording.hpp"
 
 namespace py = pybind11;
 using namespace dancerudiments;
@@ -11,6 +12,16 @@ using namespace pybind11::literals;
 PYBIND11_MODULE(dancerudiments, m) {
   m.doc() = "Integer-pip rhythmic position functions";
   m.attr("PIPS_PER_BEAT") = pips_per_beat;
+  py::class_<SampledRecording>(m, "SampledRecording")
+    .def(py::init<std::string, std::vector<std::string>, const std::vector<std::vector<double>>&, double, double, int>(),
+         py::arg("name"), py::arg("dimensions"), py::arg("samples"), py::arg("bpm"), py::arg("beat_zero_seconds")=0., py::arg("start_pip")=0)
+    .def_property_readonly("name", &SampledRecording::name)
+    .def_property_readonly("dimensions", &SampledRecording::dimensions)
+    .def_property_readonly("sample_count", &SampledRecording::sample_count)
+    .def_property_readonly("bpm", &SampledRecording::bpm)
+    .def_property_readonly("beat_zero_seconds", &SampledRecording::beat_zero_seconds)
+    .def_property_readonly("start_pip", &SampledRecording::start_pip)
+    .def("sample", &SampledRecording::sample, py::arg("pip").noconvert());
   py::class_<Offset3>(m, "Offset3")
     .def_readonly("x", &Offset3::x).def_readonly("y", &Offset3::y).def_readonly("z", &Offset3::z)
     .def("as_tuple", [](const Offset3& v) { return py::make_tuple(v.x, v.y, v.z); });

dancerudiments-0.3.0/docs/recordings.md

@@ -0,0 +1,196 @@
+# N-dimensional BPM-synchronised recordings and the shared visualizer
+
+This additive API represents **non-looping named dimensions**, sampled at **64
+pips per quarter-note beat**, with mandatory BPM provenance. It does not change
+`Offset3`, the built-in catalogue, existing XYZ compiled-pack schema, or legacy
+loop rules. Audio DSP remains in StemLab, not in this library.
+
+## Contract
+
+`dancerudiments.recording` schema 1 declares `sample_dtype: float64` and
+`sample_decimals: 12`. Components are finite, within [-1,1], and rounded to twelve
+decimal places. Native code checks the IEEE-754 binary64 contract. JSON numbers
+are not PCM audio samples with a 16/24-bit depth.
+
+Each recording requires a finite positive BPM, `bpm_status` (`estimated` or
+`confirmed`), and nonempty `bpm_source`. `phase_status` is separately `unverified`,
+`estimated` or `supplied`; confirming BPM does not confirm the beat origin.
+
+```
+time(i) = beat_zero_seconds + (start_pip + i) * 60 / (64 * bpm)
+```
+
+A row is one pip window/sample; `start_pip` may be negative. `RecordingClock`
+uses fractions derived from the decimal BPM instead of repeatedly rounded hops.
+The rate in seconds is 128 Hz at 120 BPM. This contract is constant-tempo, not a
+variable-tempo map; no default BPM, automatic beat detection or phase guessing.
+
+```json
+{
+  "format": "dancerudiments.recording",
+  "schema_version": 1,
+  "pips_per_beat": 64,
+  "sample_dtype": "float64",
+  "sample_decimals": 12,
+  "name": "four_axes",
+  "dimensions": ["bass", "treble", "drums", "vocals"],
+  "clock": {
+    "bpm": 145.0,
+    "bpm_status": "estimated",
+    "bpm_source": "artist estimate",
+    "beat_zero_seconds": 0.0,
+    "phase_status": "unverified",
+    "start_pip": 0
+  },
+  "samples": [[0.2, 0.6, 0.9, 0.1], [0.3, 0.4, 0.2, 0.7]],
+  "provenance": {"producer": "example"}
+}
+```
+
+Dimension identifiers are unique `[a-z][a-z0-9_]{0,127}` strings; every row has
+exactly their number of values, in the declared order. Unknown fields, malformed
+headers, ragged rows, non-finite data/metadata, duplicate JSON keys, missing BPM
+and invalid dimensions fail validation. At least one row/dimension is required.
+The resource guards are 8,388,608 scalar values and 64 MiB per JSON document,
+not a fixed XYZ dimension ceiling. Recordings can exceed 65,535 pips. Clock/index
+validation keeps recorded absolute pips representable by the native int API.
+
+## Python and C++ playback
+
+```python
+from dancerudiments_authoring import load_recording, write_recording
+r = load_recording("recordings/four_axes.json")
+write_recording("copy.json", r)  # refuses replacement unless explicitly requested
+native = r.to_native()  # real C++ SampledRecording, not a Python fallback
+values = native.sample(r.clock.start_pip)
+assert len(values) == len(r.dimensions)
+```
+
+`SampledRecording` owns and validates the data and returns **all dimensions**.
+An out-of-range absolute pip raises instead of looping. Name, dimensions, count,
+BPM, beat origin and first pip are readonly metadata. A moved-from object cannot
+be sampled. Data I/O is standard-library-only; Python native playback needs the
+updated extension, and raises clearly with an older/missing build.
+
+```cpp
+#include <dancerudiments/recording.hpp>
+using namespace dancerudiments;
+SampledRecording r("four_axes", {"bass","treble","drums","vocals"},
+                   {{.2,.6,.9,.1}, {.3,.4,.2,.7}}, 145.0, 0.0, 0);
+auto values = r.sample(1); // four doubles, non-looping
+```
+
+`recording_view.hpp` supplies the dependency-free `recording_component` accessor
+shared by this C++ object and the generic recording WASM. The browser does not
+regenerate mathematical curves or run a JavaScript motion fallback.
+
+## Generate the actual DanceRudiments comparison harness
+
+```python
+from pathlib import Path
+from dancerudiments_authoring.harness import build_recording_harness
+from dancerudiments_authoring import load_recording
+paths = sorted(Path("output/recordings").glob("*.json"))
+report = build_recording_harness((load_recording(p) for p in paths),
+                                  "output/index.html", collection_id="my-audio-batch")
+```
+
+All candidates must share the exact clock and captured extent; their dimension
+counts can differ. Input is consumed one recording at a time. Duplicate float64
+columns are pooled by checksum, retaining all samples without repeating the same
+stem/filter data for every candidate. Bounds are 1024 candidates and 128 MiB of
+unique binary sample columns. The audit JSON reports native WASM/data/page hashes,
+clock, counts, unique columns and byte size.
+
+The builder uses **the same template, CSS, beat player and app as release/catalogue
+pages**. Their former `tools/release_demo_assets` files now live under packaged
+`python/dancerudiments_authoring/harness_assets`; `tools/release_demo.py` delegates
+to this shared `render_template`. Do not create another renderer in StemLab.
+
+The page retains search, original four-card comparison, review choices/notes and
+review JSON import/download. Recording mode adds any-axis X/Y/Z projections and
+JSON download links for files under the sibling `recordings/` directory. It locks
+exported tempo/beat origin and stops at the end. Nothing autoplays. Paths are not
+closed across a non-looping seam. Display-decimated traces do not change full
+native samples. The exported JSON keeps axes not currently visible in the view.
+
+Optional `audio` metadata may include a **plain local basename** `relative_path`
+for a caller-copied track, plus its source hash and extent. The exporter does not
+copy or upload music. Without included audio, the existing local-file picker or
+silent transport can be used. Media playback uses the audio-element clock.
+Source codec/security support is a browser concern; do not disable browser policy
+to force loading. Review local storage is best-effort; download JSON for portability.
+
+All HTML/JS/CSS, native WASM and sampled columns are embedded. No compiler/CDN or
+external request is required to build/use a recording page. Keep any optional
+media and recording JSON companions with the HTML for their controls to work.
+The page is control-data inspection, not proof of comfortable full-body choreography.
+
+## Rebuilding the tiny generic native sampler
+
+```sh
+python tools/build_recording_wasm.py
+```
+
+This uses clang++/wasm-ld, targets freestanding wasm32, and stores base64 bytes plus
+source/binary hashes in packaged assets. Rebuild when `recording_view.hpp` or
+`tools/recording_wasm.cpp` changes. Normal exports verify the bundled WASM checksum;
+end users need no compiler. CI rebuilds and checks for a stale committed asset.
+The existing catalogue export still follows its original native snapshot workflow.
+
+## Explicit legacy XYZ conversion
+
+```python
+from pathlib import Path
+from dancerudiments_authoring import emit_json
+pack = r.to_compiled_pack(dimensions=("bass", "treble"), start=0, count=2)
+Path("xy.compiled.json").write_text(emit_json(pack), encoding="utf-8")
+```
+
+Select 1..3 axes and at most 65,535 samples; missing XYZ components become zero.
+A larger recording requires explicit axis/excerpt selection, never truncation.
+The legacy sampler loops, so conversion retains a seam warning and source clock;
+it does not smooth/close an arbitrary excerpt. The new native recording API does
+not loop. Existing C#/TypeScript XYZ interfaces remain unchanged; this addition
+provides N-D C++/Python and the recording harness, not new general N-D wrappers
+for all languages.
+
+## Validation
+
+```sh
+PYTHONPATH=python python -m unittest discover -s tests/python -p test_recording.py -v
+cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
+cmake --build build --config Release
+ctest --test-dir build -C Release --output-on-failure
+node --test tests/typescript/beat-player.test.js
+python tools/test_recording_harness.py ./test-harness/index.html --make-fixture
+```
+
+Browser testing requires Playwright/Chromium. Normal mode tests local-file loading;
+`--in-memory` is an explicitly labelled fallback only for restricted environments.
+With copied audio, that fallback hydrates the exact bytes into the existing audio
+element as a Blob, retaining actual decoding/transport/renderer/native WASM. Its
+report does not claim file loading or audible listening QA. The checker samples
+every candidate against retained JSON and tests transport, arbitrary-axis
+projection, non-looping bounds, no autoplay, search/comparison and review download.
+Set `DANCERUDIMENTS_REQUIRE_NATIVE=1` to reject missing native tests rather than skip.
+
+Existing versions/tags are unchanged by this patch. Publish a fresh matching
+release only after review and CI. This source API is not present in earlier
+published packages.
+
+## Trajectory or all-dimension bars
+
+The shared harness has a **Movement view** selector. X–Y plot is the default and
+retains its existing selectable X/Y/Z projection. **Bar graph** draws one
+signed bar for every recorded dimension (X/Y/Z for native catalogue patterns),
+not just the selected projection. Positive values extend above zero and negative
+values below it. The numerical value is the actual native sample; the existing
+amplitude slider scales the geometry only. All bars share the same fixed scale.
+Long channel sets scroll horizontally; no channels are silently dropped.
+
+The selector affects catalogue and comparison cards without seeking, pausing,
+changing the selected MIDI beat, changing review choices or rewriting recordings.
+It is remembered per collection when browser storage is available. Offscreen bars
+are released and reconstructed on demand, just like the existing canvas cache.
+Rebuild exported HTML to get a new UI: already-published snapshots are immutable.