@danieltmn/tamnora 0.21.2 → 0.22.0

package/harness/packages/server/public/voice.js

@@ -0,0 +1,1058 @@
+import { chatInput, renderFooterActivity, sendMessage } from './chat.js';
+import { onChatInputChanged, toast } from './commands.js';
+import { $, api, button, el, icon, state } from './core.js';
+import { speechText } from './markdown.js';
+import {
+  setStatus,
+  trModelEl,
+  trProviderEl,
+  vozAnnAdviceEl,
+  vozAnnAnswerEl,
+  vozAnnEndEl,
+  vozAnnStartEl,
+  vozAnnSummaryEl,
+  vozAnnToolsEl,
+  vozEnabledEl,
+  vozFfmpegEl,
+  vozPitchEl,
+  vozPitchValEl,
+  vozRateEl,
+  vozRateValEl,
+  vozVoiceEl,
+} from './settings.js';
+
+/* --- voz de entrada (dictado) --------------------------------------------- */
+
+export const micBtn = $('#mic-btn');
+
+// La cuenta 3-2-1 le da tiempo al micro a arrancar (si hablás apenas tocás se
+// pierden las primeras palabras); la cola al cortar evita perder el final.
+export const REC_COUNT = [3, 2, 1, 0];
+export const REC_COUNT_STEP_MS = 500;
+export const REC_TAIL_MS = 500;
+
+/** Estado visual del botón de dictado: cuenta regresiva, grabando (verde) o transcribiendo. */
+export function micVisual(button, { live = false, count = null, busy = false } = {}) {
+  if (!button) return;
+  button.classList.toggle('recording', live);
+  button.classList.toggle('busy', busy);
+  button.classList.toggle('mic-counting', count !== null);
+  const span = button.querySelector('.mic-count');
+  if (span) {
+    span.hidden = count === null;
+    span.textContent = count === null ? '' : String(count);
+  }
+}
+
+/** Cuenta regresiva antes de que empieces a hablar. Devuelve false si se canceló. */
+export async function micCountdown(button, isCancelled) {
+  for (const count of REC_COUNT) {
+    if (isCancelled()) return false;
+    micVisual(button, { live: true, count });
+    await new Promise((resolve) => setTimeout(resolve, REC_COUNT_STEP_MS));
+  }
+  if (isCancelled()) return false;
+  micVisual(button, { live: true });
+  return true;
+}
+
+export function blobToDataUrl(blob) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onerror = () => reject(new Error('No se pudo leer el audio'));
+    reader.onload = () => resolve(reader.result);
+    reader.readAsDataURL(blob);
+  });
+}
+
+export async function transcribirBlob(blob) {
+  const audio = await blobToDataUrl(blob);
+  const data = await api('/api/transcribe', { method: 'POST', body: { audio } });
+  return String(data?.text ?? '').trim();
+}
+
+/** Une los bloques de muestras Float32 en uno solo. */
+export function mergeFloat32(chunks) {
+  const length = chunks.reduce((total, chunk) => total + chunk.length, 0);
+  const out = new Float32Array(length);
+  let offset = 0;
+  for (const chunk of chunks) {
+    out.set(chunk, offset);
+    offset += chunk.length;
+  }
+  return out;
+}
+
+/** Remuestrea a 16 kHz mono con OfflineAudioContext (sin dependencias). */
+export async function resampleTo16k(samples, inputRate) {
+  if (!samples.length || Math.round(inputRate) === 16000) return samples;
+  const targetLength = Math.max(1, Math.round((samples.length * 16000) / inputRate));
+  const Ctx = window.OfflineAudioContext || window.webkitOfflineAudioContext;
+  const off = new Ctx(1, targetLength, 16000);
+  const buffer = off.createBuffer(1, samples.length, inputRate);
+  buffer.copyToChannel(samples, 0);
+  const source = off.createBufferSource();
+  source.buffer = buffer;
+  source.connect(off.destination);
+  source.start();
+  const rendered = await off.startRendering();
+  return rendered.getChannelData(0);
+}
+
+/** Codifica muestras Float32 (-1..1) como WAV PCM 16-bit (lo acepta cualquier proveedor). */
+export function encodeWav(samples, rate = 16000) {
+  const buffer = new ArrayBuffer(44 + samples.length * 2);
+  const view = new DataView(buffer);
+  const writeString = (offset, text) => {
+    for (let i = 0; i < text.length; i++) view.setUint8(offset + i, text.charCodeAt(i));
+  };
+  writeString(0, 'RIFF');
+  view.setUint32(4, 36 + samples.length * 2, true);
+  writeString(8, 'WAVE');
+  writeString(12, 'fmt ');
+  view.setUint32(16, 16, true);
+  view.setUint16(20, 1, true);
+  view.setUint16(22, 1, true);
+  view.setUint32(24, rate, true);
+  view.setUint32(28, rate * 2, true);
+  view.setUint16(32, 2, true);
+  view.setUint16(34, 16, true);
+  writeString(36, 'data');
+  view.setUint32(40, samples.length * 2, true);
+  let offset = 44;
+  for (let i = 0; i < samples.length; i++) {
+    const sample = Math.max(-1, Math.min(1, samples[i]));
+    view.setInt16(offset, sample < 0 ? sample * 0x8000 : sample * 0x7fff, true);
+    offset += 2;
+  }
+  return new Blob([view], { type: 'audio/wav' });
+}
+
+/**
+ * Una grabación de micrófono (motor del servidor). Graba con Web Audio y devuelve
+ * un **WAV** (no WebM): así el proveedor no depende del contenedor que produce
+ * `MediaRecorder`. `start()` abre el micro (la cuenta 3-2-1 la maneja el que llama);
+ * `stop()` espera la cola antes de cortar. La usan el micrófono del chat y el
+ * "probar" de Ajustes.
+ */
+export function createRecording({ silenceMs = 0, noSpeechMs = 0, maxMs = 0, speechThreshold = 0.02 } = {}) {
+  let resolveBlob;
+  const done = new Promise((resolve) => {
+    resolveBlob = resolve;
+  });
+  let stream = null;
+  let audioCtx = null;
+  let processor = null;
+  let source = null;
+  let sink = null;
+  let stopping = false;
+  let started = false;
+  let startedAt = 0;
+  let hasSpeech = false;
+  let lastLoudAt = 0;
+  let watchdog = null;
+  const chunks = [];
+
+  async function cleanup() {
+    if (watchdog) clearInterval(watchdog);
+    watchdog = null;
+    try {
+      processor?.disconnect();
+    } catch {
+      // ya desconectado
+    }
+    try {
+      source?.disconnect();
+    } catch {
+      // ya desconectado
+    }
+    try {
+      sink?.disconnect();
+    } catch {
+      // ya desconectado
+    }
+    try {
+      await audioCtx?.close();
+    } catch {
+      // contexto ya cerrado
+    }
+    stream?.getTracks?.().forEach((track) => track.stop());
+  }
+
+  function stopRecording() {
+    if (stopping || !started) return;
+    stopping = true;
+    if (watchdog) clearInterval(watchdog);
+    watchdog = null;
+    setTimeout(async () => {
+      const rate = audioCtx?.sampleRate || 48000;
+      const merged = mergeFloat32(chunks);
+      await cleanup();
+      const resampled = await resampleTo16k(merged, rate);
+      resolveBlob(encodeWav(resampled, 16000));
+    }, REC_TAIL_MS);
+  }
+
+  // Manos libres: corta solo por silencio (tras haber hablado), si no hubo voz en
+  // `noSpeechMs` o al llegar a `maxMs`. Sin estas opciones no interviene.
+  function startWatchdog() {
+    if (!silenceMs && !noSpeechMs && !maxMs) return;
+    watchdog = setInterval(() => {
+      if (stopping || !started) return;
+      const now = Date.now();
+      if (maxMs && now - startedAt >= maxMs) return stopRecording();
+      if (!silenceMs) return;
+      if (!hasSpeech) {
+        if (noSpeechMs && now - startedAt >= noSpeechMs) stopRecording();
+        return;
+      }
+      if (now - lastLoudAt >= silenceMs) stopRecording();
+    }, 150);
+  }
+
+  return {
+    async start() {
+      const Ctx = window.AudioContext || window.webkitAudioContext;
+      if (!navigator.mediaDevices?.getUserMedia || !Ctx) {
+        throw new Error('Este navegador no soporta dictado por voz.');
+      }
+      stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      audioCtx = new Ctx();
+      if (audioCtx.state === 'suspended') await audioCtx.resume();
+      source = audioCtx.createMediaStreamSource(stream);
+      processor = audioCtx.createScriptProcessor(4096, 1, 1);
+      processor.onaudioprocess = (event) => {
+        const frame = event.inputBuffer.getChannelData(0);
+        chunks.push(new Float32Array(frame));
+        if (!silenceMs) return;
+        let sum = 0;
+        for (let i = 0; i < frame.length; i += 2) sum += frame[i] * frame[i];
+        const rms = Math.sqrt(sum / (frame.length / 2));
+        if (rms >= speechThreshold) {
+          hasSpeech = true;
+          lastLoudAt = Date.now();
+        }
+      };
+      // El procesador solo corre si llega al destination: un gain en 0 evita el eco.
+      sink = audioCtx.createGain();
+      sink.gain.value = 0;
+      source.connect(processor);
+      processor.connect(sink);
+      sink.connect(audioCtx.destination);
+      started = true;
+      startedAt = Date.now();
+      startWatchdog();
+    },
+    get stopping() {
+      return stopping;
+    },
+    stop: stopRecording,
+    done,
+  };
+}
+
+export const ERRORES_DICTADO = {
+  network:
+    'el dictado del navegador necesita el servicio de voz de Google y no respondió (pasa en Brave o sin internet). Probá el motor «Servidor» en Ajustes → Transcripción.',
+  'not-allowed': 'permiso de micrófono denegado.',
+  'service-not-allowed': 'el navegador bloqueó el servicio de dictado.',
+  aborted: 'dictado cancelado.',
+  'audio-capture': 'no encontré micrófono.',
+  'no-speech': 'no escuché nada.',
+};
+export const DICTADO_FATAL = new Set(['network', 'not-allowed', 'service-not-allowed', 'audio-capture']);
+
+/**
+ * Dictado nativo del navegador (Web Speech API). `start()`/`stop()` controlan el
+ * ciclo. Los cortes por silencio (`no-speech`) se reconectan solos para no perder
+ * el hilo; los errores fatales (p. ej. `network`) se informan y se cortan.
+ */
+export function createBrowserDictation({ language, onText, onEnd, onError } = {}) {
+  const Ctor = window.SpeechRecognition || window.webkitSpeechRecognition;
+  if (!Ctor) throw new Error('Este navegador no soporta dictado nativo (probá Chrome/Edge).');
+  const rec = new Ctor();
+  rec.lang = language || 'es-AR';
+  rec.continuous = true;
+  rec.interimResults = true;
+  let finalText = '';
+  let wanted = false;
+  let fatal = false;
+  let restarts = 0;
+
+  rec.onresult = (event) => {
+    let interim = '';
+    for (let i = event.resultIndex; i < event.results.length; i++) {
+      const result = event.results[i];
+      if (result.isFinal) finalText += result[0].transcript;
+      else interim += result[0].transcript;
+    }
+    onText?.(finalText, finalText + interim);
+  };
+  rec.onerror = (event) => {
+    const code = event.error || 'unknown';
+    if (DICTADO_FATAL.has(code)) {
+      fatal = true;
+      wanted = false;
+      onError?.(new Error(ERRORES_DICTADO[code] || `error de dictado (${code}).`));
+    } else if (code !== 'no-speech' && code !== 'aborted') {
+      onError?.(new Error(ERRORES_DICTADO[code] || `error de dictado (${code}).`));
+    }
+  };
+  rec.onend = () => {
+    // Chrome corta tras una pausa: si seguimos "escuchando", reconectamos.
+    if (wanted && !fatal && restarts < 30) {
+      restarts += 1;
+      setTimeout(() => {
+        if (!wanted || fatal) return;
+        try {
+          rec.start();
+        } catch {
+          // se reintenta en el proximo onend
+        }
+      }, 300);
+      return;
+    }
+    wanted = false;
+    onEnd?.();
+  };
+
+  return {
+    start() {
+      wanted = true;
+      fatal = false;
+      restarts = 0;
+      rec.start();
+    },
+    stop() {
+      wanted = false;
+      try {
+        rec.stop();
+      } catch {
+        // ya estaba detenido
+      }
+    },
+  };
+}
+
+export let composerRecording = null;
+export let browserDictation = null;
+
+export function startBrowserMic() {
+  const base = chatInput.value.trim();
+  let dictation;
+  try {
+    dictation = createBrowserDictation({
+      language: transcribeConfig.language,
+      onText: (_final, combined) => {
+        chatInput.value = [base, combined.trim()].filter(Boolean).join(' ');
+        onChatInputChanged();
+      },
+      onEnd: () => {
+        if (browserDictation === dictation) browserDictation = null;
+        micVisual(micBtn);
+      },
+      onError: (error) => toast(`Dictado: ${error.message}`),
+    });
+  } catch (error) {
+    return toast(error.message);
+  }
+  browserDictation = dictation;
+  micVisual(micBtn, { live: true });
+  try {
+    dictation.start();
+  } catch (error) {
+    browserDictation = null;
+    micVisual(micBtn);
+    return toast(`Dictado: ${error.message}`);
+  }
+}
+
+export async function toggleMic() {
+  if (!micBtn) return;
+  // Con manos libres el micro lo maneja el loop: no dejamos que se pisen.
+  if (handsFree.active) return;
+  if (browserDictation) {
+    browserDictation.stop();
+    return;
+  }
+  if (composerRecording) {
+    composerRecording.stop();
+    return;
+  }
+  if (micBtn.disabled) return;
+  if (transcribeConfig.mode === 'browser') return startBrowserMic();
+
+  const rec = createRecording();
+  micBtn.disabled = true;
+  try {
+    await rec.start();
+  } catch (error) {
+    micBtn.disabled = false;
+    micVisual(micBtn);
+    return toast(`No pude acceder al micrófono: ${error.message}`);
+  }
+  micBtn.disabled = false;
+  composerRecording = rec;
+
+  // El manejo va antes de la cuenta: si cortás durante el 3-2-1, igual transcribe.
+  rec.done.then(async (blob) => {
+    if (composerRecording === rec) composerRecording = null;
+    if (!blob.size) {
+      micVisual(micBtn);
+      return;
+    }
+    micVisual(micBtn, { busy: true });
+    try {
+      const text = await transcribirBlob(blob);
+      if (!text) return toast('No se entendió el audio.');
+      chatInput.value = chatInput.value.trim() ? `${chatInput.value.trim()} ${text}` : text;
+      onChatInputChanged();
+      chatInput.focus();
+    } catch (error) {
+      toast(`No pude transcribir: ${error.message}`);
+    } finally {
+      micVisual(micBtn);
+    }
+  });
+
+  await micCountdown(micBtn, () => rec.stopping);
+}
+
+/* --- manos libres: conversación por voz ----------------------------------- */
+
+export const HANDS_FREE_SILENCE_MS = 1400; // silencio que cierra tu turno
+export const HANDS_FREE_NOSPEECH_MS = 8000; // si no hablás, vuelve a intentar
+export const HANDS_FREE_MAX_MS = 45000; // tope duro de una intervención
+
+export const handsFreeBtn = $('#hands-free-btn');
+export const handsFree = { active: false, phase: 'idle', token: 0 };
+
+export const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+export function renderHandsFree() {
+  if (handsFreeBtn) {
+    handsFreeBtn.classList.toggle('hands-free-active', handsFree.active);
+    handsFreeBtn.classList.toggle('listening', handsFree.active && handsFree.phase === 'listening');
+    handsFreeBtn.setAttribute('aria-pressed', handsFree.active ? 'true' : 'false');
+    handsFreeBtn.title = handsFree.active
+      ? 'manos libres: activado (tocá para desactivar)'
+      : 'manos libres: conversación por voz';
+  }
+  if (handsFree.active && handsFree.phase === 'listening') renderFooterActivity('listening');
+  else if (handsFree.active && handsFree.phase === 'thinking') renderFooterActivity('thinking');
+  else renderFooterActivity(null);
+}
+
+export function setHandsFreePhase(phase) {
+  handsFree.phase = phase;
+  renderHandsFree();
+}
+
+export function setHandsFree(on) {
+  const next = Boolean(on);
+  if (handsFree.active === next) return;
+  handsFree.active = next;
+  handsFree.token += 1;
+  if (next) {
+    // Cortamos un dictado manual en curso para no pisarlo.
+    composerRecording?.stop();
+    setHandsFreePhase('idle');
+    renderHandsFree();
+    runHandsFree(handsFree.token).catch(() => {});
+  } else {
+    // Cortamos lo que esté grabando para no dejar el micro abierto.
+    handsFree.recording?.stop();
+    handsFree.recording = null;
+    browserDictation?.stop();
+    setHandsFreePhase('idle');
+    renderHandsFree();
+  }
+}
+
+export function toggleHandsFree() {
+  setHandsFree(!handsFree.active);
+}
+
+/** Una escucha de manos libres: graba hasta el silencio y devuelve el texto. */
+export async function handsFreeListen(token) {
+  if (transcribeConfig.mode === 'browser') {
+    const text = await new Promise((resolve, reject) => {
+      let combined = '';
+      let dictation;
+      const finish = () => {
+        if (browserDictation === dictation) browserDictation = null;
+        resolve(combined.trim());
+      };
+      try {
+        dictation = createBrowserDictation({
+          language: transcribeConfig.language,
+          onText: (_final, all) => {
+            combined = all;
+          },
+          onEnd: finish,
+          onError: reject,
+        });
+      } catch (error) {
+        reject(error);
+        return;
+      }
+      browserDictation = dictation;
+      dictation.start();
+      setTimeout(() => {
+        if (browserDictation === dictation) dictation.stop();
+      }, HANDS_FREE_MAX_MS);
+    });
+    return token === handsFree.token ? text : '';
+  }
+
+  const rec = createRecording({
+    silenceMs: HANDS_FREE_SILENCE_MS,
+    noSpeechMs: HANDS_FREE_NOSPEECH_MS,
+    maxMs: HANDS_FREE_MAX_MS,
+  });
+  await rec.start();
+  if (token !== handsFree.token) {
+    rec.stop();
+    return '';
+  }
+  handsFree.recording = rec;
+  setHandsFreePhase('listening');
+  const blob = await rec.done;
+  handsFree.recording = null;
+  if (token !== handsFree.token || !blob.size) return '';
+  setHandsFreePhase('thinking');
+  try {
+    return await transcribirBlob(blob);
+  } catch (error) {
+    toast(`No pude transcribir: ${error.message}`);
+    return '';
+  }
+}
+
+/** Loop conversacional: escuchar → enviar → esperar la voz → repetir. */
+export async function runHandsFree(token) {
+  while (handsFree.active && token === handsFree.token) {
+    if (!state.sessionId) {
+      toast('Manos libres necesita una sesión abierta.');
+      setHandsFree(false);
+      return;
+    }
+    if (state.panes.get(state.sessionId)?.working) {
+      await sleep(400);
+      continue;
+    }
+
+    let text = '';
+    try {
+      text = await handsFreeListen(token);
+    } catch (error) {
+      if (token !== handsFree.token) return;
+      toast(`Manos libres: ${error.message}`);
+      setHandsFree(false);
+      return;
+    }
+    if (!handsFree.active || token !== handsFree.token) return;
+    if (!text) continue; // silencio o no se entendió: otra vuelta
+
+    chatInput.value = text;
+    onChatInputChanged();
+    setHandsFreePhase('thinking');
+    await sendMessage();
+    if (!handsFree.active || token !== handsFree.token) return;
+    // Esperamos a que termine de hablar antes de volver a escuchar (evita el eco).
+    await whenAudioIdle();
+    await sleep(250);
+  }
+}
+
+/* --- ajustes: voz (TTS) ---------------------------------------------------- */
+
+export const voz = {
+  settings: {
+    enabled: false,
+    voice: 'es-AR-ElenaNeural',
+    rate: '+0%',
+    pitch: '+0Hz',
+    announce: { start: true, tools: true, end: true, advice: true, answer: false, summary: false },
+  },
+};
+
+/**
+ * Un único reproductor para TODO el audio (narración, tool `speak`,
+ * `/audioresumen`, prueba de voz): encola y reproduce de a uno, en orden, con
+ * controles visibles para pausar o detener. Antes cada audio creaba su propio
+ * `<audio>` y, si el modelo pedía dos, sonaban encimados y sin forma de pararlos.
+ */
+export const ap = { el: $('#audio-player'), audio: new Audio(), queue: [], current: null, ready: false };
+
+// Avisa cuando el reproductor queda en silencio (cola vacia). Lo usa manos libres
+// para saber cuando el asistente termino de hablar y volver a escuchar.
+export const audioIdleWaiters = [];
+export function whenAudioIdle() {
+  if (!ap.current && !ap.queue.length) return Promise.resolve();
+  return new Promise((resolve) => audioIdleWaiters.push(resolve));
+}
+export function notifyAudioIdle() {
+  if (ap.current || ap.queue.length) return;
+  for (const resolve of audioIdleWaiters.splice(0)) resolve();
+}
+
+export function ensurePlayer() {
+  if (!ap.el || ap.ready) return;
+  ap.ready = true;
+  ap.toggle = button('', () => toggleAudio(), 'ap-btn');
+  ap.iconEl = el('span', 'ap-icon');
+  ap.toggle.appendChild(ap.iconEl);
+  ap.labelEl = el('span', 'ap-label');
+  ap.barEl = el('div', 'ap-bar');
+  const progress = el('div', 'ap-progress');
+  progress.appendChild(ap.barEl);
+  const info = el('div', 'ap-info');
+  info.append(ap.labelEl, progress);
+  ap.queueEl = el('span', 'ap-queue');
+  ap.stopBtn = button('', () => stopAudio(), 'ap-btn ap-stop');
+  ap.stopBtn.title = 'detener';
+  ap.stopBtn.setAttribute('aria-label', 'detener audio');
+  ap.stopBtn.appendChild(icon('square', 14));
+  ap.el.append(ap.toggle, info, ap.queueEl, ap.stopBtn);
+
+  ap.audio.addEventListener('ended', () => advanceAudio(ap.current));
+  ap.audio.addEventListener('error', () => {
+    if (ap.current && ap.audio.getAttribute('src')) advanceAudio(ap.current, new Error('No se pudo reproducir el audio.'));
+  });
+  ap.audio.addEventListener('play', renderAudio);
+  ap.audio.addEventListener('pause', renderAudio);
+  ap.audio.addEventListener('timeupdate', () => {
+    const { duration, currentTime } = ap.audio;
+    if (!Number.isFinite(duration) || duration <= 0) return;
+    ap.barEl.style.width = `${Math.min(100, (currentTime / duration) * 100)}%`;
+  });
+}
+
+/** Convierte la velocidad guardada ("+20%") al valor del slider (20). */
+export function rateToSlider(rate) {
+  const m = /^([+-]?)(\d+)%$/.exec(String(rate ?? '').trim());
+  return m ? (m[1] === '-' ? -1 : 1) * Number(m[2]) : 0;
+}
+
+/** Convierte el valor del slider (-20) a la velocidad guardada. */
+export function sliderToRate(n) {
+  const v = Math.max(-100, Math.min(100, Math.round(Number(n) || 0)));
+  return v === 0 ? '+0%' : `${v > 0 ? '+' : '-'}${Math.abs(v)}%`;
+}
+
+/** Convierte el tono guardado ("-10Hz") al valor del slider (-10). */
+export function pitchToSlider(pitch) {
+  const m = /^([+-]?)(\d+)Hz$/.exec(String(pitch ?? '').trim());
+  return m ? (m[1] === '-' ? -1 : 1) * Number(m[2]) : 0;
+}
+
+/** Convierte el valor del slider (-10) al tono guardado. */
+export function sliderToPitch(n) {
+  const v = Math.max(-50, Math.min(50, Math.round(Number(n) || 0)));
+  return v === 0 ? '+0Hz' : `${v > 0 ? '+' : '-'}${Math.abs(v)}Hz`;
+}
+
+export function etiquetaRate(n) {
+  const v = Math.round(Number(n) || 0);
+  return v === 0 ? 'normal' : `${v > 0 ? '+' : '−'}${Math.abs(v)}%`;
+}
+
+export function etiquetaPitch(n) {
+  const v = Math.round(Number(n) || 0);
+  return v === 0 ? 'normal' : `${v > 0 ? '+' : '−'}${Math.abs(v)} Hz`;
+}
+
+/** Refresca la etiqueta numérica de los sliders de voz. */
+export function renderVozSliders() {
+  if (vozRateValEl && vozRateEl) vozRateValEl.textContent = etiquetaRate(vozRateEl.value);
+  if (vozPitchValEl && vozPitchEl) vozPitchValEl.textContent = etiquetaPitch(vozPitchEl.value);
+}
+
+/** Encola un audio. La promesa se resuelve al terminar (o al detenerlo). */
+export function enqueueSpeech({ texto, voice, rate, pitch, label = 'audio', maxAgeMs = 0 } = {}) {
+  const frase = String(texto ?? '').trim();
+  if (!frase) return Promise.resolve();
+  ensurePlayer();
+  return new Promise((resolve, reject) => {
+    ap.queue.push({ texto: frase, voice, rate, pitch, label, createdAt: Date.now(), maxAgeMs, resolve, reject });
+    if (ap.current) renderAudio();
+    else playNextAudio();
+  });
+}
+
+export function playNextAudio() {
+  const item = ap.queue.shift();
+  if (!item) {
+    ap.current = null;
+    renderAudio();
+    notifyAudioIdle();
+    return;
+  }
+  if (item.maxAgeMs && Date.now() - item.createdAt > item.maxAgeMs) {
+    item.resolve?.();
+    return playNextAudio();
+  }
+  ap.current = item;
+  const params = new URLSearchParams({
+    texto: item.texto,
+    voice: item.voice ?? voz.settings.voice,
+    rate: item.rate ?? voz.settings.rate,
+    pitch: item.pitch ?? voz.settings.pitch,
+  });
+  ap.audio.src = `/api/tts?${params}`;
+  ap.audio.play().catch(() => {
+    advanceAudio(item, new Error('el navegador bloqueó el audio: tocá la página y probá de nuevo'));
+  });
+  renderAudio();
+}
+
+export function advanceAudio(item, error) {
+  if (!item || ap.current !== item) return;
+  ap.current = null;
+  if (error) item.reject?.(error);
+  else item.resolve?.();
+  playNextAudio();
+}
+
+export function toggleAudio() {
+  if (!ap.current) return;
+  if (ap.audio.paused) ap.audio.play().catch(() => {});
+  else ap.audio.pause();
+}
+
+/** Detiene lo que suena y vacía lo que espera. */
+export function stopAudio() {
+  for (const item of ap.queue) item.resolve?.();
+  ap.queue = [];
+  const current = ap.current;
+  ap.current = null;
+  current?.resolve?.();
+  ap.audio.pause();
+  ap.audio.removeAttribute('src');
+  ap.audio.load();
+  if (ap.barEl) ap.barEl.style.width = '0%';
+  renderAudio();
+  notifyAudioIdle();
+}
+
+export function renderAudio() {
+  if (!ap.el || !ap.ready) return;
+  const active = Boolean(ap.current) || ap.queue.length > 0;
+  ap.el.hidden = !active;
+  if (!active) return;
+  ap.labelEl.textContent = ap.current?.label ?? 'audio';
+  ap.queueEl.hidden = ap.queue.length === 0;
+  ap.queueEl.textContent = ap.queue.length ? `+${ap.queue.length}` : '';
+  const playing = Boolean(ap.current) && !ap.audio.paused;
+  ap.iconEl.replaceChildren(icon(playing ? 'pause' : 'play', 14));
+  ap.toggle.title = playing ? 'pausar' : 'reproducir';
+  ap.toggle.setAttribute('aria-label', ap.toggle.title);
+}
+
+/** Reproduce una frase contra el endpoint de sintesis del server. */
+export function reproducirVoz(frase, { voice, rate, pitch, label, maxAgeMs } = {}) {
+  return enqueueSpeech({ texto: frase, voice, rate, pitch, label, maxAgeMs });
+}
+
+/**
+ * Narra una frase del turno. Si el turno tarda y la frase quedó vieja en la
+ * cola, se descarta al llegar su turno (`maxAgeMs`): narrar el pasado no informa.
+ */
+export function hablar(texto, { label = 'narrando', maxAgeMs = 45000, force = false } = {}) {
+  const frase = String(texto ?? '').trim();
+  if (!frase || (!voz.settings.enabled && !force)) return;
+  reproducirVoz(frase, { label, maxAgeMs }).catch(() => {});
+}
+
+/** Habla el progreso de un turno EN VIVO: el replay de una reconexion no habla. */
+export function narrar(event, data, turn) {
+  if (!turn?.live) return;
+  const handsFreeOn = handsFree.active;
+  const { enabled, announce } = voz.settings;
+  if (!enabled && !handsFreeOn) return;
+  // Manos libres: conversacion, sin narracion de arranque/herramientas; lee la
+  // respuesta final (y el asesor) aunque la narracion este apagada en Ajustes.
+  if (handsFreeOn) {
+    if (event === 'advice') {
+      if (data?.say) hablar(data.say, { label: 'asesor', maxAgeMs: 0, force: true });
+    } else if (event === 'done') {
+      const spoken = speechText(data?.content);
+      if (spoken) hablar(spoken, { label: 'respuesta', maxAgeMs: 0, force: true });
+      else if (data?.say) hablar(data.say, { maxAgeMs: 0, force: true });
+    } else if ((event === 'aborted' || event === 'error') && data?.say) {
+      hablar(data.say, { maxAgeMs: 0, force: true });
+    }
+    return;
+  }
+  if (!enabled) return;
+  if (event === 'start' && announce.start) hablar(data?.say);
+  else if (event === 'tool_call' && announce.tools) hablar(data?.say);
+  // El asesor y la respuesta final son el cierre del turno: si quedan en cola
+  // detras de un audio largo, igual hay que leerlos (sin vencimiento).
+  else if (event === 'advice') {
+    if (data?.kind === 'summary') {
+      if (announce.summary) hablar(data?.say, { label: 'resumen', maxAgeMs: 0 });
+    } else if (announce.advice) {
+      hablar(data?.say, { label: 'asesor', maxAgeMs: 0 });
+    }
+  } else if (event === 'done' && announce.answer) {
+    // Lee la respuesta final limpia; si era solo codigo, cae al cierre.
+    const spoken = speechText(data?.content);
+    if (spoken) hablar(spoken, { label: 'respuesta', maxAgeMs: 0 });
+    else if (announce.end) hablar(data?.say);
+  } else if ((event === 'done' || event === 'aborted' || event === 'error') && announce.end) hablar(data?.say);
+}
+
+export async function cargarVoces() {
+  if (!vozVoiceEl || vozVoiceEl.options.length) return;
+  const data = await api('/api/tts/voices?filter=es-').catch(() => null);
+  if (!data?.voices?.length) return;
+  // Solo voces en español (el server ya filtra; guarda por si cambia).
+  const espanol = data.voices.filter((v) => /^es[-_]/i.test(String(v.Locale || v.ShortName || '')));
+  for (const v of espanol.sort((a, b) => String(a.ShortName).localeCompare(String(b.ShortName)))) {
+    const option = el('option', '', `${v.ShortName}${v.Gender === 'Female' ? ' · femenina' : v.Gender === 'Male' ? ' · masculina' : ''}`);
+    option.value = v.ShortName;
+    vozVoiceEl.appendChild(option);
+  }
+}
+
+export async function aplicarVoz(data) {
+  if (!data) return;
+  voz.settings = {
+    enabled: data.enabled === true,
+    voice: data.voice || 'es-AR-ElenaNeural',
+    rate: data.rate || '+0%',
+    pitch: data.pitch || '+0Hz',
+    announce: {
+      start: data.announce?.start !== false,
+      tools: data.announce?.tools !== false,
+      end: data.announce?.end !== false,
+      advice: data.announce?.advice !== false,
+      answer: data.announce?.answer === true,
+      summary: data.announce?.summary === true,
+    },
+  };
+  if (vozEnabledEl) vozEnabledEl.checked = voz.settings.enabled;
+  if (vozFfmpegEl) vozFfmpegEl.hidden = data.ffmpeg !== false;
+  if (vozVoiceEl) {
+    await cargarVoces();
+    if (![...vozVoiceEl.options].some((o) => o.value === voz.settings.voice)) {
+      const option = el('option', '', voz.settings.voice);
+      option.value = voz.settings.voice;
+      vozVoiceEl.appendChild(option);
+    }
+    vozVoiceEl.value = voz.settings.voice;
+  }
+  if (vozRateEl) vozRateEl.value = rateToSlider(voz.settings.rate);
+  if (vozPitchEl) vozPitchEl.value = pitchToSlider(voz.settings.pitch);
+  renderVozSliders();
+  if (vozAnnStartEl) vozAnnStartEl.checked = voz.settings.announce.start;
+  if (vozAnnToolsEl) vozAnnToolsEl.checked = voz.settings.announce.tools;
+  if (vozAnnEndEl) vozAnnEndEl.checked = voz.settings.announce.end;
+  if (vozAnnAdviceEl) vozAnnAdviceEl.checked = voz.settings.announce.advice;
+  if (vozAnnSummaryEl) vozAnnSummaryEl.checked = voz.settings.announce.summary;
+  if (vozAnnAnswerEl) vozAnnAnswerEl.checked = voz.settings.announce.answer;
+  const estado = $('#voz-status');
+  if (estado) {
+    estado.className = `summary${voz.settings.enabled ? ' ok' : ''}`;
+    estado.textContent = voz.settings.enabled ? 'activa' : 'apagada';
+  }
+}
+
+export async function refreshVoz() {
+  if (!vozEnabledEl) return;
+  const data = await api('/api/tts/settings').catch(() => null);
+  if (data) aplicarVoz(data);
+}
+
+export async function submitVoz() {
+  setStatus('#voz-msg', 'guardando…');
+  const body = {
+    enabled: vozEnabledEl?.checked === true,
+    voice: vozVoiceEl?.value,
+    rate: sliderToRate(vozRateEl?.value),
+    pitch: sliderToPitch(vozPitchEl?.value),
+    announce: {
+      start: vozAnnStartEl?.checked !== false,
+      tools: vozAnnToolsEl?.checked !== false,
+      end: vozAnnEndEl?.checked !== false,
+      advice: vozAnnAdviceEl?.checked !== false,
+      answer: vozAnnAnswerEl?.checked === true,
+      summary: vozAnnSummaryEl?.checked === true,
+    },
+  };
+  const data = await api('/api/tts/settings', { method: 'PUT', body }).catch((e) => ({ error: e.message }));
+  if (data?.error) return setStatus('#voz-msg', data.error, 'err');
+  await aplicarVoz(data);
+  setStatus('#voz-msg', 'guardado', 'ok');
+}
+
+/* --- ajustes: transcripción ----------------------------------------------- */
+
+export const trModeEl = $('#tr-mode');
+export const trLanguageEl = $('#tr-language');
+
+// Config efectiva del dictado; se carga al boot para que el micrófono del chat
+// la use sin abrir Ajustes.
+export const transcribeConfig = {
+  mode: 'server',
+  language: 'es-AR',
+  provider: '',
+  model: '',
+  fallback: { provider: '', model: '' },
+};
+
+export function syncTranscribeMode() {
+  const mode = trModeEl?.value ?? transcribeConfig.mode;
+  const serverFields = $('#tr-server-fields');
+  if (serverFields) serverFields.hidden = mode !== 'server';
+  const browserNote = $('#tr-browser-note');
+  if (browserNote) browserNote.hidden = mode !== 'browser';
+  const googleNote = $('#tr-google-note');
+  if (googleNote) googleNote.hidden = mode !== 'google';
+}
+
+export function aplicarTranscribe(data) {
+  if (!data) return;
+  transcribeConfig.mode = ['browser', 'google'].includes(data.mode) ? data.mode : 'server';
+  transcribeConfig.language = data.language || 'es-AR';
+  transcribeConfig.provider = data.provider ?? '';
+  transcribeConfig.model = data.model ?? '';
+  transcribeConfig.fallback = data.fallback ?? { provider: '', model: '' };
+  if (trModeEl && document.activeElement !== trModeEl) trModeEl.value = transcribeConfig.mode;
+  if (trLanguageEl && document.activeElement !== trLanguageEl) trLanguageEl.value = transcribeConfig.language;
+  if (trProviderEl && document.activeElement !== trProviderEl) trProviderEl.value = transcribeConfig.provider;
+  if (trModelEl && document.activeElement !== trModelEl) trModelEl.value = transcribeConfig.model;
+  if (trProviderEl) trProviderEl.placeholder = transcribeConfig.fallback.provider || 'groq · openai';
+  if (trModelEl) trModelEl.placeholder = transcribeConfig.fallback.model || 'whisper-large-v3-turbo';
+  syncTranscribeMode();
+  if (transcribeConfig.mode === 'browser') {
+    setStatus('#tr-status', `navegador · ${transcribeConfig.language}`, '');
+  } else if (transcribeConfig.mode === 'google') {
+    setStatus('#tr-status', `google (sin API key) · ${transcribeConfig.language}`, '');
+  } else {
+    const effProvider = transcribeConfig.provider || transcribeConfig.fallback.provider || 'proveedor activo';
+    const effModel = transcribeConfig.model || transcribeConfig.fallback.model || 'whisper-1';
+    setStatus('#tr-status', `usa: ${effProvider} · ${effModel}`, '');
+  }
+}
+
+export async function refreshTranscribe() {
+  if (!trModeEl) return;
+  const data = await api('/api/transcribe/settings').catch(() => null);
+  if (data) aplicarTranscribe(data);
+}
+
+export async function submitTranscribe() {
+  setStatus('#tr-msg', 'guardando…');
+  const data = await api('/api/transcribe/settings', {
+    method: 'PUT',
+    body: {
+      mode: trModeEl?.value || 'server',
+      language: trLanguageEl?.value.trim() || 'es-AR',
+      provider: trProviderEl?.value.trim() || '',
+      model: trModelEl?.value.trim() || '',
+    },
+  }).catch((e) => ({ error: e.message }));
+  if (data?.error) return setStatus('#tr-msg', data.error, 'err');
+  setStatus('#tr-msg', 'guardado', 'ok');
+  aplicarTranscribe(data);
+}
+
+export const trTestBtn = $('#tr-test');
+export let trRecording = null;
+export let browserTest = null;
+
+export function startBrowserTest() {
+  let dictation;
+  try {
+    dictation = createBrowserDictation({
+      language: transcribeConfig.language,
+      onText: (_final, combined) => {
+        const text = combined.trim();
+        setStatus('#tr-test-result', text ? `“${text}”` : 'escuchando…', text ? 'ok' : '');
+      },
+      onEnd: () => {
+        if (browserTest === dictation) browserTest = null;
+        micVisual(trTestBtn);
+      },
+      onError: (error) => setStatus('#tr-test-result', error.message, 'err'),
+    });
+  } catch (error) {
+    return setStatus('#tr-test-result', error.message, 'err');
+  }
+  browserTest = dictation;
+  setStatus('#tr-test-result', '');
+  micVisual(trTestBtn, { live: true });
+  try {
+    dictation.start();
+  } catch (error) {
+    browserTest = null;
+    micVisual(trTestBtn);
+    setStatus('#tr-test-result', error.message, 'err');
+  }
+}
+
+/** Graba con el micrófono y muestra acá qué devuelve la transcripción. */
+export async function toggleTrTest() {
+  if (!trTestBtn) return;
+  if (browserTest) {
+    browserTest.stop();
+    return;
+  }
+  if (trRecording) {
+    trRecording.stop();
+    return;
+  }
+  if (transcribeConfig.mode === 'browser') return startBrowserTest();
+
+  const rec = createRecording();
+  trTestBtn.disabled = true;
+  setStatus('#tr-test-result', '');
+  try {
+    await rec.start();
+  } catch (error) {
+    trTestBtn.disabled = false;
+    micVisual(trTestBtn);
+    return setStatus('#tr-test-result', `No pude acceder al micrófono: ${error.message}`, 'err');
+  }
+  trTestBtn.disabled = false;
+  trRecording = rec;
+  rec.done.then(async (blob) => {
+    if (trRecording === rec) trRecording = null;
+    if (!blob.size) {
+      micVisual(trTestBtn);
+      return setStatus('#tr-test-result', 'no se grabó audio', 'err');
+    }
+    micVisual(trTestBtn, { busy: true });
+    setStatus('#tr-test-result', 'transcribiendo…');
+    try {
+      const text = await transcribirBlob(blob);
+      setStatus('#tr-test-result', text ? `“${text}”` : 'no se entendió el audio', text ? 'ok' : 'err');
+    } catch (error) {
+      setStatus('#tr-test-result', error.message, 'err');
+    } finally {
+      micVisual(trTestBtn);
+    }
+  });
+  await micCountdown(trTestBtn, () => rec.stopping);
+}
+
+export async function testVoz() {
+  setStatus('#voz-msg', 'sintetizando…');
+  const trato = ($('#perfil-address')?.value || '').trim();
+  const frase = trato
+    ? `${trato}, esta sería la voz predeterminada para mí`
+    : 'Esta sería la voz predeterminada para mí';
+  try {
+    await reproducirVoz(frase, {
+      voice: vozVoiceEl?.value,
+      rate: sliderToRate(vozRateEl?.value),
+      pitch: sliderToPitch(vozPitchEl?.value),
+    });
+    setStatus('#voz-msg', 'sonó', 'ok');
+  } catch (error) {
+    setStatus('#voz-msg', error.message, 'err');
+  }
+}