@chat21/chat21-web-widget 5.1.34 → 5.2.1

package/src/app/providers/global-settings.service.ts

@@ -6,7 +6,6 @@ import { BehaviorSubject, Observable } from 'rxjs';
 import { Globals } from '../utils/globals';
 import { convertColorToRGBA, detectIfIsMobile, getImageUrlThumb, getParameterByName, stringToBoolean, stringToNumber } from '../utils/utils';
 
-import { TemplateBindingParseResult } from '@angular/compiler';
 import { AppStorageService } from '../../chat21-core/providers/abstract/app-storage.service';
 import { LoggerService } from '../../chat21-core/providers/abstract/logger.service';
 import { LoggerInstance } from '../../chat21-core/providers/logger/loggerInstance';
@@ -573,6 +572,9 @@ export class GlobalSettingsService {
                     if (variables.hasOwnProperty('allowedUploadExtentions')) {
                         globals['fileUploadAccept'] = variables['allowedUploadExtentions'];
                     }
+                    if(variables.hasOwnProperty('showAudioStreamFooterButton')) {
+                        globals['showAudioStreamFooterButton'] = variables['showAudioStreamFooterButton'];
+                    }
                     
                 }
             }
@@ -702,7 +704,7 @@ export class GlobalSettingsService {
         }
         TEMP = tiledeskSettings['lang'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > lang:: ', TEMP);
-        if (TemplateBindingParseResult) {
+        if (TEMP !== undefined) {
             globals.lang = TEMP;
             // globals.setParameter('lang', TEMP);
         }
@@ -919,6 +921,14 @@ export class GlobalSettingsService {
         if (TEMP !== undefined) {
             globals.soundEnabled = TEMP;
         }
+        TEMP = tiledeskSettings['keyboardSoundVolume'];
+        if (TEMP !== undefined) {
+            globals.keyboardSoundVolume = +TEMP;
+        }
+        TEMP = tiledeskSettings['keyboardSoundFile'];
+        if (TEMP !== undefined) {
+            globals.keyboardSoundFile = TEMP;
+        }
         TEMP = tiledeskSettings['openExternalLinkButton'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > openExternalLinkButton:: ', TEMP]);
         if (TEMP !== undefined) {
@@ -1125,6 +1135,11 @@ export class GlobalSettingsService {
         if (TEMP !== undefined) {
             globals.showAudioRecorderFooterButton = (TEMP === true) ? true : false;
         }
+        TEMP = tiledeskSettings['showAudioStreamFooterButton'];
+        // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > showAudioStreamFooterButton:: ', TEMP]);
+        if (TEMP !== undefined) {
+            globals.showAudioStreamFooterButton = (TEMP === true) ? true : false;
+        }
         TEMP = tiledeskSettings['size'];
         // this.logger.debug('[GLOBAL-SET] setVariablesFromSettings > size:: ', TEMP]);
         if (TEMP !== undefined) {
@@ -1297,6 +1312,14 @@ export class GlobalSettingsService {
         if (TEMP !== null) {
             this.globals.soundEnabled = TEMP;
         }
+        TEMP = el.nativeElement.getAttribute('keyboardSoundVolume');
+        if (TEMP !== null) {
+            this.globals.keyboardSoundVolume = +TEMP;
+        }
+        TEMP = el.nativeElement.getAttribute('keyboardSoundFile');
+        if (TEMP !== null) {
+            this.globals.keyboardSoundFile = TEMP;
+        }
         TEMP = el.nativeElement.getAttribute('openExternalLinkButton');
         if (TEMP !== null) {
             this.globals.openExternalLinkButton = TEMP;
@@ -1696,6 +1719,16 @@ export class GlobalSettingsService {
             globals.soundEnabled = stringToBoolean(TEMP); 
         }
 
+        TEMP = getParameterByName(windowContext, 'tiledesk_keyboardSoundVolume');
+        if (TEMP) {
+            globals.keyboardSoundVolume = +TEMP;
+        }
+
+        TEMP = getParameterByName(windowContext, 'tiledesk_keyboardSoundFile');
+        if (TEMP) {
+            globals.keyboardSoundFile = TEMP;
+        }
+
         TEMP = getParameterByName(windowContext, 'tiledesk_openExternalLinkButton');
         if (TEMP) {
             globals.openExternalLinkButton = stringToBoolean(TEMP); 
@@ -1867,6 +1900,11 @@ export class GlobalSettingsService {
             globals.showAttachmentFooterButton = stringToBoolean(TEMP);
         }
 
+        TEMP = getParameterByName(windowContext, 'tiledesk_showAudioStreamFooterButton');
+        if (TEMP) {
+            globals.showAudioStreamFooterButton = stringToBoolean(TEMP);
+        }
+
         TEMP = getParameterByName(windowContext, 'tiledesk_showEmojiFooterButton');
         if (TEMP) {
             globals.showEmojiFooterButton = stringToBoolean(TEMP);

package/src/app/providers/json-sources-parser.service.ts

@@ -5,9 +5,17 @@ import { extractUrlsFromText } from 'src/app/utils/url-utils';
 import { JsonSourceItem } from 'src/app/component/message/json-sources/json-sources.component';
 import { mergeJsonSourcesMissingFields } from 'src/app/utils/json-sources-utils';
 
+export type UrlPreviewDisplayFields = {
+  title?: boolean;
+  description?: boolean;
+  image?: boolean;
+};
+
 export type UrlPreviewMessage = {
   type?: string; // "url_preview"
   text?: string;
+  displayFields?: UrlPreviewDisplayFields;
+  previewBackgroundColor?: string;
 };
 
 /**
@@ -79,7 +87,11 @@ export class JsonSourcesParserService {
     return this.enrichSources(base);
   }
 
-  private getUrlPreviewPayload(messageLike?: any): UrlPreviewMessage | null {
+  /**
+   * Public: lets callers (UI components) read the raw `url_preview` payload to
+   * extract presentation options like `displayFields` or `previewBackgroundColor`.
+   */
+  getUrlPreviewPayload(messageLike?: any): UrlPreviewMessage | null {
     if (!messageLike) return null;
     const candidates: any[] = [
       messageLike,

package/src/app/providers/translator.service.ts

@@ -234,12 +234,27 @@ export class TranslatorService {
     this._translate.use(lang);
     this.logger.debug(`[TRANSLATOR-SERV] »»»» initI18n - »»» loadRemoteTranslations ?`, environment.loadRemoteTranslations);
     this._translate.setTranslation(lang, data, true);
-    // if (environment.loadRemoteTranslations) {
-    //   // console.log(`»»»» initI18n - »»» remote translation `, data);
-    //   this._translate.setTranslation(lang, data, true);
-    // } else {
-    //   this._translate.setTranslation(lang, data, true);
-    // }
+    this.syncDocumentLang(lang);
+  }
+
+  /**
+   * Synchronize the document `<html lang="...">` attribute with the active i18n language
+   * (WCAG 3.1.1 Language of Page, EN 301 549 § 9.3.1.1).
+   *
+   * The widget runs inside its own iframe, so we update the document of that iframe.
+   * If the widget is also embedded in a parent page (Tiledesk launcher), the parent
+   * page already declares its own `lang`, which we intentionally leave untouched.
+   */
+  private syncDocumentLang(lang: string) {
+    if (!lang) { return; }
+    const normalized = lang.toLowerCase().substring(0, 2);
+    try {
+      if (typeof document !== 'undefined' && document.documentElement) {
+        document.documentElement.setAttribute('lang', normalized);
+      }
+    } catch (e) {
+      this.logger.warn('[TRANSLATOR-SERV] syncDocumentLang error', e);
+    }
   }
 
   /** */
@@ -302,7 +317,8 @@ export class TranslatorService {
       'CLOSED',
       'LABEL_PREVIEW',
       'MAX_ATTACHMENT',
-      'EMOJI'
+      'EMOJI',
+      'BUTTON_OPEN_CHAT'
     ];
 
 
@@ -359,6 +375,7 @@ export class TranslatorService {
       globals.LABEL_ERROR_FIELD_REQUIRED= res['LABEL_ERROR_FIELD_REQUIRED']
       globals.MAX_ATTACHMENT = res['MAX_ATTACHMENT']
       globals.EMOJI = res['EMOJI']
+      globals.BUTTON_OPEN_CHAT = res['BUTTON_OPEN_CHAT']
       
       
       if(globals.WELCOME_TITLE === 'WELLCOME_TITLE') globals.WELCOME_TITLE = res['WELCOME_TITLE']

package/src/app/providers/tts-audio-playback-coordinator.service.spec.ts

@@ -0,0 +1,116 @@
+import { TtsAudioPlaybackCoordinator } from './tts-audio-playback-coordinator.service';
+
+describe('TtsAudioPlaybackCoordinator', () => {
+  let coordinator: TtsAudioPlaybackCoordinator;
+
+  beforeEach(() => {
+    coordinator = new TtsAudioPlaybackCoordinator();
+  });
+
+  // ── Basic lifecycle ───────────────────────────────────────────────────────
+
+  it('should start playing immediately when nothing is active', () => {
+    const start = jasmine.createSpy('start');
+    coordinator.requestStart('msg-1', start);
+    expect(start).toHaveBeenCalledTimes(1);
+  });
+
+  it('isTTSPlaying$ should be true while playing and false after release', () => {
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.releaseIfCurrent('msg-1');
+
+    expect(states).toEqual([false, true, false]);
+  });
+
+  it('stopAll clears the queue, sets playing=false, and emits stopAllPlayback$', () => {
+    const stopAllFired: void[] = [];
+    coordinator.stopAllPlayback$.subscribe(() => stopAllFired.push(undefined));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.stopAll();
+
+    let playing = true;
+    coordinator.isTTSPlaying$.subscribe((v) => (playing = v));
+    expect(playing).toBe(false);
+    expect(stopAllFired.length).toBe(1);
+  });
+
+  // ── Preemption tests (SPEC-002) ───────────────────────────────────────────
+
+  it('requestStart while playing preempts old owner: new start() is called immediately', () => {
+    const start1 = jasmine.createSpy('start1');
+    const start2 = jasmine.createSpy('start2');
+
+    coordinator.requestStart('msg-1', start1);
+    coordinator.requestStart('msg-2', start2);
+
+    expect(start1).toHaveBeenCalledTimes(1);
+    expect(start2).toHaveBeenCalledTimes(1); // started immediately, not queued
+  });
+
+  it('preemptPlayback$ emits evicted ownerId only (not the new owner)', () => {
+    const preempted: string[] = [];
+    coordinator.preemptPlayback$.subscribe((id) => preempted.push(id));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {}); // preempts msg-1
+
+    expect(preempted).toEqual(['msg-1']);
+  });
+
+  it('preemptPlayback$ does NOT emit the new owner id', () => {
+    const preempted: string[] = [];
+    coordinator.preemptPlayback$.subscribe((id) => preempted.push(id));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {});
+
+    expect(preempted).not.toContain('msg-2');
+  });
+
+  it('isTTSPlaying$ stays true after preemption until new owner releases', () => {
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+
+    coordinator.requestStart('msg-1', () => {});   // true
+    coordinator.requestStart('msg-2', () => {});   // still true (preemption, new owner active)
+    coordinator.releaseIfCurrent('msg-2');          // false
+
+    expect(states).toEqual([false, true, false]);
+  });
+
+  it('releaseIfCurrent for an evicted owner is a no-op', () => {
+    const states: boolean[] = [];
+    coordinator.isTTSPlaying$.subscribe((v) => states.push(v));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {}); // msg-1 evicted
+
+    // Old owner calls release after being preempted — should not affect playing state
+    coordinator.releaseIfCurrent('msg-1');
+
+    expect(states).toEqual([false, true]); // no extra false emission
+  });
+
+  it('chain of preemptions: each new requestStart immediately evicts the current owner', () => {
+    const preempted: string[] = [];
+    coordinator.preemptPlayback$.subscribe((id) => preempted.push(id));
+
+    coordinator.requestStart('msg-1', () => {});
+    coordinator.requestStart('msg-2', () => {});
+    coordinator.requestStart('msg-3', () => {});
+
+    expect(preempted).toEqual(['msg-1', 'msg-2']);
+  });
+
+  it('requestStart is idempotent for the current owner', () => {
+    const start = jasmine.createSpy('start');
+    coordinator.requestStart('msg-1', start);
+    coordinator.requestStart('msg-1', start); // same owner — should be ignored
+
+    expect(start).toHaveBeenCalledTimes(1);
+  });
+});

package/src/app/providers/tts-audio-playback-coordinator.service.ts

@@ -0,0 +1,122 @@
+import { Injectable } from '@angular/core';
+import { BehaviorSubject, Observable, Subject } from 'rxjs';
+
+/**
+ * Garantisce un solo messaggio TTS in riproduzione alla volta.
+ * Quando arriva un nuovo messaggio TTS mentre un altro è in corso, quello vecchio viene
+ * interrotto immediatamente (preemption) e il nuovo parte subito.
+ */
+@Injectable({ providedIn: 'root' })
+export class TtsAudioPlaybackCoordinator {
+  private currentOwnerId: string | null = null;
+  private readonly queue: Array<{ ownerId: string; start: () => void }> = [];
+
+  private readonly cancelAllSource = new Subject<void>();
+  /** Emesso quando la riproduzione TTS va interrotta globalmente (es. l’utente parla al microfono). */
+  readonly cancelAll$: Observable<void> = this.cancelAllSource.asObservable();
+
+  /** Emits true while any TTS is playing or queued; false when the queue is fully drained. */
+  private readonly _isTTSPlaying$ = new BehaviorSubject<boolean>(false);
+  readonly isTTSPlaying$ = this._isTTSPlaying$.asObservable();
+
+  /** Emits once when stopAll() is called — signals every AudioSyncComponent to abort immediately. */
+  private readonly _stopAll$ = new Subject<void>();
+  readonly stopAllPlayback$: Observable<void> = this._stopAll$.asObservable();
+
+  /**
+   * Emits the ownerId of the component being preempted (stopped mid-playback by a newer message).
+   * Only the component whose ownerId matches should react — unlike stopAll$ which targets everyone.
+   */
+  private readonly _preemptCurrent$ = new Subject<string>();
+  readonly preemptPlayback$: Observable<string> = this._preemptCurrent$.asObservable();
+
+  /**
+   * Richiede l'avvio della riproduzione TTS per `ownerId`.
+   * Se un altro TTS è già in corso, viene interrotto immediatamente (preemption) e
+   * `ownerId` parte subito. Qualsiasi coda pendente viene svuotata.
+   */
+  requestStart(ownerId: string, start: () => void): void {
+    const id = (ownerId || '').trim();
+    if (!id) {
+      return;
+    }
+    if (this.currentOwnerId === id) {
+      return;
+    }
+
+    if (this.currentOwnerId) {
+      // Preempt: signal only the evicted owner to stop (not a broadcast stopAll).
+      // This avoids stopping the component that is about to start playing.
+      const evicted = this.currentOwnerId;
+      this.queue.length = 0;
+      this.currentOwnerId = null;
+      this._preemptCurrent$.next(evicted);
+    } else {
+      this.queue.length = 0;
+    }
+
+    this.currentOwnerId = id;
+    if (!this._isTTSPlaying$.getValue()) {
+      this._isTTSPlaying$.next(true);
+    }
+    try {
+      start();
+    } catch {
+      this.releaseIfCurrent(id);
+    }
+  }
+
+  /** Chiamare a fine riproduzione naturale (`ended`) se questo messaggio era ancora “attivo”. */
+  releaseIfCurrent(ownerId: string): void {
+    const id = (ownerId || '').trim();
+    if (!id) {
+      return;
+    }
+    if (this.currentOwnerId !== id) {
+      // Se era in coda, rimuovilo.
+      const idx = this.queue.findIndex((j) => j.ownerId === id);
+      if (idx !== -1) {
+        this.queue.splice(idx, 1);
+      }
+      return;
+    }
+
+    this.currentOwnerId = null;
+    const next = this.queue.shift();
+    if (!next) {
+      this._isTTSPlaying$.next(false);
+      return;
+    }
+    this.currentOwnerId = next.ownerId;
+    try {
+      next.start();
+    } catch {
+      this.releaseIfCurrent(next.ownerId);
+    }
+  }
+
+  /** Distruzione componente o stop esplicito. */
+  release(ownerId: string): void {
+    this.releaseIfCurrent(ownerId);
+  }
+
+  /**
+   * Interrompe TUTTA la riproduzione TTS (corrente + coda) e notifica i componenti.
+   * I componenti devono fermare l’audio e mostrare il testo per intero.
+   */
+  cancelAll(): void {
+    this.stopAll();
+    this.cancelAllSource.next();
+  }
+
+  /**
+   * Stops all TTS playback immediately and clears the queue.
+   * Broadcasts on stopAllPlayback$ so every AudioSyncComponent can abort its stream and reveal all text.
+   */
+  stopAll(): void {
+    this.queue.length = 0;
+    this.currentOwnerId = null;
+    this._isTTSPlaying$.next(false);
+    this._stopAll$.next();
+  }
+}

package/src/app/providers/voice/STT&TTS/openai-voice.config.ts

@@ -0,0 +1,12 @@
+/**
+ * Configurazione opzionale per i servizi voce OpenAI (da `environment` o runtime).
+ */
+export interface OpenAiVoiceEnvironmentConfig {
+  /** Obbligatoria per chiamate API reali; se assente, STT/TTS non inviano richieste. */
+  apiKey?: string;
+  baseUrl?: string;
+  transcriptionModel?: string;
+  ttsModel?: string;
+  /** Voce predefinita TTS (es. `alloy`). */
+  ttsVoice?: string;
+}

package/src/app/providers/voice/STT&TTS/openai-voice.provider.ts

@@ -0,0 +1,156 @@
+import { HttpClient, HttpErrorResponse, HttpHeaders } from '@angular/common/http';
+import { Injectable } from '@angular/core';
+import { firstValueFrom } from 'rxjs';
+
+import {
+  SpeechToTextProvider,
+  TextToSpeechProvider,
+  type SpeechToTextRequest,
+  type SpeechToTextResult,
+  type TextToSpeechRequest,
+  type TextToSpeechResult,
+} from './speech-provider.abstract';
+import { AppConfigService } from '../../app-config.service';
+
+/**
+ * Routes STT and TTS calls through the tiledesk-speech-proxy.
+ *
+ * STT: POST <proxyBase>/api/stt  — multipart/form-data, field "audio"
+ * TTS: POST <proxyBase>/api/tts  — JSON body { text, ... }
+ */
+@Injectable({ providedIn: 'root' })
+export class OpenAiVoiceProviderService extends SpeechToTextProvider implements TextToSpeechProvider {
+  constructor(
+    private readonly httpClient: HttpClient,
+    private readonly appConfig: AppConfigService,
+  ) {
+    super();
+  }
+
+  async transcribe(request: SpeechToTextRequest): Promise<SpeechToTextResult> {
+    const proxyBase = this.proxyBase();
+    if (!proxyBase) {
+      return { text: '' };
+    }
+
+    const url = `${proxyBase}/api/stt`;
+    const ext = this.extensionForMime(request.mimeType);
+    const file = new File([request.audio], `segment.${ext}`, { type: request.mimeType });
+
+    const form = new FormData();
+    form.append('audio', file);
+    if (request.language) {
+      form.append('language', request.language);
+    }
+    const projectId = String(this.appConfig.g?.projectid ?? '').trim();
+    if (projectId) form.append('projectId', projectId);
+    const requestId = this.parseRequestId(this.appConfig.g?.recipientId ?? '');
+    if (requestId) {
+      form.append('requestId', requestId);
+    }
+
+    const headers = new HttpHeaders({ Authorization: this.authHeader() });
+
+    try {
+      const data = await firstValueFrom(
+        this.httpClient.post<{ transcript?: string }>(url, form, { headers }),
+      );
+      return { text: (data.transcript ?? '').trim() };
+    } catch (e) {
+      if (e instanceof HttpErrorResponse && e.error instanceof Blob) {
+        const errText = await e.error.text();
+        throw new Error(`Speech proxy STT ${e.status}: ${errText || e.statusText}`);
+      }
+      throw this.mapHttpError('Speech proxy STT', e);
+    }
+  }
+
+  async synthesize(request: TextToSpeechRequest): Promise<TextToSpeechResult> {
+    const proxyBase = this.proxyBase();
+    if (!proxyBase) {
+      throw new Error('voiceProxyApiBaseUrl not configured');
+    }
+
+    const url = `${proxyBase}/api/tts`;
+    const body: Record<string, unknown> = { text: request.text };
+    if (request.language) body['language'] = request.language;
+    if (request.voice) body['voiceId'] = request.voice;
+    if (request.responseFormat) body['outputFormat'] = request.responseFormat;
+    const projectId = String(this.appConfig.g?.projectid ?? '').trim();
+    if (projectId) body['projectId'] = projectId;
+    const requestId = this.parseRequestId(this.appConfig.g?.recipientId ?? '');
+    if (requestId) body['requestId'] = requestId;
+
+    const headers = new HttpHeaders({
+      Authorization: this.authHeader(),
+      'Content-Type': 'application/json',
+    });
+
+    try {
+      const blob = await firstValueFrom(
+        this.httpClient.post(url, body, { headers, responseType: 'blob' }),
+      );
+      return { audio: blob, mimeType: this.mimeForFormat(request.responseFormat ?? 'mp3') };
+    } catch (e) {
+      if (e instanceof HttpErrorResponse && e.error instanceof Blob) {
+        const errText = await e.error.text();
+        throw new Error(`Speech proxy TTS ${e.status}: ${errText || e.statusText}`);
+      }
+      throw this.mapHttpError('Speech proxy TTS', e);
+    }
+  }
+
+  private proxyBase(): string | null {
+    const base = String(this.appConfig.getConfig()?.voiceProxyApiBaseUrl ?? '').trim();
+    return base ? base.replace(/\/$/, '') : null;
+  }
+
+  /** Returns `JWT <rawToken>`, stripping any existing prefix first. */
+  private authHeader(): string {
+    const raw = (
+      String(this.appConfig.g?.tiledeskToken ?? this.appConfig.g?.jwt ?? '').trim()
+    ).replace(/^(JWT|Bearer)\s+/i, '').trim();
+    return raw ? `JWT ${raw}` : '';
+  }
+
+  /**
+   * Extracts the Tiledesk requestId from a Chat21 recipient string.
+   * Format: `support-group-<projectId>-<requestId>`
+   */
+  private parseRequestId(recipient: string): string | null {
+    const parts = recipient.split('-');
+    if (parts.length < 4) return null;
+    return parts.slice(3).join('-') || null;
+  }
+
+  private mapHttpError(label: string, e: unknown): Error {
+    if (!(e instanceof HttpErrorResponse)) {
+      return e instanceof Error ? e : new Error(String(e));
+    }
+    if (typeof e.error === 'object' && e.error !== null && 'error' in e.error) {
+      const err = (e.error as { error?: { message?: string } }).error;
+      return new Error(`${label} ${e.status}: ${err?.message ?? JSON.stringify(e.error)}`);
+    }
+    if (typeof e.error === 'string') {
+      return new Error(`${label} ${e.status}: ${e.error}`);
+    }
+    return new Error(`${label} ${e.status}: ${e.message || e.statusText}`);
+  }
+
+  private extensionForMime(mime: string): string {
+    if (mime.includes('webm')) return 'webm';
+    if (mime.includes('mp4') || mime.includes('m4a')) return 'm4a';
+    if (mime.includes('wav')) return 'wav';
+    if (mime.includes('mpeg') || mime.includes('mp3')) return 'mp3';
+    return 'webm';
+  }
+
+  private mimeForFormat(fmt: string): string {
+    switch (fmt) {
+      case 'opus': return 'audio/opus';
+      case 'aac':  return 'audio/aac';
+      case 'flac': return 'audio/flac';
+      default:     return 'audio/mpeg';
+    }
+  }
+}

package/src/app/providers/voice/STT&TTS/speech-provider.abstract.ts

@@ -0,0 +1,39 @@
+/**
+ * Contratti astratti per Speech-to-Text e Text-to-Speech.
+ * Implementazione OpenAI unificata: `OpenAiVoiceProviderService` (`openai-voice.provider.ts`).
+ */
+
+/** Input per la trascrizione di un segmento audio. */
+export interface SpeechToTextRequest {
+  audio: Blob;
+  mimeType: string;
+  /** ISO 639-1 opzionale (es. `it`, `en`). */
+  language?: string;
+}
+
+export interface SpeechToTextResult {
+  text: string;
+}
+
+/** Input per la sintesi vocale. */
+export interface TextToSpeechRequest {
+  text: string;
+  /** Voce provider-specific (es. OpenAI: `alloy`, `echo`, …). */
+  voice?: string;
+  language?: string;
+  /** Formato audio desiderato (dipende dal provider). */
+  responseFormat?: string;
+}
+
+export interface TextToSpeechResult {
+  audio: Blob;
+  mimeType: string;
+}
+
+export abstract class SpeechToTextProvider {
+  abstract transcribe(request: SpeechToTextRequest): Promise<SpeechToTextResult>;
+}
+
+export abstract class TextToSpeechProvider {
+  abstract synthesize(request: TextToSpeechRequest): Promise<TextToSpeechResult>;
+}

package/src/app/providers/voice/audio.types.ts

@@ -0,0 +1,40 @@
+/**
+ * Tipi condivisi per cattura microfono, VAD e registrazione (WebM).
+ */
+import type { VoiceStreamingSessionConfig } from './voice-streaming.types';
+
+export const DEFAULT_VOICE_AUDIO_CONSTRAINTS: MediaTrackConstraints = {
+  echoCancellation: true,
+  noiseSuppression: true,
+  autoGainControl: true,
+};
+
+export const DEFAULT_VOICE_MEDIA_STREAM_CONSTRAINTS: MediaStreamConstraints = {
+  audio: DEFAULT_VOICE_AUDIO_CONSTRAINTS,
+};
+
+export interface VoiceRecordedBlob {
+  blob: Blob;
+  mimeType: string;
+}
+
+/**
+ * Segmento audio dopo VAD; può includere `transcript` se STT è configurato e abilitato.
+ */
+export interface VoiceSegmentPayload extends VoiceRecordedBlob {
+  transcript?: string;
+  transcriptionError?: string;
+}
+
+export interface VoiceSessionStartOptions {
+  /** Opzionale se usi solo {@link VoiceService.audioSegment$}. */
+  onRecordingComplete?: (result: VoiceSegmentPayload) => void;
+  constraints?: MediaStreamConstraints;
+  /** Default `true`. Se `false`, non viene chiamato lo STT sul segmento. */
+  enableTranscription?: boolean;
+  /**
+   * Con `voiceIngressStream`: solo streaming WSS — niente VAD locale; transcript e TTS dal server.
+   * Senza: MicVAD + segmenti e upload/STT lato client.
+   */
+  voiceIngressStream?: VoiceStreamingSessionConfig | null;
+}