brief-spec-renderer-audio 0.5.0__tar.gz

brief_spec_renderer_audio-0.5.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.briefspec/
+.coverage
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.egg-info/
+*.py[cod]
+build/
+dist/
+coverage.xml
+htmlcov/

brief_spec_renderer_audio-0.5.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.5
+Name: brief-spec-renderer-audio
+Version: 0.5.0
+Summary: Verified local macOS and opt-in OpenAI audio rendering for Brief-Spec.
+Author: Luan Moreno Maciel
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: brief-spec<0.6,>=0.5
+Description-Content-Type: text/markdown
+
+# Brief-Spec audio renderer
+
+Optional MP3 renderer for Spoken Briefs. It supports offline macOS `say` and an explicitly
+authorized OpenAI text-to-speech provider. It never falls back from local speech to the network.

brief_spec_renderer_audio-0.5.0/README.md

@@ -0,0 +1,4 @@
+# Brief-Spec audio renderer
+
+Optional MP3 renderer for Spoken Briefs. It supports offline macOS `say` and an explicitly
+authorized OpenAI text-to-speech provider. It never falls back from local speech to the network.

brief_spec_renderer_audio-0.5.0/pyproject.toml

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "brief-spec-renderer-audio"
+version = "0.5.0"
+description = "Verified local macOS and opt-in OpenAI audio rendering for Brief-Spec."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Luan Moreno Maciel" }]
+dependencies = ["brief-spec>=0.5,<0.6"]
+
+[project.entry-points."brief_spec.renderers"]
+audio = "briefspec_renderer_audio:AudioRenderer"
+
+[project.entry-points."briefspec.renderers"]
+audio = "briefspec_renderer_audio:AudioRenderer"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/briefspec_renderer_audio"]

brief_spec_renderer_audio-0.5.0/src/briefspec_renderer_audio/__init__.py

@@ -0,0 +1,271 @@
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import subprocess
+import tempfile
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any
+
+from briefspec.delivery import render_spoken_text, sha256_bytes
+from briefspec.state import atomic_write_public
+
+__version__ = "0.5.0"
+
+
+def _tool_version(command: str) -> str:
+    result = subprocess.run(
+        [command, "-version"],
+        text=True,
+        capture_output=True,
+        timeout=30,
+        check=False,
+    )
+    output = result.stdout or result.stderr
+    return output.splitlines()[0].strip() if output else "unknown"
+
+
+def _probe_audio(artifact: Path, ffprobe: str) -> tuple[float, set[str], str | None]:
+    result = subprocess.run(
+        [
+            ffprobe,
+            "-v",
+            "error",
+            "-show_entries",
+            "format=duration:format_tags=comment:stream=codec_name,codec_type",
+            "-of",
+            "json",
+            str(artifact),
+        ],
+        text=True,
+        capture_output=True,
+        timeout=60,
+        check=False,
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip() or "ffprobe failed")
+    try:
+        value = json.loads(result.stdout)
+        duration = float(value["format"]["duration"])
+        codecs = {
+            stream.get("codec_name")
+            for stream in value.get("streams", [])
+            if stream.get("codec_type") == "audio"
+        }
+        comment = value.get("format", {}).get("tags", {}).get("comment")
+    except (KeyError, TypeError, ValueError, json.JSONDecodeError) as exc:
+        raise ValueError(f"invalid ffprobe output: {exc}") from exc
+    return duration, codecs, str(comment) if comment is not None else None
+
+
+class AudioRenderer:
+    name = "audio"
+    media_type = "audio/mpeg"
+    filename = "brief.mp3"
+
+    def capabilities(self) -> dict[str, Any]:
+        tools = {name: shutil.which(name) for name in ("say", "ffmpeg", "ffprobe")}
+        return {
+            "renderer_version": __version__,
+            "media_type": self.media_type,
+            "providers": {
+                "macos": bool(tools["say"] and tools["ffmpeg"]),
+                "openai": bool(os.environ.get("OPENAI_API_KEY") and tools["ffmpeg"]),
+            },
+            "verification_tools": tools,
+            "ready": bool(tools["ffmpeg"] and tools["ffprobe"]),
+        }
+
+    def setup(self, *, dry_run: bool = False) -> dict[str, Any]:
+        missing = [name for name in ("ffmpeg", "ffprobe") if shutil.which(name) is None]
+        status = "PASS" if not missing else "WARN"
+        return {
+            "status": "DRY-RUN" if dry_run else status,
+            "detail": "ready" if not missing else f"install manually: {', '.join(missing)}",
+        }
+
+    def _macos(self, script: str, target: Path, voice: str, rate: int) -> None:
+        say = shutil.which("say")
+        if say is None:
+            raise RuntimeError("macOS say is unavailable; no cloud fallback was attempted")
+        result = subprocess.run(
+            [say, "-v", voice, "-r", str(rate), "-o", str(target), script],
+            text=True,
+            capture_output=True,
+            timeout=300,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(result.stderr.strip() or "macOS say failed")
+
+    def _openai(self, script: str, target: Path, voice: str, options: dict[str, Any]) -> str:
+        if not options.get("consent_network"):
+            raise ValueError("OpenAI audio requires --consent-network")
+        api_key = os.environ.get("OPENAI_API_KEY")
+        if not api_key:
+            raise ValueError("OPENAI_API_KEY is required for the OpenAI audio provider")
+        model = str(options.get("model", "gpt-4o-mini-tts"))
+        payload = json.dumps(
+            {
+                "model": model,
+                "voice": voice,
+                "input": script,
+                "response_format": "mp3",
+            }
+        ).encode("utf-8")
+        request = urllib.request.Request(
+            "https://api.openai.com/v1/audio/speech",
+            data=payload,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            method="POST",
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=180) as response:
+                target.write_bytes(response.read())
+        except urllib.error.HTTPError as exc:
+            raise RuntimeError(f"OpenAI audio request failed with HTTP {exc.code}") from exc
+        return model
+
+    def render(
+        self,
+        delivery: dict[str, Any],
+        output: Path,
+        options: dict[str, Any],
+    ) -> dict[str, Any]:
+        script = render_spoken_text(delivery).strip()
+        record = render_script_document(
+            script,
+            output,
+            created_at=str(delivery.get("source", {}).get("created_at") or ""),
+            provider=str(options.get("provider", "macos")),
+            voice=options.get("voice"),
+            rate=int(options.get("rate", 190)),
+            consent_network=bool(options.get("consent_network")),
+            model=str(options.get("model", "gpt-4o-mini-tts")),
+        )
+        record["path"] = str(output)
+        return record
+
+    def verify(self, artifact: Path) -> dict[str, Any]:
+        ffprobe = shutil.which("ffprobe")
+        if ffprobe is None:
+            return {"status": "FAIL", "detail": "ffprobe is required for MP3 verification"}
+        try:
+            duration, codecs, comment = _probe_audio(artifact, ffprobe)
+        except (RuntimeError, ValueError) as exc:
+            return {"status": "FAIL", "detail": str(exc)}
+        if duration <= 0 or "mp3" not in codecs:
+            return {"status": "FAIL", "detail": "audio is empty or not MP3"}
+        if comment not in {
+            "AI-generated speech by Brief-Spec",
+            "AI-generated speech by BriefSpec",  # legacy 0.x artifact compatibility
+        }:
+            return {"status": "FAIL", "detail": "AI-generated speech disclosure is missing"}
+        return {
+            "status": "PASS",
+            "detail": f"MP3 decoded; duration {duration:.2f}s; disclosure verified",
+            "duration_seconds": duration,
+        }
+
+
+def render_script_document(
+    script: str,
+    output: Path,
+    *,
+    created_at: str,
+    provider: str = "macos",
+    voice: str | None = None,
+    rate: int = 190,
+    consent_network: bool = False,
+    model: str = "gpt-4o-mini-tts",
+    force: bool = False,
+) -> dict[str, Any]:
+    """Render one canonical spoken script without reading screen-only evidence content."""
+    if output.exists() and not force:
+        raise FileExistsError(f"Refusing to overwrite existing output: {output}")
+    if not created_at:
+        raise ValueError("Audio rendering requires a canonical created_at")
+    ffmpeg = shutil.which("ffmpeg")
+    if ffmpeg is None:
+        raise RuntimeError("ffmpeg is required for Brief-Spec MP3 output")
+    ffprobe = shutil.which("ffprobe")
+    if ffprobe is None:
+        raise RuntimeError("ffprobe is required for Brief-Spec MP3 verification")
+    selected_voice = str(voice or ("marin" if provider == "openai" else "Samantha"))
+    if not 80 <= rate <= 400:
+        raise ValueError("Audio rate must be between 80 and 400 words per minute")
+    renderer = AudioRenderer()
+    selected_model: str | None = None
+    with tempfile.TemporaryDirectory(prefix="briefspec-audio-") as temporary:
+        root = Path(temporary)
+        source = root / ("source.aiff" if provider == "macos" else "source.mp3")
+        rendered = root / "brief.mp3"
+        if provider == "macos":
+            renderer._macos(script, source, selected_voice, rate)
+        elif provider == "openai":
+            selected_model = renderer._openai(
+                script,
+                source,
+                selected_voice,
+                {"consent_network": consent_network, "model": model},
+            )
+        else:
+            raise ValueError("Audio provider must be macos or openai")
+        result = subprocess.run(
+            [
+                ffmpeg,
+                "-y",
+                "-i",
+                str(source),
+                "-codec:a",
+                "libmp3lame",
+                "-q:a",
+                "2",
+                "-metadata",
+                "comment=AI-generated speech by Brief-Spec",
+                str(rendered),
+            ],
+            text=True,
+            capture_output=True,
+            timeout=300,
+            check=False,
+        )
+        if result.returncode != 0:
+            raise RuntimeError(result.stderr.strip() or "ffmpeg MP3 conversion failed")
+        content = rendered.read_bytes()
+        duration, codecs, comment = _probe_audio(rendered, ffprobe)
+        if duration <= 0 or "mp3" not in codecs:
+            raise RuntimeError("rendered audio is empty or not MP3")
+    atomic_write_public(output, content, mode=0o644)
+    metadata = {
+        "renderer": "audio",
+        "renderer_version": __version__,
+        "provider": provider,
+        "model": selected_model,
+        "voice": selected_voice,
+        "rate": rate,
+        "source_script_sha256": sha256_bytes(script.encode("utf-8")),
+        "canonical_created_at": created_at,
+        "say_version": (f"macOS {platform.mac_ver()[0]} say" if provider == "macos" else None),
+        "ffmpeg_version": _tool_version(ffmpeg),
+        "ffprobe_version": _tool_version(ffprobe),
+        "duration_seconds": duration,
+        "ai_generated": True,
+        "disclosure": comment or "AI-generated speech",
+    }
+    return {
+        "format": "audio",
+        "path": output.name,
+        "media_type": "audio/mpeg",
+        "size_bytes": len(content),
+        "sha256": sha256_bytes(content),
+        "renderer_version": __version__,
+        "metadata": metadata,
+    }

brief_spec_renderer_audio-0.5.0/tests/test_audio_renderer.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import briefspec_renderer_audio as audio
+import pytest
+
+
+class _Response:
+    def __enter__(self) -> _Response:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        return None
+
+    def read(self) -> bytes:
+        return b"mock-mp3"
+
+
+def test_openai_requires_explicit_consent_and_environment_key(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    renderer = audio.AudioRenderer()
+    target = tmp_path / "speech.mp3"
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    with pytest.raises(ValueError, match="consent"):
+        renderer._openai("bounded script", target, "marin", {})
+    with pytest.raises(ValueError, match="OPENAI_API_KEY"):
+        renderer._openai("bounded script", target, "marin", {"consent_network": True})
+
+
+def test_openai_request_uses_documented_defaults_without_persisting_credentials(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    captured: dict[str, object] = {}
+
+    def urlopen(request: object, timeout: int) -> _Response:
+        captured["request"] = request
+        captured["timeout"] = timeout
+        return _Response()
+
+    monkeypatch.setenv("OPENAI_API_KEY", "test-secret-never-persist")
+    monkeypatch.setattr(audio.urllib.request, "urlopen", urlopen)
+    target = tmp_path / "speech.mp3"
+    model = audio.AudioRenderer()._openai(
+        "bounded script",
+        target,
+        "marin",
+        {"consent_network": True},
+    )
+    request = captured["request"]
+    payload = json.loads(request.data)
+    assert model == "gpt-4o-mini-tts"
+    assert payload == {
+        "model": "gpt-4o-mini-tts",
+        "voice": "marin",
+        "input": "bounded script",
+        "response_format": "mp3",
+    }
+    assert request.get_header("Authorization") == "Bearer test-secret-never-persist"
+    assert target.read_bytes() == b"mock-mp3"
+    assert b"test-secret-never-persist" not in target.read_bytes()
+
+
+def test_local_provider_never_falls_back_to_network(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(audio.shutil, "which", lambda _name: None)
+    monkeypatch.setattr(
+        audio.urllib.request,
+        "urlopen",
+        lambda *_args, **_kwargs: (_ for _ in ()).throw(AssertionError("network attempted")),
+    )
+    with pytest.raises(RuntimeError, match="no cloud fallback"):
+        audio.AudioRenderer()._macos("script", tmp_path / "speech.aiff", "Samantha", 190)
+
+
+def test_generic_script_helper_fails_closed_before_tool_use(tmp_path: Path) -> None:
+    target = tmp_path / "chronicle.mp3"
+    target.write_bytes(b"existing")
+    with pytest.raises(FileExistsError, match="Refusing to overwrite"):
+        audio.render_script_document(
+            "Bounded script",
+            target,
+            created_at="2026-08-14T12:00:00+00:00",
+        )
+    with pytest.raises(ValueError, match="canonical created_at"):
+        audio.render_script_document("Bounded script", tmp_path / "new.mp3", created_at="")