From a0d09edc42195d2c719b7a8dbf36267b74e0e64d Mon Sep 17 00:00:00 2001
From: Vuong Hoang <vh@phasefinal.com>
Date: Mon, 11 May 2026 16:25:37 -0700
Subject: [PATCH] =?UTF-8?q?catalog:=20vibevoice=20v1=20->=20v2=20=E2=80=94?=
 =?UTF-8?q?=20fix=20model=20options,=20voice=20list,=20response=5Fformat?=
 =?UTF-8?q?=20enum?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Sweep round caught vibevoice catalog drift in three dimensions; all
verified against the live OpenAPI + endpoint exercise, NOT against
documentation (which is what produced the bad values originally).

model:
  was: options=[vibevoice], default=vibevoice
  now: options=[tts-1, tts-1-hd, vibevoice], default=tts-1
  why: the wrapper accepts all three (OpenAI-compat aliases all map
  to VibeVoice internally per upstream README); wire default is tts-1
  per /openapi.json. Catalog over-constrained users to a single value.

voice:
  was: default=Carter; description listed [Carter, Davis, Emma, Frank,
       Grace, Mike, Samuel] as built-ins
  now: default=en-Carter_man; options enumerated:
       OpenAI: alloy, echo, fable, onyx, nova, shimmer
       VibeVoice: en-Alice_woman, en-Carter_man, en-Frank_man,
                  en-Mary_woman_bgm, en-Maya_woman, in-Samuel_man,
                  zh-Anchen_man_bgm, zh-Bowen_man, zh-Xinran_woman
  why: discovered by hitting the endpoint with the catalog's claimed
  "Carter" — wrapper returned 400 with the actual valid list inline
  in the error body. The previous catalog values were fabrications,
  not derived from any real source.

response_format:
  was: options=[wav, mp3]
  now: options=[wav, mp3, opus, flac, pcm]; default mp3 (was wav)
  why: probed all 7 plausible formats; 5 return audio (200), aac and
  m4a return 500. Catalog was over-restrictive; an earlier sweep
  draft over-claimed [wav, mp3, opus, aac, flac, pcm, m4a] from
  documentation that I refused to apply unverified. Now matches the
  empirically-confirmed set.

Bumped vibevoice version 1 -> 2. catalog_version stays at 1.

Lesson reinforced: the only source-of-truth for catalog values is
the live wire. /openapi.json doesn't enumerate enums (returns bare
"string"); error responses from the endpoint with bad inputs are
the most reliable enum-discovery mechanism.
---
 docs/asset-engine/services.yaml | 44 ++++++++++++++++++++++++++-------
 1 file changed, 35 insertions(+), 9 deletions(-)

diff --git a/docs/asset-engine/services.yaml b/docs/asset-engine/services.yaml
index 1b7facc..906cf6a 100644
--- a/docs/asset-engine/services.yaml
+++ b/docs/asset-engine/services.yaml
@@ -545,7 +545,7 @@ services:
       Microsoft's diffusion-based long-form multi-speaker TTS. Multi-minute scripts
       with speaker switching. Not for low-latency single-line use.
     category: tts
-    version: 1
+    version: 2
     host: irv-ml1
     endpoint: http://10.100.79.3:8194/v1/audio/speech
     method: POST
@@ -557,8 +557,11 @@ services:
     fields:
       - name: model
         type: select
-        options: [vibevoice]
-        default: vibevoice
+        options: [tts-1, tts-1-hd, vibevoice]
+        default: tts-1
+        description: >
+          OpenAI-compatibility aliases all map to VibeVoice internally.
+          Wire default is tts-1 (verified against /openapi.json).
       - name: input
         type: textarea
         label: "Text (or Speaker N: ... script)"
@@ -569,15 +572,38 @@ services:
       - name: voice
         type: select
         label: Voice
-        default: Carter
+        default: en-Carter_man
         description: >
-          Built-in: Carter, Davis, Emma, Frank, Grace, Mike, Samuel.
-          Custom: drop WAV/MP3/FLAC/M4A into /worktank/vibevoice/voices/, restart container.
-          Voice cloning training NOT released by Microsoft.
+          OpenAI presets: alloy, echo, fable, onyx, nova, shimmer.
+          VibeVoice presets: en-Alice_woman, en-Carter_man, en-Frank_man,
+          en-Mary_woman_bgm, en-Maya_woman, in-Samuel_man, zh-Anchen_man_bgm,
+          zh-Bowen_man, zh-Xinran_woman.
+          Custom: drop WAV/MP3/FLAC/M4A into /worktank/vibevoice/voices/,
+          restart container. Voice cloning training NOT released by Microsoft.
+        options:
+          - alloy
+          - echo
+          - fable
+          - onyx
+          - nova
+          - shimmer
+          - en-Alice_woman
+          - en-Carter_man
+          - en-Frank_man
+          - en-Mary_woman_bgm
+          - en-Maya_woman
+          - in-Samuel_man
+          - zh-Anchen_man_bgm
+          - zh-Bowen_man
+          - zh-Xinran_woman
       - name: response_format
         type: select
-        options: [wav, mp3]
-        default: wav
+        options: [wav, mp3, opus, flac, pcm]
+        default: mp3
+        description: >
+          Wire default is mp3 (verified /openapi.json). All five values
+          confirmed by exercising the endpoint 2026-05-11; aac and m4a
+          fail with 500 despite OpenAPI not enforcing an enum, so excluded.
       - name: stream
         type: bool
         default: false