audioexport 0.1.2__tar.gz → 0.1.4__tar.gz

{audioexport-0.1.2 → audioexport-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: audioexport
-Version: 0.1.2
+Version: 0.1.4
 Summary: Standalone FFmpeg audio encoder with metadata, chapter, cover and reproducible export manifests
 Author: audioexport contributors
 License-Expression: Apache-2.0
@@ -33,7 +33,7 @@ Dynamic: license-file
 
 # audioexport
 
-An independent Python library and command-line interface for exporting audio through **FFmpeg**. This is the first extraction step from Readio's output/encoding subsystem, but **audioexport does not import or install Readio, AudioCompose, UtterPlan, or synthesis engines**.
+AudioExport is a standalone Python library and CLI for verified FFmpeg audio export.
 
 Supported formats: WAV (PCM16), FLAC, MP3, M4A (AAC), M4B (AAC audiobook), OGG (Vorbis), and Opus. Handles tagged metadata, embedded JPEG/PNG cover art for MP3/M4A/M4B, JSON chapter timelines for M4A/M4B, standalone ordered multi-track audiobook assembly, FFprobe verification, artifact identities and safe reuse.
 
@@ -57,7 +57,7 @@ audioexport doctor --json
 
 `doctor` reports package/tool versions and encoder availability per format. Its existing `ready` key means FFmpeg and FFprobe are present; `all_formats_ready` and each `formats` entry report encoder capability and a reason when unavailable. The additive `features` entries report `m4b_encode`, `m4b_audiobook`, and `m4b_stream_copy` availability; missing optional capabilities do not make `ready` false. `run_profile()` checks the encoders selected by the profile before writing outputs.
 
-Base Python dependencies are `langcodes>=3.3` on all supported versions and `tomli>=2` on Python 3.10. FFmpeg/FFprobe are external executables; AudioExport does not install or import Readio, AudioCompose, UtterPlan, VoiceRender, soundfile, or NumPy.
+Base Python dependencies are `langcodes>=3.3` on all supported versions and `tomli>=2` on Python 3.10. FFmpeg/FFprobe are external executables; AudioExport has no runtime dependency on synthesis, planning, or composition packages.
 
 ## CLI quickstart
 
@@ -96,7 +96,7 @@ audioexport audiobook book-tracks/ -o book.m4b \
 audioexport audiobook 01-intro.mp3 02-chapter-one.flac 03-chapter-two.wav \
   -o book.m4b --bitrate 96k --language eng
 
-# Explicit chapter starts from chapters.txt or the existing JSON/Readio timeline format.
+# Explicit chapter starts from chapters.txt or a generic JSON timeline.
 audioexport audiobook book-tracks/ -o book.m4b --chapters-file chapters.txt
 ```
 
@@ -147,29 +147,43 @@ mode = "explicit"       # tracks | explicit | none
 # title_source = "tag"  # tag (falls back to filename) | filename
 ```
 
-Run it with `audioexport audiobook --profile audiobook.toml`. CLI `--output`, metadata, audio settings, cover, and `--chapters-file` override profile values; the TOML input order remains authoritative. `mode = "tracks"` (the default) creates one chapter per track; `mode = "explicit"` requires `chapters_file`; `mode = "none"` disables chapters. Existing `encode(..., format="m4b", timeline=...)` remains the right choice for Readio's prepared master and project timeline.
+Run it with `audioexport audiobook --profile audiobook.toml`. CLI `--output`, metadata, audio settings, cover, and `--chapters-file` override profile values; the TOML input order remains authoritative. `mode = "tracks"` (the default) creates one chapter per track; `mode = "explicit"` requires `chapters_file`; `mode = "none"` disables chapters. Existing `encode(..., format="m4b", timeline=...)` remains the right choice for one prepared source with caller-supplied chapters.
 
-## Native `.ssmdbook` pipeline
+## SSMD bundle export
 
-Use `export-book` when AudioCompose has already written a variant in a standard `.ssmdbook` workspace. It is the native book-workspace adapter; `audioexport audiobook` remains the generic standalone track/directory assembler, and `encode` remains for one prepared source with a timeline.
+Book and single-document workspaces share one canonical editable directory root, `<name>.ssmd-bundle/`. The manifest selects the export path: `format = "ssmdconvert.book"` uses verified audiobook assembly, while `format = "ssmdconvert.document"` uses verified one-document encoding; both manifest schemas remain at version 1. AudioExport accepts only the bundle root, not an internal chapter directory, the document source file, or a ZIP archive.
+
+Use the same command for either kind:
 
 ```bash
-audiocompose compose-book . --variant "$VARIANT"
-audioexport export-book . --variant "$VARIANT"
+audiocompose bundle compose "My Book.ssmd-bundle" --variant "$VARIANT"
+audioexport bundle export "My Book.ssmd-bundle" --variant "$VARIANT" \
+  --chapters 5,7,11-13 --audiocompose-root /srv/audio-stages/audiocompose \
+  --output-root /srv/audio-exports --title "My Book" --author "An Author" \
+  --language en-US
+
+audioexport bundle export story.ssmd-bundle --variant "$VARIANT" \
+  --output story.m4a --title "Story" --artist "An Author"
 ```
 
-`export-book` reads `manifest.json` and `audiocompose/<variant>/compose-report.toml`, accepts the producer's singular `[[item]]` tables (and legacy `[[items]]` tables), validates selected entries and WAV checksums/geometry with bare or `sha256:`-prefixed digests, then delegates final M4B assembly and verification to AudioExport. It does not run AudioCompose, repair or synthesize chapters, or use Readio-specific state. Chapter selection accepts `all` (the default), a source number, an inclusive range, or comma-separated source numbers/ranges, for example `--chapters 5,7,11-13`. Selection follows manifest chapter order.
+AudioExport verifies the selected AudioCompose report, output paths, WAV checksums, and audio geometry before exporting. For a book, `--chapters` selects manifest chapters (`all` by default), output defaults to M4B, `--format` accepts only `m4b`, and audiobook profiles remain supported. For a document, only `--chapters all` is valid; `--format` or the output filename extension selects the final format, and `--timeline` supplies an optional generic chapter timeline. `--author` and `--artist` are aliases for the appropriate author/artist metadata field. Kind-specific options that have no meaning for the selected manifest are rejected rather than ignored.
 
-For M4A/M4B, language metadata is written on the audio track using ISO 639-2/T. BCP 47 tags such as `en-US` are normalized to their three-letter track code (`eng`).
+Default output names strip only `.ssmd-bundle`: books use `audioexport/<variant>/<name>.m4b`, while documents use `audioexport/<variant>/<name>.<format>`. `--output-root` relocates these defaults; `--output` selects an explicit destination. Book metadata precedence is manifest, then audiobook profile, then explicit CLI/API values. BCP 47 language tags such as `en-US` are normalized to ISO 639-2/T track codes such as `eng` for M4A/M4B.
 
-By default, output is written to `audioexport/<variant>/<workspace-name-without-.ssmdbook>.m4b` in the workspace. `--output` may override this; when an audiobook profile is supplied, its output is used unless `--output` is specified.
+The JSON result uses one versioned envelope with `format: "audioexport-bundle-result"`, `version: 1`, `kind`, and a kind-specific `result` object. Human output begins with `AudioExport bundle export` and reports the selected kind, workspace, variant, and output.
 
-Metadata precedence is **manifest metadata < audiobook profile metadata < explicit CLI/API metadata**. Audio settings use **AudioExport defaults < audiobook profile < explicit CLI/API flags**. Thus explicit metadata fields replace matching profile/manifest values, profile values replace manifest defaults, and unset values continue to fall through. Explicit cover and audio flags override corresponding profile settings. The profile's inputs and chapter configuration do not replace the variant chapters selected from the compose report.
+Python callers use the same manifest-dispatched facade:
 
-If `--output` is not set for `encode`, the output filename defaults to the input stem and chosen format. To avoid destroying the input, encoding input and output to the same real path is always rejected.
+```python
+from audioexport import export_bundle
 
-Without `--force`, an untracked, symlink, or manually modified output is never overwritten. A previously generated output is updated when its sidecar and checksum still match; re-running identical options returns `reused: true` without re-encoding. `--force` authorizes replacing an unknown or modified regular file, but symlink outputs and sidecars are always rejected. Writes are staged with their manifest; a failed manifest commit restores the last good pair when possible, and an incomplete recovery reports the preserved backup path. A per-target process lock rejects concurrent writers with `audioexport.output_busy`; remove a stale lock only after confirming no writer is active.
+book_result = export_bundle("My Book.ssmd-bundle", variant=variant, chapters="5,7")
+document_result = export_bundle("story.ssmd-bundle", variant=variant, format="mp3")
+print(book_result.kind, book_result.output)
+print(document_result.kind, document_result.output)
+```
 
+`BundleExportResult.value` contains the specialized book or document result; `BundleExportResult.output` gives the final artifact path. The facade is available from both `audioexport` and `audioexport.api`.
 OGG defaults to Vorbis quality-based encoding (`-qscale:a 4`) to avoid low-rate/mono bitrate incompatibilities. `--bitrate` accepts values such as `192k`, `192000`, or `1M`; whitespace is trimmed. A bare integer is interpreted as **bits per second**, so use `192k` (or `192000`), not `192`, for a nominal 192 kb/s rate. WAV/FLAC don't accept bitrate. WAV output is always PCM16 conversion, not a byte-for-byte passthrough; lossy codecs and even PCM output can vary with FFmpeg versions, which are included in the export identity.
 
 ## Python API
@@ -203,7 +217,7 @@ print(probe("exported/book.m4b")["chapters"])
 
 You may import the same public functions from `audioexport.api` as well as from `audioexport`.
 
-The public errors are `AudioExportError` and subclasses `InvalidExportError`, `ToolNotFoundError`, `EncodingError`, and `VerificationError`, with a stable machine-readable `.code` value. `encode()` returns an immutable `ExportResult`; `build_audiobook()` returns an `AudiobookResult`; `export_book()` and `resolve_book_export()` provide verified composed-book export through `BookExportContext`, `BookExportResult`, and `ComposedChapter`. These symbols, like the other public functions, are available from both `audioexport` and `audioexport.api`.
+The public errors are `AudioExportError` and subclasses `InvalidExportError`, `ToolNotFoundError`, `EncodingError`, and `VerificationError`, with a stable machine-readable `.code` value. `encode()` returns an immutable `ExportResult`; `build_audiobook()` returns an `AudiobookResult`; `export_bundle()` provides one manifest-dispatched entry point for verified book and document bundles and returns `BundleExportResult`. The facade and result types are available from both `audioexport` and `audioexport.api`.
 
 ## Export profile
 
@@ -279,7 +293,7 @@ resolved_outputs = preflight_profile(profile, source)
 
 for resolved in resolved_outputs:
     target = Path("exports") / resolved.filename
-    # A consumer such as Readio performs its target/ownership/overwrite checks here.
+    # Applications should perform their own target and overwrite checks here.
     result = encode(
         source,
         target,
@@ -291,7 +305,7 @@ for resolved in resolved_outputs:
     )
 ```
 
-A consumer may instead call `resolve_output()` for a single selected spec; use full-profile preflight when the operation requires every configured output validated. Preflight is not an ownership authorization: Readio remains responsible for project locks and freshness, destination selection and collision/ownership checks, overwrite authorization, state/index updates, result types, and partial-batch bookkeeping. Call `encode()` only after those consumer-owned checks pass. `ResolvedOutput`, `resolve_output`, and `preflight_profile` are available from both `audioexport` and `audioexport.api`.
+A consumer may instead call `resolve_output()` for a single selected spec; use full-profile preflight when the operation requires every configured output validated. Preflight is not an ownership authorization: applications remain responsible for their own locks, target selection, overwrite authorization, and state updates. Call `encode()` only after those consumer-owned checks pass. `ResolvedOutput`, `resolve_output`, and `preflight_profile` are available from both `audioexport` and `audioexport.api`.
 
 ## Chapters/timeline
 
@@ -308,7 +322,7 @@ Use an independent JSON file such as [`examples/chapters.json`](examples/chapter
 
 `end_ms` is optional; without it, chapter ends are the next chapter start or the audio duration. Chapter offsets must be strictly increasing and within the audio file. FFmpeg metadata escaping is handled internally. Embedded chapter markers are currently supported for **M4A and M4B**.
 
-For an incremental Readio migration, the same `--timeline` API also reads **Readio's `readio.composition-timeline` JSON** with `sample_rate` and chapter `start_sample`. FFmetadata is constructed with its original sample timebase for precision, with generic millisecond chapter fields available for non-Readio workflows.
+Exact-sample timelines may include a top-level `sample_rate` and chapter `start_sample` values. FFmetadata preserves their original sample timebase and coordinates using `TIMEBASE=1/<sample_rate>`.
 
 ## Integrity and versioning
 
@@ -320,10 +334,6 @@ Version is dynamic through `setuptools-scm`: `pyproject.toml` has no static `ver
 
 For a release, first commit the code and wait for the complete Linux/Windows/macOS, Python 3.10–3.14 CI matrix, including its Sphinx warning-as-error documentation build. Then create and push the intended version tag (for example `v0.1.2`). Manually dispatch the GitHub Actions workflow named **Release** with that existing tag. It reruns the full supported-Python test matrix, checks the tag against wheel/sdist metadata, inspects package contents, installs the wheel outside the checkout, and checks CLI/API version parity. Publishing uses the configured `PYPI_API_TOKEN` secret after approval in the `pypi` GitHub environment; repository administrators must ensure the token and environment approval rules are configured. Do not publish from an untagged/fallback build.
 
-## Readio migration
-
-**Readio is deliberately not patched by this project.** Its existing export commands continue using their current code until an opt-in bridge is tested. A future integration must call AudioExport's Python library API; it must never launch the `audioexport` CLI as a subprocess. See [`docs/readio-migration.md`](docs/readio-migration.md) for the compatibility boundary, integration order, and rollback rules. Readio continues owning project locks, path defaults, staleness, indexed state, and orchestration.
-
 ## Tests
 
 ```bash
@@ -339,11 +349,11 @@ python scripts/check_package_artifacts.py
 audioexport doctor --json
 ```
 
-Tests cover seven real formats in one profile, mixed-format audiobook assembly, 100-track ordering/chapters, audiobook cache invalidation, M4A/M4B chapters and covers, Readio sample timelines, malformed probes, encoder availability, transactional failure recovery, no-clobber behavior, and concurrent writers. Normal CI runs Python 3.10–3.14 on Linux, Windows, and macOS, and checks tests, lint, formatting, typing, build metadata, Twine, package contents, and isolated wheel installation. CI also builds the Sphinx documentation on Linux/Python 3.13 with warnings treated as errors. The manually dispatched **Release** workflow retests the full supported Python range before packaging and API-token publishing. Cross-platform encoder availability depends on the FFmpeg build installed by each runner.
+Tests cover seven real formats in one profile, mixed-format audiobook assembly, 100-track ordering/chapters, audiobook cache invalidation, M4A/M4B chapters and covers, exact-sample chapter timelines, malformed probes, encoder availability, transactional failure recovery, no-clobber behavior, and concurrent writers. Normal CI runs Python 3.10–3.14 on Linux, Windows, and macOS, and checks tests, lint, formatting, typing, build metadata, Twine, package contents, and isolated wheel installation. CI also builds the Sphinx documentation on Linux/Python 3.13 with warnings treated as errors. The manually dispatched **Release** workflow retests the full supported Python range before packaging and API-token publishing. Cross-platform encoder availability depends on the FFmpeg build installed by each runner.
 
 ## Limitations (MVP)
 
-No audio mastering, TTS, audio mixing, streaming PCM API, FFmpeg filter graphs, network service, or GUI. No automatic conversion of Readio project configs, legacy export cache, or Audiocompose timeline semantics other than chapter starts. Encoder output may vary across FFmpeg versions; the cache key includes tool versions. Chapter verification has a small tolerance for FFmpeg container timebase rounding. Standalone encoding does not modify Readio projects.
+No audio mastering, TTS, audio mixing, streaming PCM API, FFmpeg filter graphs, network service, or GUI. Encoder output may vary across FFmpeg versions; the export identity includes tool versions. Chapter verification tolerates small FFmpeg container timebase rounding.
 
 ## License
 

{audioexport-0.1.2 → audioexport-0.1.4}/README.md

@@ -1,6 +1,6 @@
 # audioexport
 
-An independent Python library and command-line interface for exporting audio through **FFmpeg**. This is the first extraction step from Readio's output/encoding subsystem, but **audioexport does not import or install Readio, AudioCompose, UtterPlan, or synthesis engines**.
+AudioExport is a standalone Python library and CLI for verified FFmpeg audio export.
 
 Supported formats: WAV (PCM16), FLAC, MP3, M4A (AAC), M4B (AAC audiobook), OGG (Vorbis), and Opus. Handles tagged metadata, embedded JPEG/PNG cover art for MP3/M4A/M4B, JSON chapter timelines for M4A/M4B, standalone ordered multi-track audiobook assembly, FFprobe verification, artifact identities and safe reuse.
 
@@ -24,7 +24,7 @@ audioexport doctor --json
 
 `doctor` reports package/tool versions and encoder availability per format. Its existing `ready` key means FFmpeg and FFprobe are present; `all_formats_ready` and each `formats` entry report encoder capability and a reason when unavailable. The additive `features` entries report `m4b_encode`, `m4b_audiobook`, and `m4b_stream_copy` availability; missing optional capabilities do not make `ready` false. `run_profile()` checks the encoders selected by the profile before writing outputs.
 
-Base Python dependencies are `langcodes>=3.3` on all supported versions and `tomli>=2` on Python 3.10. FFmpeg/FFprobe are external executables; AudioExport does not install or import Readio, AudioCompose, UtterPlan, VoiceRender, soundfile, or NumPy.
+Base Python dependencies are `langcodes>=3.3` on all supported versions and `tomli>=2` on Python 3.10. FFmpeg/FFprobe are external executables; AudioExport has no runtime dependency on synthesis, planning, or composition packages.
 
 ## CLI quickstart
 
@@ -63,7 +63,7 @@ audioexport audiobook book-tracks/ -o book.m4b \
 audioexport audiobook 01-intro.mp3 02-chapter-one.flac 03-chapter-two.wav \
   -o book.m4b --bitrate 96k --language eng
 
-# Explicit chapter starts from chapters.txt or the existing JSON/Readio timeline format.
+# Explicit chapter starts from chapters.txt or a generic JSON timeline.
 audioexport audiobook book-tracks/ -o book.m4b --chapters-file chapters.txt
 ```
 
@@ -114,29 +114,43 @@ mode = "explicit"       # tracks | explicit | none
 # title_source = "tag"  # tag (falls back to filename) | filename
 ```
 
-Run it with `audioexport audiobook --profile audiobook.toml`. CLI `--output`, metadata, audio settings, cover, and `--chapters-file` override profile values; the TOML input order remains authoritative. `mode = "tracks"` (the default) creates one chapter per track; `mode = "explicit"` requires `chapters_file`; `mode = "none"` disables chapters. Existing `encode(..., format="m4b", timeline=...)` remains the right choice for Readio's prepared master and project timeline.
+Run it with `audioexport audiobook --profile audiobook.toml`. CLI `--output`, metadata, audio settings, cover, and `--chapters-file` override profile values; the TOML input order remains authoritative. `mode = "tracks"` (the default) creates one chapter per track; `mode = "explicit"` requires `chapters_file`; `mode = "none"` disables chapters. Existing `encode(..., format="m4b", timeline=...)` remains the right choice for one prepared source with caller-supplied chapters.
 
-## Native `.ssmdbook` pipeline
+## SSMD bundle export
 
-Use `export-book` when AudioCompose has already written a variant in a standard `.ssmdbook` workspace. It is the native book-workspace adapter; `audioexport audiobook` remains the generic standalone track/directory assembler, and `encode` remains for one prepared source with a timeline.
+Book and single-document workspaces share one canonical editable directory root, `<name>.ssmd-bundle/`. The manifest selects the export path: `format = "ssmdconvert.book"` uses verified audiobook assembly, while `format = "ssmdconvert.document"` uses verified one-document encoding; both manifest schemas remain at version 1. AudioExport accepts only the bundle root, not an internal chapter directory, the document source file, or a ZIP archive.
+
+Use the same command for either kind:
 
 ```bash
-audiocompose compose-book . --variant "$VARIANT"
-audioexport export-book . --variant "$VARIANT"
+audiocompose bundle compose "My Book.ssmd-bundle" --variant "$VARIANT"
+audioexport bundle export "My Book.ssmd-bundle" --variant "$VARIANT" \
+  --chapters 5,7,11-13 --audiocompose-root /srv/audio-stages/audiocompose \
+  --output-root /srv/audio-exports --title "My Book" --author "An Author" \
+  --language en-US
+
+audioexport bundle export story.ssmd-bundle --variant "$VARIANT" \
+  --output story.m4a --title "Story" --artist "An Author"
 ```
 
-`export-book` reads `manifest.json` and `audiocompose/<variant>/compose-report.toml`, accepts the producer's singular `[[item]]` tables (and legacy `[[items]]` tables), validates selected entries and WAV checksums/geometry with bare or `sha256:`-prefixed digests, then delegates final M4B assembly and verification to AudioExport. It does not run AudioCompose, repair or synthesize chapters, or use Readio-specific state. Chapter selection accepts `all` (the default), a source number, an inclusive range, or comma-separated source numbers/ranges, for example `--chapters 5,7,11-13`. Selection follows manifest chapter order.
+AudioExport verifies the selected AudioCompose report, output paths, WAV checksums, and audio geometry before exporting. For a book, `--chapters` selects manifest chapters (`all` by default), output defaults to M4B, `--format` accepts only `m4b`, and audiobook profiles remain supported. For a document, only `--chapters all` is valid; `--format` or the output filename extension selects the final format, and `--timeline` supplies an optional generic chapter timeline. `--author` and `--artist` are aliases for the appropriate author/artist metadata field. Kind-specific options that have no meaning for the selected manifest are rejected rather than ignored.
 
-For M4A/M4B, language metadata is written on the audio track using ISO 639-2/T. BCP 47 tags such as `en-US` are normalized to their three-letter track code (`eng`).
+Default output names strip only `.ssmd-bundle`: books use `audioexport/<variant>/<name>.m4b`, while documents use `audioexport/<variant>/<name>.<format>`. `--output-root` relocates these defaults; `--output` selects an explicit destination. Book metadata precedence is manifest, then audiobook profile, then explicit CLI/API values. BCP 47 language tags such as `en-US` are normalized to ISO 639-2/T track codes such as `eng` for M4A/M4B.
 
-By default, output is written to `audioexport/<variant>/<workspace-name-without-.ssmdbook>.m4b` in the workspace. `--output` may override this; when an audiobook profile is supplied, its output is used unless `--output` is specified.
+The JSON result uses one versioned envelope with `format: "audioexport-bundle-result"`, `version: 1`, `kind`, and a kind-specific `result` object. Human output begins with `AudioExport bundle export` and reports the selected kind, workspace, variant, and output.
 
-Metadata precedence is **manifest metadata < audiobook profile metadata < explicit CLI/API metadata**. Audio settings use **AudioExport defaults < audiobook profile < explicit CLI/API flags**. Thus explicit metadata fields replace matching profile/manifest values, profile values replace manifest defaults, and unset values continue to fall through. Explicit cover and audio flags override corresponding profile settings. The profile's inputs and chapter configuration do not replace the variant chapters selected from the compose report.
+Python callers use the same manifest-dispatched facade:
 
-If `--output` is not set for `encode`, the output filename defaults to the input stem and chosen format. To avoid destroying the input, encoding input and output to the same real path is always rejected.
+```python
+from audioexport import export_bundle
 
-Without `--force`, an untracked, symlink, or manually modified output is never overwritten. A previously generated output is updated when its sidecar and checksum still match; re-running identical options returns `reused: true` without re-encoding. `--force` authorizes replacing an unknown or modified regular file, but symlink outputs and sidecars are always rejected. Writes are staged with their manifest; a failed manifest commit restores the last good pair when possible, and an incomplete recovery reports the preserved backup path. A per-target process lock rejects concurrent writers with `audioexport.output_busy`; remove a stale lock only after confirming no writer is active.
+book_result = export_bundle("My Book.ssmd-bundle", variant=variant, chapters="5,7")
+document_result = export_bundle("story.ssmd-bundle", variant=variant, format="mp3")
+print(book_result.kind, book_result.output)
+print(document_result.kind, document_result.output)
+```
 
+`BundleExportResult.value` contains the specialized book or document result; `BundleExportResult.output` gives the final artifact path. The facade is available from both `audioexport` and `audioexport.api`.
 OGG defaults to Vorbis quality-based encoding (`-qscale:a 4`) to avoid low-rate/mono bitrate incompatibilities. `--bitrate` accepts values such as `192k`, `192000`, or `1M`; whitespace is trimmed. A bare integer is interpreted as **bits per second**, so use `192k` (or `192000`), not `192`, for a nominal 192 kb/s rate. WAV/FLAC don't accept bitrate. WAV output is always PCM16 conversion, not a byte-for-byte passthrough; lossy codecs and even PCM output can vary with FFmpeg versions, which are included in the export identity.
 
 ## Python API
@@ -170,7 +184,7 @@ print(probe("exported/book.m4b")["chapters"])
 
 You may import the same public functions from `audioexport.api` as well as from `audioexport`.
 
-The public errors are `AudioExportError` and subclasses `InvalidExportError`, `ToolNotFoundError`, `EncodingError`, and `VerificationError`, with a stable machine-readable `.code` value. `encode()` returns an immutable `ExportResult`; `build_audiobook()` returns an `AudiobookResult`; `export_book()` and `resolve_book_export()` provide verified composed-book export through `BookExportContext`, `BookExportResult`, and `ComposedChapter`. These symbols, like the other public functions, are available from both `audioexport` and `audioexport.api`.
+The public errors are `AudioExportError` and subclasses `InvalidExportError`, `ToolNotFoundError`, `EncodingError`, and `VerificationError`, with a stable machine-readable `.code` value. `encode()` returns an immutable `ExportResult`; `build_audiobook()` returns an `AudiobookResult`; `export_bundle()` provides one manifest-dispatched entry point for verified book and document bundles and returns `BundleExportResult`. The facade and result types are available from both `audioexport` and `audioexport.api`.
 
 ## Export profile
 
@@ -246,7 +260,7 @@ resolved_outputs = preflight_profile(profile, source)
 
 for resolved in resolved_outputs:
     target = Path("exports") / resolved.filename
-    # A consumer such as Readio performs its target/ownership/overwrite checks here.
+    # Applications should perform their own target and overwrite checks here.
     result = encode(
         source,
         target,
@@ -258,7 +272,7 @@ for resolved in resolved_outputs:
     )
 ```
 
-A consumer may instead call `resolve_output()` for a single selected spec; use full-profile preflight when the operation requires every configured output validated. Preflight is not an ownership authorization: Readio remains responsible for project locks and freshness, destination selection and collision/ownership checks, overwrite authorization, state/index updates, result types, and partial-batch bookkeeping. Call `encode()` only after those consumer-owned checks pass. `ResolvedOutput`, `resolve_output`, and `preflight_profile` are available from both `audioexport` and `audioexport.api`.
+A consumer may instead call `resolve_output()` for a single selected spec; use full-profile preflight when the operation requires every configured output validated. Preflight is not an ownership authorization: applications remain responsible for their own locks, target selection, overwrite authorization, and state updates. Call `encode()` only after those consumer-owned checks pass. `ResolvedOutput`, `resolve_output`, and `preflight_profile` are available from both `audioexport` and `audioexport.api`.
 
 ## Chapters/timeline
 
@@ -275,7 +289,7 @@ Use an independent JSON file such as [`examples/chapters.json`](examples/chapter
 
 `end_ms` is optional; without it, chapter ends are the next chapter start or the audio duration. Chapter offsets must be strictly increasing and within the audio file. FFmpeg metadata escaping is handled internally. Embedded chapter markers are currently supported for **M4A and M4B**.
 
-For an incremental Readio migration, the same `--timeline` API also reads **Readio's `readio.composition-timeline` JSON** with `sample_rate` and chapter `start_sample`. FFmetadata is constructed with its original sample timebase for precision, with generic millisecond chapter fields available for non-Readio workflows.
+Exact-sample timelines may include a top-level `sample_rate` and chapter `start_sample` values. FFmetadata preserves their original sample timebase and coordinates using `TIMEBASE=1/<sample_rate>`.
 
 ## Integrity and versioning
 
@@ -287,10 +301,6 @@ Version is dynamic through `setuptools-scm`: `pyproject.toml` has no static `ver
 
 For a release, first commit the code and wait for the complete Linux/Windows/macOS, Python 3.10–3.14 CI matrix, including its Sphinx warning-as-error documentation build. Then create and push the intended version tag (for example `v0.1.2`). Manually dispatch the GitHub Actions workflow named **Release** with that existing tag. It reruns the full supported-Python test matrix, checks the tag against wheel/sdist metadata, inspects package contents, installs the wheel outside the checkout, and checks CLI/API version parity. Publishing uses the configured `PYPI_API_TOKEN` secret after approval in the `pypi` GitHub environment; repository administrators must ensure the token and environment approval rules are configured. Do not publish from an untagged/fallback build.
 
-## Readio migration
-
-**Readio is deliberately not patched by this project.** Its existing export commands continue using their current code until an opt-in bridge is tested. A future integration must call AudioExport's Python library API; it must never launch the `audioexport` CLI as a subprocess. See [`docs/readio-migration.md`](docs/readio-migration.md) for the compatibility boundary, integration order, and rollback rules. Readio continues owning project locks, path defaults, staleness, indexed state, and orchestration.
-
 ## Tests
 
 ```bash
@@ -306,11 +316,11 @@ python scripts/check_package_artifacts.py
 audioexport doctor --json
 ```
 
-Tests cover seven real formats in one profile, mixed-format audiobook assembly, 100-track ordering/chapters, audiobook cache invalidation, M4A/M4B chapters and covers, Readio sample timelines, malformed probes, encoder availability, transactional failure recovery, no-clobber behavior, and concurrent writers. Normal CI runs Python 3.10–3.14 on Linux, Windows, and macOS, and checks tests, lint, formatting, typing, build metadata, Twine, package contents, and isolated wheel installation. CI also builds the Sphinx documentation on Linux/Python 3.13 with warnings treated as errors. The manually dispatched **Release** workflow retests the full supported Python range before packaging and API-token publishing. Cross-platform encoder availability depends on the FFmpeg build installed by each runner.
+Tests cover seven real formats in one profile, mixed-format audiobook assembly, 100-track ordering/chapters, audiobook cache invalidation, M4A/M4B chapters and covers, exact-sample chapter timelines, malformed probes, encoder availability, transactional failure recovery, no-clobber behavior, and concurrent writers. Normal CI runs Python 3.10–3.14 on Linux, Windows, and macOS, and checks tests, lint, formatting, typing, build metadata, Twine, package contents, and isolated wheel installation. CI also builds the Sphinx documentation on Linux/Python 3.13 with warnings treated as errors. The manually dispatched **Release** workflow retests the full supported Python range before packaging and API-token publishing. Cross-platform encoder availability depends on the FFmpeg build installed by each runner.
 
 ## Limitations (MVP)
 
-No audio mastering, TTS, audio mixing, streaming PCM API, FFmpeg filter graphs, network service, or GUI. No automatic conversion of Readio project configs, legacy export cache, or Audiocompose timeline semantics other than chapter starts. Encoder output may vary across FFmpeg versions; the cache key includes tool versions. Chapter verification has a small tolerance for FFmpeg container timebase rounding. Standalone encoding does not modify Readio projects.
+No audio mastering, TTS, audio mixing, streaming PCM API, FFmpeg filter graphs, network service, or GUI. Encoder output may vary across FFmpeg versions; the export identity includes tool versions. Chapter verification tolerates small FFmpeg container timebase rounding.
 
 ## License
 

{audioexport-0.1.2 → audioexport-0.1.4}/audioexport/__init__.py

@@ -1,4 +1,4 @@
-"""Standalone audio export; no import of Readio or AudioCompose."""
+"""Standalone verified audio export and workspace adapters."""
 
 from __future__ import annotations
 
@@ -13,7 +13,15 @@ from .book import (
     export_book,
     resolve_book_export,
 )
+from .bundle import BundleExportResult, export_bundle
 from .chapters import Chapter, load_chapters
+from .document import (
+    ComposedDocument,
+    DocumentExportContext,
+    DocumentExportResult,
+    export_document,
+    resolve_document_export,
+)
 from .errors import (
     AudioExportError,
     EncodingError,
@@ -43,8 +51,12 @@ __all__ = [
     "AudiobookTrack",
     "BookExportContext",
     "BookExportResult",
+    "BundleExportResult",
     "Chapter",
     "ComposedChapter",
+    "ComposedDocument",
+    "DocumentExportContext",
+    "DocumentExportResult",
     "EncodingError",
     "ExportProfile",
     "ExportResult",
@@ -58,6 +70,8 @@ __all__ = [
     "doctor",
     "encode",
     "export_book",
+    "export_bundle",
+    "export_document",
     "load_audiobook_profile",
     "load_chapters",
     "load_profile",
@@ -65,6 +79,7 @@ __all__ = [
     "preflight_profile",
     "probe",
     "resolve_book_export",
+    "resolve_document_export",
     "resolve_output",
     "run_profile",
 ]

{audioexport-0.1.2 → audioexport-0.1.4}/audioexport/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.2'
-__version_tuple__ = version_tuple = (0, 1, 2)
+__version__ = version = '0.1.4'
+__version_tuple__ = version_tuple = (0, 1, 4)
 
-__commit_id__ = commit_id = 'g356ce267b'
+__commit_id__ = commit_id = 'gb9fbcb9c0'

audioexport-0.1.4/audioexport/_workspace.py

@@ -0,0 +1,215 @@
+"""Shared security checks for native workspace adapters."""
+
+from __future__ import annotations
+
+import hashlib
+import math
+import stat
+import unicodedata
+import wave
+from collections.abc import Mapping
+from pathlib import Path, PureWindowsPath
+from typing import Any
+
+from .errors import InvalidExportError, VerificationError
+
+DURATION_TOLERANCE_SECONDS = 0.01
+
+
+def safe_variant(variant: str, *, error_code: str) -> str:
+    """Validate a variant as one portable, safe directory component."""
+    if (
+        not isinstance(variant, str)
+        or not variant
+        or variant in {".", ".."}
+        or "/" in variant
+        or "\\" in variant
+        or ":" in variant
+        or PureWindowsPath(variant).is_absolute()
+        or any(unicodedata.category(character) == "Cc" for character in variant)
+    ):
+        raise InvalidExportError(
+            "variant must be a safe single directory component", code=error_code
+        )
+    return variant
+
+
+def resolve_stage_root(
+    workspace: Path,
+    root: str | Path | None,
+    *,
+    stage_name: str,
+    missing_code: str,
+    invalid_code: str,
+) -> Path:
+    """Resolve an existing stage root, interpreting relative overrides under workspace."""
+    selected = Path(root).expanduser() if root is not None else workspace / stage_name
+    if not selected.is_absolute():
+        selected = workspace / selected
+    try:
+        resolved = selected.resolve(strict=True)
+    except (OSError, RuntimeError) as exc:
+        raise InvalidExportError(
+            f"{stage_name} directory does not exist: {selected}", code=missing_code
+        ) from exc
+    if selected.is_symlink() or not resolved.is_dir():
+        raise InvalidExportError(
+            f"{stage_name} root must be a non-symlink directory: {selected}",
+            code=invalid_code,
+        )
+    return resolved
+
+
+def path_is_within(root: Path, path: Path) -> bool:
+    """Return whether an absolute path is contained by an absolute directory."""
+    try:
+        path.relative_to(root)
+    except ValueError:
+        return False
+    return True
+
+
+def safe_report_file(
+    variant_dir: Path,
+    reported: Any,
+    *,
+    error_code: str,
+) -> Path:
+    """Resolve a regular report-declared file without traversal or symlink hops."""
+    if not isinstance(reported, str) or not reported or "\x00" in reported or "\\" in reported:
+        raise VerificationError(
+            "compose report output must be a relative POSIX path", code=error_code
+        )
+    relative = Path(reported)
+    windows = PureWindowsPath(reported)
+    if relative.is_absolute() or windows.is_absolute() or windows.drive:
+        raise VerificationError(
+            "compose report output must be relative to its variant directory",
+            code=error_code,
+        )
+    if any(part in {"", ".", ".."} for part in reported.split("/")):
+        raise VerificationError(
+            "compose report output must not contain traversal components",
+            code=error_code,
+        )
+    candidate = variant_dir / relative
+    current = variant_dir
+    try:
+        for part in relative.parts:
+            current = current / part
+            if current.is_symlink():
+                raise VerificationError(
+                    "compose report output must not traverse symlinks", code=error_code
+                )
+        resolved = candidate.resolve(strict=True)
+    except VerificationError:
+        raise
+    except (OSError, RuntimeError) as exc:
+        raise VerificationError(
+            f"compose report output does not resolve to a regular file: {reported}",
+            code=error_code,
+        ) from exc
+    if not path_is_within(variant_dir, resolved):
+        raise VerificationError(
+            "compose report output escapes its variant directory", code=error_code
+        )
+    try:
+        mode = resolved.lstat().st_mode
+    except OSError as exc:
+        raise VerificationError(
+            f"compose report output is unavailable: {reported}", code=error_code
+        ) from exc
+    if not stat.S_ISREG(mode):
+        raise VerificationError(
+            f"compose report output must be a regular non-symlink file: {reported}",
+            code=error_code,
+        )
+    return resolved
+
+
+def sha256_file(path: Path, *, error_code: str) -> str:
+    digest = hashlib.sha256()
+    try:
+        with path.open("rb") as stream:
+            for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                digest.update(chunk)
+    except OSError as exc:
+        raise VerificationError(f"cannot hash composed WAV {path}", code=error_code) from exc
+    return digest.hexdigest()
+
+
+def _positive_int(value: Any, field: str, *, error_code: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise InvalidExportError(f"{field} must be a positive integer", code=error_code)
+    return value
+
+
+def verify_reported_wav(
+    path: Path,
+    report: Mapping[str, Any],
+    *,
+    report_code: str,
+    geometry_code: str,
+    item_label: str = "compose item",
+) -> tuple[int, int, int, float]:
+    """Verify a WAV header against report geometry using the established tolerance."""
+    expected_rate = _positive_int(
+        report.get("sample_rate"), f"{item_label} sample_rate", error_code=report_code
+    )
+    expected_channels = _positive_int(
+        report.get("channels"), f"{item_label} channels", error_code=report_code
+    )
+    expected_frames = _positive_int(
+        report.get("frames"), f"{item_label} frames", error_code=report_code
+    )
+    duration = report.get("duration_seconds")
+    if (
+        isinstance(duration, bool)
+        or not isinstance(duration, (int, float))
+        or not math.isfinite(float(duration))
+        or duration <= 0
+    ):
+        raise InvalidExportError(
+            f"{item_label} duration_seconds must be a positive finite number",
+            code=report_code,
+        )
+    complete_audio = True
+    try:
+        with wave.open(str(path), "rb") as source:
+            actual_rate = source.getframerate()
+            actual_channels = source.getnchannels()
+            actual_frames = source.getnframes()
+            sample_width = source.getsampwidth()
+            frame_size = actual_channels * sample_width
+            if frame_size <= 0:
+                complete_audio = False
+            else:
+                remaining_frames = actual_frames
+                while remaining_frames > 0:
+                    chunk = source.readframes(min(remaining_frames, 65536))
+                    if not chunk or len(chunk) % frame_size:
+                        complete_audio = False
+                        break
+                    frames_read = len(chunk) // frame_size
+                    if frames_read <= 0:
+                        complete_audio = False
+                        break
+                    remaining_frames -= frames_read
+                if remaining_frames:
+                    complete_audio = False
+    except (OSError, EOFError, wave.Error) as exc:
+        raise VerificationError(
+            f"composed artifact is not a readable WAV file: {path}", code=geometry_code
+        ) from exc
+    actual_duration = actual_frames / actual_rate if actual_rate > 0 else 0.0
+    if (
+        not complete_audio
+        or actual_rate != expected_rate
+        or actual_channels != expected_channels
+        or actual_frames != expected_frames
+        or abs(actual_duration - float(duration)) > DURATION_TOLERANCE_SECONDS
+    ):
+        raise VerificationError(
+            f"composed WAV geometry does not match the report: {path}", code=geometry_code
+        )
+    return actual_rate, actual_channels, actual_frames, actual_duration