fix(audio): expose sample rate setting in Convert Audio (#561)

The Convert Audio tool promised configurable bitrate, sample rate, and channel count, but only format and bitrate were exposed. Adds an optional sampleRate setting (8000 to 96000 Hz, omitted = preserve source) wired through the Zod schema, the FFmpeg -ar flag, the standalone settings panel, and the pipeline builder controls.

Impossible combinations fail loudly instead of degrading silently: MP3 + 96000 Hz is rejected (libmp3lame caps at 48 kHz), and MP3 bitrates above the encoder ceiling at low rates (64 kbps at 8 kHz, 160 kbps at 16/22.05 kHz) are rejected rather than clamped. The UI offers only legal combinations and sanitizes stored pipeline settings on load.

Docs updated in English plus all 20 localized pages with refreshed i18n_source_hash stamps; two new UI strings added to all 21 locales.

Fixes #558

tests/integration/generated/settings-matrix.test.ts

@@ -795,6 +795,13 @@ const SETTINGS_VARIATIONS: Record<string, Variation[]> = {
     { label: "bitrate min", settings: { format: "mp3", bitrateKbps: 32 } },
     { label: "bitrate mid", settings: { format: "mp3", bitrateKbps: 128 } },
     { label: "bitrate max", settings: { format: "mp3", bitrateKbps: 320 } },
+    { label: "sample rate min", settings: { format: "mp3", sampleRate: 8000, bitrateKbps: 64 } },
+    { label: "sample rate 44100", settings: { format: "mp3", sampleRate: 44100 } },
+    { label: "sample rate max mp3", settings: { format: "mp3", sampleRate: 48000 } },
+    { label: "sample rate max wav", settings: { format: "wav", sampleRate: 96000 } },
+    { label: "sample rate ogg", settings: { format: "ogg", sampleRate: 44100 } },
+    { label: "sample rate m4a", settings: { format: "m4a", sampleRate: 96000 } },
+    { label: "sample rate flac", settings: { format: "flac", sampleRate: 48000 } },
   ],
 
   "trim-audio": [

tests/integration/tools/audio/convert-audio.test.ts

@@ -1,3 +1,7 @@
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { ffmpegAvailable } from "@snapotter/media-engine";
 import { afterAll, beforeAll, describe, expect, it } from "vitest";
 import { fixtures, readFixture } from "../../../fixtures/index.js";
@@ -36,6 +40,24 @@ async function runTool(settings: Record<string, unknown>, file = WAV, filename =
   });
 }
 
+function probeSampleRate(payload: Buffer, filename: string): string {
+  const tmpDir = mkdtempSync(join(tmpdir(), "convert-audio-test-"));
+  const probeFile = join(tmpDir, filename);
+  writeFileSync(probeFile, payload);
+  const result = spawnSync("ffprobe", [
+    "-v",
+    "error",
+    "-select_streams",
+    "a:0",
+    "-show_entries",
+    "stream=sample_rate",
+    "-of",
+    "csv=p=0",
+    probeFile,
+  ]);
+  return result.stdout.toString().trim();
+}
+
 describe.skipIf(!ffmpegAvailable())("convert-audio (requires ffmpeg)", () => {
   it("converts wav to mp3 and returns 200", async () => {
     const res = await runTool({ format: "mp3" });
@@ -68,6 +90,66 @@ describe.skipIf(!ffmpegAvailable())("convert-audio (requires ffmpeg)", () => {
     expect(outName.endsWith(".ogg")).toBe(true);
   }, 60_000);
 
+  it("resamples to 44100 Hz when sampleRate is set", async () => {
+    // tiny.wav is 8 kHz; the output must carry the requested rate.
+    const res = await runTool({ format: "mp3", sampleRate: 44100 });
+    expect(res.statusCode).toBe(200);
+    const envelope = JSON.parse(res.body);
+    const dl = await testApp.app.inject({ method: "GET", url: envelope.downloadUrl });
+    expect(dl.statusCode).toBe(200);
+    expect(probeSampleRate(dl.rawPayload, "out.mp3")).toBe("44100");
+  }, 60_000);
+
+  it("preserves the source sample rate when sampleRate is omitted", async () => {
+    const res = await runTool({ format: "mp3" });
+    expect(res.statusCode).toBe(200);
+    const envelope = JSON.parse(res.body);
+    const dl = await testApp.app.inject({ method: "GET", url: envelope.downloadUrl });
+    expect(dl.statusCode).toBe(200);
+    expect(probeSampleRate(dl.rawPayload, "out.mp3")).toBe("8000");
+  }, 60_000);
+
+  it("resamples to 96000 Hz for wav output", async () => {
+    const res = await runTool({ format: "wav", sampleRate: 96000 });
+    expect(res.statusCode).toBe(200);
+    const envelope = JSON.parse(res.body);
+    const dl = await testApp.app.inject({ method: "GET", url: envelope.downloadUrl });
+    expect(dl.statusCode).toBe(200);
+    expect(probeSampleRate(dl.rawPayload, "out.wav")).toBe("96000");
+  }, 60_000);
+
+  it("rejects 96000 Hz for mp3 output (libmp3lame caps at 48000)", async () => {
+    const res = await runTool({ format: "mp3", sampleRate: 96000 });
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).error).toBe("Invalid settings");
+  });
+
+  it("rejects a sample rate outside the supported set with an actionable message", async () => {
+    const res = await runTool({ format: "wav", sampleRate: 12345 });
+    expect(res.statusCode).toBe(400);
+    const body = JSON.parse(res.body);
+    expect(body.error).toBe("Invalid settings");
+    // API users should see the accepted set, not zod's generic "Invalid input".
+    expect(body.details).toContain("8000");
+    expect(body.details).toContain("96000");
+  });
+
+  it("rejects a bitrate above the MP3 ceiling for low sample rates", async () => {
+    // libmp3lame would silently clamp 192 kbps to 64 kbps at 8 kHz.
+    const res = await runTool({ format: "mp3", sampleRate: 8000 });
+    expect(res.statusCode).toBe(400);
+    expect(JSON.parse(res.body).error).toBe("Invalid settings");
+  });
+
+  it("converts mp3 at 8000 Hz with a bitrate under the ceiling", async () => {
+    const res = await runTool({ format: "mp3", sampleRate: 8000, bitrateKbps: 64 });
+    expect(res.statusCode).toBe(200);
+    const envelope = JSON.parse(res.body);
+    const dl = await testApp.app.inject({ method: "GET", url: envelope.downloadUrl });
+    expect(dl.statusCode).toBe(200);
+    expect(probeSampleRate(dl.rawPayload, "out.mp3")).toBe("8000");
+  }, 60_000);
+
   it("converts 8 kHz wav to ogg (regression: libvorbis low samplerate)", async () => {
     // tiny.wav is 8 kHz; a fixed bitrate (-b:a) made libvorbis "encoder setup failed".
     // The ogg path now uses -q:a (quality VBR), which adapts to the sample rate.

tests/unit/web/pipeline-controls.test.tsx

@@ -1,6 +1,6 @@
 // @vitest-environment jsdom
 
-import { cleanup, render, screen } from "@testing-library/react";
+import { cleanup, render, screen, within } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { ConvertAudioControls } from "@/components/tools/convert-audio-settings";
@@ -42,6 +42,73 @@ describe("ConvertAudioControls", () => {
       expect.objectContaining({ format: "wav", bitrateKbps: 256 }),
     );
   });
+
+  it("omits sampleRate by default (preserve original)", () => {
+    const onChange = vi.fn();
+    render(<ConvertAudioControls onChange={onChange} />);
+    expect(onChange.mock.lastCall?.[0]).not.toHaveProperty("sampleRate");
+  });
+
+  it("emits the chosen sample rate on change", async () => {
+    const onChange = vi.fn();
+    render(<ConvertAudioControls onChange={onChange} />);
+    await userEvent.selectOptions(screen.getByLabelText(/sample rate/i), "44100");
+    expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({ sampleRate: 44100 }));
+  });
+
+  it("initializes sampleRate from incoming settings", () => {
+    const onChange = vi.fn();
+    render(
+      <ConvertAudioControls settings={{ format: "wav", sampleRate: 48000 }} onChange={onChange} />,
+    );
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ format: "wav", sampleRate: 48000 }),
+    );
+  });
+
+  it("caps bitrate options for low mp3 sample rates and resets the bitrate", async () => {
+    const onChange = vi.fn();
+    render(<ConvertAudioControls onChange={onChange} />);
+    await userEvent.selectOptions(screen.getByLabelText(/sample rate/i), "8000");
+    // 192 kbps is illegal at 8 kHz (libmp3lame caps at 64); the control must
+    // reset to a legal value rather than let ffmpeg clamp silently.
+    expect(onChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({ sampleRate: 8000, bitrateKbps: 64 }),
+    );
+    const bitrateSelect = screen.getByLabelText(/bitrate/i);
+    const options = [...bitrateSelect.querySelectorAll("option")].map((o) => o.value);
+    expect(options).toEqual(["32", "48", "64"]);
+
+    // Moving back to a full-range rate restores the regular options.
+    await userEvent.selectOptions(screen.getByLabelText(/sample rate/i), "44100");
+    expect(onChange).toHaveBeenLastCalledWith(
+      expect.objectContaining({ sampleRate: 44100, bitrateKbps: 192 }),
+    );
+  });
+
+  it("sanitizes an out-of-range stored sampleRate to preserve-original", () => {
+    const onChange = vi.fn();
+    render(
+      <ConvertAudioControls settings={{ format: "mp3", sampleRate: 96000 }} onChange={onChange} />,
+    );
+    // A stale or API-written value the UI cannot represent must not be emitted
+    // behind a blank select.
+    expect(onChange.mock.lastCall?.[0]).toMatchObject({ format: "mp3" });
+    expect(onChange.mock.lastCall?.[0]).not.toHaveProperty("sampleRate");
+  });
+
+  it("hides 96 kHz for mp3 and drops it when switching to mp3", async () => {
+    const onChange = vi.fn();
+    render(<ConvertAudioControls settings={{ format: "wav" }} onChange={onChange} />);
+    const rateSelect = screen.getByLabelText(/sample rate/i);
+    await userEvent.selectOptions(rateSelect, "96000");
+    expect(onChange).toHaveBeenLastCalledWith(expect.objectContaining({ sampleRate: 96000 }));
+
+    await userEvent.selectOptions(screen.getByLabelText(/output format/i), "mp3");
+    expect(onChange.mock.lastCall?.[0]).toMatchObject({ format: "mp3" });
+    expect(onChange.mock.lastCall?.[0]).not.toHaveProperty("sampleRate");
+    expect(within(rateSelect).queryByRole("option", { name: /96000/ })).toBeNull();
+  });
 });
 
 describe("TrimVideoControls", async () => {