audio-as-code 0.1.0__tar.gz

audio_as_code-0.1.0/.github/FUNDING.yml

@@ -0,0 +1 @@
+ko_fi: joaothecarvalho

audio_as_code-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,42 @@
+name: Bug report
+description: Report a reproducible score, rendering, export, or CLI problem.
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This is an early procedural-audio prototype. Please use a minimal original
+        or public-domain score. Do not include credentials or private project files.
+        For a suspected vulnerability, read [SECURITY.md](https://github.com/joaoCarvalho1000/audio-as-code/blob/main/SECURITY.md) before sharing details.
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected and actual behavior
+      description: What did you expect, and what happened instead?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Smallest reproduction
+      description: Paste the command and a small JSON score or Python example.
+      render: text
+    validations:
+      required: true
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Include your OS, Python version, aac --version, and installation method.
+      placeholder: Source checkout or source ZIP; Python version; OS; package version.
+    validations:
+      required: true
+  - type: textarea
+    id: diagnostics
+    attributes:
+      label: Diagnostics and audio observations
+      description: |
+        Include the complete JSON error or relevant render/analyze report. For sound
+        problems, identify the instrument, pitch, tempo, and what you heard. State
+        whether you listened; signal measurements alone do not establish sound quality.
+      render: text

audio_as_code-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Report a security vulnerability privately
+    url: https://github.com/joaoCarvalho1000/audio-as-code/security/advisories/new
+    about: Use the private reporting route instead of sharing exploit details in a public issue.

audio_as_code-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,28 @@
+name: Feature request
+description: Describe a composition workflow or API capability you need.
+labels: [enhancement]
+body:
+  - type: textarea
+    id: task
+    attributes:
+      label: What are you trying to make?
+      description: Describe the musical or integration task and what currently gets in the way.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behavior
+      description: A small score, command, or Python example helps make the request concrete.
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Current workaround and constraints
+      description: Include compatibility needs, timing, instrument controls, or export requirements.
+  - type: markdown
+    attributes:
+      value: |
+        Instrument sources must be generated from code. Recorded samples, SoundFonts,
+        and measured impulse responses are outside this project's synthesis direction.

audio_as_code-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,18 @@
+## What changes?
+
+Describe the concrete problem and resulting behavior. Include a small before/after
+example when it helps someone review the change.
+
+## Validation
+
+List the commands you ran and their results. Mention checks you could not run.
+For audio changes, state what you listened to and keep numerical checks separate
+from perceptual observations.
+
+- [ ] Relevant tests, Ruff lint, and formatting pass.
+- [ ] User-facing behavior and compatibility changes are documented.
+- [ ] Score schema regenerated if the models changed.
+- [ ] New instrument controls affect implemented synthesis and are tested.
+- [ ] No generated output, credentials, or workstation state is included.
+
+Mark checks that do not apply as such; see CONTRIBUTING.md for the full workflow.

audio_as_code-0.1.0/.github/dependabot.yml

@@ -0,0 +1,29 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 2
+    groups:
+      python-minor-patch:
+        patterns: ['*']
+        update-types: [minor, patch]
+  - package-ecosystem: npm
+    directory: /web/cloudflare
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 2
+    groups:
+      hosting-minor-patch:
+        patterns: ['*']
+        update-types: [minor, patch]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    open-pull-requests-limit: 2
+    groups:
+      actions-minor-patch:
+        patterns: ['*']
+        update-types: [minor, patch]

audio_as_code-0.1.0/.github/scripts/check_distribution.py

@@ -0,0 +1,272 @@
+"""Inspect release artifacts without importing or extracting their contents."""
+
+from __future__ import annotations
+
+import argparse
+import ast
+import json
+import re
+import stat
+import tarfile
+import zipfile
+from email.parser import BytesParser
+from pathlib import Path, PurePosixPath
+
+ROOT = Path(__file__).resolve().parents[2]
+PRIVATE_PARTS = {
+    ".git",
+    ".env",
+    ".agents",
+    ".codex",
+    ".impeccable",
+    ".wrangler",
+    ".claude",
+    ".orca",
+    ".cursor",
+    ".idea",
+    ".vscode",
+    ".internal",
+    ".venv",
+    "node_modules",
+    "__pycache__",
+    ".pytest_cache",
+    ".ruff_cache",
+    ".mypy_cache",
+    ".hypothesis",
+    ".tox",
+    ".nox",
+    "playwright-report",
+    "test-results",
+    "htmlcov",
+    "%systemdrive%",
+    "output",
+    "dist",
+    "build",
+}
+PRIVATE_SUFFIXES = {
+    ".pyc",
+    ".pyo",
+    ".log",
+    ".key",
+    ".pem",
+    ".p12",
+    ".pfx",
+    ".prof",
+    ".wav",
+    ".mp3",
+    ".mid",
+    ".midi",
+}
+INTERNAL_DOCS = {
+    "design.md",
+    "product.md",
+    "plan.md",
+    "handoff.md",
+    "session.md",
+    "notes.md",
+    "progress.md",
+    "checkpoint.md",
+    "tasks.md",
+    "instrument-browser-brief.md",
+    "instrument-refinement.md",
+}
+SDIST_ROOTS = {
+    "src",
+    "tests",
+    "examples",
+    "docs",
+    "schemas",
+    "skills",
+    "web",
+    ".github",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "AGENTS.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    ".gitignore",
+    "pyproject.toml",
+    "uv.lock",
+    "PKG-INFO",
+}
+REQUIRED_SOURCE = {
+    "src/audio_as_code/__init__.py",
+    "src/audio_as_code/py.typed",
+    "src/audio_as_code/extended.py",
+    "src/audio_as_code/_audio.py",
+    "src/audio_as_code/_voices.py",
+    "src/audio_as_code/_export_rules.py",
+    "src/audio_as_code/_orchestra_profiles.py",
+    "pyproject.toml",
+    "uv.lock",
+    "README.md",
+    "LICENSE",
+    "CONTRIBUTING.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "docs/architecture.md",
+    "docs/extended-instruments.md",
+    "docs/synthesis.md",
+    "docs/piano-sustain.md",
+    "docs/creative-workflows.md",
+    "docs/render-performance.md",
+    "docs/cloudflare-hosting.md",
+    "docs/releasing.md",
+    "schemas/song-v1.schema.json",
+    "examples/first_light.py",
+    "examples/classic_showcase.py",
+    "examples/piano_sustain.py",
+    "examples/creative_workflows.py",
+    "examples/benchmark_render.py",
+    "examples/prepare_cloudflare.py",
+    "examples/music/classics-full.json",
+    "skills/audio-as-code/SKILL.md",
+    ".github/workflows/ci.yml",
+    ".github/scripts/check_distribution.py",
+    ".github/scripts/smoke_installed.py",
+    "web/cloudflare/worker.js",
+    "web/cloudflare/media-handler.js",
+    "web/cloudflare/package.json",
+    "web/cloudflare/package-lock.json",
+}
+
+
+def private_path(name: str) -> bool:
+    """Reject private/generated paths at any nesting depth, including Windows spelling."""
+    normalized = name.replace("\\", "/")
+    parts = normalized.split("/")
+    if normalized.startswith("/") or ".." in parts or any(":" in part for part in parts):
+        return True
+    if normalized.lower().startswith("docs/internal/"):
+        return True
+    for part in parts:
+        lower = part.lower()
+        if lower in PRIVATE_PARTS or lower in INTERNAL_DOCS:
+            return True
+        if lower.startswith((".env", ".dev.vars", ".coverage", "credentials")):
+            return True
+        if lower.endswith(".egg-info") or PurePosixPath(lower).suffix in PRIVATE_SUFFIXES:
+            return True
+    return False
+
+
+def source_version(root: Path = ROOT) -> str:
+    tree = ast.parse((root / "src/audio_as_code/__init__.py").read_text(encoding="utf-8"))
+    for statement in tree.body:
+        if isinstance(statement, ast.Assign) and any(
+            isinstance(target, ast.Name) and target.id == "__version__"
+            for target in statement.targets
+        ):
+            value = ast.literal_eval(statement.value)
+            if isinstance(value, str):
+                return value
+    raise ValueError("No literal __version__ in the package entry point")
+
+
+def check_metadata(data: bytes, expected_version: str) -> None:
+    metadata = BytesParser().parsebytes(data)
+    if metadata["Name"] != "audio-as-code" or metadata["Version"] != expected_version:
+        raise ValueError("Distribution name/version disagree with the package's __version__")
+    if metadata["Requires-Python"] != ">=3.10":
+        raise ValueError("Unexpected Python requirement")
+    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}
+    if names != {"numpy", "pydantic", "mido"} or any("@" in item for item in requirements):
+        raise ValueError("Runtime dependencies changed or contain nonportable direct URLs")
+
+
+def check_wheel(path: Path, expected_version: str) -> dict:
+    with zipfile.ZipFile(path) as archive:
+        names = archive.namelist()
+        if len(names) != len(set(names)):
+            raise ValueError("Duplicate wheel members")
+        info_root = f"audio_as_code-{expected_version}.dist-info"
+        for info in archive.infolist():
+            if private_path(info.filename) or PurePosixPath(info.filename).parts[0] not in {
+                "audio_as_code",
+                info_root,
+            }:
+                raise ValueError(f"Unexpected wheel member: {info.filename}")
+            if stat.S_ISLNK(info.external_attr >> 16):
+                raise ValueError(f"Wheel may not contain symlinks: {info.filename}")
+        required = {
+            f"audio_as_code/{name}"
+            for name in (
+                "__init__.py",
+                "__main__.py",
+                "cli.py",
+                "model.py",
+                "pattern.py",
+                "render.py",
+                "extended.py",
+                "_audio.py",
+                "_voices.py",
+                "_export_rules.py",
+                "_orchestra_profiles.py",
+                "py.typed",
+            )
+        }
+        required |= {f"{info_root}/METADATA", f"{info_root}/WHEEL", f"{info_root}/entry_points.txt"}
+        if missing := required - set(names):
+            raise ValueError(f"Missing wheel files: {sorted(missing)}")
+        if not any(
+            name.startswith(info_root + "/") and name.endswith("/LICENSE") for name in names
+        ):
+            raise ValueError("Wheel is missing the license file")
+        check_metadata(archive.read(f"{info_root}/METADATA"), expected_version)
+        entry_points = archive.read(f"{info_root}/entry_points.txt").decode()
+        if "aac = audio_as_code.cli:main" not in entry_points:
+            raise ValueError("Wheel is missing the aac console entry point")
+    return {"file": path.name, "files": len(names), "typed": True}
+
+
+def check_sdist(path: Path, expected_version: str) -> dict:
+    with tarfile.open(path, "r:gz") as archive:
+        members = archive.getmembers()
+        prefix = f"audio_as_code-{expected_version}/"
+        names = set()
+        for member in members:
+            if member.isdir():
+                continue
+            if not member.isfile() or not member.name.startswith(prefix):
+                raise ValueError(f"Unexpected sdist member: {member.name}")
+            name = member.name[len(prefix) :]
+            if private_path(name) or PurePosixPath(name).parts[0] not in SDIST_ROOTS:
+                raise ValueError(f"Private/generated or unlisted sdist member: {name}")
+            if name in names:
+                raise ValueError(f"Duplicate sdist member: {name}")
+            names.add(name)
+        if missing := REQUIRED_SOURCE - names:
+            raise ValueError(f"Missing sdist files: {sorted(missing)}")
+        metadata = archive.extractfile(prefix + "PKG-INFO")
+        if metadata is None:
+            raise ValueError("Missing sdist metadata")
+        check_metadata(metadata.read(), expected_version)
+    return {"file": path.name, "files": len(names), "portable_source": True}
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("directory", nargs="?", type=Path, default=Path("dist"))
+    args = parser.parse_args()
+    wheels = sorted(args.directory.glob("*.whl"))
+    sdists = sorted(args.directory.glob("*.tar.gz"))
+    if len(wheels) != 1 or len(sdists) != 1:
+        parser.error("Expected exactly one wheel and one sdist; use a fresh output directory")
+    version = source_version()
+    try:
+        result = {
+            "version": version,
+            "wheel": check_wheel(wheels[0], version),
+            "sdist": check_sdist(sdists[0], version),
+        }
+    except (ValueError, KeyError) as error:
+        parser.error(str(error))
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

audio_as_code-0.1.0/.github/scripts/check_schema.py

@@ -0,0 +1,11 @@
+"""Fail when the checked-in schema differs from the installed score model."""
+
+import json
+from pathlib import Path
+
+from audio_as_code import Song
+
+path = Path(__file__).resolve().parents[2] / "schemas/song-v1.schema.json"
+if json.loads(path.read_text(encoding="utf-8")) != Song.model_json_schema():
+    raise SystemExit("Schema drift: run uv run aac schema -o schemas/song-v1.schema.json")
+print("The checked-in score schema matches Song.model_json_schema().")

audio_as_code-0.1.0/.github/scripts/smoke_distribution.py

@@ -0,0 +1,80 @@
+"""Rebuild the sdist and smoke-test both wheels in isolated installed environments."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import tempfile
+import zipfile
+from pathlib import Path
+
+from check_distribution import check_wheel, source_version
+
+
+def payload(path: Path) -> dict[str, bytes]:
+    with zipfile.ZipFile(path) as archive:
+        return {
+            name: archive.read(name)
+            for name in archive.namelist()
+            if name.startswith("audio_as_code/")
+        }
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("directory", nargs="?", type=Path, default=Path("dist"))
+    args = parser.parse_args()
+    wheels = list(args.directory.glob("*.whl"))
+    sdists = list(args.directory.glob("*.tar.gz"))
+    if len(wheels) != 1 or len(sdists) != 1:
+        parser.error("Expected exactly one wheel and one sdist")
+    uv = shutil.which("uv")
+    if uv is None:
+        parser.error("Install uv to run the isolated distribution checks")
+    script = Path(__file__).with_name("smoke_installed.py").resolve()
+    with tempfile.TemporaryDirectory(prefix="aac-distribution-") as folder:
+        work = Path(folder)
+        subprocess.run(
+            [
+                uv,
+                "build",
+                str(sdists[0].resolve()),
+                "--wheel",
+                "--no-sources",
+                "--out-dir",
+                str(work / "rebuilt"),
+                "--python",
+                sys.executable,
+            ],
+            check=True,
+            cwd=work,
+        )
+        rebuilt = next((work / "rebuilt").glob("*.whl"))
+        check_wheel(rebuilt, source_version())
+        assert payload(wheels[0]) == payload(rebuilt), "Sdist rebuild changed the installed package"
+        for wheel in (wheels[0].resolve(), rebuilt):
+            subprocess.run(
+                [
+                    uv,
+                    "run",
+                    "--isolated",
+                    "--no-project",
+                    "--python",
+                    sys.executable,
+                    "--with",
+                    str(wheel),
+                    "python",
+                    "-I",
+                    str(script),
+                ],
+                check=True,
+                cwd=work,
+            )
+    print(json.dumps({"sdist_rebuild": "passed", "isolated_wheel_installs": 2}))
+
+
+if __name__ == "__main__":
+    main()

audio_as_code-0.1.0/.github/scripts/smoke_installed.py

@@ -0,0 +1,112 @@
+"""Exercise an installed artifact from a temporary working directory, never the checkout."""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+import tempfile
+from importlib.metadata import distribution
+from pathlib import Path
+
+import audio_as_code
+from audio_as_code import (
+    Note,
+    Pattern,
+    Song,
+    Track,
+    analyze_wav,
+    export_midi,
+    get_instrument,
+    inspect_score,
+    render,
+)
+
+
+def main() -> None:
+    repo = Path(__file__).resolve().parents[2]
+    package = Path(audio_as_code.__file__).resolve()
+    if package.is_relative_to(repo / "src"):
+        raise SystemExit("Smoke test imported the checkout; install the built wheel in isolation")
+    metadata = distribution("audio-as-code")
+    assert metadata.version == audio_as_code.__version__
+    assert (package.parent / "py.typed").is_file()
+    console = Path(sys.executable).with_name("aac.exe" if sys.platform == "win32" else "aac")
+    with tempfile.TemporaryDirectory(prefix="aac-installed-") as folder:
+        work = Path(folder)
+        for command in ([str(console)], [sys.executable, "-m", "audio_as_code"]):
+            version = subprocess.run(
+                [*command, "--version"], cwd=work, capture_output=True, text=True, check=True
+            )
+            assert json.loads(version.stdout) == {"version": metadata.version}
+            subprocess.run([*command, "--help"], cwd=work, capture_output=True, check=True)
+        phrase = Pattern.sequence(["C4"], step=0.25)
+        phrase = phrase.overlay(phrase.transpose(12), offset=0.25).stretch(2).scale_velocity(0.5)
+        song = Song(
+            title="Installed artifact smoke test",
+            bpm=120,
+            beats=1,
+            sample_rate=22050,
+            seed=7,
+            tracks=[Track(name="Lead", instrument="sine", notes=phrase.notes)],
+        )
+        score = work / "score.json"
+        song.save(score)
+        assert Song.load(score) == song
+        inspection = inspect_score(song)
+        assert inspection["summary"]["note_count"] == 2
+        assert inspection["readiness"]["render"]["ready"]
+        assert inspection["readiness"]["midi"]["ready"]
+        inspected = subprocess.run(
+            [str(console), "inspect", str(score)],
+            cwd=work,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        assert json.loads(inspected.stdout) == inspection
+        report = render(song, work / "score.wav")
+        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"]
+        validation = subprocess.run(
+            [str(console), "validate", str(score)],
+            cwd=work,
+            capture_output=True,
+            text=True,
+            check=True,
+        )
+        assert json.loads(validation.stdout)["valid"]
+        for voice in ("mandolin", "kalimba", "celesta", "recorder"):
+            info = get_instrument(voice)
+            probe = Song(
+                bpm=120,
+                beats=1,
+                sample_rate=22050,
+                tracks=[
+                    Track(
+                        name=voice,
+                        instrument=voice,
+                        notes=[Note(pitch=info.preview_pitch, duration=1)],
+                    )
+                ],
+            )
+            voice_report = render(probe, work / f"{voice}.wav")
+            assert not voice_report["wav"]["silent"]
+            assert not voice_report["wav"]["full_scale_samples"]
+            export_midi(probe, work / f"{voice}.mid")
+        invalid = work / "invalid.json"
+        invalid.write_text('{"tracks":[]}', encoding="utf-8")
+        failure = subprocess.run(
+            [str(console), "validate", str(invalid)],
+            cwd=work,
+            capture_output=True,
+            text=True,
+        )
+        assert failure.returncode == 2 and not failure.stdout
+        assert json.loads(failure.stderr)["error"] == "invalid_score"
+    print(json.dumps({"version": metadata.version, "installed_artifact_smoke": "passed"}))
+
+
+if __name__ == "__main__":
+    main()

audio_as_code-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+on: [push, pull_request, workflow_dispatch]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  hosting:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: '24'
+      - run: npm ci
+        working-directory: web/cloudflare
+      - run: npm exec --no -- wrangler --version
+        working-directory: web/cloudflare
+      - run: node --test web/cloudflare/media-handler.test.js
+
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ['3.10', '3.13']
+        include:
+          - os: macos-latest
+            python: '3.13'
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: ${{ matrix.python }}
+          version: '0.12.15'
+      - 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
+
+  distribution:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
+        with:
+          python-version: '3.13'
+          version: '0.12.15'
+      - run: uv sync --locked
+      - run: uv run --locked ruff check .
+      - run: uv run --locked ruff format --check .
+      - name: Build without local dependency source overrides
+        run: uv build --no-sources
+      - name: Inspect archive contents and metadata
+        run: uv run --locked python .github/scripts/check_distribution.py dist
+      - name: Install wheel and rebuilt sdist outside the checkout
+        run: uv run --locked python .github/scripts/smoke_distribution.py dist