Add multi-user speaker profiles, collective voice, and mode toggle

Task 1 — SpeakerProfileManager (src/voice/speaker_profiles.py):
SpeechBrain ECAPA-TDNN identifies speakers by cosine similarity of
192-d embeddings (threshold 0.75). Each user gets user_N_sb.npy
(running-average SpeechBrain embedding) and user_N_ov.npy
(running-average OpenVoice V2 tone-color SE). New utterances update
the running average so profiles sharpen over time.

Task 2 — get_collective_embedding() (speaker_profiles.py):
Loads all user_N_ov.npy files and returns their mean vector — the
"Collective Voice" that blends all known speakers into one SE.

Task 3 — Voice Mode toggle (app_lab.py + src/tts/voice_cloner.py):
Added Individual / Collective radio to the UI. In Individual mode
the TTS output is cloned into the last detected speaker's voice via
OpenVoice V2 ToneColorConverter. In Collective mode the mean SE is
used. Text-input path falls back to the collective SE. Both modes
degrade gracefully to base VITS voice if OpenVoice is not ready.

requirements.txt: add speechbrain>=0.5.15 and openvoice (git install
at Docker build time — HF Spaces blocks GitHub only at runtime).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app_lab.py

@@ -49,6 +49,8 @@ LANGUAGE_NAMES = {
 from src.memory.memory_manager      import MemoryManager
 from src.llm.gemma_client           import GemmaClient
 from src.tts.waxal_tts              import WaxalTTSEngine
+from src.tts.voice_cloner           import VoiceCloner
+from src.voice.speaker_profiles     import SpeakerProfileManager
 from src.engine.stt_processor       import (
     transcribe_with_confidence,
     LOW_CONFIDENCE_THRESHOLD,
@@ -56,10 +58,12 @@ from src.engine.stt_processor       import (
 )
 from src.engine.curiosity           import CuriosityEngine
 
-_memory    = MemoryManager(repo_id=FEEDBACK_REPO_ID, hf_token=HF_TOKEN)
-_gemma     = GemmaClient(model_id=LLM_MODEL_ID, hf_token=HF_TOKEN)
-_tts       = WaxalTTSEngine()
-_curiosity = CuriosityEngine(interval=5)
+_memory          = MemoryManager(repo_id=FEEDBACK_REPO_ID, hf_token=HF_TOKEN)
+_gemma           = GemmaClient(model_id=LLM_MODEL_ID, hf_token=HF_TOKEN)
+_tts             = WaxalTTSEngine()
+_voice_cloner    = VoiceCloner()
+_speaker_profiles = SpeakerProfileManager()
+_curiosity       = CuriosityEngine(interval=5)
 
 # Whisper — loaded lazily in background
 _whisper_model     = None
@@ -149,10 +153,14 @@ def _run_llm_and_tts(
     lang_code: str,
     history: list,
     source_label: str,
+    active_se=None,
 ) -> tuple:
     """
-    Shared core: Gemma → memory update → TTS.
+    Shared core: Gemma → memory update → TTS → optional voice cloning.
     Returns: (history, recent_words_md, status_msg, audio_tuple_or_None)
+
+    active_se: OpenVoice V2 tone-color SE (numpy array) to clone into, or None
+               for the base VITS voice.
     """
     # 1. Ask Gemma (with vocabulary context)
     vocab_ctx  = _memory.get_vocabulary_context()
@@ -169,11 +177,16 @@ def _run_llm_and_tts(
         if word and trans:
             _memory.add_word_pair(word, lang, trans, trans_l, source="user_taught")
 
-    # 3. TTS — speak the response if language supported
+    # 3. TTS → optional voice cloning
     audio_out = None
     tts_result = _tts.synthesize(response, lang_code)
     if tts_result is not None:
-        audio_out = WaxalTTSEngine.audio_to_gradio(*tts_result)
+        audio_np, sr = tts_result
+        if active_se is not None:
+            cloned = _voice_cloner.convert(audio_np, sr, active_se)
+            if cloned is not None:
+                audio_np, sr = cloned
+        audio_out = WaxalTTSEngine.audio_to_gradio(audio_np, sr)
 
     # 4. Update chat history
     history = list(history or [])
@@ -196,9 +209,14 @@ def _run_llm_and_tts(
     return history, _render_recent_words(), status_msg, audio_out
 
 
-def process_audio(audio_path, language_label: str, history: list) -> tuple:
+def process_audio(
+    audio_path,
+    language_label: str,
+    voice_mode: str,
+    history: list,
+) -> tuple:
     """
-    Full pipeline: audio → Whisper STT → Gemma → TTS.
+    Full pipeline: audio → speaker ID → Whisper STT → Gemma → TTS → voice clone.
     Returns: (history, recent_words_md, status_msg, audio_out)
     """
     try:
@@ -211,11 +229,30 @@ def process_audio(audio_path, language_label: str, history: list) -> tuple:
         if _whisper_model is None:
             return history, _render_recent_words(), f"⏳ {status} — wait a moment and try again.", None
 
+        # Load audio once — used for both speaker ID and STT
+        import librosa
+        audio_np, _ = librosa.load(audio_path, sr=16_000, mono=True)
+
+        # ── Speaker identification (Task 1) ───────────────────────────────────
+        uid, _ = _speaker_profiles.identify_or_create(audio_np)
+
+        # Extract OpenVoice SE and update the user's profile
+        if uid is not None:
+            ov_se = _voice_cloner.extract_se(audio_np, 16_000)
+            if ov_se is not None:
+                _speaker_profiles.update_ov_embedding(uid, ov_se)
+
+        # ── Select target SE based on mode (Task 3) ───────────────────────────
+        if voice_mode == "Individual" and uid is not None:
+            active_se = _speaker_profiles.get_openvoice_se(uid)
+        else:
+            active_se = _speaker_profiles.get_collective_embedding()
+
+        # ── Transcription with confidence scoring ─────────────────────────────
         transcript, avg_logprob = _transcribe(audio_path, lang_code)
         if not transcript:
             return history, _render_recent_words(), "⚠️ Could not transcribe audio.", None
 
-        # Low-confidence transcription → ask user to repeat and explain
         if avg_logprob < LOW_CONFIDENCE_THRESHOLD:
             logger.info(
                 "Low STT confidence (avg_logprob=%.3f) — switching to confusion prompt",
@@ -223,20 +260,24 @@ def process_audio(audio_path, language_label: str, history: list) -> tuple:
             )
             transcript = CONFUSION_PROMPT
 
-        return _run_llm_and_tts(transcript, lang_code, history, "voice")
+        return _run_llm_and_tts(transcript, lang_code, history, "voice", active_se)
     except Exception as exc:
         logger.exception("process_audio error")
         return history, _render_recent_words(), f"❌ Error: {exc}", None
 
 
-def process_text(text: str, language_label: str, history: list) -> tuple:
-    """Text input path — Gemma → TTS. Returns: (history, recent_words_md, status_msg, audio_out)"""
+def process_text(text: str, language_label: str, voice_mode: str, history: list) -> tuple:
+    """Text input path — Gemma → TTS → optional voice clone."""
     try:
         if not text.strip():
             return history, _render_recent_words(), "⚠️ Please type something.", None
 
         lang_code = _label_to_code(language_label)
-        return _run_llm_and_tts(text.strip(), lang_code, history, "text")
+
+        # Text has no speaker signal — use Collective in both modes as fallback
+        active_se = _speaker_profiles.get_collective_embedding()
+
+        return _run_llm_and_tts(text.strip(), lang_code, history, "text", active_se)
     except Exception as exc:
         logger.exception("process_text error")
         return history, _render_recent_words(), f"❌ Error: {exc}", None
@@ -289,13 +330,16 @@ def build_ui() -> gr.Blocks:
                     tts = _tts.get_status()
                     bam = "🟢" if tts["bam"] == "ready" else ("🟡" if "not" in tts["bam"] else "🔴")
                     ful = "🟢" if tts["ful"] == "ready" else ("🟡" if "not" in tts["ful"] else "🔴")
-                    return f"{stt} | TTS Bambara {bam} | TTS Fula {ful}"
+                    spk = _speaker_profiles.get_status()
+                    cln = "🟢 Cloner" if _voice_cloner._ready else (
+                          "🔴 Cloner" if _voice_cloner._error else "🟡 Cloner")
+                    return f"{stt} | TTS Bambara {bam} | TTS Fula {ful}\n{spk} | {cln}"
 
                 status_box = gr.Textbox(
                     value=_full_status(),
                     label="System status",
                     interactive=False,
-                    max_lines=1,
+                    max_lines=2,
                 )
                 status_timer = gr.Timer(value=4)
                 status_timer.tick(fn=_full_status, outputs=status_box)
@@ -306,6 +350,16 @@ def build_ui() -> gr.Blocks:
                     label="Language you are speaking",
                 )
 
+                voice_mode_radio = gr.Radio(
+                    choices=["Individual", "Collective"],
+                    value="Individual",
+                    label="Voice Mode",
+                    info=(
+                        "Individual — respond in the voice of the last speaker detected.  "
+                        "Collective — blend all known voices into one shared voice."
+                    ),
+                )
+
                 with gr.Tab("🎙️ Push-to-Talk"):
                     audio_input = gr.Audio(
                         sources=["microphone"],
@@ -370,7 +424,7 @@ def build_ui() -> gr.Blocks:
 
         talk_btn.click(
             fn=process_audio,
-            inputs=[audio_input, language_dd, history_state],
+            inputs=[audio_input, language_dd, voice_mode_radio, history_state],
             outputs=[history_state, recent_words, action_status, audio_output],
         ).then(
             fn=lambda h: h,
@@ -380,7 +434,7 @@ def build_ui() -> gr.Blocks:
 
         text_btn.click(
             fn=process_text,
-            inputs=[text_input, language_dd, history_state],
+            inputs=[text_input, language_dd, voice_mode_radio, history_state],
             outputs=[history_state, recent_words, action_status, audio_output],
         ).then(
             fn=lambda h: (h, ""),
@@ -390,7 +444,7 @@ def build_ui() -> gr.Blocks:
 
         text_input.submit(
             fn=process_text,
-            inputs=[text_input, language_dd, history_state],
+            inputs=[text_input, language_dd, voice_mode_radio, history_state],
             outputs=[history_state, recent_words, action_status, audio_output],
         ).then(
             fn=lambda h: (h, ""),
@@ -414,6 +468,10 @@ threading.Thread(target=_memory.load, daemon=True).start()
 _ensure_whisper()
 # Preload TTS models in background
 _tts.preload()
+# Preload speaker identification (SpeechBrain ECAPA-TDNN)
+_speaker_profiles.preload()
+# Preload voice cloner (OpenVoice V2) — gracefully degrades if unavailable
+_voice_cloner.preload()
 
 if __name__ == "__main__":
     from dotenv import load_dotenv

requirements.txt

@@ -52,5 +52,12 @@ scipy==1.15.2
 # Phrase matching (fuzzy match for Whisper mis-transcriptions of Bambara/Fula)
 rapidfuzz==3.13.0
 
+# Speaker identification (ECAPA-TDNN 192-d embeddings, used by SpeakerProfileManager)
+speechbrain>=0.5.15
+
+# Voice cloning (OpenVoice V2 ToneColorConverter — installed at build time from GitHub)
+# HF Spaces blocks GitHub at *runtime* but allows it during Docker build via requirements.txt
+openvoice @ git+https://github.com/myshell-ai/OpenVoice.git
+
 # maliba-ai is NOT listed here — it has strict conflicting pins (librosa, soundfile).
 # It is installed lazily at runtime on first Bambara TTS call (see src/tts/waxal_tts.py).

src/tts/voice_cloner.py

@@ -0,0 +1,223 @@
+"""
+VoiceCloner — OpenVoice V2 tone-color converter.
+
+Sits downstream of WaxalTTSEngine: takes the base VITS audio and reshapes it
+to match a target speaker's tone color.
+
+Usage:
+    cloner = VoiceCloner()
+    cloner.preload()                          # background thread
+
+    # After WaxalTTS produces (audio_np, sr) …
+    se = cloner.extract_se(audio_np, sr)      # extract SE from user's mic audio
+    result = cloner.convert(audio_np, sr, se) # returns (cloned_audio, sr) or None
+
+The OpenVoice V2 checkpoint is downloaded from myshell-ai/openvoice-v2 on
+HuggingFace Hub at first use (cached in data/openvoice_v2/).
+
+Falls back gracefully (returns None) if openvoice is not installed or the
+checkpoint download fails — in that case the caller uses the raw VITS output.
+"""
+from __future__ import annotations
+
+import logging
+import os
+import tempfile
+import threading
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+OV_HF_REPO  = "myshell-ai/openvoice-v2"
+OV_CKPT_DIR = Path("data/openvoice_v2")
+HF_TOKEN    = os.environ.get("HF_TOKEN")
+
+
+class VoiceCloner:
+    """
+    Thin wrapper around OpenVoice V2 ToneColorConverter.
+
+    Thread-safety: convert() holds _lock so parallel calls are serialised;
+    the lock is released while waiting for subprocess/IO.
+    """
+
+    def __init__(self) -> None:
+        self._lock      = threading.Lock()
+        self._converter = None
+        self._src_se    = None   # cached base-TTS source SE (computed on first convert)
+        self._ready     = False
+        self._error: Optional[str] = None
+
+    def preload(self) -> None:
+        threading.Thread(target=self._load, daemon=True).start()
+
+    def get_status(self) -> str:
+        if self._ready:  return "ready"
+        if self._error:  return f"error: {self._error}"
+        return "loading…"
+
+    # ── Loading ───────────────────────────────────────────────────────────────
+
+    def _load(self) -> None:
+        try:
+            from openvoice.api import ToneColorConverter   # noqa: F401 — validate import
+            OV_CKPT_DIR.mkdir(parents=True, exist_ok=True)
+
+            # Download checkpoint from HF Hub once, then use local cache
+            converter_cfg = OV_CKPT_DIR / "converter" / "config.json"
+            if not converter_cfg.exists():
+                logger.info("VoiceCloner: downloading OpenVoice V2 from HF Hub …")
+                from huggingface_hub import snapshot_download
+                snapshot_download(
+                    repo_id=OV_HF_REPO,
+                    local_dir=str(OV_CKPT_DIR),
+                    token=HF_TOKEN,
+                )
+
+            # Find config — repo layout may vary
+            cfg_path = self._find_converter_config()
+            if cfg_path is None:
+                raise FileNotFoundError(
+                    f"converter/config.json not found under {OV_CKPT_DIR}"
+                )
+
+            from openvoice.api import ToneColorConverter
+            logger.info("VoiceCloner: loading ToneColorConverter from %s …", cfg_path)
+            converter = ToneColorConverter(str(cfg_path), device="cpu")
+            ckpt = cfg_path.parent / "checkpoint.pth"
+            converter.load_ckpt(str(ckpt))
+
+            with self._lock:
+                self._converter = converter
+                self._ready     = True
+            logger.info("VoiceCloner: OpenVoice V2 ready")
+
+        except Exception as exc:
+            self._error = str(exc)
+            logger.warning(
+                "VoiceCloner: load failed — voice cloning disabled: %s", exc
+            )
+
+    def _find_converter_config(self) -> Optional[Path]:
+        """Probe known checkpoint layouts to locate converter/config.json."""
+        candidates = [
+            OV_CKPT_DIR / "converter" / "config.json",
+            OV_CKPT_DIR / "checkpoints_v2" / "converter" / "config.json",
+        ]
+        for p in candidates:
+            if p.exists():
+                return p
+        # Walk one level deep as fallback
+        for p in OV_CKPT_DIR.rglob("config.json"):
+            if p.parent.name == "converter":
+                return p
+        return None
+
+    # ── SE extraction ─────────────────────────────────────────────────────────
+
+    def extract_se(self, audio_np: np.ndarray, sr: int) -> Optional[np.ndarray]:
+        """
+        Extract OpenVoice V2 tone-color SE from raw float32 audio.
+        Returns a numpy array (shape depends on OV model, typically (1, 256)),
+        or None if not ready.
+        """
+        if not self._ready:
+            return None
+        try:
+            import soundfile as sf
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                tmp = f.name
+            sf.write(tmp, audio_np, sr)
+            se = self._extract_se_from_file(tmp)
+            Path(tmp).unlink(missing_ok=True)
+            return se
+        except Exception as exc:
+            logger.debug("VoiceCloner.extract_se: %s", exc)
+            return None
+
+    def _extract_se_from_file(self, audio_path: str) -> Optional[np.ndarray]:
+        try:
+            from openvoice import se_extractor
+            se, _ = se_extractor.get_se(
+                audio_path,
+                self._converter,
+                target_dir=str(OV_CKPT_DIR / "tmp"),
+                vad=False,
+            )
+            arr = se.cpu().numpy() if hasattr(se, "cpu") else np.array(se)
+            return arr
+        except Exception as exc:
+            logger.debug("VoiceCloner._extract_se_from_file: %s", exc)
+            return None
+
+    # ── Voice conversion ──────────────────────────────────────────────────────
+
+    def convert(
+        self,
+        audio_np: np.ndarray,
+        sr: int,
+        target_se: np.ndarray,
+    ) -> Optional[tuple[np.ndarray, int]]:
+        """
+        Reshape audio to match the target speaker's tone color.
+
+        Args:
+            audio_np:  float32 audio from WaxalTTS (base voice).
+            sr:        sample rate of audio_np.
+            target_se: OpenVoice SE from SpeakerProfileManager (Individual or
+                       Collective).
+
+        Returns (cloned_audio_float32, sample_rate) or None if not ready.
+        """
+        if not self._ready:
+            return None
+        try:
+            import soundfile as sf
+            import torch
+
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                src_path = f.name
+            with tempfile.NamedTemporaryFile(suffix=".wav", delete=False) as f:
+                out_path = f.name
+
+            sf.write(src_path, audio_np, sr)
+
+            with self._lock:
+                # Extract source SE on first call, then cache it for the session
+                if self._src_se is None:
+                    se = self._extract_se_from_file(src_path)
+                    if se is not None:
+                        self._src_se = se
+
+                if self._src_se is None:
+                    logger.warning("VoiceCloner: could not extract source SE")
+                    return None
+
+                src_se_t = torch.tensor(self._src_se)
+                tgt_se_t = torch.tensor(target_se)
+
+                # Ensure batch dim matches what the converter expects
+                if src_se_t.dim() == 1:
+                    src_se_t = src_se_t.unsqueeze(0)
+                if tgt_se_t.dim() == 1:
+                    tgt_se_t = tgt_se_t.unsqueeze(0)
+
+                self._converter.convert(
+                    audio_src_path=src_path,
+                    src_se=src_se_t,
+                    tgt_se=tgt_se_t,
+                    output_path=out_path,
+                    message="@MyShell",
+                )
+
+            audio_out, out_sr = sf.read(out_path, dtype="float32")
+            Path(src_path).unlink(missing_ok=True)
+            Path(out_path).unlink(missing_ok=True)
+            return audio_out.astype(np.float32), out_sr
+
+        except Exception as exc:
+            logger.error("VoiceCloner.convert: %s", exc)
+            return None

src/voice/speaker_profiles.py

@@ -0,0 +1,215 @@
+"""
+SpeakerProfileManager — multi-user voice identity.
+
+SpeechBrain ECAPA-TDNN extracts 192-d embeddings for speaker identification.
+Each confirmed user gets two files in data/profiles/:
+
+  user_N_sb.npy    — running-average SpeechBrain embedding  (identification)
+  user_N_ov.npy    — running-average OpenVoice V2 tone-color SE  (cloning)
+  user_N_count.txt — number of utterances averaged so far
+
+Speaker matching uses cosine similarity.  If similarity ≥ COSINE_THRESHOLD the
+new utterance is attributed to that user and their embedding is updated;
+otherwise a new profile is created.
+
+get_collective_embedding() (Task 2) returns the mean of all stored OV SEs.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from pathlib import Path
+from typing import Optional
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+PROFILES_DIR     = Path("data/profiles")
+COSINE_THRESHOLD = 0.75   # empirical threshold for ECAPA-TDNN
+
+
+def _cosine(a: np.ndarray, b: np.ndarray) -> float:
+    denom = np.linalg.norm(a) * np.linalg.norm(b)
+    return float(np.dot(a, b) / denom) if denom > 1e-8 else 0.0
+
+
+def _running_avg(old: np.ndarray, new: np.ndarray, count: int) -> np.ndarray:
+    """Weighted running average — older observations decay gently."""
+    alpha = 1.0 / (count + 1)
+    return (1.0 - alpha) * old + alpha * new
+
+
+class SpeakerProfileManager:
+    """Thread-safe multi-user voice profile store backed by .npy files."""
+
+    def __init__(self, profiles_dir: Path = PROFILES_DIR) -> None:
+        self._dir  = Path(profiles_dir)
+        self._dir.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.Lock()
+
+        # SpeechBrain state
+        self._sb_model = None
+        self._sb_ready = False
+        self._sb_error: Optional[str] = None
+
+        # In-memory cache: { "user_0": {"sb": ndarray, "ov": ndarray|None, "count": int} }
+        self._profiles: dict[str, dict] = {}
+        self._load_profiles()
+
+    # ── SpeechBrain loading ───────────────────────────────────────────────────
+
+    def preload(self) -> None:
+        threading.Thread(target=self._load_sb, daemon=True).start()
+
+    def _load_sb(self) -> None:
+        try:
+            try:
+                from speechbrain.inference.classifiers import EncoderClassifier
+            except ImportError:
+                from speechbrain.pretrained import EncoderClassifier
+
+            logger.info("SpeakerProfiles: loading SpeechBrain ECAPA-TDNN …")
+            self._sb_model = EncoderClassifier.from_hparams(
+                source="speechbrain/spkrec-ecapa-voxceleb",
+                run_opts={"device": "cpu"},
+                savedir="data/speechbrain_cache",
+            )
+            self._sb_ready = True
+            logger.info("SpeakerProfiles: SpeechBrain ready")
+        except Exception as exc:
+            self._sb_error = str(exc)
+            logger.error("SpeakerProfiles: SpeechBrain load failed: %s", exc)
+
+    def _extract_sb(self, audio_np: np.ndarray) -> Optional[np.ndarray]:
+        """Return 192-d ECAPA embedding, or None if model not ready."""
+        if not self._sb_ready:
+            self._load_sb()
+        if not self._sb_ready:
+            return None
+        try:
+            import torch
+            wav = torch.tensor(audio_np, dtype=torch.float32).unsqueeze(0)
+            with torch.no_grad():
+                emb = self._sb_model.encode_batch(wav)   # (1, 1, 192)
+            return emb.squeeze().cpu().numpy()
+        except Exception as exc:
+            logger.error("SpeakerProfiles: SpeechBrain inference error: %s", exc)
+            return None
+
+    # ── Profile I/O ───────────────────────────────────────────────────────────
+
+    def _load_profiles(self) -> None:
+        profiles = {}
+        for sb_path in sorted(self._dir.glob("user_*_sb.npy")):
+            uid      = sb_path.stem[:-3]          # "user_N_sb" → "user_N"
+            ov_path  = self._dir / f"{uid}_ov.npy"
+            cnt_path = self._dir / f"{uid}_count.txt"
+            profiles[uid] = {
+                "sb":    np.load(sb_path),
+                "ov":    np.load(ov_path) if ov_path.exists() else None,
+                "count": int(cnt_path.read_text()) if cnt_path.exists() else 1,
+            }
+        with self._lock:
+            self._profiles = profiles
+        logger.info("SpeakerProfiles: loaded %d profile(s)", len(profiles))
+
+    def _save_profile(self, uid: str) -> None:
+        p = self._profiles[uid]
+        np.save(self._dir / f"{uid}_sb.npy",  p["sb"])
+        if p["ov"] is not None:
+            np.save(self._dir / f"{uid}_ov.npy", p["ov"])
+        (self._dir / f"{uid}_count.txt").write_text(str(p["count"]))
+
+    # ── Task 1: Speaker identification ────────────────────────────────────────
+
+    def identify_or_create(
+        self, audio_np: np.ndarray
+    ) -> tuple[Optional[str], Optional[np.ndarray]]:
+        """
+        Extract a SpeechBrain embedding and match it to an existing profile
+        (cosine similarity ≥ threshold) or create a new one.
+
+        Returns (user_id, sb_embedding).
+        Returns (None, None) if SpeechBrain is not available.
+        """
+        sb_emb = self._extract_sb(audio_np)
+        if sb_emb is None:
+            return None, None
+
+        with self._lock:
+            best_uid, best_sim = None, -1.0
+            for uid, profile in self._profiles.items():
+                sim = _cosine(sb_emb, profile["sb"])
+                if sim > best_sim:
+                    best_sim, best_uid = sim, uid
+
+            if best_uid is not None and best_sim >= COSINE_THRESHOLD:
+                # Known speaker — update running average
+                p         = self._profiles[best_uid]
+                new_count = p["count"] + 1
+                p["sb"]   = _running_avg(p["sb"], sb_emb, p["count"])
+                p["count"] = new_count
+                uid = best_uid
+                logger.debug(
+                    "SpeakerProfiles: recognised %s (sim=%.3f, n=%d)",
+                    uid, best_sim, new_count,
+                )
+            else:
+                # New speaker
+                uid = f"user_{len(self._profiles)}"
+                self._profiles[uid] = {"sb": sb_emb, "ov": None, "count": 1}
+                logger.info("SpeakerProfiles: new profile → %s", uid)
+
+            self._save_profile(uid)
+
+        return uid, sb_emb
+
+    # ── OpenVoice SE management ───────────────────────────────────────────────
+
+    def update_ov_embedding(self, uid: str, ov_emb: np.ndarray) -> None:
+        """Store or running-average the OpenVoice tone-color SE for a user."""
+        with self._lock:
+            if uid not in self._profiles:
+                return
+            p = self._profiles[uid]
+            if p["ov"] is None:
+                p["ov"] = ov_emb.copy()
+            else:
+                p["ov"] = _running_avg(p["ov"], ov_emb, p["count"])
+            self._save_profile(uid)
+
+    def get_openvoice_se(self, uid: str) -> Optional[np.ndarray]:
+        """Return the stored OpenVoice SE for this user, or None."""
+        with self._lock:
+            p = self._profiles.get(uid)
+            return p["ov"].copy() if p and p["ov"] is not None else None
+
+    # ── Task 2: Collective Voice ──────────────────────────────────────────────
+
+    def get_collective_embedding(self) -> Optional[np.ndarray]:
+        """
+        Load all user_N_ov.npy files, return the mean vector.
+        This is the "Median Embedding" that represents all known speakers.
+        Returns None if no OpenVoice SEs have been collected yet.
+        """
+        # Prefer in-memory cache
+        with self._lock:
+            ov_list = [p["ov"] for p in self._profiles.values() if p["ov"] is not None]
+
+        if not ov_list:
+            # Fall back to disk scan (e.g. after a restart that didn't re-identify)
+            ov_list = [np.load(p) for p in sorted(self._dir.glob("user_*_ov.npy"))]
+
+        if not ov_list:
+            return None
+
+        stacked = np.stack(ov_list, axis=0)
+        return stacked.mean(axis=0)
+
+    # ── Status ────────────────────────────────────────────────────────────────
+
+    def get_status(self) -> str:
+        n  = len(self._profiles)
+        sb = "🟢" if self._sb_ready else ("🔴" if self._sb_error else "🟡")
+        return f"{sb} SpeechBrain | {n} speaker profile{'s' if n != 1 else ''}"