@event4u/agent-config 5.10.1 → 6.1.0

package/src/scripts/ai-video/adapters/sora.sh

@@ -0,0 +1,207 @@
+#!/usr/bin/env bash
+# sora.sh — OpenAI Sora structural-prompt video adapter.
+#
+# Capability: audio=native. Sora-class models produce muxed MP4 with
+# dialogue + ambient sound; we pass the audio block straight through.
+# Structural-prompt path informed by upstream `awesome-sora-prompts`
+# (attribution in agents/reference/ai-video/prompts/cinematic-blueprint.md).
+#
+# Lifecycle: stable — promoted 2026-06-10 (maintainer-authorized): live
+# round-trip validated 1/1 — 4.1s h264 720p with native AAC audio,
+# ~60s render, ~$0.40 (sora-2, 4s). API param enums verified empirically
+# (seconds {4,8,12}, size {720x1280,1280x720,1024x1792,1792x1024}). Raw
+# trace is local-only operator evidence (smoke-traces/, gitignored).
+#
+# Live API (OpenAI Videos API — param enums verified empirically
+# 2026-06-10 via validation-error probes, no spend):
+#   base   https://api.openai.com/v1   (from XML <endpoint>)
+#   auth   Authorization: Bearer <API_KEY>
+#   submit POST {base}/videos
+#          {"model":"sora-2"|"sora-2-pro","prompt":"…",
+#           "seconds":"4"|"8"|"12" (string enum, verified),
+#           "size":"720x1280"|"1280x720"|"1024x1792"|"1792x1024" (verified)}
+#          -> {id:"video_…", status:"queued"}
+#   poll   GET  {base}/videos/{id}
+#          -> status: queued|in_progress|completed|failed (ASSUMED names)
+#   fetch  GET  {base}/videos/{id}/content -> MP4 bytes (ASSUMED route;
+#          download needs the same Bearer header -> AIV_FETCH_HEADER)
+#
+# job_id = the provider video id; re-validated as untrusted input on
+# every poll/fetch (charset whitelist, no traversal).
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md (v2 — trust
+# boundary: downloads via aiv_fetch_url, returned paths via
+# aiv_validate_artifact_path).
+# Provider: top-level <provider id="sora" kind="video"> in
+# agents/.ai-video.xml. Kill-switch: <enabled>false</enabled>.
+# Encoder note: provider-specific prompt grammar comes from the
+#   motion-choreographer encoder table; the scene blueprint stays
+#   provider-agnostic (see adapter-contract.md § Blueprint → provider translation).
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="sora"
+
+_sora_auth() {
+  printf 'Authorization: Bearer %s' "${AIV_KEY}"
+}
+
+_sora_assert_enabled() {
+  [ "$(aiv_provider_enabled "${ADAPTER_ID}")" = "true" ] \
+    || aiv_die 6 "${ADAPTER_ID}: provider disabled via <enabled>false</enabled> in agents/.ai-video.xml"
+}
+
+# _sora_validate_video_id <id> — video ids are tainted input (provider
+# response / orchestrator replay); they land in the request URL. Sets
+# SORA_VIDEO_ID (global; not command-substituted so aiv_die's exit
+# reaches the caller).
+_sora_validate_video_id() {
+  SORA_VIDEO_ID="${1:-}"
+  [ -n "${SORA_VIDEO_ID}" ] || aiv_die 2 "${ADAPTER_ID}: job_id (video id) required"
+  printf '%s' "${SORA_VIDEO_ID}" | grep -Eq '^[A-Za-z0-9._-]+$' \
+    || aiv_die 7 "${ADAPTER_ID}: illegal video id: ${SORA_VIDEO_ID}"
+}
+
+# _sora_model_rate_usd_per_s <model> — modeled per-second USD rate for
+# cost_estimate (documented-best-effort; ASSUMED until the invoice
+# confirms). Unknown models → empty ("unknown").
+_sora_model_rate_usd_per_s() {
+  case "${1:-}" in
+    sora-2-pro*) printf '0.30' ;;
+    sora-2*)     printf '0.10' ;;
+    *)           printf '' ;;
+  esac
+}
+
+# _sora_video_json <video_id> — GET the video job; echoes the raw body.
+_sora_video_json() {
+  local vid="${1}" base resp http body
+  base="${AIV_ENDPOINT%/}"
+  resp="$(curl -sS -w '\n%{http_code}' -X GET "${base}/videos/${vid}" \
+    -H "$(_sora_auth)")" \
+    || aiv_die 8 "${ADAPTER_ID}: poll curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: poll HTTP ${http}: $(printf '%s' "${body}" | jq -r '.error.message // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+  printf '%s' "${body}"
+}
+
+# Submit: read contract JSON from stdin, return {job_id, status:"queued",
+# cost_estimate?}.
+aiv_cmd_submit() {
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  aiv_assert_dryrun
+  _sora_assert_enabled
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json model base req resp http body vid secs size rate
+  stdin_json="$(cat)"
+  # Sora's structural-prompt path expects all eight blocks present;
+  # fail loud if the blueprint parser dropped any.
+  printf '%s' "${stdin_json}" \
+    | jq -e '.prompt.style and .prompt.subject and .prompt.environment and
+             .prompt.action and .prompt.camera and .prompt.lens and
+             .prompt.lighting and .prompt.mood' >/dev/null \
+    || aiv_die 3 "${ADAPTER_ID}: stdin JSON missing one or more required prompt blocks"
+
+  model="${AIV_MODEL:-sora-2}"
+  base="${AIV_ENDPOINT%/}"
+
+  # stdin duration → seconds enum {"4","8","12"} (string, verified).
+  secs="$(printf '%s' "${stdin_json}" | jq -r '
+    if .duration == null then "4"
+    elif .duration <= 4 then "4"
+    elif .duration <= 8 then "8"
+    else "12" end')"
+  # aspect → size enum (verified): landscape 1280x720, portrait 720x1280.
+  size="$(printf '%s' "${stdin_json}" | jq -r '
+    if .aspect == "9:16" then "720x1280" else "1280x720" end')"
+
+  req="$(printf '%s' "${stdin_json}" | jq --arg model "${model}" --arg secs "${secs}" --arg size "${size}" '{
+    model: $model,
+    seconds: $secs,
+    size: $size,
+    prompt: ([.prompt.style, .prompt.subject, .prompt.environment,
+              .prompt.action, .prompt.camera, .prompt.lens,
+              .prompt.lighting, .prompt.mood]
+             | map(select(. != null and . != "")) | join(". "))
+  }')"
+
+  resp="$(curl -sS -w '\n%{http_code}' -X POST "${base}/videos" \
+    -H "$(_sora_auth)" -H "Content-Type: application/json" \
+    --data-binary "${req}")" \
+    || aiv_die 8 "${ADAPTER_ID}: submit curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: submit HTTP ${http}: $(printf '%s' "${body}" | jq -r '.error.message // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+
+  vid="$(printf '%s' "${body}" | jq -r '.id // empty')"
+  [ -n "${vid}" ] || aiv_die 8 "${ADAPTER_ID}: no video id in submit response (got: $(printf '%s' "${body}" | head -c 200))"
+  _sora_validate_video_id "${vid}"
+
+  rate="$(_sora_model_rate_usd_per_s "${model}")"
+  if [ -n "${rate}" ]; then
+    jq -n --arg id "${SORA_VIDEO_ID}" --argjson c "$(jq -n --argjson r "${rate}" --argjson s "${secs}" '$r * $s')" \
+      '{job_id:$id, status:"queued", cost_estimate:$c}'
+  else
+    jq -n --arg id "${SORA_VIDEO_ID}" '{job_id:$id, status:"queued", cost_estimate:"unknown"}'
+  fi
+}
+
+# Poll: stateless — the video id IS the job_id.
+aiv_cmd_poll() {
+  _sora_validate_video_id "${1:-}"
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  aiv_assert_dryrun
+  _sora_assert_enabled
+  local body st err
+  body="$(_sora_video_json "${SORA_VIDEO_ID}")" || exit $?
+  st="$(printf '%s' "${body}" | jq -r '.status // empty')"
+  case "${st}" in
+    completed|succeeded)      printf '{"status":"done"}\n' ;;
+    queued)                   printf '{"status":"queued"}\n' ;;
+    in_progress|processing)   printf '{"status":"running"}\n' ;;
+    failed|error)
+      err="$(printf '%s' "${body}" | jq -r '.error.message // .failure_reason // "failed"' | head -c 200)"
+      jq -n --arg r "${err}" '{status:"failed", reason:$r}' ;;
+    *)                        printf '{"status":"running","raw":"%s"}\n' "${st:-unknown}" ;;
+  esac
+}
+
+# Fetch: confirm the job completed, then download the MP4 from the
+# content route through the v2 trust boundary (Bearer header via
+# AIV_FETCH_HEADER; size-cap + path validation).
+aiv_cmd_fetch() {
+  _sora_validate_video_id "${1:-}"
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  aiv_assert_dryrun
+  _sora_assert_enabled
+  local body st base url dest root out
+  body="$(_sora_video_json "${SORA_VIDEO_ID}")" || exit $?
+  st="$(printf '%s' "${body}" | jq -r '.status // empty')"
+  case "${st}" in completed|succeeded) : ;; *) aiv_die 8 "${ADAPTER_ID}: fetch before completion (status=${st:-unknown}; poll first)" ;; esac
+
+  base="${AIV_ENDPOINT%/}"
+  url="${base}/videos/${SORA_VIDEO_ID}/content"
+
+  if [ -n "${AIV_PROJECT_DIR:-}" ] && [ -n "${AIV_SCENE_ID:-}" ]; then
+    dest="$(aiv_scene_dir "${AIV_PROJECT_DIR}" "${AIV_SCENE_ID}")/scene-${SORA_VIDEO_ID}.mp4"
+    root="${AIV_PROJECT_DIR}"
+  elif [ -n "${AIV_OUT:-}" ]; then
+    dest="${AIV_OUT}"
+    root="$(dirname "${AIV_OUT}")"
+  else
+    root="$(mktemp -d -t aiv-sora-XXXXXX)"
+    dest="${root}/scene-${SORA_VIDEO_ID}.mp4"
+  fi
+  AIV_FETCH_HEADER="$(_sora_auth)" aiv_fetch_url "${url}" "${dest}" >/dev/null
+  out="$(aiv_validate_artifact_path "${root}" "${dest}")"
+  jq -n --arg p "${out}" '{video_path:$p, audio_embedded:true}'
+}
+
+aiv_dispatch "${ADAPTER_ID}" "native" "$@"

package/src/scripts/ai-video/adapters/syncso.sh

@@ -0,0 +1,200 @@
+#!/usr/bin/env bash
+# syncso.sh — sync.so lip-sync post-process adapter: one rendered clip +
+# one audio line in, a lip-synced clip out. Hosted, singing-capable, no
+# GPU — the reference implementation for the lip-sync adapter class.
+#
+# Capability: audio=native — the returned clip embeds the driving audio
+# line, so dropping its track at mux time would desync the mouth (the
+# orchestrator keeps lip-sync scenes' native audio per /video:from-song
+# Step 9.1).
+#
+# Lifecycle: experimental — structural shape conformant; no maintainer
+# real-API smoke trace captured yet. See docs/contracts/provider-lifecycle.md
+# for promotion criteria.
+# Encoder note: provider-specific prompt grammar comes from the
+#   motion-choreographer encoder table; the scene blueprint stays
+#   provider-agnostic (see adapter-contract.md § Blueprint → provider translation).
+#
+# Kind: lipsync (adapter-contract.md v2 § Lip-sync adapters). Stdin is
+# NOT the prompt-block shape — a lip-sync job consumes:
+#   {"video_url":"https://…/scene.mp4", "audio_url":"https://…/line.wav",
+#    "model_id":"lipsync-2"}
+# Both URLs must be https and publicly fetchable by the provider; local
+# paths are rejected with the host-the-artifacts hint (exit 7).
+#
+# Sparse-budget discipline: per-song lip-sync limits live MACHINE-READABLE
+# in lib/model-capabilities/syncso.json under `lipsync_budget`
+# (max_segments_per_song, max_segment_seconds, frontal_close_up_only) —
+# the orchestrator enforces them BEFORE submitting anything; this
+# adapter renders single segments and never sees the whole song.
+#
+# API (documented-best-effort — fields tagged ASSUMED are verified on
+# the first live smoke; this adapter has no captured smoke trace yet):
+#   base   https://api.sync.so
+#   auth   x-api-key: <API_KEY>            (ASSUMED header name)
+#   submit POST {base}/v2/generate          -> { id, status }
+#          body {model, input:[{type:"video",url},{type:"audio",url}]}
+#   poll   GET  {base}/v2/generate/<id>     -> { status }
+#   fetch  GET  {base}/v2/generate/<id>     -> { outputUrl }   (ASSUMED)
+#
+# Contract: scripts/ai-video/lib/adapter-contract.md (v2 — trust
+# boundary: downloads via aiv_fetch_url, returned paths via
+# aiv_validate_artifact_path).
+# Provider: top-level <provider id="syncso" kind="lipsync"> in
+# agents/.ai-video.xml. Kill-switch: <enabled>false</enabled> refuses
+# every network subcommand.
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="syncso"
+SYNCSO_BASE_DEFAULT="https://api.sync.so"
+SYNCSO_MANIFEST="${AIV_LIB_DIR}/model-capabilities/syncso.json"
+
+_syncso_base() {
+  case "${AIV_ENDPOINT:-}" in
+    https://*) printf '%s' "${AIV_ENDPOINT%/}" ;;
+    *) printf '%s' "${SYNCSO_BASE_DEFAULT}" ;;
+  esac
+}
+
+_syncso_auth() {
+  printf 'x-api-key: %s' "${AIV_KEY}"
+}
+
+_syncso_assert_enabled() {
+  [ "$(aiv_provider_enabled "${ADAPTER_ID}")" = "true" ] \
+    || aiv_die 6 "${ADAPTER_ID}: provider disabled via <enabled>false</enabled> in agents/.ai-video.xml"
+}
+
+# _syncso_validate_url <url> <label> — input URLs are operator/orchestrator
+# supplied but still constrained: https only, no quotes/control chars
+# (they land in a JSON body and in redacted logs).
+_syncso_validate_url() {
+  local url="${1:-}" label="${2:-url}"
+  [ -n "${url}" ] || aiv_die 7 "${ADAPTER_ID}: ${label} required (host the artifact and pass an https URL — local paths are not fetchable by the provider)"
+  case "${url}" in
+    https://*) : ;;
+    /*|./*|file://*) aiv_die 7 "${ADAPTER_ID}: ${label} is a local path — host the clip/line first (https only)" ;;
+    *) aiv_die 7 "${ADAPTER_ID}: ${label} must be https: ${url}" ;;
+  esac
+  case "${url}" in
+    *"'"* | *'`'* | *'$('* | *'"'*) aiv_die 7 "${ADAPTER_ID}: illegal character in ${label}" ;;
+  esac
+  printf '%s' "${url}"
+}
+
+# _syncso_validate_job_id <id> — provider-returned ids are tainted input;
+# re-validated on every poll/fetch (stateless, no side-channel files).
+_syncso_validate_job_id() {
+  local jid="${1:-}"
+  [ -n "${jid}" ] || aiv_die 2 "${ADAPTER_ID}: job_id required"
+  printf '%s' "${jid}" | grep -Eq '^[A-Za-z0-9._-]+$' \
+    || aiv_die 7 "${ADAPTER_ID}: illegal job_id: ${jid}"
+  printf '%s' "${jid}"
+}
+
+_syncso_resolve_model() {
+  local mid
+  mid="$(printf '%s' "${1}" | jq -r '.model_id // empty')"
+  [ -n "${mid}" ] || mid="${AIV_MODEL:-lipsync-2}"
+  printf '%s' "${mid}" | grep -Eq '^[A-Za-z0-9._-]+$' \
+    || aiv_die 7 "${ADAPTER_ID}: illegal model_id: ${mid}"
+  printf '%s' "${mid}"
+}
+
+# Submit: read lip-sync job JSON from stdin, return {job_id, status:"queued"}.
+aiv_cmd_submit() {
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  _syncso_assert_enabled
+  [ "$(aiv_key_status)" = "present" ] \
+    || aiv_die 6 "${ADAPTER_ID}: api key missing in agents/.ai-video.xml"
+
+  local stdin_json model video_url audio_url base req resp http body jid
+  stdin_json="$(cat)"
+  model="$(_syncso_resolve_model "${stdin_json}")"
+  video_url="$(_syncso_validate_url "$(printf '%s' "${stdin_json}" | jq -r '.video_url // empty')" video_url)"
+  audio_url="$(_syncso_validate_url "$(printf '%s' "${stdin_json}" | jq -r '.audio_url // empty')" audio_url)"
+  base="$(_syncso_base)"
+
+  req="$(jq -n --arg m "${model}" --arg v "${video_url}" --arg a "${audio_url}" \
+    '{model:$m, input:[{type:"video",url:$v},{type:"audio",url:$a}]}')"
+
+  resp="$(curl -sS -w '\n%{http_code}' -X POST "${base}/v2/generate" \
+    -H "$(_syncso_auth)" -H "Content-Type: application/json" \
+    --data-binary "${req}")" \
+    || aiv_die 8 "${ADAPTER_ID}: submit curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: submit HTTP ${http}: $(printf '%s' "${body}" | jq -r '.message // .error // "unknown"' 2>/dev/null | head -c 300)" ;; esac
+
+  jid="$(printf '%s' "${body}" | jq -r '.id // empty')"
+  [ -n "${jid}" ] || aiv_die 8 "${ADAPTER_ID}: no id in submit response (got: $(printf '%s' "${body}" | head -c 200))"
+  _syncso_validate_job_id "${jid}" >/dev/null
+  jq -n --arg id "${jid}" '{job_id:$id, status:"queued"}'
+}
+
+_syncso_status_json() {
+  local jid="${1}" base resp http body
+  base="$(_syncso_base)"
+  resp="$(curl -sS -w '\n%{http_code}' -X GET "${base}/v2/generate/${jid}" \
+    -H "$(_syncso_auth)")" \
+    || aiv_die 8 "${ADAPTER_ID}: status curl failed"
+  http="$(printf '%s' "${resp}" | tail -n1)"; body="$(printf '%s' "${resp}" | sed '$d')"
+  case "${http}" in 2*) : ;; *) aiv_die 8 "${ADAPTER_ID}: status HTTP ${http}" ;; esac
+  printf '%s' "${body}"
+}
+
+aiv_cmd_poll() {
+  local jid
+  jid="$(_syncso_validate_job_id "${1:-}")"
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  _syncso_assert_enabled
+  local st
+  st="$(_syncso_status_json "${jid}" | jq -r '.status // empty')"
+  case "${st}" in
+    COMPLETED|completed)              printf '{"status":"done"}\n' ;;
+    PENDING|pending|QUEUED|queued)    printf '{"status":"queued"}\n' ;;
+    PROCESSING|processing)            printf '{"status":"running"}\n' ;;
+    FAILED|failed|REJECTED|rejected|CANCELED|canceled)
+      printf '{"status":"failed","reason":"%s"}\n' "${st}" ;;
+    *)                                printf '{"status":"running","raw":"%s"}\n' "${st:-unknown}" ;;
+  esac
+}
+
+aiv_cmd_fetch() {
+  local jid
+  jid="$(_syncso_validate_job_id "${1:-}")"
+  aiv_assert_dryrun
+  aiv_require_cmd curl jq
+  aiv_load_provider "${ADAPTER_ID}"
+  _syncso_assert_enabled
+  local body url dest root out
+  body="$(_syncso_status_json "${jid}")"
+  url="$(printf '%s' "${body}" | jq -r '.outputUrl // .output_url // .output.url // empty')"
+  [ -n "${url}" ] || aiv_die 8 "${ADAPTER_ID}: no output url in result (status=$(printf '%s' "${body}" | jq -r '.status // "?"'))"
+
+  # Trust boundary (contract v2): scene-scoped dest when the orchestrator
+  # scoped us, else AIV_OUT, else a temp dir; download via aiv_fetch_url
+  # and validate the final path against its scope root.
+  if [ -n "${AIV_PROJECT_DIR:-}" ] && [ -n "${AIV_SCENE_ID:-}" ]; then
+    dest="$(aiv_scene_dir "${AIV_PROJECT_DIR}" "${AIV_SCENE_ID}")/lipsync-${jid}.mp4"
+    root="${AIV_PROJECT_DIR}"
+  elif [ -n "${AIV_OUT:-}" ]; then
+    dest="${AIV_OUT}"
+    root="$(dirname "${AIV_OUT}")"
+  else
+    root="$(mktemp -d -t aiv-syncso-XXXXXX)"
+    dest="${root}/lipsync-${jid}.mp4"
+  fi
+  aiv_fetch_url "${url}" "${dest}" >/dev/null
+  out="$(aiv_validate_artifact_path "${root}" "${dest}")"
+  jq -n --arg p "${out}" '{video_path:$p, audio_embedded:true}'
+}
+
+aiv_dispatch "${ADAPTER_ID}" "native" "$@"

package/src/scripts/ai-video/audio-adapters/allin1.sh

@@ -0,0 +1,115 @@
+#!/usr/bin/env bash
+# allin1.sh — reference audio-analysis adapter: BPM + beats + downbeats +
+# named sections in one pass, backed by an operator-installed `allin1`
+# CLI (https://github.com/mir-aidj/all-in-one — installed via pip by the
+# OPERATOR; the suite ships only this wrapper, never the ML deps).
+#
+# Class: audio-analysis (filter-shape, synchronous `analyze`).
+# Contract: scripts/ai-video/lib/audio-adapter-contract.md (v1).
+#
+# Lifecycle: experimental — wrapper is structurally conformant; no
+# maintainer trace against a real allin1 install captured yet. See
+# docs/contracts/provider-lifecycle.md for promotion criteria.
+#
+# Backend: local-cli. allin1 separates stems internally (demucs) and
+# returns beats/downbeats/segments for the full mix — the optional
+# stdin `stem` hint is accepted and ignored. No network, no spend, so
+# `analyze` runs under the AIV_DRYRUN=true default; a missing CLI
+# exits 3 with the install hint (contract § fallback semantics: that
+# is a CONFIG failure — the orchestrator hard-fails instead of
+# silently degrading to probe-audio.sh when this provider is enabled).
+#
+# Provider block (agents/.ai-video.xml):
+#   <provider id="allin1" kind="audio-analysis">
+#     <lifecycle>experimental</lifecycle>
+#     <enabled>true</enabled>
+#   </provider>
+# Kill-switch: <enabled>false</enabled> refuses `analyze` (exit 6).
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="allin1"
+
+_allin1_assert_enabled() {
+  [ "$(aiv_provider_enabled "${ADAPTER_ID}")" = "true" ] \
+    || aiv_die 6 "${ADAPTER_ID}: provider disabled via <enabled>false</enabled> in agents/.ai-video.xml"
+}
+
+# _allin1_read_audio_path — parse + validate stdin {audio_path}. The
+# path is operator-supplied (not provider-returned) but still checked:
+# must exist and carry an audio stream before any exec.
+_allin1_read_audio_path() {
+  local stdin_json audio_path
+  stdin_json="$(cat)"
+  audio_path="$(printf '%s' "${stdin_json}" | jq -r '.audio_path // empty' 2>/dev/null)" \
+    || aiv_die 7 "${ADAPTER_ID}: malformed stdin JSON"
+  [ -n "${audio_path}" ] || aiv_die 7 "${ADAPTER_ID}: audio_path required on stdin"
+  [ -f "${audio_path}" ] || aiv_die 7 "${ADAPTER_ID}: audio file not found: ${audio_path}"
+  if command -v ffprobe >/dev/null 2>&1; then
+    ffprobe -v error -select_streams a:0 -show_entries format=duration \
+      -of default=nk=1:nw=1 "${audio_path}" >/dev/null 2>&1 \
+      || aiv_die 7 "${ADAPTER_ID}: no audio stream in: ${audio_path}"
+  fi
+  printf '%s' "${audio_path}"
+}
+
+# analyze — run the local allin1 CLI and map its JSON to the contract
+# shape. allin1 writes ./struct/<name>.json by default; we direct it to
+# a temp dir and read the single result file. Output mapping:
+#   allin1: {bpm, beats:[...], downbeats:[...], segments:[{start,end,label}]}
+#   contract: {schema, source, bpm, beats, downbeats, sections:[{start,end,label}]}
+aiv_cmd_analyze() {
+  aiv_require_cmd jq
+  aiv_load_provider "${ADAPTER_ID}" >/dev/null 2>&1 || true
+  _allin1_assert_enabled
+  command -v allin1 >/dev/null 2>&1 \
+    || aiv_die 3 "${ADAPTER_ID}: 'allin1' CLI not found — install it (pip install allin1) or disable the provider with <enabled>false</enabled>"
+
+  local audio_path out_dir result
+  audio_path="$(_allin1_read_audio_path)"
+  out_dir="$(mktemp -d "${TMPDIR:-/tmp}/aiv-allin1.XXXXXX")"
+  trap 'rm -rf "${out_dir}"' EXIT
+
+  # Local exec, no network: tolerated under the AIV_DRYRUN default
+  # (contract v1 — dry-run gates SPEND, local analysis has none).
+  if ! allin1 --out-dir "${out_dir}" "${audio_path}" >&2; then
+    aiv_die 75 "${ADAPTER_ID}: allin1 run failed (transient — caller may retry or fall back to probe-audio.sh)"
+  fi
+
+  result="$(find "${out_dir}" -name '*.json' -type f | head -1)"
+  [ -n "${result}" ] || aiv_die 75 "${ADAPTER_ID}: allin1 produced no result JSON"
+
+  jq '{
+    schema: 1,
+    source: "allin1",
+    bpm: (.bpm // 0),
+    beats: (.beats // []),
+    downbeats: (.downbeats // []),
+    sections: [ (.segments // [])[] | {start: .start, end: .end, label: .label} ]
+  }' "${result}" \
+    || aiv_die 75 "${ADAPTER_ID}: allin1 result JSON did not match the expected shape"
+}
+
+aiv_audio_capability() {
+  printf '{"kind":"audio-analysis","provides":["bpm","beats","downbeats","sections"],"backend":"local-cli"}\n'
+}
+
+aiv_audio_dry_run() {
+  local fixture="${AIV_FIXTURE_ROOT}/${ADAPTER_ID}/analysis.json"
+  [ -f "${fixture}" ] || aiv_die 3 "fixture missing: ${fixture}"
+  cat "${fixture}"
+}
+
+# Dispatch — filter-shape contract (analyze | capability | dry-run);
+# fail-closed on anything else (exit 2, named error).
+sub="${1:-}"
+case "${sub}" in
+  analyze)    shift; aiv_cmd_analyze "$@" ;;
+  capability) aiv_audio_capability ;;
+  dry-run)    aiv_audio_dry_run ;;
+  "")         aiv_die 2 "${ADAPTER_ID}: subcommand required (analyze|capability|dry-run)" ;;
+  *)          aiv_die 2 "${ADAPTER_ID}: unknown subcommand: ${sub}" ;;
+esac

package/src/scripts/ai-video/audio-adapters/whisperx.sh

@@ -0,0 +1,128 @@
+#!/usr/bin/env bash
+# whisperx.sh — reference lyrics adapter: word-level timestamps + per-line
+# speaker (forced alignment + diarization), backed by an operator-installed
+# `whisperx` CLI (https://github.com/m-bain/whisperX — installed via pip by
+# the OPERATOR; the suite ships only this wrapper, never the ML deps).
+#
+# Class: lyrics (filter-shape, synchronous `analyze`).
+# Contract: scripts/ai-video/lib/audio-adapter-contract.md (v1).
+#
+# Lifecycle: experimental — wrapper is structurally conformant; no
+# maintainer trace against a real whisperx install captured yet. See
+# docs/contracts/provider-lifecycle.md for promotion criteria.
+#
+# Ground truth (media-sync-ground-truth Iron Law): the emitted timing is
+# VERBATIM whisperx output — this adapter never re-times, merges, or
+# invents lines. `speaker` is the raw diarization label (SPEAKER_00, …)
+# or "?" when diarization is unavailable or a line mixes speakers; the
+# adapter NEVER guesses a name. Mapping labels → cast names is the
+# song-to-script skill's job (operator roster); unmatched stays "?".
+#
+# Backend: local-cli. No network, no spend → `analyze` runs under the
+# AIV_DRYRUN=true default; a missing CLI exits 3 with the install hint
+# (config failure → the orchestrator hard-fails rather than silently
+# degrading when this provider is enabled).
+#
+# Provider block (agents/.ai-video.xml):
+#   <provider id="whisperx" kind="lyrics">
+#     <lifecycle>experimental</lifecycle>
+#     <enabled>true</enabled>
+#   </provider>
+# Kill-switch: <enabled>false</enabled> refuses `analyze` (exit 6).
+
+set -euo pipefail
+
+# shellcheck source=../lib/adapter-common.sh
+. "$(dirname "$0")/../lib/adapter-common.sh"
+
+ADAPTER_ID="whisperx"
+
+_whisperx_assert_enabled() {
+  [ "$(aiv_provider_enabled "${ADAPTER_ID}")" = "true" ] \
+    || aiv_die 6 "${ADAPTER_ID}: provider disabled via <enabled>false</enabled> in agents/.ai-video.xml"
+}
+
+# analyze — run the local whisperx CLI (JSON output, word alignment,
+# diarization when the operator's install supports it) and map its
+# output to the contract shape.
+aiv_cmd_analyze() {
+  aiv_require_cmd jq
+  aiv_load_provider "${ADAPTER_ID}" >/dev/null 2>&1 || true
+  _whisperx_assert_enabled
+  command -v whisperx >/dev/null 2>&1 \
+    || aiv_die 3 "${ADAPTER_ID}: 'whisperx' CLI not found — install it (pip install whisperx) or disable the provider with <enabled>false</enabled>"
+
+  local stdin_json audio_path language out_dir result
+  stdin_json="$(cat)"
+  audio_path="$(printf '%s' "${stdin_json}" | jq -r '.audio_path // empty' 2>/dev/null)" \
+    || aiv_die 7 "${ADAPTER_ID}: malformed stdin JSON"
+  [ -n "${audio_path}" ] || aiv_die 7 "${ADAPTER_ID}: audio_path required on stdin"
+  [ -f "${audio_path}" ] || aiv_die 7 "${ADAPTER_ID}: audio file not found: ${audio_path}"
+  language="$(printf '%s' "${stdin_json}" | jq -r '.language // empty')"
+
+  out_dir="$(mktemp -d "${TMPDIR:-/tmp}/aiv-whisperx.XXXXXX")"
+  trap 'rm -rf "${out_dir}"' EXIT
+
+  # --diarize requires the operator's HF token setup; run without it
+  # when unavailable — speakers then come back absent and every line is
+  # emitted with speaker "?" (never a guessed name).
+  local -a args
+  args=("${audio_path}" --output_dir "${out_dir}" --output_format json)
+  [ -n "${language}" ] && args+=(--language "${language}")
+  if [ "${WHISPERX_DIARIZE:-true}" != "false" ] && [ -n "${HF_TOKEN:-}" ]; then
+    args+=(--diarize)
+  fi
+
+  if ! whisperx "${args[@]}" >&2; then
+    aiv_die 75 "${ADAPTER_ID}: whisperx run failed (transient — caller may retry or fall back)"
+  fi
+
+  result="$(find "${out_dir}" -name '*.json' -type f | head -1)"
+  [ -n "${result}" ] || aiv_die 75 "${ADAPTER_ID}: whisperx produced no result JSON"
+
+  # whisperx JSON: {segments:[{start,end,text,speaker?,words:[{word,start,end,speaker?}]}], language}
+  # Contract: lines[].speaker = raw label or "?" — a segment without a
+  # speaker, or whose words carry >1 distinct label, maps to "?".
+  jq '{
+    schema: 1,
+    source: "whisperx",
+    language: (.language // "unknown"),
+    lines: [ (.segments // [])[] | {
+      start: .start,
+      end: .end,
+      text: (.text | gsub("^\\s+|\\s+$"; "")),
+      speaker: (
+        ([.words[]?.speaker] + [.speaker] | map(select(. != null)) | unique) as $sp
+        | if ($sp | length) == 1 then $sp[0] else "?" end
+      )
+    } ],
+    words: [ (.segments // [])[].words[]? | {
+      start: (.start // null),
+      end: (.end // null),
+      word: .word,
+      speaker: (.speaker // "?")
+    } ]
+  }' "${result}" \
+    || aiv_die 75 "${ADAPTER_ID}: whisperx result JSON did not match the expected shape"
+}
+
+aiv_audio_capability() {
+  printf '{"kind":"lyrics","provides":["lines","words","speakers"],"backend":"local-cli"}\n'
+}
+
+aiv_audio_dry_run() {
+  local fixture="${AIV_FIXTURE_ROOT}/${ADAPTER_ID}/transcript.json"
+  [ -f "${fixture}" ] || aiv_die 3 "fixture missing: ${fixture}"
+  cat "${fixture}"
+}
+
+# Dispatch — filter-shape contract (analyze | capability | dry-run);
+# fail-closed on anything else (exit 2, named error).
+sub="${1:-}"
+case "${sub}" in
+  analyze)    shift; aiv_cmd_analyze "$@" ;;
+  capability) aiv_audio_capability ;;
+  dry-run)    aiv_audio_dry_run ;;
+  "")         aiv_die 2 "${ADAPTER_ID}: subcommand required (analyze|capability|dry-run)" ;;
+  *)          aiv_die 2 "${ADAPTER_ID}: unknown subcommand: ${sub}" ;;
+esac