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

apps/web/src/components/tools/convert-audio-settings.tsx

@@ -9,6 +9,28 @@ type AudioFormat = "mp3" | "wav" | "ogg" | "flac" | "m4a";
 
 const BITRATE_OPTIONS = [96, 128, 192, 256, 320] as const;
 
+const SAMPLE_RATE_OPTIONS = [8000, 16000, 22050, 32000, 44100, 48000, 96000] as const;
+
+// libmp3lame caps at 48 kHz, so MP3 output must not offer 96 kHz.
+function sampleRatesFor(format: AudioFormat): number[] {
+  return format === "mp3"
+    ? SAMPLE_RATE_OPTIONS.filter((r) => r <= 48000)
+    : [...SAMPLE_RATE_OPTIONS];
+}
+
+// libmp3lame also caps the bitrate at low rates (64 kbps at 8 kHz, 160 kbps at
+// 16/22.05 kHz) and would clamp silently; offer only combinations it honors.
+function bitratesFor(format: AudioFormat, sampleRate: number): number[] {
+  if (format !== "mp3" || !sampleRate || sampleRate >= 32000) return [...BITRATE_OPTIONS];
+  if (sampleRate === 8000) return [32, 48, 64];
+  return BITRATE_OPTIONS.filter((b) => b <= 160);
+}
+
+function reconcileBitrate(bitrateKbps: number, options: number[]): number {
+  if (options.includes(bitrateKbps)) return bitrateKbps;
+  return options.includes(192) ? 192 : options[options.length - 1];
+}
+
 export function ConvertAudioSettings() {
   const { t } = useTranslation();
   const s = t.toolSettings["convert-audio"];
@@ -18,12 +40,30 @@ export function ConvertAudioSettings() {
 
   const [outFormat, setOutFormat] = useState<AudioFormat>("mp3");
   const [bitrateKbps, setBitrateKbps] = useState(192);
+  // 0 = preserve the source sample rate (omit the setting).
+  const [sampleRate, setSampleRate] = useState(0);
 
   const hasFile = files.length > 0;
   const hasMultiple = files.length > 1;
 
+  const handleFormatChange = (format: AudioFormat) => {
+    setOutFormat(format);
+    const rate = sampleRatesFor(format).includes(sampleRate) ? sampleRate : 0;
+    if (rate !== sampleRate) setSampleRate(rate);
+    setBitrateKbps((b) => reconcileBitrate(b, bitratesFor(format, rate)));
+  };
+
+  const handleSampleRateChange = (rate: number) => {
+    setSampleRate(rate);
+    setBitrateKbps((b) => reconcileBitrate(b, bitratesFor(outFormat, rate)));
+  };
+
   const handleProcess = () => {
-    const settings = { format: outFormat, bitrateKbps };
+    const settings = {
+      format: outFormat,
+      bitrateKbps,
+      ...(sampleRate ? { sampleRate } : {}),
+    };
     if (hasMultiple) {
       processAllFiles(files, settings);
     } else {
@@ -40,7 +80,7 @@ export function ConvertAudioSettings() {
         <select
           id="ca-format"
           value={outFormat}
-          onChange={(e) => setOutFormat(e.target.value as AudioFormat)}
+          onChange={(e) => handleFormatChange(e.target.value as AudioFormat)}
           className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
         >
           <option value="mp3">MP3</option>
@@ -61,7 +101,7 @@ export function ConvertAudioSettings() {
           onChange={(e) => setBitrateKbps(Number(e.target.value))}
           className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
         >
-          {BITRATE_OPTIONS.map((br) => (
+          {bitratesFor(outFormat, sampleRate).map((br) => (
             <option key={br} value={br}>
               {br} kbps
             </option>
@@ -69,6 +109,25 @@ export function ConvertAudioSettings() {
         </select>
       </div>
 
+      <div>
+        <label htmlFor="ca-samplerate" className="text-xs text-muted-foreground">
+          {s.sampleRate}
+        </label>
+        <select
+          id="ca-samplerate"
+          value={sampleRate}
+          onChange={(e) => handleSampleRateChange(Number(e.target.value))}
+          className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
+        >
+          <option value={0}>{s.sampleRatePreserve}</option>
+          {sampleRatesFor(outFormat).map((r) => (
+            <option key={r} value={r}>
+              {r} Hz
+            </option>
+          ))}
+        </select>
+      </div>
+
       {error && <p className="text-xs text-red-500">{error}</p>}
 
       {processing ? (
@@ -105,13 +164,23 @@ export function ConvertAudioControls({ settings: initial, onChange }: ConvertAud
   const s = t.toolSettings["convert-audio"];
   const [outFormat, setOutFormat] = useState<AudioFormat>("mp3");
   const [bitrateKbps, setBitrateKbps] = useState(192);
+  // 0 = preserve the source sample rate (omit the setting).
+  const [sampleRate, setSampleRate] = useState(0);
 
   const initializedRef = useRef(false);
   useEffect(() => {
     if (!initial || initializedRef.current) return;
     initializedRef.current = true;
-    if (initial.format != null) setOutFormat(initial.format as AudioFormat);
-    if (initial.bitrateKbps != null) setBitrateKbps(Number(initial.bitrateKbps));
+    const format = initial.format != null ? (initial.format as AudioFormat) : "mp3";
+    if (initial.format != null) setOutFormat(format);
+    // Sanitize stored values so the selects always show what will be emitted:
+    // a rate the UI cannot represent falls back to preserve-original.
+    const rawRate = initial.sampleRate != null ? Number(initial.sampleRate) : 0;
+    const rate = sampleRatesFor(format).includes(rawRate) ? rawRate : 0;
+    if (rate) setSampleRate(rate);
+    if (initial.bitrateKbps != null) {
+      setBitrateKbps(reconcileBitrate(Number(initial.bitrateKbps), bitratesFor(format, rate)));
+    }
   }, [initial]);
 
   const onChangeRef = useRef(onChange);
@@ -119,8 +188,24 @@ export function ConvertAudioControls({ settings: initial, onChange }: ConvertAud
     onChangeRef.current = onChange;
   });
   useEffect(() => {
-    onChangeRef.current?.({ format: outFormat, bitrateKbps });
-  }, [outFormat, bitrateKbps]);
+    onChangeRef.current?.({
+      format: outFormat,
+      bitrateKbps,
+      ...(sampleRate ? { sampleRate } : {}),
+    });
+  }, [outFormat, bitrateKbps, sampleRate]);
+
+  const handleFormatChange = (format: AudioFormat) => {
+    setOutFormat(format);
+    const rate = sampleRatesFor(format).includes(sampleRate) ? sampleRate : 0;
+    if (rate !== sampleRate) setSampleRate(rate);
+    setBitrateKbps((b) => reconcileBitrate(b, bitratesFor(format, rate)));
+  };
+
+  const handleSampleRateChange = (rate: number) => {
+    setSampleRate(rate);
+    setBitrateKbps((b) => reconcileBitrate(b, bitratesFor(outFormat, rate)));
+  };
 
   return (
     <div className="space-y-4">
@@ -131,7 +216,7 @@ export function ConvertAudioControls({ settings: initial, onChange }: ConvertAud
         <select
           id="ca-format"
           value={outFormat}
-          onChange={(e) => setOutFormat(e.target.value as AudioFormat)}
+          onChange={(e) => handleFormatChange(e.target.value as AudioFormat)}
           className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
         >
           <option value="mp3">MP3</option>
@@ -151,13 +236,31 @@ export function ConvertAudioControls({ settings: initial, onChange }: ConvertAud
           onChange={(e) => setBitrateKbps(Number(e.target.value))}
           className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
         >
-          {BITRATE_OPTIONS.map((br) => (
+          {bitratesFor(outFormat, sampleRate).map((br) => (
             <option key={br} value={br}>
               {br} kbps
             </option>
           ))}
         </select>
       </div>
+      <div>
+        <label htmlFor="ca-samplerate" className="text-xs text-muted-foreground">
+          {s.sampleRate}
+        </label>
+        <select
+          id="ca-samplerate"
+          value={sampleRate}
+          onChange={(e) => handleSampleRateChange(Number(e.target.value))}
+          className="w-full mt-0.5 px-2 py-1.5 rounded border border-border bg-background text-sm text-foreground"
+        >
+          <option value={0}>{s.sampleRatePreserve}</option>
+          {sampleRatesFor(outFormat).map((r) => (
+            <option key={r} value={r}>
+              {r} Hz
+            </option>
+          ))}
+        </select>
+      </div>
     </div>
   );
 }