audioexport 0.1.0__py3-none-any.whl

audioexport/__init__.py

@@ -0,0 +1,44 @@
+"""Standalone audio export; no import of Readio or AudioCompose."""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+from .chapters import Chapter, load_chapters
+from .errors import (
+    AudioExportError,
+    EncodingError,
+    InvalidExportError,
+    ToolNotFoundError,
+    VerificationError,
+)
+from .fftools import doctor, probe
+from .formats import FORMATS, normalize_bitrate
+from .pipeline import ExportResult, encode, run_profile
+from .profile import ExportProfile, OutputSpec, load_profile
+
+try:
+    __version__ = version("audioexport")
+except PackageNotFoundError:
+    __version__ = "0+uninstalled"
+
+__all__ = [
+    "FORMATS",
+    "AudioExportError",
+    "Chapter",
+    "EncodingError",
+    "ExportProfile",
+    "ExportResult",
+    "InvalidExportError",
+    "OutputSpec",
+    "ToolNotFoundError",
+    "VerificationError",
+    "__version__",
+    "doctor",
+    "encode",
+    "load_chapters",
+    "load_profile",
+    "normalize_bitrate",
+    "probe",
+    "run_profile",
+]

audioexport/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

audioexport/_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 = None

audioexport/api.py

@@ -0,0 +1,36 @@
+"""Stable library API import surface (also available from `audioexport`)."""
+
+from __future__ import annotations
+
+from .chapters import Chapter, load_chapters
+from .errors import (
+    AudioExportError,
+    EncodingError,
+    InvalidExportError,
+    ToolNotFoundError,
+    VerificationError,
+)
+from .fftools import doctor, probe
+from .formats import FORMATS, normalize_bitrate
+from .pipeline import ExportResult, encode, run_profile
+from .profile import ExportProfile, OutputSpec, load_profile
+
+__all__ = [
+    "FORMATS",
+    "AudioExportError",
+    "Chapter",
+    "EncodingError",
+    "ExportProfile",
+    "ExportResult",
+    "InvalidExportError",
+    "OutputSpec",
+    "ToolNotFoundError",
+    "VerificationError",
+    "doctor",
+    "encode",
+    "load_chapters",
+    "load_profile",
+    "normalize_bitrate",
+    "probe",
+    "run_profile",
+]

audioexport/chapters.py

@@ -0,0 +1,159 @@
+"""Portable chapter input plus optional Readio composition-timeline adapter."""
+
+from __future__ import annotations
+
+import json
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .errors import InvalidExportError
+
+
+@dataclass(frozen=True, slots=True)
+class Chapter:
+    title: str
+    start_ms: int
+    end_ms: int | None = None
+    start_sample: int | None = None
+    end_sample: int | None = None
+    sample_rate: int | None = None
+
+
+def escape_ffmetadata_value(value: str) -> str:
+    """Ported from Readio: escape FFmetadata delimiters and newlines."""
+    value = value.replace("\\", "\\\\").replace("=", "\\=")
+    value = value.replace(";", "\\;").replace("#", "\\#")
+    return value.replace("\r\n", "\n").replace("\r", "\n").replace("\n", "\\n")
+
+
+def _milliseconds(value: Any, field: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, (float, int)) or not math.isfinite(value):
+        raise InvalidExportError(f"invalid chapter {field}", code="audioexport.chapters_invalid")
+    # generic chapter schema uses integer millisecond offsets
+    if int(value) != value:
+        raise InvalidExportError(
+            f"chapter {field} must be whole milliseconds", code="audioexport.chapters_invalid"
+        )
+    return int(value)
+
+
+def load_chapters(timeline: Path | str) -> tuple[Chapter, ...]:
+    """Read JSON {chapters: [{title,start_ms,end_ms?}]} or Readio start_sample timeline."""
+    path = Path(timeline)
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError) as exc:
+        raise InvalidExportError(
+            f"invalid timeline {path}: {exc}", code="audioexport.timeline_invalid"
+        ) from exc
+    if not isinstance(data, dict) or not isinstance(data.get("chapters"), list):
+        raise InvalidExportError(
+            "timeline must have chapters array", code="audioexport.timeline_invalid"
+        )
+    chapters = []
+    sample_rate = data.get("sample_rate")
+    for index, row in enumerate(data["chapters"], 1):
+        if not isinstance(row, dict):
+            raise InvalidExportError("invalid chapter row", code="audioexport.chapters_invalid")
+        title = row.get("title") or f"Chapter {index}"
+        if not isinstance(title, str) or not title.strip():
+            raise InvalidExportError("invalid chapter title", code="audioexport.chapters_invalid")
+        if "start_sample" in row:
+            if (
+                isinstance(sample_rate, bool)
+                or not isinstance(sample_rate, int)
+                or sample_rate <= 0
+            ):
+                raise InvalidExportError(
+                    "sample chapter requires sample_rate", code="audioexport.chapters_invalid"
+                )
+            sample = row["start_sample"]
+            if isinstance(sample, bool) or not isinstance(sample, int):
+                raise InvalidExportError(
+                    "invalid start_sample", code="audioexport.chapters_invalid"
+                )
+            start_ms = round(sample * 1000 / sample_rate)
+            end_ms = None
+            chapters.append(Chapter(title.strip(), start_ms, end_ms, sample, None, sample_rate))
+            continue
+        else:
+            start_ms = _milliseconds(row.get("start_ms"), "start_ms")
+            end_ms = _milliseconds(row["end_ms"], "end_ms") if "end_ms" in row else None
+        chapters.append(Chapter(title.strip(), start_ms, end_ms))
+    return tuple(chapters)
+
+
+def normalize_chapters(chapters: Sequence[Chapter], duration_ms: int) -> tuple[Chapter, ...]:
+    if not chapters:
+        return ()
+    if duration_ms <= 0:
+        raise InvalidExportError(
+            "audio duration must be positive", code="audioexport.chapters_invalid"
+        )
+    normalized = []
+    for index, chapter in enumerate(chapters):
+        next_start = chapters[index + 1].start_ms if index + 1 < len(chapters) else duration_ms
+        end_ms = chapter.end_ms if chapter.end_ms is not None else next_start
+        if (
+            not isinstance(chapter.title, str)
+            or not chapter.title.strip()
+            or chapter.start_ms < 0
+            or chapter.start_ms >= duration_ms
+            or end_ms <= chapter.start_ms
+            or end_ms > duration_ms
+            or (index > 0 and chapter.start_ms <= chapters[index - 1].start_ms)
+            or (index + 1 < len(chapters) and end_ms > next_start)
+        ):
+            raise InvalidExportError(
+                "chapters must be ordered, non-overlapping and within audio duration",
+                code="audioexport.chapters_invalid",
+            )
+        end_sample = None
+        if chapter.start_sample is not None:
+            if chapter.sample_rate is None or chapter.sample_rate <= 0:
+                raise InvalidExportError(
+                    "sample chapter requires sample_rate", code="audioexport.chapters_invalid"
+                )
+            if index + 1 < len(chapters) and chapters[index + 1].start_sample is not None:
+                end_sample = chapters[index + 1].start_sample
+            else:
+                end_sample = round(end_ms * chapter.sample_rate / 1000)
+        normalized.append(
+            Chapter(
+                chapter.title,
+                chapter.start_ms,
+                end_ms,
+                chapter.start_sample,
+                end_sample,
+                chapter.sample_rate,
+            )
+        )
+    return tuple(normalized)
+
+
+def ffmetadata_text(chapters: Sequence[Chapter]) -> str:
+    lines = [";FFMETADATA1", ""]
+    for chapter in chapters:
+        assert chapter.end_ms is not None
+        if (
+            chapter.sample_rate
+            and chapter.start_sample is not None
+            and chapter.end_sample is not None
+        ):
+            timebase, start, end = chapter.sample_rate, chapter.start_sample, chapter.end_sample
+        else:
+            timebase, start, end = 1000, chapter.start_ms, chapter.end_ms
+        lines.extend(
+            (
+                "[CHAPTER]",
+                f"TIMEBASE=1/{timebase}",
+                f"START={start}",
+                f"END={end}",
+                f"title={escape_ffmetadata_value(chapter.title)}",
+                "",
+            )
+        )
+    return "\n".join(lines)

audioexport/cli.py

@@ -0,0 +1,141 @@
+"""CLI delegates to the same public library API."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+from typing import Any
+
+from . import __version__
+from .errors import AudioExportError
+from .fftools import doctor, probe
+from .formats import FORMATS
+from .pipeline import encode, run_profile
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="audioexport", description="Standalone FFmpeg audio encoder"
+    )
+    parser.add_argument("--version", action="version", version=f"audioexport {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+    encode_parser = sub.add_parser(
+        "encode", help="Encode one input to MP3/FLAC/M4A/M4B/OGG/Opus/WAV"
+    )
+    encode_parser.add_argument("input", type=Path)
+    encode_parser.add_argument("-o", "--output", type=Path)
+    encode_parser.add_argument("--format", choices=tuple(FORMATS))
+    encode_parser.add_argument("--bitrate", help="Bitrate e.g. 192k (lossy only)")
+    encode_parser.add_argument("--title")
+    encode_parser.add_argument("--artist")
+    encode_parser.add_argument("--album")
+    encode_parser.add_argument("--metadata", action="append", default=[], metavar="KEY=VALUE")
+    encode_parser.add_argument("--cover", type=Path)
+    encode_parser.add_argument(
+        "--timeline", type=Path, help="Generic JSON chapters or Readio timeline"
+    )
+    encode_parser.add_argument("--force", action="store_true")
+    encode_parser.add_argument("--json", action="store_true")
+    encode_parser.add_argument("--ffmpeg")
+    encode_parser.add_argument("--ffprobe")
+
+    run_parser = sub.add_parser("run", help="Encode several outputs from an export TOML profile")
+    run_parser.add_argument("input", type=Path)
+    run_parser.add_argument("--profile", type=Path, required=True)
+    run_parser.add_argument("--out-dir", type=Path, required=True)
+    run_parser.add_argument("--force", action="store_true")
+    run_parser.add_argument("--json", action="store_true")
+    run_parser.add_argument("--ffmpeg")
+    run_parser.add_argument("--ffprobe")
+
+    inspect = sub.add_parser("inspect", help="Inspect audio and audioexport sidecar")
+    inspect.add_argument("input", type=Path)
+    inspect.add_argument("--json", action="store_true")
+    inspect.add_argument("--ffprobe")
+    doctor_parser = sub.add_parser("doctor", help="Check FFmpeg tools and encoders")
+    doctor_parser.add_argument("--json", action="store_true")
+    doctor_parser.add_argument("--ffmpeg")
+    doctor_parser.add_argument("--ffprobe")
+    return parser
+
+
+def _print(payload: Any, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(payload, indent=2, ensure_ascii=False, sort_keys=True))
+    else:
+        print(json.dumps(payload, indent=2, ensure_ascii=False))
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "doctor":
+            data = doctor(ffmpeg=args.ffmpeg, ffprobe=args.ffprobe)
+            _print(data, as_json=args.json)
+            return 0 if data["ready"] else 1
+        if args.command == "inspect":
+            data = probe(args.input, args.ffprobe)
+            manifest = args.input.with_name(args.input.name + ".audioexport.json")
+            if manifest.is_file():
+                try:
+                    data["audioexport"] = json.loads(manifest.read_text(encoding="utf-8"))
+                except ValueError:
+                    data["audioexport"] = {"invalid_manifest": True}
+            _print(data, as_json=args.json)
+            return 0
+        if args.command == "encode":
+            fmt = args.format or (args.output.suffix.lstrip(".").lower() if args.output else None)
+            if fmt is None:
+                parser.error("encode requires --format or --output with an audio extension")
+            output = args.output or args.input.with_suffix(FORMATS[fmt].extension)
+            metadata = {}
+            for item in args.metadata:
+                if "=" not in item:
+                    parser.error("--metadata requires KEY=VALUE")
+                key, value = item.split("=", 1)
+                metadata[key] = value
+            for field in ("title", "artist", "album"):
+                value = getattr(args, field)
+                if value is not None:
+                    metadata[field] = value
+            result = encode(
+                args.input,
+                output,
+                format=fmt,
+                bitrate=args.bitrate,
+                metadata=metadata,
+                cover=args.cover,
+                timeline=args.timeline,
+                force=args.force,
+                ffmpeg=args.ffmpeg,
+                ffprobe=args.ffprobe,
+            )
+            _print(result.to_dict(), as_json=args.json)
+            return 0
+        if args.command == "run":
+            results = run_profile(
+                args.input,
+                args.profile,
+                args.out_dir,
+                force=args.force,
+                ffmpeg=args.ffmpeg,
+                ffprobe=args.ffprobe,
+            )
+            _print([item.to_dict() for item in results], as_json=args.json)
+            return 0
+    except (AudioExportError, OSError, FileExistsError, ValueError, KeyError) as exc:
+        code = exc.code if isinstance(exc, AudioExportError) else "audioexport.error"
+        if getattr(args, "json", False):
+            _print({"error": {"code": code, "message": str(exc)}}, as_json=True)
+        else:
+            print(f"audioexport: {code}: {exc}", file=sys.stderr)
+        return 2
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

audioexport/errors.py

@@ -0,0 +1,25 @@
+"""Stable public exceptions suitable for API consumers."""
+
+from __future__ import annotations
+
+
+class AudioExportError(Exception):
+    def __init__(self, message: str, *, code: str = "audioexport.error") -> None:
+        super().__init__(message)
+        self.code = code
+
+
+class InvalidExportError(AudioExportError, ValueError):
+    pass
+
+
+class ToolNotFoundError(AudioExportError):
+    pass
+
+
+class EncodingError(AudioExportError):
+    pass
+
+
+class VerificationError(AudioExportError):
+    pass