feat: enhance audio playback handling with improved chunk processing and setup management

Author: Gabry848

src/hooks/useVoiceChat.ts

@@ -72,6 +72,7 @@ export function useVoiceChat() {
   const isMutedRef = useRef<boolean>(false);
   const isManuallyMutedRef = useRef<boolean>(false); // Distingue tra mute manuale e automatico
   const isStartingRecordingRef = useRef<boolean>(false); // Previene avvii concorrenti di registrazione
+  const isReceivingAudioRef = useRef<boolean>(false); // true quando stiamo ricevendo chunk audio dal server
 
   /**
    * Verifica e richiede i permessi audio
@@ -149,7 +150,7 @@ export function useVoiceChat() {
       }
     },
 
-    onStatus: (phase: VoiceServerPhase, message: string) => {
+    onStatus: async (phase: VoiceServerPhase, message: string) => {
       console.log(`[useVoiceChat] onStatus: phase=${phase}, message=${message}`);
       setServerStatus({ phase, message });
 
@@ -217,12 +218,13 @@ export function useVoiceChat() {
           agentEndedRef.current = true;
 
           // IMPORTANTE: Non riattivare il microfono se:
-          // 1. Ci sono chunk audio in coda da riprodurre
+          // 1. Ci sono chunk audio in coda o in fase di processamento
           // 2. L'audio player sta ATTIVAMENTE riproducendo
-          const hasQueuedChunks = audioPlayerRef.current && audioPlayerRef.current.getChunksCount() > 0;
+          // 3. Stiamo ancora ricevendo audio dal server
+          const hasPending = audioPlayerRef.current?.hasPendingOrQueuedChunks();
           const isPlaying = audioPlayerRef.current?.isCurrentlyPlaying();
 
-          if (!hasQueuedChunks && !isPlaying) {
+          if (!hasPending && !isPlaying && !isReceivingAudioRef.current) {
             console.log('[useVoiceChat] Nessun audio in riproduzione, auto-unmute');
             setState('ready');
 
@@ -239,17 +241,20 @@ export function useVoiceChat() {
               }, 100);
             }
           } else {
-            console.log(`[useVoiceChat] Audio in corso (chunks: ${audioPlayerRef.current?.getChunksCount() || 0}, playing: ${isPlaying}), mantengo mute fino a fine riproduzione`);
+            console.log(`[useVoiceChat] Audio in corso (pending: ${hasPending}, playing: ${isPlaying}, receiving: ${isReceivingAudioRef.current}), mantengo mute fino a fine riproduzione`);
           }
           break;
 
         case 'audio_end':
           // Server ha finito di inviare chunk audio per questo segmento.
+          // Segna che non arriveranno altri chunk.
+          isReceivingAudioRef.current = false;
+
           // Con TrackPlayer la riproduzione è già in corso in streaming.
-          // Segnaliamo che non arriveranno altri chunk per gestire il completamento.
-          if (audioPlayerRef.current && audioPlayerRef.current.getChunksCount() > 0) {
+          // Controlliamo sia i chunk processati che quelli ancora pending.
+          if (audioPlayerRef.current && audioPlayerRef.current.hasPendingOrQueuedChunks()) {
             setState('speaking');
-            console.log(`[useVoiceChat] audio_end ricevuto (${audioPlayerRef.current.getChunksCount()} chunk) - riproduzione streaming in corso`);
+            console.log(`[useVoiceChat] audio_end ricevuto (${audioPlayerRef.current.getChunksCount()} chunk processati, pending: ${audioPlayerRef.current.hasPendingOrQueuedChunks()}) - avvio completamento`);
             audioPlayerRef.current.signalAllChunksReceived(() => {
               console.log('[useVoiceChat] Riproduzione streaming completata');
               // Riattiva il microfono SOLO se l'agent ha finito completamente
@@ -300,8 +305,9 @@ export function useVoiceChat() {
           // Risposta interrotta dall'utente, torna pronto
           console.log('[useVoiceChat] Risposta interrotta, auto-unmute');
           agentEndedRef.current = true; // Reset
+          isReceivingAudioRef.current = false; // Reset
           if (audioPlayerRef.current) {
-            audioPlayerRef.current.stopPlayback();
+            await audioPlayerRef.current.stopPlayback();
             audioPlayerRef.current.clearChunks();
           }
           setState('ready');
@@ -324,6 +330,9 @@ export function useVoiceChat() {
 
     onAudioChunk: (audioData: string, chunkIndex: number) => {
       if (audioPlayerRef.current) {
+        // Segna che stiamo ricevendo audio SINCRONAMENTE prima dell'async addChunk
+        isReceivingAudioRef.current = true;
+
         // Aggiunge il chunk alla queue di TrackPlayer e avvia riproduzione streaming
         audioPlayerRef.current.addChunk(audioData, chunkIndex).catch(err => {
           console.error('[useVoiceChat] Errore aggiunta chunk a TrackPlayer:', err);
@@ -375,6 +384,11 @@ export function useVoiceChat() {
       audioPlayerRef.current = new AudioPlayer();
       websocketRef.current = new VoiceBotWebSocket(websocketCallbacks);
 
+      // Pre-inizializza TrackPlayer per evitare ritardi al primo chunk audio.
+      // Questo elimina la race condition dove audio_end/agent_end arrivano
+      // prima che TrackPlayer abbia finito il setup.
+      await audioPlayerRef.current.preSetup();
+
       return true;
     } catch (err) {
       console.error('Errore inizializzazione:', err);
@@ -401,6 +415,7 @@ export function useVoiceChat() {
     shouldAutoStartRecordingRef.current = true;
     agentEndedRef.current = true; // Reset per nuova sessione
     isManuallyMutedRef.current = false; // Reset mute manuale
+    isReceivingAudioRef.current = false; // Reset audio reception
 
     try {
       const connected = await websocketRef.current!.connect();

src/services/voiceBotService.ts

@@ -101,7 +101,7 @@ export enum WebSocketAuthState {
  * Callback per gestire i diversi tipi di risposta dal WebSocket vocale
  */
 export interface VoiceChatCallbacks {
-  onStatus?: (phase: VoiceServerPhase, message: string) => void;
+  onStatus?: (phase: VoiceServerPhase, message: string) => void | Promise<void>;
   onAudioChunk?: (audioData: string, chunkIndex: number) => void;
   onTranscript?: (role: 'user' | 'assistant', content: string) => void;
   onToolCall?: (toolName: string, args: string) => void;

src/utils/audioUtils.ts

@@ -281,18 +281,40 @@ export class AudioRecorder {
 export class AudioPlayer {
   private isPlaying: boolean = false;
   private isSetup: boolean = false;
+  private isSettingUp: boolean = false;
+  private setupPromise: Promise<void> | null = null;
   private tempFiles: string[] = [];
   private chunkCounter: number = 0;
+  private pendingChunks: number = 0; // Incrementato SINCRONAMENTE prima dell'async
   private onCompleteCallback: (() => void) | null = null;
   private queueEndedListener: any = null;
   private allChunksReceived: boolean = false;
 
   /**
-   * Inizializza TrackPlayer se non ancora configurato
+   * Inizializza TrackPlayer se non ancora configurato.
+   * Usa un pattern singleton per evitare setup multipli concorrenti.
    */
   async setup(): Promise<void> {
     if (this.isSetup) return;
 
+    // Se è già in corso un setup, attendi quello
+    if (this.isSettingUp && this.setupPromise) {
+      await this.setupPromise;
+      return;
+    }
+
+    this.isSettingUp = true;
+    this.setupPromise = this._doSetup();
+
+    try {
+      await this.setupPromise;
+    } finally {
+      this.isSettingUp = false;
+      this.setupPromise = null;
+    }
+  }
+
+  private async _doSetup(): Promise<void> {
     try {
       await TrackPlayer.setupPlayer({
         autoHandleInterruptions: true,
@@ -311,17 +333,38 @@ export class AudioPlayer {
     }
   }
 
+  /**
+   * Pre-inizializza TrackPlayer anticipatamente (da chiamare all'avvio sessione).
+   * Evita il ritardo del primo addChunk().
+   */
+  async preSetup(): Promise<void> {
+    try {
+      await this.setup();
+    } catch (error) {
+      console.error('TrackPlayer: Errore pre-setup:', error);
+    }
+  }
+
   /**
    * Aggiunge un chunk PCM16 base64 direttamente alla queue di TrackPlayer.
    * Il chunk viene wrappato in WAV, scritto su file e aggiunto alla queue.
    * Se è il primo chunk, avvia la riproduzione immediatamente.
    */
   async addChunk(base64Data: string, chunkIndex?: number): Promise<boolean> {
+    // Incrementa il contatore SINCRONAMENTE prima di qualsiasi operazione async.
+    // Questo garantisce che getChunksCount() e hasPendingChunks() riflettano
+    // immediatamente la presenza di chunk in arrivo, evitando race conditions
+    // con agent_end/audio_end che controllano se c'è audio da riprodurre.
+    this.pendingChunks++;
+
     try {
       await this.setup();
 
       const binary = decodeBase64(base64Data);
-      if (binary.length === 0) return false;
+      if (binary.length === 0) {
+        this.pendingChunks--;
+        return false;
+      }
 
       // Wrappa in WAV
       const wavData = wrapPcm16InWav(binary, AUDIO_CONFIG.SAMPLE_RATE);
@@ -343,6 +386,7 @@ export class AudioPlayer {
       });
 
       this.chunkCounter++;
+      this.pendingChunks--;
 
       // Avvia la riproduzione al primo chunk
       if (!this.isPlaying) {
@@ -351,34 +395,88 @@ export class AudioPlayer {
         console.log('TrackPlayer: Riproduzione streaming avviata');
       }
 
+      // Se tutti i chunk sono stati segnalati (audio_end ricevuto) e non ci sono
+      // altri chunk in attesa, ora possiamo configurare il listener di completamento.
+      // Questo gestisce il caso in cui audio_end arriva mentre i chunk sono ancora
+      // in fase di scrittura su file.
+      if (this.allChunksReceived && this.pendingChunks === 0 && !this.queueEndedListener) {
+        console.log(`TrackPlayer: Ultimo chunk pending processato, configuro listener completamento (${this.chunkCounter} chunk totali)`);
+        this.setupQueueEndedListener();
+      }
+
       return true;
     } catch (error) {
+      this.pendingChunks--;
+
+      // Anche in caso di errore, se era l'ultimo pending e allChunksReceived,
+      // dobbiamo configurare il completamento
+      if (this.allChunksReceived && this.pendingChunks === 0 && !this.queueEndedListener) {
+        this.setupQueueEndedListener();
+      }
+
       console.error('TrackPlayer: Errore aggiunta chunk:', error);
       return false;
     }
   }
 
   /**
    * Segnala che tutti i chunk sono stati ricevuti (audio_end).
-   * Registra il listener per la fine della queue per invocare onComplete.
+   * Se ci sono chunk ancora in fase di processamento (pendingChunks > 0),
+   * il listener di completamento verrà configurato da addChunk() quando
+   * l'ultimo chunk pending viene processato.
    */
   async signalAllChunksReceived(onComplete?: () => void): Promise<void> {
     this.allChunksReceived = true;
     this.onCompleteCallback = onComplete || null;
 
-    // Se non sta riproducendo (nessun chunk ricevuto), completa subito
-    if (!this.isPlaying) {
+    // Se ci sono chunk ancora in fase di processamento async (scrittura file WAV),
+    // NON configurare il listener ora. addChunk() lo farà dopo aver processato
+    // l'ultimo chunk pending.
+    if (this.pendingChunks > 0) {
+      console.log(`TrackPlayer: ${this.pendingChunks} chunk ancora in elaborazione, listener differito`);
+      return;
+    }
+
+    // Nessun chunk pending. Se non sta nemmeno riproducendo (nessun chunk mai ricevuto),
+    // completa subito.
+    if (!this.isPlaying && this.chunkCounter === 0) {
+      console.log('TrackPlayer: Nessun chunk ricevuto, completamento immediato');
       this.handlePlaybackComplete();
       return;
     }
 
-    // Controlla se la riproduzione è già terminata
-    const state = await TrackPlayer.getPlaybackState();
-    if (state.state === State.Ended || state.state === State.Stopped) {
+    // Tutti i chunk sono stati aggiunti alla queue, configura il listener
+    this.setupQueueEndedListener();
+  }
+
+  /**
+   * Configura il listener per la fine della riproduzione della queue.
+   * Controlla prima se la riproduzione è già terminata.
+   */
+  private async setupQueueEndedListener(): Promise<void> {
+    // Safety: rimuovi listener precedente se presente
+    if (this.queueEndedListener) {
+      this.queueEndedListener.remove();
+      this.queueEndedListener = null;
+    }
+
+    // Se non sta riproducendo (tutti i chunk sono falliti?), completa subito
+    if (!this.isPlaying) {
       this.handlePlaybackComplete();
       return;
     }
 
+    // Controlla se la riproduzione è già terminata
+    try {
+      const state = await TrackPlayer.getPlaybackState();
+      if (state.state === State.Ended || state.state === State.Stopped) {
+        this.handlePlaybackComplete();
+        return;
+      }
+    } catch (error) {
+      console.error('TrackPlayer: Errore verifica stato:', error);
+    }
+
     // Registra listener per la fine della queue
     this.queueEndedListener = TrackPlayer.addEventListener(
       Event.PlaybackQueueEnded,
@@ -440,6 +538,7 @@ export class AudioPlayer {
   clearChunks(): void {
     this.allChunksReceived = false;
     this.chunkCounter = 0;
+    this.pendingChunks = 0;
   }
 
   async stopPlayback(): Promise<void> {
@@ -458,6 +557,7 @@ export class AudioPlayer {
     this.onCompleteCallback = null;
     this.allChunksReceived = false;
     this.chunkCounter = 0;
+    this.pendingChunks = 0;
     await this.cleanupTempFiles();
   }
 
@@ -469,6 +569,14 @@ export class AudioPlayer {
     return this.chunkCounter;
   }
 
+  /**
+   * Restituisce true se ci sono chunk in fase di processamento (non ancora aggiunti alla queue)
+   * o già aggiunti alla queue. Utile per evitare premature auto-unmute.
+   */
+  hasPendingOrQueuedChunks(): boolean {
+    return this.pendingChunks > 0 || this.chunkCounter > 0;
+  }
+
   async destroy(): Promise<void> {
     await this.stopPlayback();
   }