Merge pull request 'feat: wave-3 audio surfaces — stems, SFX, speech enhance, voice clone, translate (ADR-0024)' (#18) from feat/wave3-audio-surfaces into main

provider/llamaswap/audio.go

@@ -9,6 +9,7 @@ import (
 	"mime"
 	"net/http"
 	"net/url"
+	"strconv"
 	"strings"
 
 	"gitea.stevedudenhoeffer.com/steve/majordomo/audio"
@@ -42,7 +43,11 @@ type speechRequest struct {
 	Speed          float64 `json:"speed,omitempty"`
 }
 
-// Speak implements audio.SpeechModel via POST {base}/v1/audio/speech.
+// Speak implements audio.SpeechModel via POST {base}/v1/audio/speech, or —
+// when the request carries reference audio for voice cloning — via multipart
+// POST {base}/upstream/<id>/v1/audio/speech/upload (the chatterbox clone
+// route; verified live 2026-07-16: stateless per-request cloning, fields
+// `input` + `voice_file`).
 func (m *speechModel) Speak(ctx context.Context, req audio.SpeechRequest, opts ...audio.SpeechOption) (*audio.SpeechResult, error) {
 	req = req.Apply(opts...)
 	if strings.TrimSpace(req.Input) == "" {
@@ -51,6 +56,9 @@ func (m *speechModel) Speak(ctx context.Context, req audio.SpeechRequest, opts .
 	if req.Speed < 0 {
 		return nil, fmt.Errorf("%w: speech speed must be >= 0, got %g", llm.ErrUnsupported, req.Speed)
 	}
+	if len(req.ReferenceAudio) > 0 {
+		return m.speakWithReference(ctx, req)
+	}
 	wire := speechRequest{
 		Model:          m.id,
 		Input:          req.Input,
@@ -72,6 +80,48 @@ func (m *speechModel) Speak(ctx context.Context, req audio.SpeechRequest, opts .
 	return &audio.SpeechResult{Audio: audioBytes, MIME: speechMIME(contentType, req.Format)}, nil
 }
 
+// speakWithReference performs zero-shot voice cloning via the upstream
+// passthrough clone route. The reference sample rides as the `voice_file`
+// part and the text as an `input` field; voice/format/speed still go on the
+// wire when set (upstreams ignore fields they don't understand). The result
+// MIME comes from the response header or content sniffing (audioResultMIME,
+// same validation as the sfx/enhance surfaces) — a JSON soft error or an
+// HTML proxy page must never be wrapped up as audio bytes.
+func (m *speechModel) speakWithReference(ctx context.Context, req audio.SpeechRequest) (*audio.SpeechResult, error) {
+	upPath, err := upstreamPath(m.id, "/v1/audio/speech/upload")
+	if err != nil {
+		return nil, err
+	}
+	speed := ""
+	if req.Speed != 0 {
+		speed = strconv.FormatFloat(req.Speed, 'g', -1, 64)
+	}
+	body, formType, err := buildMultipart("build speech clone form",
+		filePart{field: "voice_file", filename: transcriptionFilename("", req.ReferenceMIME), data: req.ReferenceAudio},
+		[]formField{
+			{"input", req.Input, true},
+			{"voice", req.Voice, false},
+			{"response_format", req.Format, false},
+			{"speed", speed, false},
+		})
+	if err != nil {
+		return nil, err
+	}
+	audioBytes, contentType, err := m.p.doRaw(ctx, http.MethodPost, upPath, m.id, formType, body, maxAudioResponseBytes)
+	if err != nil {
+		return nil, err
+	}
+	if len(audioBytes) == 0 {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id, Message: "speech clone response contained no audio"}
+	}
+	mimeType := audioResultMIME(contentType, audioBytes)
+	if mimeType == "" {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+			Message: fmt.Sprintf("speech clone response is not audio (Content-Type %q): %s", contentType, truncateForError(audioBytes))}
+	}
+	return &audio.SpeechResult{Audio: audioBytes, MIME: mimeType}, nil
+}
+
 // speechMIME resolves the result MIME type: the response Content-Type when it
 // is a concrete audio type, else a mapping from the requested format, else
 // audio/mpeg (the OpenAI endpoint's default container is mp3).
@@ -93,6 +143,28 @@ func speechMIME(contentType, format string) string {
 	}
 }
 
+// audioResultMIME resolves an audio body's MIME type: the response
+// Content-Type when it is a concrete audio type, else content sniffing
+// (RIFF/WAVE, Ogg and friends), else "" — the caller treats undetectable as
+// an upstream error, mirroring videoMIME. Sniffed "audio/wave" is normalized
+// to the conventional "audio/wav", and Ogg's container type
+// "application/ogg" to "audio/ogg". Shared by the clone, sfx, and enhance
+// surfaces, which all answer raw audio bodies.
+func audioResultMIME(contentType string, data []byte) string {
+	if mt := mimeFromContentType(contentType, "audio/"); mt != "" {
+		return mt
+	}
+	switch mt := http.DetectContentType(data); {
+	case mt == "audio/wave":
+		return "audio/wav"
+	case mt == "application/ogg":
+		return "audio/ogg"
+	case strings.HasPrefix(mt, "audio/"):
+		return mt
+	}
+	return ""
+}
+
 // TranscriptionModel implements audio.TranscriptionProvider, binding a
 // speech-to-text model served by llama-swap (routed to a whisper.cpp-style
 // upstream).
@@ -118,13 +190,26 @@ func (m *transcriptionModel) Transcribe(ctx context.Context, req audio.Transcrip
 		return nil, fmt.Errorf("%w: transcription requires audio bytes", llm.ErrUnsupported)
 	}
 
+	// Translation is a per-request bool form field on whisper.cpp's server
+	// (server.cpp:534, verified 2026-07-16). Its language DEFAULT is "en",
+	// which would make translate a no-op — so an explicit language hint
+	// wins, but an unset one is forced to auto-detection.
+	translate := ""
+	language := req.Language
+	if req.Translate {
+		translate = "true"
+		if language == "" {
+			language = "auto"
+		}
+	}
 	buf, formType, err := buildMultipart("build transcription form",
 		filePart{field: "file", filename: transcriptionFilename(req.Filename, req.MIME), data: req.Audio},
 		[]formField{
 			{"model", m.id, true},
 			{"response_format", "json", true},
-			{"language", req.Language, false},
+			{"language", language, false},
 			{"prompt", req.Prompt, false},
+			{"translate", translate, false},
 		})
 	if err != nil {
 		return nil, err
@@ -177,10 +262,13 @@ func transcriptionFilename(filename, mimeType string) string {
 }
 
 // sanitizeFilename strips characters that would corrupt or inject into the
-// multipart Content-Disposition header. Quotes and backslashes are escaped
-// by mime/multipart itself; CR/LF are not — they must go.
+// multipart Content-Disposition header, or smuggle directory structure to
+// the receiving side. Quotes and backslashes are escaped by mime/multipart
+// itself, but a file-writing shim decodes them right back — so CR/LF/NUL
+// and both path separators are dropped: an upload-metadata filename must
+// never traverse ("../x", "a/b", "C:\x").
 func sanitizeFilename(name string) string {
-	name = strings.NewReplacer("\r", "", "\n", "").Replace(name)
+	name = strings.NewReplacer("\r", "", "\n", "", "\x00", "", "/", "", "\\", "").Replace(name)
 	return strings.TrimSpace(name)
 }
 

provider/llamaswap/clone_translate_test.go

@@ -0,0 +1,215 @@
+package llamaswap
+
+import (
+	"context"
+	"errors"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/audio"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+func TestSpeakWithReferenceUsesCloneRoute(t *testing.T) {
+	var gotPath, gotInput, gotVoice, gotFilename string
+	var gotRef []byte
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		gotInput = r.FormValue("input")
+		gotVoice = r.FormValue("voice")
+		f, hdr, err := r.FormFile("voice_file")
+		if err != nil {
+			t.Fatalf("voice_file part: %v", err)
+		}
+		defer f.Close()
+		gotRef, _ = io.ReadAll(f)
+		gotFilename = hdr.Filename
+		w.Header().Set("Content-Type", "audio/wav")
+		_, _ = w.Write(wavFixture())
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, _ := p.SpeechModel("chatterbox")
+	res, err := sm.Speak(context.Background(),
+		audio.SpeechRequest{Input: "hello in my voice", Voice: "narrator"},
+		audio.WithReferenceAudio([]byte("REFWAV"), "audio/wav"))
+	if err != nil {
+		t.Fatalf("Speak: %v", err)
+	}
+	if gotPath != "/upstream/chatterbox/v1/audio/speech/upload" {
+		t.Errorf("path = %q, want clone route", gotPath)
+	}
+	if gotInput != "hello in my voice" || gotVoice != "narrator" {
+		t.Errorf("input/voice = %q/%q", gotInput, gotVoice)
+	}
+	if string(gotRef) != "REFWAV" || gotFilename != "audio.wav" {
+		t.Errorf("ref = %q name = %q", gotRef, gotFilename)
+	}
+	if res.MIME != "audio/wav" || len(res.Audio) == 0 {
+		t.Errorf("result = %q/%d bytes", res.MIME, len(res.Audio))
+	}
+}
+
+func TestSpeakWithReferenceSniffsHeaderlessWav(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		for _, k := range []string{"voice", "response_format", "speed"} {
+			if v, ok := r.MultipartForm.Value[k]; ok {
+				t.Errorf("unset request sent %q = %v, want omitted", k, v)
+			}
+		}
+		w.Header()["Content-Type"] = nil // no declared type at all
+		_, _ = w.Write(wavFixture())
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, _ := p.SpeechModel("chatterbox")
+	res, err := sm.Speak(context.Background(),
+		audio.SpeechRequest{Input: "hi"},
+		audio.WithReferenceAudio([]byte("REF"), ""))
+	if err != nil {
+		t.Fatalf("Speak: %v", err)
+	}
+	// Headerless RIFF sniffs audio/wave, normalized to the conventional wav.
+	if res.MIME != "audio/wav" {
+		t.Errorf("MIME = %q, want sniffed audio/wav", res.MIME)
+	}
+}
+
+func TestSpeakWithReferenceRejectsNonAudioResponse(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		// A FastAPI-style 2xx soft error must not be wrapped up as audio.
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"detail":"reference audio too short"}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, _ := p.SpeechModel("chatterbox")
+	_, err := sm.Speak(context.Background(),
+		audio.SpeechRequest{Input: "hi"},
+		audio.WithReferenceAudio([]byte("REF"), "audio/wav"))
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("err = %v, want APIError for non-audio clone body", err)
+	}
+}
+
+func TestSanitizeFilenameStripsPathAndControlBytes(t *testing.T) {
+	for in, want := range map[string]string{
+		"song.mp3":                "song.mp3",
+		"../../etc/passwd":        "....etcpasswd",
+		"a\r\nContent-Type: evil": "aContent-Type: evil",
+		"..\\..\\boot.ini":        "....boot.ini",
+		"nul\x00byte.wav":         "nulbyte.wav",
+		"  /  ":                   "",
+	} {
+		if got := sanitizeFilename(in); got != want {
+			t.Errorf("sanitizeFilename(%q) = %q, want %q", in, got, want)
+		}
+	}
+}
+
+func TestSpeakWithoutReferenceKeepsJSONRoute(t *testing.T) {
+	var gotPath, gotContentType string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		gotContentType = r.Header.Get("Content-Type")
+		_, _ = w.Write([]byte("MP3"))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, _ := p.SpeechModel("chatterbox")
+	if _, err := sm.Speak(context.Background(), audio.SpeechRequest{Input: "hi"}); err != nil {
+		t.Fatalf("Speak: %v", err)
+	}
+	if gotPath != "/v1/audio/speech" || gotContentType != "application/json" {
+		t.Errorf("path/content-type = %q/%q, want JSON route", gotPath, gotContentType)
+	}
+}
+
+func TestTranscribeTranslateForcesAutoLanguage(t *testing.T) {
+	var gotTranslate, gotLanguage string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		gotTranslate = r.FormValue("translate")
+		gotLanguage = r.FormValue("language")
+		_, _ = w.Write([]byte(`{"text":"hello"}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	tm, _ := p.TranscriptionModel("whisper-large-v3-turbo")
+	res, err := tm.Transcribe(context.Background(),
+		audio.TranscriptionRequest{Audio: []byte("AUDIO")},
+		audio.WithTranslate())
+	if err != nil {
+		t.Fatalf("Transcribe: %v", err)
+	}
+	// whisper.cpp's server default language is "en", which would skip
+	// translation — translate must force auto-detection when no explicit
+	// language hint was given.
+	if gotTranslate != "true" || gotLanguage != "auto" {
+		t.Errorf("translate/language = %q/%q, want true/auto", gotTranslate, gotLanguage)
+	}
+	if res.Text != "hello" {
+		t.Errorf("text = %q", res.Text)
+	}
+}
+
+func TestTranscribeTranslateKeepsExplicitLanguage(t *testing.T) {
+	var gotTranslate, gotLanguage string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		gotTranslate = r.FormValue("translate")
+		gotLanguage = r.FormValue("language")
+		_, _ = w.Write([]byte(`{"text":"hello"}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	tm, _ := p.TranscriptionModel("whisper-large-v3-turbo")
+	if _, err := tm.Transcribe(context.Background(),
+		audio.TranscriptionRequest{Audio: []byte("AUDIO"), Language: "de", Translate: true}); err != nil {
+		t.Fatalf("Transcribe: %v", err)
+	}
+	if gotTranslate != "true" || gotLanguage != "de" {
+		t.Errorf("translate/language = %q/%q, want true/de", gotTranslate, gotLanguage)
+	}
+}
+
+func TestTranscribeWithoutTranslateOmitsFields(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		for _, k := range []string{"translate", "language"} {
+			if v, ok := r.MultipartForm.Value[k]; ok {
+				t.Errorf("unset request sent %q = %v, want omitted", k, v)
+			}
+		}
+		_, _ = w.Write([]byte(`{"text":"hi"}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	tm, _ := p.TranscriptionModel("whisper-large-v3-turbo")
+	if _, err := tm.Transcribe(context.Background(),
+		audio.TranscriptionRequest{Audio: []byte("AUDIO")}); err != nil {
+		t.Fatalf("Transcribe: %v", err)
+	}
+}

provider/llamaswap/enhance.go

@@ -0,0 +1,61 @@
+// enhance.go implements audio.SpeechEnhancementProvider against a
+// DeepFilterNet shim (audioutils) reached through llama-swap's /upstream
+// passthrough (ADR-0024):
+//
+//	POST /upstream/<id>/v1/enhance   multipart file -> WAV
+package llamaswap
+
+import (
+	"context"
+	"fmt"
+	"net/http"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/audio"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// SpeechEnhancerModel implements audio.SpeechEnhancementProvider. The id
+// selects which upstream llama-swap loads.
+func (p *Provider) SpeechEnhancerModel(id string, opts ...audio.SpeechEnhancerModelOption) (audio.SpeechEnhancer, error) {
+	if err := p.requireBaseURL(); err != nil {
+		return nil, err
+	}
+	_ = audio.ApplySpeechEnhancerModelOptions(opts)
+	return &speechEnhancerModel{p: p, id: id}, nil
+}
+
+type speechEnhancerModel struct {
+	p  *Provider
+	id string
+}
+
+// Enhance implements audio.SpeechEnhancer. The endpoint always answers WAV.
+func (m *speechEnhancerModel) Enhance(ctx context.Context, req audio.EnhancementRequest, opts ...audio.EnhancementOption) (*audio.SpeechResult, error) {
+	req = req.Apply(opts...)
+	if len(req.Audio) == 0 {
+		return nil, fmt.Errorf("%w: speech enhancement requires audio bytes", llm.ErrUnsupported)
+	}
+	path, err := upstreamPath(m.id, "/v1/enhance")
+	if err != nil {
+		return nil, err
+	}
+	body, contentType, err := buildMultipart("build enhance form",
+		filePart{field: "file", filename: transcriptionFilename(req.Filename, req.MIME), data: req.Audio},
+		nil)
+	if err != nil {
+		return nil, err
+	}
+	raw, respType, err := m.p.doRaw(ctx, http.MethodPost, path, m.id, contentType, body, maxAudioResponseBytes)
+	if err != nil {
+		return nil, err
+	}
+	if len(raw) == 0 {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id, Message: "enhance response contained no audio"}
+	}
+	mimeType := audioResultMIME(respType, raw)
+	if mimeType == "" {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+			Message: fmt.Sprintf("enhance response is not audio (Content-Type %q): %s", respType, truncateForError(raw))}
+	}
+	return &audio.SpeechResult{Audio: raw, MIME: mimeType}, nil
+}

provider/llamaswap/llamaswap.go

@@ -53,6 +53,12 @@ const maxResponseBytes = 64 << 20
 // can't allocate without limit.
 const maxVideoResponseBytes = 512 << 20
 
+// maxAudioResponseBytes caps bodies that ARE a single encoded audio clip
+// (voice clone, speech enhancement, sfx): a long uncompressed WAV
+// legitimately passes the 64MB JSON cap. Still bounded so a buggy upstream
+// can't allocate without limit.
+const maxAudioResponseBytes = 256 << 20
+
 // Provider is a llama-swap client. It satisfies llm.Provider (chat, delegated
 // to provider/openai) and imagegen.Provider (image generation), and exposes
 // llama-swap's management endpoints as concrete methods.

provider/llamaswap/sfx.go

@@ -0,0 +1,100 @@
+// sfx.go implements a second musicgen.Model factory against a Stable Audio
+// Open shim (sfxgen) reached through llama-swap's /upstream passthrough
+// (ADR-0024):
+//
+//	POST /upstream/<id>/v1/sfx   JSON {prompt, seconds?, steps?, cfg_scale?, seed?}
+//
+// Unlike the ACE-Step music path (music.go), /v1/sfx is SYNCHRONOUS: the
+// response body is the finished WAV clip — no job queue, no polling. The
+// surface reuses the musicgen types (a sound effect is a short audio clip
+// from a text prompt); only the provider method differs.
+package llamaswap
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"fmt"
+	"net/http"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/musicgen"
+)
+
+// SFXModel returns a musicgen.Model bound to a sync sound-effect backend.
+// The id selects which upstream llama-swap loads.
+func (p *Provider) SFXModel(id string, opts ...musicgen.ModelOption) (musicgen.Model, error) {
+	if err := p.requireBaseURL(); err != nil {
+		return nil, err
+	}
+	_ = musicgen.ApplyModelOptions(opts)
+	return &sfxModel{p: p, id: id}, nil
+}
+
+type sfxModel struct {
+	p  *Provider
+	id string
+}
+
+// sfxRequest is the sfxgen shim's /v1/sfx shape. Optional fields stay off
+// the wire so the model's own defaults apply.
+type sfxRequest struct {
+	Prompt   string   `json:"prompt"`
+	Seconds  int      `json:"seconds,omitempty"`
+	Steps    *int     `json:"steps,omitempty"`
+	CFGScale *float64 `json:"cfg_scale,omitempty"`
+	Seed     *int64   `json:"seed,omitempty"`
+}
+
+// Generate implements musicgen.Model. The clip-length ceiling (~11s for
+// Stable Audio Open Small) is the backend's to enforce, not this client's.
+func (m *sfxModel) Generate(ctx context.Context, req musicgen.Request, opts ...musicgen.Option) (*musicgen.Result, error) {
+	req = req.Apply(opts...)
+	if strings.TrimSpace(req.Prompt) == "" {
+		return nil, fmt.Errorf("%w: sfx generation requires a prompt", llm.ErrUnsupported)
+	}
+	if req.Lyrics != "" {
+		return nil, fmt.Errorf("%w: sfx generation does not support lyrics", llm.ErrUnsupported)
+	}
+	if req.DurationSeconds < 0 {
+		return nil, fmt.Errorf("%w: duration must be >= 0, got %d", llm.ErrUnsupported, req.DurationSeconds)
+	}
+	if req.Steps != nil && *req.Steps <= 0 {
+		return nil, fmt.Errorf("%w: inference steps must be > 0, got %d", llm.ErrUnsupported, *req.Steps)
+	}
+	// The endpoint emits WAV only; a caller asking for another container
+	// would silently get mislabelled bytes — reject instead.
+	if f := strings.ToLower(strings.TrimSpace(req.Format)); f != "" && f != "wav" {
+		return nil, fmt.Errorf("%w: sfx output is wav only, got format %q", llm.ErrUnsupported, req.Format)
+	}
+
+	path, err := upstreamPath(m.id, "/v1/sfx")
+	if err != nil {
+		return nil, err
+	}
+	wire := sfxRequest{
+		Prompt:   req.Prompt,
+		Seconds:  req.DurationSeconds,
+		Steps:    req.Steps,
+		CFGScale: req.CFGScale,
+		Seed:     req.Seed,
+	}
+	encoded, err := json.Marshal(wire)
+	if err != nil {
+		return nil, fmt.Errorf("llama-swap: encode sfx request: %w", err)
+	}
+	raw, contentType, err := m.p.doRaw(ctx, http.MethodPost, path, m.id, "application/json", bytes.NewReader(encoded), maxAudioResponseBytes)
+	if err != nil {
+		return nil, err
+	}
+	if len(raw) == 0 {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id, Message: "sfx response contained no audio"}
+	}
+	mimeType := audioResultMIME(contentType, raw)
+	if mimeType == "" {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+			Message: fmt.Sprintf("sfx response is not audio (Content-Type %q): %s", contentType, truncateForError(raw))}
+	}
+	return &musicgen.Result{Audio: musicgen.Audio{Data: raw, MIME: mimeType}}, nil
+}

provider/llamaswap/stems.go

@@ -0,0 +1,165 @@
+// stems.go implements audio.StemSeparationProvider against a Demucs shim
+// (audioutils) reached through llama-swap's /upstream passthrough (ADR-0024):
+//
+//	POST /upstream/<id>/v1/stems   multipart file[,model,two_stems,format]
+//
+// The response is a ZIP of the separated stems — one entry per stem, entry
+// name = stem name, extension = container. Zip transport keeps a 4-stem WAV
+// result (hundreds of MB decoded) off the JSON-of-base64 path entirely.
+package llamaswap
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"path"
+	"strings"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/audio"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+)
+
+// maxStemsResponseBytes caps the /v1/stems zip body: four WAV stems of a
+// long song legitimately pass the 64MB JSON cap. Bounded so a buggy
+// upstream can't allocate without limit.
+const maxStemsResponseBytes = 512 << 20
+
+// maxStemEntryBytes caps ONE decompressed zip entry — the zip-bomb guard.
+// A single WAV stem of even a very long song stays far under this.
+const maxStemEntryBytes = 256 << 20
+
+// maxStemEntries caps how many stem entries are unpacked: Demucs emits at
+// most six, so anything past a small multiple of that is a hostile or
+// broken archive, not a result.
+const maxStemEntries = 16
+
+// maxStemsTotalBytes caps the AGGREGATE decompressed size across entries —
+// the per-entry bound alone would still let a many-entry bomb multiply up.
+const maxStemsTotalBytes = 1 << 30
+
+// StemSeparatorModel implements audio.StemSeparationProvider. The id selects
+// which upstream llama-swap loads.
+func (p *Provider) StemSeparatorModel(id string, opts ...audio.StemSeparatorModelOption) (audio.StemSeparator, error) {
+	if err := p.requireBaseURL(); err != nil {
+		return nil, err
+	}
+	_ = audio.ApplyStemSeparatorModelOptions(opts)
+	return &stemSeparatorModel{p: p, id: id}, nil
+}
+
+type stemSeparatorModel struct {
+	p  *Provider
+	id string
+}
+
+// SeparateStems implements audio.StemSeparator.
+func (m *stemSeparatorModel) SeparateStems(ctx context.Context, req audio.StemSeparationRequest, opts ...audio.StemSeparationOption) (*audio.StemSeparationResult, error) {
+	req = req.Apply(opts...)
+	if len(req.Audio) == 0 {
+		return nil, fmt.Errorf("%w: stem separation requires audio bytes", llm.ErrUnsupported)
+	}
+	mode := strings.ToLower(strings.TrimSpace(req.Mode))
+	if mode != "" && mode != "two" && mode != "four" {
+		return nil, fmt.Errorf("%w: stem mode must be \"two\" or \"four\", got %q", llm.ErrUnsupported, req.Mode)
+	}
+	format := strings.ToLower(strings.TrimSpace(req.Format))
+	if format != "" && format != "mp3" && format != "wav" {
+		return nil, fmt.Errorf("%w: stem format must be \"mp3\" or \"wav\", got %q", llm.ErrUnsupported, req.Format)
+	}
+	upPath, err := upstreamPath(m.id, "/v1/stems")
+	if err != nil {
+		return nil, err
+	}
+	// Demucs' two-stem mode is "isolate one source vs the rest"; vocals is
+	// the split this surface promises ("two" = vocals + accompaniment).
+	twoStems := ""
+	if mode == "two" {
+		twoStems = "vocals"
+	}
+	body, contentType, err := buildMultipart("build stems form",
+		filePart{field: "file", filename: transcriptionFilename(req.Filename, req.MIME), data: req.Audio},
+		[]formField{
+			{"model", req.Model, false},
+			{"two_stems", twoStems, false},
+			{"format", format, false},
+		})
+	if err != nil {
+		return nil, err
+	}
+	raw, respType, err := m.p.doRaw(ctx, http.MethodPost, upPath, m.id, contentType, body, maxStemsResponseBytes)
+	if err != nil {
+		return nil, err
+	}
+	if len(raw) == 0 {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id, Message: "stems response contained no data"}
+	}
+	zr, err := zip.NewReader(bytes.NewReader(raw), int64(len(raw)))
+	if err != nil {
+		// A non-zip 2xx body is a misconfigured upstream (an HTML error page
+		// behind a proxy, a JSON soft error) — fail loud, quoting a slice.
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+			Message: fmt.Sprintf("stems response is not a zip (Content-Type %q): %s", respType, truncateForError(raw))}
+	}
+	res := &audio.StemSeparationResult{}
+	var totalBytes int64
+	for _, f := range zr.File {
+		if f.FileInfo().IsDir() {
+			continue
+		}
+		if len(res.Stems) >= maxStemEntries {
+			return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+				Message: fmt.Sprintf("stems zip holds more than %d entries", maxStemEntries)}
+		}
+		data, err := readZipEntry(f)
+		if err != nil {
+			return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+				Message: fmt.Sprintf("stems zip entry %q: %v", f.Name, err)}
+		}
+		totalBytes += int64(len(data))
+		if totalBytes > maxStemsTotalBytes {
+			return nil, &llm.APIError{Provider: m.p.name, Model: m.id,
+				Message: fmt.Sprintf("stems zip decompresses past %d bytes", int64(maxStemsTotalBytes))}
+		}
+		// Entry name → stem name; extension → MIME. Entries may sit in a
+		// per-model directory ("htdemucs/vocals.mp3"), so use the base name.
+		base := path.Base(f.Name)
+		ext := path.Ext(base)
+		res.Stems = append(res.Stems, audio.Stem{
+			Name:  strings.TrimSuffix(base, ext),
+			Audio: data,
+			MIME:  stemMIME(ext),
+		})
+	}
+	if len(res.Stems) == 0 {
+		return nil, &llm.APIError{Provider: m.p.name, Model: m.id, Message: "stems zip contained no stems"}
+	}
+	return res, nil
+}
+
+// readZipEntry decompresses one entry, bounded by maxStemEntryBytes so a
+// zip bomb can't allocate without limit.
+func readZipEntry(f *zip.File) ([]byte, error) {
+	rc, err := f.Open()
+	if err != nil {
+		return nil, err
+	}
+	defer rc.Close()
+	data, err := io.ReadAll(io.LimitReader(rc, maxStemEntryBytes+1))
+	if err != nil {
+		return nil, err
+	}
+	if int64(len(data)) > maxStemEntryBytes {
+		return nil, fmt.Errorf("decompressed entry exceeds %d bytes", int64(maxStemEntryBytes))
+	}
+	return data, nil
+}
+
+// stemMIME maps a stem file extension to its MIME type, reusing speechMIME's
+// format table ("" and unknown extensions land on the mp3 default — Demucs'
+// own default container).
+func stemMIME(ext string) string {
+	return speechMIME("", strings.TrimPrefix(strings.ToLower(ext), "."))
+}

provider/llamaswap/stems_sfx_enhance_test.go

@@ -0,0 +1,355 @@
+package llamaswap
+
+import (
+	"archive/zip"
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"fmt"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"gitea.stevedudenhoeffer.com/steve/majordomo/audio"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/llm"
+	"gitea.stevedudenhoeffer.com/steve/majordomo/musicgen"
+)
+
+// stemsZipFixture builds a Demucs-style stems zip: entries under a per-model
+// directory, entry name = stem name, extension = container.
+func stemsZipFixture(t *testing.T, entries map[string]string) []byte {
+	t.Helper()
+	var buf bytes.Buffer
+	zw := zip.NewWriter(&buf)
+	for name, data := range entries {
+		w, err := zw.Create(name)
+		if err != nil {
+			t.Fatalf("zip create: %v", err)
+		}
+		if _, err := w.Write([]byte(data)); err != nil {
+			t.Fatalf("zip write: %v", err)
+		}
+	}
+	if err := zw.Close(); err != nil {
+		t.Fatalf("zip close: %v", err)
+	}
+	return buf.Bytes()
+}
+
+func TestSeparateStems(t *testing.T) {
+	zipBody := stemsZipFixture(t, map[string]string{
+		"htdemucs/vocals.mp3":    "VOX",
+		"htdemucs/no_vocals.mp3": "ACC",
+	})
+	var gotPath, gotTwoStems, gotModel, gotFormat, gotFilename string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		gotTwoStems = r.FormValue("two_stems")
+		gotModel = r.FormValue("model")
+		gotFormat = r.FormValue("format")
+		if _, hdr, err := r.FormFile("file"); err == nil {
+			gotFilename = hdr.Filename
+		} else {
+			t.Errorf("file part: %v", err)
+		}
+		w.Header().Set("Content-Type", "application/zip")
+		_, _ = w.Write(zipBody)
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	ss, err := p.StemSeparatorModel("audioutils")
+	if err != nil {
+		t.Fatalf("StemSeparatorModel: %v", err)
+	}
+	res, err := ss.SeparateStems(context.Background(),
+		audio.StemSeparationRequest{Audio: []byte("SONG"), MIME: "audio/mpeg"},
+		audio.WithStemMode("two"), audio.WithStemModel("htdemucs_ft"), audio.WithStemFormat("mp3"))
+	if err != nil {
+		t.Fatalf("SeparateStems: %v", err)
+	}
+	if gotPath != "/upstream/audioutils/v1/stems" {
+		t.Errorf("path = %q", gotPath)
+	}
+	if gotTwoStems != "vocals" || gotModel != "htdemucs_ft" || gotFormat != "mp3" || gotFilename != "audio.mp3" {
+		t.Errorf("two_stems/model/format/filename = %q/%q/%q/%q", gotTwoStems, gotModel, gotFormat, gotFilename)
+	}
+	if len(res.Stems) != 2 {
+		t.Fatalf("stems = %+v", res.Stems)
+	}
+	byName := map[string]audio.Stem{}
+	for _, s := range res.Stems {
+		byName[s.Name] = s
+	}
+	if v := byName["vocals"]; string(v.Audio) != "VOX" || v.MIME != "audio/mpeg" {
+		t.Errorf("vocals = %+v", v)
+	}
+	if a := byName["no_vocals"]; string(a.Audio) != "ACC" || a.MIME != "audio/mpeg" {
+		t.Errorf("no_vocals = %+v", a)
+	}
+}
+
+func TestSeparateStemsOmitsUnsetFields(t *testing.T) {
+	zipBody := stemsZipFixture(t, map[string]string{"vocals.wav": "V"})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		for _, k := range []string{"two_stems", "model", "format"} {
+			if v, ok := r.MultipartForm.Value[k]; ok {
+				t.Errorf("unset request sent %q = %v, want omitted", k, v)
+			}
+		}
+		_, _ = w.Write(zipBody)
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	ss, _ := p.StemSeparatorModel("audioutils")
+	res, err := ss.SeparateStems(context.Background(),
+		audio.StemSeparationRequest{Audio: []byte("SONG")})
+	if err != nil {
+		t.Fatalf("SeparateStems: %v", err)
+	}
+	// Top-level entry, wav extension.
+	if len(res.Stems) != 1 || res.Stems[0].Name != "vocals" || res.Stems[0].MIME != "audio/wav" {
+		t.Errorf("stems = %+v", res.Stems)
+	}
+}
+
+func TestSeparateStemsRejectsBadArgs(t *testing.T) {
+	p := New(WithBaseURL("http://unused"))
+	ss, _ := p.StemSeparatorModel("audioutils")
+	if _, err := ss.SeparateStems(context.Background(), audio.StemSeparationRequest{}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("no audio: err = %v, want ErrUnsupported", err)
+	}
+	if _, err := ss.SeparateStems(context.Background(),
+		audio.StemSeparationRequest{Audio: []byte{1}, Mode: "three"}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("mode three: err = %v, want ErrUnsupported", err)
+	}
+	if _, err := ss.SeparateStems(context.Background(),
+		audio.StemSeparationRequest{Audio: []byte{1}, Format: "flac"}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("format flac: err = %v, want ErrUnsupported", err)
+	}
+}
+
+func TestSeparateStemsRejectsNonZip(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		_, _ = w.Write([]byte("<html>proxy error page</html>"))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	ss, _ := p.StemSeparatorModel("audioutils")
+	_, err := ss.SeparateStems(context.Background(), audio.StemSeparationRequest{Audio: []byte("SONG")})
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("err = %v, want APIError for non-zip body", err)
+	}
+}
+
+func TestSeparateStemsRejectsEmptyZip(t *testing.T) {
+	zipBody := stemsZipFixture(t, map[string]string{})
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/zip")
+		_, _ = w.Write(zipBody)
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	ss, _ := p.StemSeparatorModel("audioutils")
+	_, err := ss.SeparateStems(context.Background(), audio.StemSeparationRequest{Audio: []byte("SONG")})
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("err = %v, want APIError for stem-less zip", err)
+	}
+}
+
+func TestSeparateStemsRejectsTooManyEntries(t *testing.T) {
+	entries := map[string]string{}
+	for i := 0; i <= maxStemEntries; i++ {
+		entries[fmt.Sprintf("stem%02d.wav", i)] = "X"
+	}
+	zipBody := stemsZipFixture(t, entries)
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/zip")
+		_, _ = w.Write(zipBody)
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	ss, _ := p.StemSeparatorModel("audioutils")
+	_, err := ss.SeparateStems(context.Background(), audio.StemSeparationRequest{Audio: []byte("SONG")})
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) || !strings.Contains(apiErr.Message, "entries") {
+		t.Fatalf("err = %v, want APIError for over-long stems zip", err)
+	}
+}
+
+// wavFixture is a minimal RIFF/WAVE header so http.DetectContentType sniffs
+// audio/wave.
+func wavFixture() []byte {
+	return []byte("RIFF\x24\x00\x00\x00WAVEfmt ")
+}
+
+func TestSFXGenerate(t *testing.T) {
+	var gotPath string
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		w.Header().Set("Content-Type", "audio/wav")
+		_, _ = w.Write(wavFixture())
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, err := p.SFXModel("sfxgen-stableaudio")
+	if err != nil {
+		t.Fatalf("SFXModel: %v", err)
+	}
+	res, err := sm.Generate(context.Background(),
+		musicgen.Request{Prompt: "glass shattering", DurationSeconds: 8},
+		musicgen.WithSteps(50), musicgen.WithCFGScale(7), musicgen.WithSeed(42))
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	if gotPath != "/upstream/sfxgen-stableaudio/v1/sfx" {
+		t.Errorf("path = %q", gotPath)
+	}
+	want := map[string]any{"prompt": "glass shattering", "seconds": 8.0, "steps": 50.0, "cfg_scale": 7.0, "seed": 42.0}
+	for k, w := range want {
+		if gotBody[k] != w {
+			t.Errorf("%s = %v, want %v", k, gotBody[k], w)
+		}
+	}
+	if res.Audio.MIME != "audio/wav" || len(res.Audio.Data) == 0 {
+		t.Errorf("audio = %q/%d bytes", res.Audio.MIME, len(res.Audio.Data))
+	}
+}
+
+func TestSFXOmitsDefaults(t *testing.T) {
+	var gotBody map[string]any
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		_ = json.NewDecoder(r.Body).Decode(&gotBody)
+		// No Content-Type: the RIFF sniff must still label the clip.
+		w.Header()["Content-Type"] = nil
+		_, _ = w.Write(wavFixture())
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, _ := p.SFXModel("sfxgen-stableaudio")
+	res, err := sm.Generate(context.Background(), musicgen.Request{Prompt: "boom"})
+	if err != nil {
+		t.Fatalf("Generate: %v", err)
+	}
+	for _, k := range []string{"seconds", "steps", "cfg_scale", "seed"} {
+		if v, ok := gotBody[k]; ok {
+			t.Errorf("unset request sent %q = %v, want omitted", k, v)
+		}
+	}
+	if res.Audio.MIME != "audio/wav" {
+		t.Errorf("MIME = %q, want sniffed audio/wav", res.Audio.MIME)
+	}
+}
+
+func TestSFXRejectsBadArgs(t *testing.T) {
+	p := New(WithBaseURL("http://unused"))
+	sm, _ := p.SFXModel("sfxgen-stableaudio")
+	if _, err := sm.Generate(context.Background(), musicgen.Request{Prompt: "  "}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("empty prompt: err = %v, want ErrUnsupported", err)
+	}
+	if _, err := sm.Generate(context.Background(),
+		musicgen.Request{Prompt: "boom", Lyrics: "la la"}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("lyrics: err = %v, want ErrUnsupported", err)
+	}
+	if _, err := sm.Generate(context.Background(),
+		musicgen.Request{Prompt: "boom", Format: "mp3"}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("format mp3: err = %v, want ErrUnsupported", err)
+	}
+}
+
+func TestSFXRejectsNonAudioResponse(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "application/json")
+		_, _ = w.Write([]byte(`{"detail":"queue full"}`))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	sm, _ := p.SFXModel("sfxgen-stableaudio")
+	_, err := sm.Generate(context.Background(), musicgen.Request{Prompt: "boom"})
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("err = %v, want APIError for non-audio body", err)
+	}
+}
+
+func TestEnhance(t *testing.T) {
+	var gotPath, gotFilename string
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		gotPath = r.URL.Path
+		if err := r.ParseMultipartForm(1 << 20); err != nil {
+			t.Fatalf("parse multipart: %v", err)
+		}
+		if _, hdr, err := r.FormFile("file"); err == nil {
+			gotFilename = hdr.Filename
+		} else {
+			t.Errorf("file part: %v", err)
+		}
+		w.Header().Set("Content-Type", "audio/wav")
+		_, _ = w.Write(wavFixture())
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	en, err := p.SpeechEnhancerModel("audioutils")
+	if err != nil {
+		t.Fatalf("SpeechEnhancerModel: %v", err)
+	}
+	res, err := en.Enhance(context.Background(),
+		audio.EnhancementRequest{Audio: []byte("NOISY"), MIME: "audio/ogg"})
+	if err != nil {
+		t.Fatalf("Enhance: %v", err)
+	}
+	if gotPath != "/upstream/audioutils/v1/enhance" {
+		t.Errorf("path = %q", gotPath)
+	}
+	if gotFilename != "audio.ogg" {
+		t.Errorf("filename = %q", gotFilename)
+	}
+	if res.MIME != "audio/wav" || len(res.Audio) == 0 {
+		t.Errorf("result = %q/%d bytes", res.MIME, len(res.Audio))
+	}
+}
+
+func TestEnhanceRejectsEmptyAudio(t *testing.T) {
+	p := New(WithBaseURL("http://unused"))
+	en, _ := p.SpeechEnhancerModel("audioutils")
+	if _, err := en.Enhance(context.Background(), audio.EnhancementRequest{}); !errors.Is(err, llm.ErrUnsupported) {
+		t.Errorf("err = %v, want ErrUnsupported", err)
+	}
+}
+
+func TestEnhanceRejectsNonAudioResponse(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Header().Set("Content-Type", "text/html")
+		_, _ = w.Write([]byte("<html>oops</html>"))
+	}))
+	defer srv.Close()
+
+	p := New(WithBaseURL(srv.URL), WithHTTPClient(srv.Client()))
+	en, _ := p.SpeechEnhancerModel("audioutils")
+	_, err := en.Enhance(context.Background(), audio.EnhancementRequest{Audio: []byte("NOISY")})
+	var apiErr *llm.APIError
+	if !errors.As(err, &apiErr) {
+		t.Fatalf("err = %v, want APIError for non-audio body", err)
+	}
+}