curate-audiobooks

name	curate-audiobooks
description	Safely inventory, compare, identify, convert, enrich, and validate audiobook audio as a single M4B. Use for source-quality selection, Audible candidate review, Audiolocate acoustic confirmation, Whisper language or identity checks, artwork and chapter construction, metadata cleanup, filesystem-safe naming, full-decode integrity checks, SHA-256 receipts, or reusable audiobook audit reports.

Curate audiobooks

Use the bundled CLI at <plugin-root>/bin/audiobook-curator. The plugin root is two directories above this SKILL.md. Run <plugin-root>/scripts/bootstrap.sh once if its isolated environment is absent; do not substitute an unrelated global executable.

Guardrails

• Treat source audio as immutable. Never delete, rename, or overwrite an original. apply-metadata and apply-chapters may update only a separately identified, user-approved derived M4B.
• Start with inventory and select. Read their JSON before proposing a conversion.
• Keep evidence gates distinct: catalog metadata is a candidate, acoustic matching supports edition identity, and Whisper excerpts support language/story/narrator review.
• Require the user to approve the candidate identity and conversion destination before using --apply.
• Omit --apply for a dry-run conversion plan. Do not use --overwrite unless the exact existing derived output is confirmed replaceable.
• Remove apostrophes and unsafe characters from output filenames only. Retain correct punctuation in embedded title, author, narrator, descriptions, and chapter titles.
• Finish with audit --full-decode; report file SHA-256, audio-stream SHA-256, byte size, chapter findings, and decode status separately.
• Do not infer media-server, database, or listening-history work. This skill has no such integration.

Workflow

1. For a library or holding folder, run library-audit SOURCE --report receipts/library-audit.json. Treat duplicate and multipart groups only as review leads.
2. Run inventory SOURCE --report receipts/inventory.json. Review probe errors, duration, codecs, bit depth, sample rate, bitrate, layout, existing artwork, and chapters.
3. Run select --inventory receipts/inventory.json --report receipts/selection.json. Confirm natural ordering, duration-conflict warnings, and every selected-vs-alternate decision. Edit the selection receipt only when human evidence overrides the deterministic quality ranking.
4. Establish identity. Run audible-search with title, author, narrator when known, and source duration. Review the top candidates; do not auto-accept rank one. Record the explicit choice with audible-select.
5. After a candidate is accepted, run audible-cache to retain product, chapter, and artwork evidence. Downloads are bounded and retried.
6. When edition ambiguity matters, run acoustic-verify. When several search candidates stay plausible, run acoustic-identify --candidates receipts/audible-candidates.json to try the top-ranked samples automatically; it stops at the first match and records every attempt. A positive match is strong same-recording evidence; a negative match is inconclusive if samples differ by intro, mastering, or region. Accepting an edition still requires audible-select.
7. When language, narrator, or story identity is uncertain, run whisper-verify. It begins with five distributed windows and samples more positions when fewer than three contain usable speech. Read at least three usable excerpts and record the human conclusion.
8. Run convert without --apply and inspect the plan. Confirm output name, embedded punctuation, source order, metadata, artwork, engine, codec, and destination. Prefer --engine audiobook-forge when available for multipart sources. A single existing M4B is stream-copied automatically. For multipart ffmpeg conversion, prefer --audio-codec alac: it keeps the decoded source audio lossless at the original sample rate and channel layout, so varied sources (including MP3) gain no further lossy compression. Use --audio-codec aac only when a smaller lossy output is required; --audio-bitrate controls its bitrate (default 128k), while ffmpeg retains source sample rate and channels when supported. Never pass MP3 audio through into an M4B — MP3-in-MP4 is not a compatibility-safe target. --jobs defaults to an automatic value scaled to available CPU cores and runnable work; with more than one job the ffmpeg engine transcodes segments in parallel and stream-copy muxes them. Parallel AAC segments keep roughly one priming frame at each part boundary (accepted trade-off; chapters use the actual segment durations), and the stream-copy concat requires uniform sample rate, channels, and bit depth across segments after transcode. ALAC and native AAC encoders are single-threaded, so parallelism comes from processes: with ALAC, one or a few large inputs may be split into internal PCM chunks to use many cores while chapters stay per original input; AAC stays per-input to avoid extra priming seams. For sources above 96 kHz, use ALAC — AAC tops out at 96 kHz. ALAC M4B is the quality target for Apple Books/iBooks/Prologue; AAC M4B is the smaller compatibility fallback.

Read references/evidence-gates.md when identity is ambiguous or a result is being promoted as verified. Read references/dependencies.md for bootstrap and platform requirements.