audio-as-code 0.1.0__tar.gz → 0.2.0__tar.gz

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/.github/scripts/check_distribution.py

@@ -98,6 +98,11 @@ REQUIRED_SOURCE = {
     "src/audio_as_code/_voices.py",
     "src/audio_as_code/_export_rules.py",
     "src/audio_as_code/_orchestra_profiles.py",
+    "src/audio_as_code/arrangement.py",
+    "src/audio_as_code/project_setup.py",
+    "src/audio_as_code/loudness.py",
+    "src/audio_as_code/_render_control.py",
+    "src/audio_as_code/_cli_progress.py",
     "pyproject.toml",
     "uv.lock",
     "README.md",
@@ -113,6 +118,10 @@ REQUIRED_SOURCE = {
     "docs/render-performance.md",
     "docs/cloudflare-hosting.md",
     "docs/releasing.md",
+    "docs/project-setup.md",
+    "docs/arrangement.md",
+    "docs/articulations.md",
+    "docs/production-output.md",
     "schemas/song-v1.schema.json",
     "examples/first_light.py",
     "examples/classic_showcase.py",
@@ -173,9 +182,15 @@ def check_metadata(data: bytes, expected_version: str) -> None:
     if (metadata["License-Expression"] or metadata["License"]) != "MIT":
         raise ValueError("MIT license metadata is missing")
     requirements = metadata.get_all("Requires-Dist", [])
-    names = {re.split(r"[<>=!~;\s\[]", item, maxsplit=1)[0].lower() for item in requirements}
+    required = [item for item in requirements if "extra ==" not in item]
+    optional = [item for item in requirements if "extra ==" in item]
+    names = {re.split(r"[<>=!~;\s\[]", item, maxsplit=1)[0].lower() for item in required}
     if names != {"numpy", "pydantic", "mido"} or any("@" in item for item in requirements):
         raise ValueError("Runtime dependencies changed or contain nonportable direct URLs")
+    if metadata.get_all("Provides-Extra", []) != ["loudness"] or [
+        item.replace('"', "'") for item in optional
+    ] != ["pyloudnorm<0.3,>=0.2; extra == 'loudness'"]:
+        raise ValueError("Unexpected optional dependency metadata")
 
 
 def check_wheel(path: Path, expected_version: str) -> dict:
@@ -206,6 +221,17 @@ def check_wheel(path: Path, expected_version: str) -> dict:
                 "_voices.py",
                 "_export_rules.py",
                 "_orchestra_profiles.py",
+                "arrangement.py",
+                "project_setup.py",
+                "loudness.py",
+                "_render_control.py",
+                "_cli_progress.py",
+                "_project_templates/compose.py.txt",
+                "_project_templates/score.json",
+                "_project_templates/README.md.txt",
+                "_project_templates/AGENTS.md.txt",
+                "_project_templates/pyproject.toml.txt",
+                "_project_templates/gitignore.txt",
                 "py.typed",
             )
         }

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/.github/scripts/smoke_installed.py

@@ -7,6 +7,7 @@ import subprocess
 import sys
 import tempfile
 from importlib.metadata import distribution
+from importlib.util import find_spec
 from pathlib import Path
 
 import audio_as_code
@@ -40,6 +41,27 @@ def main() -> None:
             )
             assert json.loads(version.stdout) == {"version": metadata.version}
             subprocess.run([*command, "--help"], cwd=work, capture_output=True, check=True)
+        health = subprocess.run(
+            [str(console), "doctor"], cwd=work, capture_output=True, text=True, check=True
+        )
+        assert json.loads(health.stdout)["ok"] and not health.stderr
+        starter = work / "composition project"
+        initialized = subprocess.run(
+            [str(console), "init", str(starter)],
+            cwd=work,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        assert len(json.loads(initialized.stdout)["files"]) == 6
+        assert f"audio-as-code=={metadata.version}" in (starter / "pyproject.toml").read_text()
+        subprocess.run(
+            [sys.executable, str(starter / "compose.py")],
+            cwd=work,
+            capture_output=True,
+            check=True,
+        )
+        assert (starter / "output" / "song.wav").is_file()
         phrase = Pattern.sequence(["C4"], step=0.25)
         phrase = phrase.overlay(phrase.transpose(12), offset=0.25).stretch(2).scale_velocity(0.5)
         song = Song(
@@ -69,6 +91,48 @@ def main() -> None:
         export_midi(song, work / "score.mid")
         assert report["wav"] == analyze_wav(work / "score.wav")
         assert not report["wav"]["silent"] and not report["wav"]["full_scale_samples"]
+        preview = subprocess.run(
+            [
+                str(console),
+                "preview",
+                str(score),
+                "-o",
+                str(work / "preview.wav"),
+                "--start",
+                "0.1",
+                "--duration",
+                "0.2",
+                "--format",
+                "float32",
+                "--progress-file",
+                str(work / "progress.jsonl"),
+            ],
+            cwd=work,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        assert json.loads(preview.stdout)["wav"]["wav_format"] == "float32"
+        assert not preview.stderr
+        assert (work / "progress.jsonl").read_text().strip()
+        if find_spec("pyloudnorm") is None:
+            missing = subprocess.run(
+                [
+                    str(console),
+                    "render",
+                    str(score),
+                    "-o",
+                    str(work / "optional.wav"),
+                    "--target-lufs",
+                    "-18",
+                ],
+                cwd=work,
+                capture_output=True,
+                text=True,
+            )
+            assert missing.returncode == 2 and not missing.stdout
+            assert "optional extra" in json.loads(missing.stderr)["message"]
+            assert not (work / "optional.wav").exists()
         validation = subprocess.run(
             [str(console), "validate", str(score)],
             cwd=work,

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/.github/workflows/ci.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 5
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
       - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
@@ -37,29 +37,34 @@ jobs:
     runs-on: ${{ matrix.os }}
     timeout-minutes: 20
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           python-version: ${{ matrix.python }}
           version: '0.12.15'
+          prune-cache: true
       - run: uv sync --locked
       - name: Schema stays in sync with the score model
         run: uv run --locked python .github/scripts/check_schema.py
       - run: uv run --locked pytest
+      - name: Optional loudness backend
+        if: matrix.os == 'ubuntu-latest' && matrix.python == '3.13'
+        run: uv run --locked --extra loudness pytest tests/test_loudness.py tests/test_production_output.py tests/test_production_cli.py -W error
 
   distribution:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           python-version: '3.13'
           version: '0.12.15'
+          prune-cache: true
       - run: uv sync --locked
       - run: uv run --locked ruff check .
       - run: uv run --locked ruff format --check .

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/.github/workflows/publish.yml

@@ -22,13 +22,14 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           python-version: '3.13'
           version: '0.12.15'
+          prune-cache: true
       - run: uv sync --locked
       - name: Check the requested version against both source declarations
         env:
@@ -90,13 +91,14 @@ jobs:
     permissions:
       contents: read
     steps:
-      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
-      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+      - uses: astral-sh/setup-uv@c18668ad3cf93ea998bef934396af7bb5c839dc7 # v10.2.0
         with:
           python-version: '3.13'
           version: '0.12.15'
+          prune-cache: true
       - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
         with:
           name: pypi-distributions

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/CHANGELOG.md

@@ -1,13 +1,38 @@
 # Changelog
 
-This project is an unpublished prototype. `0.1.0` identifies the current development
-baseline; it is not a claim that a package or tagged release exists. Changes below
-are unreleased. Package versions and score schema versions are separate.
+Audio as Code is an early prototype. Package versions and score schema versions
+are separate.
 
 ## Unreleased
 
 ### Added
 
+- `aac init` creates an editable composition project from installed wheel resources;
+  `aac doctor` checks the active runtime with a short local synthesis probe.
+- Tempo-aware timestamp cues, named section replacement and repeated loop previews
+  with boundary measurements through the Python arrangement helpers.
+- Optional `soft` and `accented` note/track articulations for 13 bowed-string and
+  wind voices, with shaped harmonic attacks and releases. Existing unarticulated
+  scores retain their deterministic audio and score hashes.
+- PCM24 and float32 WAV export, full-context excerpt previews, progress callbacks,
+  cooperative cancellation and staged audio publication. CLI progress uses a
+  separate JSON Lines file.
+- Optional `loudness` extra for BS.1770-4 integrated measurement and constant-gain
+  targeting with a sample-peak ceiling. It does not measure or limit true peak.
+
+### Changed
+
+- Documented versioned PyPI installation alongside the source workspace and pinned
+  Git routes. These onboarding updates follow the 0.1.0 package release.
+- HTML responses allow compression after disabling the Cloudflare RUM injection;
+  post-deployment checks still verify that no beacon is added.
+
+## 0.1.0 — 2026-10-03
+
+Initial release on [PyPI](https://pypi.org/project/audio-as-code/0.1.0/).
+
+### Added
+
 - Website sitemap, canonical page URLs, structured project metadata, social
   previews, and full plain-text agent documentation alongside `llms.txt`.
 

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/CONTRIBUTING.md

@@ -58,6 +58,8 @@ CLI entry points, including the normal error path. These checks do not publish.
 
 CI runs the tests and schema check on Python 3.10 and 3.13 on Linux/Windows, and
 3.13 on macOS. A separate job checks lint, formatting, and installed artifacts.
+The Linux Python 3.13 job also tests the optional loudness backend. For changes
+to that path, run `uv run --extra loudness pytest tests/test_loudness.py -W error`.
 Report checks you could not run; do not label an unrun audition or CI job as passed.
 
 For website hosting changes, install Node.js 24 and run the hosting checks from

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: audio-as-code
-Version: 0.1.0
+Version: 0.2.0
 Summary: An agent-friendly music score, composition toolkit, and offline renderer.
 Project-URL: Homepage, https://audioascode.com
 Project-URL: Repository, https://github.com/joaoCarvalho1000/audio-as-code
@@ -24,6 +24,8 @@ Requires-Python: >=3.10
 Requires-Dist: mido<2,>=1.3
 Requires-Dist: numpy<3,>=1.24
 Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: loudness
+Requires-Dist: pyloudnorm<0.3,>=0.2; extra == 'loudness'
 Description-Content-Type: text/markdown
 
 # Audio as Code
@@ -38,7 +40,7 @@ then carry the rendered WAV into your video, game or slides. See the
 [creative workflow integrations](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/integrations.md) for Codex, Claude Code
 and Hyperframes recipes.
 
-**Status: working 0.1 prototype.** Python 3.10+, a versioned JSON score, a headless CLI, and an offline synthesis backend. No API keys, audio device, model weights, sample downloads, or DAW are required.
+**Status: 0.2.0 alpha, [available on PyPI](https://pypi.org/project/audio-as-code/0.2.0/).** Python 3.10+, a versioned JSON score, a headless CLI, and an offline synthesis backend. No API keys, audio device, model weights, sample downloads, or DAW are required.
 
 A **score** is the editable recipe for a piece: instruments, notes, timing,
 volume and tempo. Write it in Python or JSON; rendering turns it into audio.
@@ -91,17 +93,31 @@ To browse and audition the catalog, run `uv run python examples/instrument_brows
 For a coding agent, start with: **“Read https://audioascode.com/llms.txt and add
 Audio as Code to this project. Then compose the music in my brief.”**
 
-To add it to an existing uv project with Git installed:
+To add version 0.2.0 to an existing uv project:
 
 ```sh
-uv add "audio-as-code @ git+https://github.com/joaoCarvalho1000/audio-as-code.git"
+uv add "audio-as-code==0.2.0"
 uv run --locked aac instruments
 uv run --locked aac schema
 ```
 
-Commit your project's `uv.lock` to preserve the resolved Git revision and
-dependency versions. See the [quickstart](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/quickstart.md) for a first
-composition and the standalone source-workspace route below.
+Commit your project's `uv.lock` to preserve the package and dependency versions.
+For a new composition project, run `uvx --from audio-as-code==0.2.0 aac init my-soundtrack`,
+then `cd my-soundtrack`, `uv sync`, `uv run aac doctor` and `uv run python compose.py`.
+The starter includes an editable composer, JSON score and agent instructions.
+
+For a one-off CLI check, run `uvx --from audio-as-code==0.2.0 aac --help`.
+The package contains the Python library and CLI. Use a source checkout or the
+website's source ZIP for the complete examples, guides and portable skill.
+
+Without uv, create a local environment with `python -m venv .venv`. On Windows,
+run `.venv/Scripts/python.exe -m pip install audio-as-code==0.2.0`; on macOS/Linux,
+run `.venv/bin/python -m pip install audio-as-code==0.2.0`. Use that interpreter
+with `-m audio_as_code --help`; no activation or global installation is needed.
+
+The [quickstart](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/quickstart.md)
+also covers first compositions and installation from a pinned Git revision.
+The standalone source-workspace route follows below.
 
 For complete video, game-loop and presentation examples with exact durations and
 verified revisions, see [creative workflows](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/creative-workflows.md).
@@ -270,6 +286,18 @@ render(song, "output/string.wav")
 
 Brightness and decay work on the modeled decaying voices. Pluck position is available on plucked-string models and harpsichord. Held voices expose selected breath/vibrato controls; `aac instruments` reports each voice's supported settings and defaults. Velocity changes loudness and model brightness. By default notes fade within their score duration. Optional note/track `release_seconds` lets a sound ring after note-off. Ordered `tempo_map` steps, gain/pan automation, and procedural delay/reverb chains add expression; see the [composition guide](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/composition.md).
 
+Use [arrangement helpers](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/arrangement.md)
+to place cues by seconds across tempo changes, replace named sections and measure
+repeated loop previews. Section names remain outside the version 1 score JSON.
+Thirteen bowed-string and wind voices support optional `soft` and `accented`
+[articulations](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/articulations.md).
+Existing scores keep their sound and score identity when these controls are omitted.
+
+[Production output](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/production-output.md)
+adds higher-resolution WAV, exact-context excerpts, progress callbacks and
+cooperative cancellation. Install `audio-as-code[loudness]` for optional integrated
+LUFS targeting with a sample-peak ceiling. There is no true-peak limiter.
+
 ## An agent's working loop
 
 1. Read the schema, discover available voices with `aac instruments`, and choose tempo, harmony, rhythm, and arrangement.
@@ -296,7 +324,7 @@ can report an export blocker, so check its readiness fields.
 
 ## Rendering and export
 
-- WAV: 16-bit stereo PCM, synthesized offline in memory. The prototype limits each render, including release/effect tails, to five minutes. A five-minute render can consume hundreds of MB of RAM; shorter previews are preferable in agent loops.
+- WAV: stereo PCM16 by default, with explicit PCM24 and float32 exports. Rendering happens offline in memory and is limited to five minutes including tails. Excerpt previews preserve full-song context and still cost a full render; compose shorter test scores to reduce iteration time.
 - Default normalization only reduces gain when the mix exceeds a 0.95 peak ceiling. It never increases a quiet mix. `--no-normalize` preserves mix gain and hard-clips values outside full scale on WAV export; the report exposes this.
 - Stems include track gain, pan, master gain, and the same attenuation applied to the mix. They approximately reconstruct the mix within PCM rounding when there are no master effects and no individual stem clips. Stems include track effects but omit master effects, with a warning when the mix uses them. Numeric filenames avoid interpreting track names as paths.
 - MIDI: type 1, 480 ticks per quarter note, tempo, track names, programs, volume, and pan. Up to 15 melodic tracks and one track per drum instrument. Overlapping notes of the same pitch on one channel are rejected, including collisions between a drum kit and an individual drum. Quantization can differ from WAV timing by a MIDI tick.
@@ -309,14 +337,14 @@ can report an export blocker, so check its readiness fields.
 
 The framework's instrument direction is sound generated from code. The score is the extension boundary for more detailed physical models. Proposed next steps:
 
-- Named clips and sections, continuous tempo ramps, and arrangement edits.
+- Continuous tempo ramps, variable-length arrangement edits and clip scheduling.
 - Coupled string/body, nonlinear reed/bore, and bow-friction models beyond the current approximations.
 - Half-pedaling, instrument articulation switches, and more expression controls.
 - An MCP server wrapping the existing validate/render/analyze operations.
-- Richer analysis, preview excerpts, and agent-assisted audition workflows.
+- Faster bounded previews, true-peak analysis and agent-assisted audition workflows.
 - Streaming renders, real-time playback, and a browser editor.
 
-These are roadmap items, not implemented features. The 0.1 API may change; score schema changes will use an explicit version.
+These are roadmap items, not implemented features. The 0.2 API may change; score schema changes will use an explicit version.
 
 Related projects worth exploring: [Strudel](https://strudel.cc/), [Sonic Pi](https://sonic-pi.net/), and [SCAMP](https://www.scamp.marcevanstein.com/). This prototype uses its own small score and synthesis implementation; it does not wrap those engines.
 

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/README.md

@@ -10,7 +10,7 @@ then carry the rendered WAV into your video, game or slides. See the
 [creative workflow integrations](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/integrations.md) for Codex, Claude Code
 and Hyperframes recipes.
 
-**Status: working 0.1 prototype.** Python 3.10+, a versioned JSON score, a headless CLI, and an offline synthesis backend. No API keys, audio device, model weights, sample downloads, or DAW are required.
+**Status: 0.2.0 alpha, [available on PyPI](https://pypi.org/project/audio-as-code/0.2.0/).** Python 3.10+, a versioned JSON score, a headless CLI, and an offline synthesis backend. No API keys, audio device, model weights, sample downloads, or DAW are required.
 
 A **score** is the editable recipe for a piece: instruments, notes, timing,
 volume and tempo. Write it in Python or JSON; rendering turns it into audio.
@@ -63,17 +63,31 @@ To browse and audition the catalog, run `uv run python examples/instrument_brows
 For a coding agent, start with: **“Read https://audioascode.com/llms.txt and add
 Audio as Code to this project. Then compose the music in my brief.”**
 
-To add it to an existing uv project with Git installed:
+To add version 0.2.0 to an existing uv project:
 
 ```sh
-uv add "audio-as-code @ git+https://github.com/joaoCarvalho1000/audio-as-code.git"
+uv add "audio-as-code==0.2.0"
 uv run --locked aac instruments
 uv run --locked aac schema
 ```
 
-Commit your project's `uv.lock` to preserve the resolved Git revision and
-dependency versions. See the [quickstart](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/quickstart.md) for a first
-composition and the standalone source-workspace route below.
+Commit your project's `uv.lock` to preserve the package and dependency versions.
+For a new composition project, run `uvx --from audio-as-code==0.2.0 aac init my-soundtrack`,
+then `cd my-soundtrack`, `uv sync`, `uv run aac doctor` and `uv run python compose.py`.
+The starter includes an editable composer, JSON score and agent instructions.
+
+For a one-off CLI check, run `uvx --from audio-as-code==0.2.0 aac --help`.
+The package contains the Python library and CLI. Use a source checkout or the
+website's source ZIP for the complete examples, guides and portable skill.
+
+Without uv, create a local environment with `python -m venv .venv`. On Windows,
+run `.venv/Scripts/python.exe -m pip install audio-as-code==0.2.0`; on macOS/Linux,
+run `.venv/bin/python -m pip install audio-as-code==0.2.0`. Use that interpreter
+with `-m audio_as_code --help`; no activation or global installation is needed.
+
+The [quickstart](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/quickstart.md)
+also covers first compositions and installation from a pinned Git revision.
+The standalone source-workspace route follows below.
 
 For complete video, game-loop and presentation examples with exact durations and
 verified revisions, see [creative workflows](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/creative-workflows.md).
@@ -242,6 +256,18 @@ render(song, "output/string.wav")
 
 Brightness and decay work on the modeled decaying voices. Pluck position is available on plucked-string models and harpsichord. Held voices expose selected breath/vibrato controls; `aac instruments` reports each voice's supported settings and defaults. Velocity changes loudness and model brightness. By default notes fade within their score duration. Optional note/track `release_seconds` lets a sound ring after note-off. Ordered `tempo_map` steps, gain/pan automation, and procedural delay/reverb chains add expression; see the [composition guide](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/site/composition.md).
 
+Use [arrangement helpers](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/arrangement.md)
+to place cues by seconds across tempo changes, replace named sections and measure
+repeated loop previews. Section names remain outside the version 1 score JSON.
+Thirteen bowed-string and wind voices support optional `soft` and `accented`
+[articulations](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/articulations.md).
+Existing scores keep their sound and score identity when these controls are omitted.
+
+[Production output](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/docs/production-output.md)
+adds higher-resolution WAV, exact-context excerpts, progress callbacks and
+cooperative cancellation. Install `audio-as-code[loudness]` for optional integrated
+LUFS targeting with a sample-peak ceiling. There is no true-peak limiter.
+
 ## An agent's working loop
 
 1. Read the schema, discover available voices with `aac instruments`, and choose tempo, harmony, rhythm, and arrangement.
@@ -268,7 +294,7 @@ can report an export blocker, so check its readiness fields.
 
 ## Rendering and export
 
-- WAV: 16-bit stereo PCM, synthesized offline in memory. The prototype limits each render, including release/effect tails, to five minutes. A five-minute render can consume hundreds of MB of RAM; shorter previews are preferable in agent loops.
+- WAV: stereo PCM16 by default, with explicit PCM24 and float32 exports. Rendering happens offline in memory and is limited to five minutes including tails. Excerpt previews preserve full-song context and still cost a full render; compose shorter test scores to reduce iteration time.
 - Default normalization only reduces gain when the mix exceeds a 0.95 peak ceiling. It never increases a quiet mix. `--no-normalize` preserves mix gain and hard-clips values outside full scale on WAV export; the report exposes this.
 - Stems include track gain, pan, master gain, and the same attenuation applied to the mix. They approximately reconstruct the mix within PCM rounding when there are no master effects and no individual stem clips. Stems include track effects but omit master effects, with a warning when the mix uses them. Numeric filenames avoid interpreting track names as paths.
 - MIDI: type 1, 480 ticks per quarter note, tempo, track names, programs, volume, and pan. Up to 15 melodic tracks and one track per drum instrument. Overlapping notes of the same pitch on one channel are rejected, including collisions between a drum kit and an individual drum. Quantization can differ from WAV timing by a MIDI tick.
@@ -281,14 +307,14 @@ can report an export blocker, so check its readiness fields.
 
 The framework's instrument direction is sound generated from code. The score is the extension boundary for more detailed physical models. Proposed next steps:
 
-- Named clips and sections, continuous tempo ramps, and arrangement edits.
+- Continuous tempo ramps, variable-length arrangement edits and clip scheduling.
 - Coupled string/body, nonlinear reed/bore, and bow-friction models beyond the current approximations.
 - Half-pedaling, instrument articulation switches, and more expression controls.
 - An MCP server wrapping the existing validate/render/analyze operations.
-- Richer analysis, preview excerpts, and agent-assisted audition workflows.
+- Faster bounded previews, true-peak analysis and agent-assisted audition workflows.
 - Streaming renders, real-time playback, and a browser editor.
 
-These are roadmap items, not implemented features. The 0.1 API may change; score schema changes will use an explicit version.
+These are roadmap items, not implemented features. The 0.2 API may change; score schema changes will use an explicit version.
 
 Related projects worth exploring: [Strudel](https://strudel.cc/), [Sonic Pi](https://sonic-pi.net/), and [SCAMP](https://www.scamp.marcevanstein.com/). This prototype uses its own small score and synthesis implementation; it does not wrap those engines.
 

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/docs/agents.md

@@ -2,11 +2,25 @@
 
 Start with the [portable composition skill](../skills/audio-as-code/SKILL.md).
 It covers setup, interpreting a musical brief, composing, rendering, checking,
-delivering files, and revisions. Give your agent this checkout (or the website's
-source ZIP) and say:
+delivering files, and revisions. Add the released library to an existing uv project:
+
+```sh
+uv add "audio-as-code==0.2.0"
+uv run --locked aac instruments
+uv run --locked aac schema
+```
+
+Keep the project's lockfile. The package contains the engine and CLI; get the
+portable skill and complete examples from the source checkout or website's source
+ZIP. See the [quickstart](site/quickstart.md) for pip and pinned Git alternatives.
+For a new composition workspace, the installed CLI can scaffold one with
+`aac init "my music"`; run `aac doctor` to check its imported runtime. Init does
+not install dependencies or overwrite a nonempty directory. See
+[project setup](project-setup.md).
+Give your agent the skill and say:
 
 ```text
-Read skills/audio-as-code/SKILL.md in the Audio as Code source folder and use it
+Read the Audio as Code skill and use the installed dependency in this project
 to create an original 30-second hopeful instrumental for piano, marimba and bass.
 Build a memorable motif, vary the second phrase, and finish with a clear cadence.
 Set up locally, validate and render, then deliver WAV, MIDI, editable score,
@@ -38,6 +52,8 @@ The CLI is the initial agent integration. Call it through your existing shell to
 | Operation | Command | JSON response |
 | --- | --- | --- |
 | Identify engine | `aac --version` | Engine version |
+| Start a project | `aac init "my music"` | Output directory, created filenames and next steps |
+| Check setup | `aac doctor` | `ok`, per-check results and recovery hints |
 | Discover playable voices | `aac instruments` | Families, engines, available voices, controls, MIDI mappings |
 | Inspect a family | `aac instruments --all --family woodwinds` | Catalog entries with explicit availability status |
 | Discover score shape | `aac schema` | JSON Schema |
@@ -45,18 +61,22 @@ The CLI is the initial agent integration. Call it through your existing shell to
 | Check score | `aac validate song.json` | Validity, tempo, length, track/note counts |
 | Inspect before rendering | `aac inspect song.json` | Per-track timing, pitches, polyphony, export readiness and structured issues |
 | Render | `aac render song.json -o song.wav --report report.json` | Render metadata, measurements, warnings |
+| Preview excerpt | `aac preview song.json -o excerpt.wav --start 12 --duration 8` | Excerpt report with full-render context; costs a complete render |
 | Render stems | `aac render song.json -o song.wav --stems stems` | Same report plus track-to-file mapping |
+| Production WAV | `aac render song.json -o song.wav --format pcm24` | 24-bit PCM report; `float32` is also available |
+| Target loudness | `aac render song.json -o song.wav --target-lufs -18` | Optional `loudness` report; requires the `loudness` extra |
+| Live progress | `aac render song.json -o song.wav --progress-file progress.jsonl` | JSON Lines progress in the file; one final JSON object on stdout |
 | Export | `aac midi song.json -o song.mid` | MIDI path, duration, export warnings |
 | Check audio | `aac analyze song.wav` | Signal measurements |
 
 MIDI warnings describe features present in the score, such as tone controls,
 percussion or effects. The receiver determines instrument sound in every MIDI export.
 
-When running from the source checkout, first run `uv sync --locked`, then prefix
-commands with `uv run`. `uv run python -m audio_as_code` is an equivalent entry
-point. The package is not published to PyPI; use the local checkout. Commands
-need no network after installation. Run from the checkout root, or invoke the
-installed environment's Python by its absolute path.
+In a uv project, prefix commands with `uv run --locked`;
+`uv run --locked python -m audio_as_code` is an equivalent entry point. For a
+source checkout, run `uv sync --locked` first and work from its root. With pip,
+invoke the local environment's Python with `-m audio_as_code`. Commands need no
+network after installation.
 
 Output files are replaced if they already exist. Input score, output audio,
 report, and stem filenames must be distinct, including symlink and existing
@@ -125,7 +145,8 @@ Pass arguments as an array and avoid `shell=True`. Resolve relative score and
 output paths against your chosen working directory. A missing executable,
 process timeout, or termination is a process-level failure; it does not promise
 a JSON diagnostic. Set a larger timeout for renders based on score length and
-voice complexity. Start with short previews to bound memory and iteration time.
+voice complexity. Compose shorter candidate scores to bound iteration time;
+`aac preview` crops a full render, so a short excerpt is not cheaper to synthesize.
 
 Keep discovery separate from rendering: `aac instruments` returns playable
 voices, `aac instruments --all` can also describe planned voices, and
@@ -142,14 +163,15 @@ Validate before rendering. Render a short arrangement, check the report, and aud
 
 Report fields:
 
-- `before_gain`: float mix measurements before optional peak attenuation.
-- `gain_applied`: global attenuation, at most 1.
-- `audio`: float mix measurements after attenuation, before PCM quantization.
-- `wav`: measurements from the saved 16-bit file.
+- `before_gain`: float mix measurements before the selected mix gain.
+- `gain_applied`: global gain; at most 1 with default peak attenuation, but it may
+  exceed 1 when optional LUFS targeting boosts the mix.
+- `audio`: float mix measurements after gain, before WAV encoding.
+- `wav`: measurements from the saved WAV, normally 16-bit PCM.
 - `warnings`: silence, gain reduction, clipping, or sub-sample notes.
 - `score_sha256`, `engine_version`, `numpy_version`, and `seed`: reproduction metadata.
 
-`clipped_samples` in float measurements counts individual channel samples with absolute amplitude at least 1. `full_scale_samples` in WAV analysis counts samples at a PCM rail; this is evidence of full-scale values, not proof of upstream clipping. Silence means exact digital zero. dB values are `null` for silence so output remains valid JSON.
+`clipped_samples` in float measurements counts individual channel samples with absolute amplitude at least 1. In PCM WAV analysis, `full_scale_samples` counts samples at an integer rail; for float WAV it counts samples with absolute amplitude at least 1 and does not imply clipping. Silence means exact digital zero. dB values are `null` for silence so output remains valid JSON.
 
 ## Inspecting a score before rendering
 
@@ -180,6 +202,18 @@ All 49 catalog entries have generated prototypes. Read each entry's `description
 
 The schema accepts no arbitrary extra fields and rejects unsupported versions, non-finite numbers, duplicate track names, out-of-range pitches, and notes extending beyond the arrangement. Names must be unique within a score. All score timing is in quarter-note beats. Optional `tempo_map` entries change BPM at ordered beat positions. Track gain/pan and song master-gain automation use ordered points with linear or step interpolation. Track/song effects support generated delay and reverb. There is no meter metadata, swing field, clip graph or sample loading. Swing can be expressed by placing individual notes at explicit beat positions.
 
+For exact media cues across tempo changes, use `beat_at_seconds` or
+`place_at_seconds`; `Arrangement` and `Section` support bounded named-section
+revisions, and `render_loop_preview` repeats a region for join inspection. These
+are Python helpers around score version 1, not extra JSON fields. The loop
+preview renders the complete score before extracting cycles and still needs
+listening in the target player. See [arrangement](arrangement.md). Track and note
+`articulation` support `soft` and `accented` gestures on 13 bowed-string and wind
+voices; discover support in the catalog and see [articulations](articulations.md).
+Automation point values are absolute gain or pan values, not multipliers. For
+production encodings, optional LUFS targeting, exact excerpts, and progress or
+cancellation, see [production output](production-output.md).
+
 For `piano` only, `Track.pedal` accepts ordered `PedalEvent(beat=..., down=True/False)`
 events and MIDI exports binary CC64. This models a binary damper gate, with no
 half-pedaling or sympathetic resonance. Other voices, including `electric_piano`,

{audio_as_code-0.1.0 → audio_as_code-0.2.0}/docs/architecture.md

@@ -24,11 +24,15 @@ flowchart TD
 | `__init__.py`, `__main__.py` | Public Python exports/version and `python -m audio_as_code` entry point. |
 | `model.py` | Immutable Pydantic score objects, strict validation, pitch conversion, piecewise tempo integration, and release/effect-tail duration. |
 | `pattern.py` | Explicit phrase length and composition transforms, including sequence, repeat, transpose, append, overlay, stretch, velocity scaling, and placement. |
+| `arrangement.py` | Timestamp placement, named section edits and measured loop previews; section metadata stays outside score JSON. |
+| `project_setup.py`, `_project_templates/` | Installed project scaffolds and local runtime diagnostics. |
 | `instruments.py` | Central family/engine catalog, playable versus planned status, tone capabilities, and MIDI mappings. |
 | `inspection.py` | Read-only facts and static WAV/MIDI readiness checks with structured issues; no synthesis or file writes. |
 | `render.py` | Sample scheduling, stable note seeds, track mixing, normalization and render/stem orchestration. |
 | `_voices.py` | Instrument dispatch, electronic voices, drum-kit routing and note envelopes. |
 | `_audio.py` | PCM WAV encoding and signal measurements; independent of score objects and synthesis engines. |
+| `loudness.py` | Optional integrated metering and constant-gain targeting; imports its backend only when requested. |
+| `_render_control.py`, `_cli_progress.py` | Cooperative cancellation, staged audio publication and separate JSON Lines progress. |
 | `_export_rules.py` | Shared sample/tick rounding, percussion pitch mapping and export limits for rendering, MIDI and inspection. |
 | `physical.py` | Original generated string and modal instrument models. |
 | `orchestra.py` | Additional procedural instrument synthesis and source/filter approximations. |
@@ -59,11 +63,14 @@ half-pedaling and sympathetic resonance are not modeled. See [piano sustain](pia
 `schemas/song-v1.schema.json` is generated from `Song.model_json_schema()`. Runtime
 checks additionally enforce unique track names, note bounds, supported controls,
 and cross-field relationships. Schema version `"1"` is independent of package
-version `0.1.0`. Breaking the score contract requires explicit version/migration
+version `0.2.0`. Breaking the score contract requires explicit version/migration
 work; adding a Python helper does not automatically change the score schema.
 
 Rendering revalidates scores and is limited to 300 seconds including tails. It
-produces stereo float32 audio internally and 16-bit PCM WAV on export. Seeds are
+produces stereo float32 audio internally and defaults to 16-bit PCM WAV on export;
+24-bit PCM and 32-bit float WAV are optional. Context-preserving previews crop a
+complete render. See [production output](production-output.md) for encodings,
+progress, cancellation, and publication behavior. Seeds are
 derived deterministically from score/track/note context. Reproducibility is scoped
 to a fixed environment; changing algorithms or numeric dependencies can change
 samples. Reports include a score hash, engine/NumPy versions, duration, peak/RMS,