audiocompose 0.1.0__py3-none-any.whl

audiocompose/__init__.py

@@ -0,0 +1,89 @@
+from ._version import __version__
+from .alignment import AudioAnchor, AudioSpan, ComposedMarker, ComposedSpan, Marker
+from .analysis import (
+    AcousticGap,
+    ActivityConfig,
+    ActivityRegion,
+    ActivityReport,
+    analyze_activity,
+    measure_gap_near,
+)
+from .composer import Composer
+from .diagnostics import CompositionDiagnostic, DiagnosticSeverity
+from .errors import AudioComposeError, AudioValidationError, CompositionError
+from .job import load_job, save_job, validate_job
+from .loudness import (
+    LoudnessMetrics,
+    LoudnessPolicy,
+    LoudnessResult,
+    apply_complete_output_loudness,
+)
+from .model import AudioClip, AudioJob, ComposedItem, CompositionResult, OutputPolicy, Silence
+from .operations import (
+    AudioOperation,
+    FadeIn,
+    FadeOut,
+    Gain,
+    PitchShift,
+    Tempo,
+    apply_operation,
+    operation_from_dict,
+)
+from .resampling import resample_audio
+from .sources import AudioBufferSource, AudioFileSource, AudioSource
+from .timeline import samples_for_duration, silence
+from .wav import prepare_output, read_wav, sha256_file, wav_info, write_intermediate_wav, write_wav
+
+__all__ = [
+    "ActivityConfig",
+    "ActivityRegion",
+    "ActivityReport",
+    "AcousticGap",
+    "analyze_activity",
+    "measure_gap_near",
+    "__version__",
+    "AudioAnchor",
+    "AudioBufferSource",
+    "AudioClip",
+    "AudioComposeError",
+    "AudioFileSource",
+    "AudioJob",
+    "AudioOperation",
+    "AudioSource",
+    "AudioSpan",
+    "CompositionDiagnostic",
+    "CompositionError",
+    "CompositionResult",
+    "ComposedItem",
+    "ComposedMarker",
+    "ComposedSpan",
+    "Composer",
+    "DiagnosticSeverity",
+    "FadeIn",
+    "FadeOut",
+    "LoudnessMetrics",
+    "Gain",
+    "LoudnessPolicy",
+    "LoudnessResult",
+    "Marker",
+    "OutputPolicy",
+    "PitchShift",
+    "Silence",
+    "Tempo",
+    "apply_complete_output_loudness",
+    "apply_operation",
+    "load_job",
+    "operation_from_dict",
+    "prepare_output",
+    "read_wav",
+    "resample_audio",
+    "samples_for_duration",
+    "save_job",
+    "sha256_file",
+    "silence",
+    "validate_job",
+    "wav_info",
+    "write_intermediate_wav",
+    "write_wav",
+    "AudioValidationError",
+]

audiocompose/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

audiocompose/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = 'g88a3e01d9'

audiocompose/alignment.py

@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import AudioValidationError
+
+
+@dataclass(frozen=True, slots=True)
+class AudioAnchor:
+    id: str
+    sample_offset: int
+    name: str | None = None
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.id, str) or not self.id:
+            raise AudioValidationError("anchor id must not be empty")
+        if (
+            isinstance(self.sample_offset, bool)
+            or not isinstance(self.sample_offset, int)
+            or self.sample_offset < 0
+        ):
+            raise AudioValidationError("sample_offset must be a non-negative integer")
+
+
+@dataclass(frozen=True, slots=True)
+class AudioSpan:
+    source_start: int
+    source_end: int
+    sample_start: int
+    sample_end: int
+    id: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        values = (
+            ("source_start", self.source_start),
+            ("source_end", self.source_end),
+            ("sample_start", self.sample_start),
+            ("sample_end", self.sample_end),
+        )
+        for name, value in values:
+            if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+                raise AudioValidationError(f"{name} must be a non-negative integer")
+        if self.source_end < self.source_start:
+            raise AudioValidationError("source_end must be >= source_start")
+        if self.sample_end < self.sample_start:
+            raise AudioValidationError("sample_end must be >= sample_start")
+        if self.id is not None and (not isinstance(self.id, str) or not self.id):
+            raise AudioValidationError("span id must be a non-empty string or None")
+        if not isinstance(self.metadata, Mapping):
+            raise AudioValidationError("span metadata must be an object")
+
+
+@dataclass(frozen=True, slots=True)
+class ComposedSpan:
+    item_id: str
+    source_start: int
+    source_end: int
+    sample_start: int
+    sample_end: int
+    id: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        values = (
+            ("source_start", self.source_start),
+            ("source_end", self.source_end),
+            ("sample_start", self.sample_start),
+            ("sample_end", self.sample_end),
+        )
+        for name, value in values:
+            if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+                raise AudioValidationError(f"{name} must be a non-negative integer")
+        if self.source_end < self.source_start:
+            raise AudioValidationError("source_end must be >= source_start")
+        if self.sample_end < self.sample_start:
+            raise AudioValidationError("sample_end must be >= sample_start")
+        if self.id is not None and (not isinstance(self.id, str) or not self.id):
+            raise AudioValidationError("span id must be a non-empty string or None")
+        if not isinstance(self.metadata, Mapping):
+            raise AudioValidationError("composed span metadata must be an object")
+
+
+@dataclass(frozen=True, slots=True)
+class ComposedMarker:
+    id: str
+    sample_offset: int
+    name: str | None = None
+    item_id: str | None = None
+
+
+Marker = AudioAnchor

audiocompose/analysis.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+import numpy as np
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityConfig:
+    frame_ms: float = 20.0
+    hop_ms: float = 5.0
+    active_threshold_dbfs: float = -40.0
+    release_threshold_dbfs: float = -45.0
+    min_active_ms: float = 30.0
+    min_gap_ms: float = 60.0
+
+    def __post_init__(self) -> None:
+        if self.frame_ms <= 0 or self.hop_ms <= 0:
+            raise ValueError("frame_ms and hop_ms must be positive")
+        if self.release_threshold_dbfs > self.active_threshold_dbfs:
+            raise ValueError("release threshold must not exceed active threshold")
+        if self.min_active_ms < 0 or self.min_gap_ms < 0:
+            raise ValueError("minimum durations must be non-negative")
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityRegion:
+    start_sample: int
+    end_sample: int
+    rms_dbfs: float
+    peak_dbfs: float
+
+    @property
+    def duration_samples(self) -> int:
+        return self.end_sample - self.start_sample
+
+
+@dataclass(frozen=True, slots=True)
+class AcousticGap:
+    start_sample: int
+    end_sample: int
+
+    @property
+    def duration_samples(self) -> int:
+        return self.end_sample - self.start_sample
+
+
+@dataclass(frozen=True, slots=True)
+class ActivityReport:
+    sample_rate: int
+    frames: int
+    activity: tuple[ActivityRegion, ...]
+    gaps: tuple[AcousticGap, ...]
+    leading_gap: AcousticGap | None
+    trailing_gap: AcousticGap | None
+
+    @property
+    def duration_seconds(self) -> float:
+        return self.frames / self.sample_rate
+
+    def seconds(self, samples: int) -> float:
+        return samples / self.sample_rate
+
+
+def _dbfs(values: np.ndarray) -> tuple[float, float]:
+    if values.size == 0:
+        return -math.inf, -math.inf
+    rms = float(np.sqrt(np.mean(values.astype(np.float64) ** 2)))
+    peak = float(np.max(np.abs(values)))
+    return (
+        20.0 * math.log10(rms) if rms > 0 else -math.inf,
+        20.0 * math.log10(peak) if peak > 0 else -math.inf,
+    )
+
+
+def _raw_regions(
+    values: np.ndarray,
+    sample_rate: int,
+    config: ActivityConfig,
+) -> list[tuple[int, int]]:
+    frame_size = max(1, round(config.frame_ms * sample_rate / 1000.0))
+    hop_size = max(1, round(config.hop_ms * sample_rate / 1000.0))
+    active = False
+    regions: list[tuple[int, int]] = []
+    start = 0
+    for frame_start in range(0, len(values), hop_size):
+        frame = values[frame_start : frame_start + frame_size]
+        rms_dbfs, _ = _dbfs(frame)
+        if not active and rms_dbfs >= config.active_threshold_dbfs:
+            active = True
+            start = frame_start
+        elif active and rms_dbfs < config.release_threshold_dbfs:
+            end = min(len(values), frame_start + frame_size)
+            regions.append((start, end))
+            active = False
+    if active:
+        regions.append((start, len(values)))
+    minimum = round(config.min_active_ms * sample_rate / 1000.0)
+    return [region for region in regions if region[1] - region[0] >= minimum]
+
+
+def _merge_regions(regions: list[tuple[int, int]], minimum_gap: int) -> list[tuple[int, int]]:
+    merged: list[tuple[int, int]] = []
+    for start, end in regions:
+        if merged and start - merged[-1][1] < minimum_gap:
+            merged[-1] = (merged[-1][0], end)
+        else:
+            merged.append((start, end))
+    return merged
+
+
+def analyze_activity(
+    audio: np.ndarray,
+    sample_rate: int,
+    config: ActivityConfig | None = None,
+) -> ActivityReport:
+    if isinstance(sample_rate, bool) or not isinstance(sample_rate, int) or sample_rate <= 0:
+        raise ValueError("sample_rate must be a positive integer")
+    if config is None:
+        config = ActivityConfig()
+    values = np.asarray(audio, dtype=np.float32)
+    if values.ndim != 1 or not np.all(np.isfinite(values)):
+        raise ValueError("audio must be a finite one-dimensional waveform")
+    raw = _raw_regions(values, sample_rate, config)
+    minimum_gap = round(config.min_gap_ms * sample_rate / 1000.0)
+    merged = _merge_regions(raw, minimum_gap)
+    activity = tuple(ActivityRegion(start, end, *_dbfs(values[start:end])) for start, end in merged)
+    gaps: list[AcousticGap] = []
+    if activity:
+        for left, right in zip(activity, activity[1:], strict=False):
+            gap = AcousticGap(left.end_sample, right.start_sample)
+            if gap.duration_samples >= minimum_gap:
+                gaps.append(gap)
+        leading = (
+            AcousticGap(0, activity[0].start_sample)
+            if activity[0].start_sample >= minimum_gap
+            else None
+        )
+        trailing = (
+            AcousticGap(activity[-1].end_sample, len(values))
+            if len(values) - activity[-1].end_sample >= minimum_gap
+            else None
+        )
+    else:
+        whole = AcousticGap(0, len(values))
+        leading = whole if whole.duration_samples >= minimum_gap else None
+        trailing = None
+    if activity:
+        gaps_with_edges = ([leading] if leading else []) + gaps + ([trailing] if trailing else [])
+    else:
+        gaps_with_edges = [leading] if leading else []
+    return ActivityReport(
+        sample_rate, len(values), activity, tuple(gaps_with_edges), leading, trailing
+    )
+
+
+def measure_gap_near(
+    report: ActivityReport,
+    sample_offset: int,
+    *,
+    search_window_ms: float = 500.0,
+) -> AcousticGap | None:
+    window = round(search_window_ms * report.sample_rate / 1000.0)
+    candidates = [
+        gap
+        for gap in report.gaps
+        if gap.end_sample >= sample_offset - window and gap.start_sample <= sample_offset + window
+    ]
+    if not candidates:
+        return None
+    return min(
+        candidates,
+        key=lambda gap: (
+            0
+            if gap.start_sample <= sample_offset <= gap.end_sample
+            else min(abs(sample_offset - gap.start_sample), abs(sample_offset - gap.end_sample))
+        ),
+    )

audiocompose/cli.py

@@ -0,0 +1,293 @@
+from __future__ import annotations
+
+import argparse
+import html
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+from ._version import __version__
+from .analysis import ActivityConfig, ActivityReport, analyze_activity, measure_gap_near
+from .composer import Composer
+from .errors import AudioComposeError
+from .model import AudioClip, AudioJob, Silence
+from .wav import read_wav
+
+
+def _add_json(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--json", action="store_true", help="write machine-readable JSON")
+
+
+def _add_analysis_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument("--frame-ms", type=float, default=20.0)
+    parser.add_argument("--hop-ms", type=float, default=5.0)
+    parser.add_argument("--active-threshold-dbfs", type=float, default=-40.0)
+    parser.add_argument("--release-threshold-dbfs", type=float, default=-45.0)
+    parser.add_argument("--min-active-ms", type=float, default=30.0)
+    parser.add_argument("--min-gap-ms", type=float, default=60.0)
+    parser.add_argument("--near-marker")
+    parser.add_argument("--window-ms", type=float, default=500.0)
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="audiocompose", description="Compose declarative AudioJob bundles"
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    validate = subparsers.add_parser("validate")
+    validate.add_argument("manifest")
+    _add_json(validate)
+
+    inspect = subparsers.add_parser("inspect")
+    inspect.add_argument("manifest")
+    _add_json(inspect)
+
+    compose = subparsers.add_parser("compose")
+    compose.add_argument("manifest")
+    compose.add_argument("output")
+
+    timeline = subparsers.add_parser("timeline")
+    timeline.add_argument("manifest")
+    _add_json(timeline)
+
+    analyze = subparsers.add_parser("analyze")
+    analyze.add_argument("input")
+    _add_analysis_options(analyze)
+    _add_json(analyze)
+
+    report = subparsers.add_parser("report")
+    report.add_argument("input")
+    report.add_argument("-o", "--output", required=True)
+    _add_analysis_options(report)
+
+    return parser
+
+
+def _analysis_config(args: argparse.Namespace) -> ActivityConfig:
+    return ActivityConfig(
+        frame_ms=args.frame_ms,
+        hop_ms=args.hop_ms,
+        active_threshold_dbfs=args.active_threshold_dbfs,
+        release_threshold_dbfs=args.release_threshold_dbfs,
+        min_active_ms=args.min_active_ms,
+        min_gap_ms=args.min_gap_ms,
+    )
+
+
+def _report_dict(report: ActivityReport) -> dict[str, Any]:
+    def gap_dict(gap: Any) -> dict[str, Any]:
+        return {
+            "start_sample": gap.start_sample,
+            "end_sample": gap.end_sample,
+            "duration_samples": gap.duration_samples,
+            "duration_seconds": report.seconds(gap.duration_samples),
+        }
+
+    return {
+        "sample_rate": report.sample_rate,
+        "frames": report.frames,
+        "duration_seconds": report.duration_seconds,
+        "activity": [
+            {
+                "start_sample": region.start_sample,
+                "end_sample": region.end_sample,
+                "duration_samples": region.duration_samples,
+                "rms_dbfs": region.rms_dbfs,
+                "peak_dbfs": region.peak_dbfs,
+            }
+            for region in report.activity
+        ],
+        "gaps": [gap_dict(gap) for gap in report.gaps],
+        "leading_gap": gap_dict(report.leading_gap) if report.leading_gap else None,
+        "trailing_gap": gap_dict(report.trailing_gap) if report.trailing_gap else None,
+    }
+
+
+def _load_input(path: str) -> tuple[Any, int, AudioJob | None]:
+    if Path(path).suffix.lower() == ".wav":
+        audio, sample_rate = read_wav(path)
+        return audio, sample_rate, None
+    job = AudioJob.load(path)
+    result = Composer().compose(job)
+    return result.audio, result.sample_rate, job
+
+
+def _inspect(job: AudioJob) -> dict[str, Any]:
+    clips = [item for item in job.items if isinstance(item, AudioClip)]
+    silence = [item for item in job.items if isinstance(item, Silence)]
+    loaded = [(item, *item.source.load()) for item in clips]
+    rates = sorted({rate for _, _, rate in loaded})
+    operations = sorted({operation.type for item in clips for operation in item.operations})
+    raw_duration = sum(len(audio) / rate for _, audio, rate in loaded) + sum(
+        item.seconds for item in silence
+    )
+    return {
+        "job_id": job.job_id,
+        "producer": dict(job.producer),
+        "clips": len(clips),
+        "silence": len(silence),
+        "source_sample_rates": rates,
+        "operations": operations,
+        "expected_output_rate": job.output.sample_rate,
+        "total_raw_duration": raw_duration,
+        "loudness": {
+            "target_lufs": job.output.loudness.target_lufs,
+            "true_peak_ceiling_dbtp": job.output.loudness.true_peak_ceiling_dbtp,
+        },
+    }
+
+
+def _timeline(job: AudioJob) -> dict[str, Any]:
+    result = Composer().compose(job)
+    return {
+        "sample_rate": result.sample_rate,
+        "items": [
+            {
+                "id": item.item_id,
+                "kind": item.kind,
+                "start_sample": item.start_sample,
+                "end_sample": item.end_sample,
+            }
+            for item in result.items
+        ],
+        "markers": [
+            {
+                "id": marker.id,
+                "item_id": marker.item_id,
+                "sample_offset": marker.sample_offset,
+                "name": marker.name,
+            }
+            for marker in result.markers
+        ],
+        "spans": [
+            {
+                "item_id": span.item_id,
+                "source_start": span.source_start,
+                "source_end": span.source_end,
+                "sample_start": span.sample_start,
+                "sample_end": span.sample_end,
+            }
+            for span in result.spans
+        ],
+    }
+
+
+def _svg_report(audio: Any, report: ActivityReport, job: AudioJob | None) -> str:
+    width = 1000
+    height = 260
+    scale = width / max(1, len(audio))
+    lines: list[str] = [f'<svg viewBox="0 0 {width} {height}" role="img">']
+    lines.append('<rect width="100%" height="100%" fill="white"/>')
+    for gap in report.gaps:
+        x = gap.start_sample * scale
+        w = max(1.0, gap.duration_samples * scale)
+        lines.append(f'<rect x="{x:.2f}" y="20" width="{w:.2f}" height="180" fill="#fee2e2"/>')
+    if len(audio):
+        step = max(1, len(audio) // width)
+        points = []
+        for index in range(0, len(audio), step):
+            values = audio[index : index + step]
+            points.append(f"{index * scale:.2f},{130 - float(max(abs(values))) * 100:.2f}")
+        lines.append(
+            f'<polyline points="{" ".join(points)}" fill="none" stroke="#1d4ed8" stroke-width="1"/>'
+        )
+    for region in report.activity:
+        x = region.start_sample * scale
+        w = max(1.0, region.duration_samples * scale)
+        lines.append(f'<rect x="{x:.2f}" y="205" width="{w:.2f}" height="20" fill="#86efac"/>')
+    lines.append("</svg>")
+    payload = json.dumps(_report_dict(report), indent=2, sort_keys=True)
+    title = "AudioCompose activity report"
+    if job is not None:
+        title += f" ({job.job_id})"
+    return (
+        '<!doctype html><html><head><meta charset="utf-8"><title>'
+        + html.escape(title)
+        + "</title></head><body>"
+        + f"<h1>{html.escape(title)}</h1>"
+        + "<p>Green regions are detected audio activity. Red regions are acoustic gaps.</p>"
+        + "<section>"
+        + "".join(lines)
+        + "</section><pre>"
+        + html.escape(payload)
+        + "</pre></body></html>\n"
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        if args.command == "validate":
+            validated_job = AudioJob.load(args.manifest)
+            result = {
+                "valid": True,
+                "format": "audiojob",
+                "schema_version": 1,
+                "job_id": validated_job.job_id,
+            }
+            if args.json:
+                print(json.dumps(result, indent=2, sort_keys=True))
+            else:
+                print(f"valid AudioJob: {args.manifest}")
+        elif args.command == "inspect":
+            result = _inspect(AudioJob.load(args.manifest))
+            print(json.dumps(result, indent=2, sort_keys=True))
+        elif args.command == "compose":
+            Composer().to_wav(AudioJob.load(args.manifest), args.output)
+            print(f"wrote {args.output}")
+        elif args.command == "timeline":
+            result = _timeline(AudioJob.load(args.manifest))
+            print(json.dumps(result, indent=2, sort_keys=True))
+        elif args.command in {"analyze", "report"}:
+            audio, sample_rate, job = _load_input(args.input)
+            report = analyze_activity(audio, sample_rate, _analysis_config(args))
+            if args.command == "analyze":
+                result = _report_dict(report)
+                if args.near_marker:
+                    if job is None:
+                        raise AudioComposeError("--near-marker requires an AudioJob input")
+                    timeline = Composer().compose(job)
+                    marker = next(
+                        (marker for marker in timeline.markers if marker.id == args.near_marker),
+                        None,
+                    )
+                    if marker is None:
+                        raise AudioComposeError(f"unknown marker: {args.near_marker}")
+                    gap = measure_gap_near(
+                        report, marker.sample_offset, search_window_ms=args.window_ms
+                    )
+                    result["near_marker"] = args.near_marker
+                    result["near_gap"] = (
+                        _report_dict(
+                            ActivityReport(
+                                report.sample_rate,
+                                report.frames,
+                                (),
+                                (gap,) if gap else (),
+                                gap,
+                                gap,
+                            )
+                        )["leading_gap"]
+                        if gap
+                        else None
+                    )
+                print(json.dumps(result, indent=2, sort_keys=True))
+            else:
+                Path(args.output).write_text(_svg_report(audio, report, job), encoding="utf-8")
+                print(f"wrote {args.output}")
+        return 0
+    except (AudioComposeError, ValueError, OSError) as exc:
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {"valid": False, "errors": [{"code": "validation_error", "message": str(exc)}]},
+                    indent=2,
+                ),
+                file=sys.stderr,
+            )
+        else:
+            print(f"audiocompose: {exc}", file=sys.stderr)
+        return 2