@mooncompany/uplink-chat 0.5.0

package/public/js/realtime-voice.js

@@ -0,0 +1,844 @@
+// ============================================
+// REALTIME VOICE MODULE
+// OpenAI Realtime API WebSocket client
+// Supports two modes:
+//   - standalone: Direct OpenAI voice (existing)
+//   - agent: OpenAI transcription + OpenClaw agent + TTS
+// ============================================
+
+import { UplinkLogger } from './logger.js';
+
+// State
+let ws = null;
+let isActive = false;
+let sessionReady = false; // True after session.created/session.updated from OpenAI
+let currentMode = 'standalone'; // 'standalone' or 'agent'
+let micStream = null;
+let audioContext = null;
+let audioWorkletNode = null;
+let playbackContext = null;
+let playbackQueue = [];
+let isPlayingAudio = false;
+let nextPlaybackTime = 0;
+let sessionStartTime = null;
+let timerInterval = null;
+let agentName = null; // Loaded from config in agent mode
+let currentUserTranscript = ''; // Buffer for user speech in agent mode
+let currentAgentResponse = ''; // Buffer for agent response in agent mode
+let isMicMuted = false; // Muted during TTS playback to prevent echo
+let streamingMessageDiv = null; // Active streaming chat bubble for agent responses
+
+// Constants - WebSocket
+const WS_CLOSE_NORMAL = 1000;
+const WS_RECONNECT_DELAY_MS = 1000;
+
+// Constants - Audio
+const SAMPLE_RATE = 24000;
+const BUFFER_SIZE = 4096;
+const PLAYBACK_BUFFER_DURATION = 0.1; // 100ms of buffering
+
+// Constants - UI
+const TIMER_UPDATE_INTERVAL_MS = 1000;
+
+// ============================================
+// MAIN API
+// ============================================
+
+/**
+ * Start a real-time voice session
+ * @param {string} mode - 'standalone' or 'agent' (default: 'standalone')
+ * @returns {Promise<boolean>} Success status
+ */
+export async function start(mode = 'standalone') {
+  if (isActive) {
+    UplinkLogger.warn('Realtime: Session already active');
+    return false;
+  }
+
+  if (mode !== 'standalone' && mode !== 'agent') {
+    UplinkLogger.error(`Realtime: Invalid mode "${mode}"`);
+    return false;
+  }
+
+  currentMode = mode;
+
+  try {
+    // Premium check
+    if (window.UplinkPremium && !window.UplinkPremium.isActive()) {
+      window.UplinkPremium.showUpgradeModal('Real-time voice chat');
+      return false;
+    }
+
+    UplinkLogger.debug(`Realtime: Starting session in ${mode} mode`);
+
+    // Load agent config if in agent mode
+    if (mode === 'agent') {
+      await loadAgentConfig();
+    }
+
+    // Request mic access
+    if (!await initMicrophone()) {
+      UplinkLogger.error('Realtime: Failed to access microphone');
+      showError('Microphone access denied');
+      return false;
+    }
+
+    // Initialize audio playback
+    if (!initPlaybackContext()) {
+      UplinkLogger.error('Realtime: Failed to initialize audio playback');
+      showError('Audio playback initialization failed');
+      cleanup();
+      return false;
+    }
+
+    // Open WebSocket
+    if (!await connectWebSocket()) {
+      UplinkLogger.error('Realtime: Failed to connect WebSocket');
+      showError('Connection failed');
+      cleanup();
+      return false;
+    }
+
+    isActive = true;
+    sessionStartTime = Date.now();
+    updateUI();
+    startTimer();
+    
+    // Add glow class to voice button
+    const voiceBtn = document.getElementById('voiceBtn');
+    if (voiceBtn) voiceBtn.classList.add('realtime-active');
+
+    UplinkLogger.debug('Realtime: Session started successfully');
+    return true;
+  } catch (err) {
+    UplinkLogger.error('Realtime: Start failed:', err);
+    if (window.UplinkDeveloper) {
+      window.UplinkDeveloper.logError(err, 'Realtime.start');
+    }
+    cleanup();
+    return false;
+  }
+}
+
+/**
+ * Stop the real-time voice session
+ * Closes WebSocket, stops mic, cleans up audio contexts
+ */
+export function stop() {
+  if (!isActive) {
+    UplinkLogger.warn('Realtime: No active session to stop');
+    return;
+  }
+
+  UplinkLogger.debug('Realtime: Stopping session');
+  isActive = false;
+  cleanup();
+  updateUI();
+  UplinkLogger.debug('Realtime: Session stopped');
+}
+
+/**
+ * Check if a session is currently active
+ * @returns {boolean}
+ */
+export function isSessionActive() {
+  return isActive;
+}
+
+/**
+ * Get the current mode
+ * @returns {string} 'standalone' or 'agent'
+ */
+export function getMode() {
+  return currentMode;
+}
+
+// ============================================
+// AGENT CONFIG
+// ============================================
+
+async function loadAgentConfig() {
+  try {
+    const response = await fetch('/api/config');
+    if (!response.ok) {
+      UplinkLogger.warn('Realtime: Failed to load agent config, using default name');
+      agentName = 'Agent';
+      return;
+    }
+    const config = await response.json();
+    agentName = config.assistantName || 'Agent';
+    UplinkLogger.debug(`Realtime: Agent name loaded: ${agentName}`);
+  } catch (err) {
+    UplinkLogger.error('Realtime: Config load error:', err);
+    agentName = 'Agent';
+  }
+}
+
+// ============================================
+// MICROPHONE CAPTURE
+// ============================================
+
+async function initMicrophone() {
+  try {
+    micStream = await navigator.mediaDevices.getUserMedia({ 
+      audio: {
+        echoCancellation: true,
+        noiseSuppression: true,
+        autoGainControl: true,
+        sampleRate: SAMPLE_RATE
+      } 
+    });
+
+    audioContext = new (window.AudioContext || window.webkitAudioContext)({
+      sampleRate: SAMPLE_RATE
+    });
+
+    const source = audioContext.createMediaStreamSource(micStream);
+
+    // Use ScriptProcessorNode for compatibility (AudioWorklet is better but requires separate file)
+    const processor = audioContext.createScriptProcessor(BUFFER_SIZE, 1, 1);
+    
+    processor.onaudioprocess = (e) => {
+      if (!isActive || !sessionReady || !ws || ws.readyState !== WebSocket.OPEN) return;
+      
+      const inputData = e.inputBuffer.getChannelData(0);
+      
+      // Convert Float32 to Int16 PCM
+      const pcm16 = new Int16Array(inputData.length);
+      for (let i = 0; i < inputData.length; i++) {
+        const s = Math.max(-1, Math.min(1, inputData[i]));
+        pcm16[i] = s < 0 ? s * 0x8000 : s * 0x7FFF;
+      }
+
+      // Encode to base64
+      const base64 = arrayBufferToBase64(pcm16.buffer);
+
+      // Send to server
+      try {
+        ws.send(JSON.stringify({
+          type: 'input_audio_buffer.append',
+          audio: base64
+        }));
+      } catch (err) {
+        UplinkLogger.error('Realtime: Failed to send audio:', err);
+      }
+    };
+
+    source.connect(processor);
+    processor.connect(audioContext.destination);
+    audioWorkletNode = processor; // Store for cleanup
+
+    UplinkLogger.debug('Realtime: Microphone initialized');
+    return true;
+  } catch (err) {
+    UplinkLogger.error('Realtime: Microphone init failed:', err);
+    return false;
+  }
+}
+
+// ============================================
+// AUDIO PLAYBACK
+// ============================================
+
+function initPlaybackContext() {
+  try {
+    playbackContext = new (window.AudioContext || window.webkitAudioContext)({
+      sampleRate: SAMPLE_RATE
+    });
+    
+    playbackQueue = [];
+    isPlayingAudio = false;
+    nextPlaybackTime = playbackContext.currentTime + PLAYBACK_BUFFER_DURATION;
+
+    UplinkLogger.debug('Realtime: Playback context initialized');
+    return true;
+  } catch (err) {
+    UplinkLogger.error('Realtime: Playback init failed:', err);
+    return false;
+  }
+}
+
+function playAudioChunk(base64Audio) {
+  if (!playbackContext || !isActive) return;
+
+  try {
+    // Decode base64 to PCM16
+    const pcmData = base64ToArrayBuffer(base64Audio);
+    const pcm16 = new Int16Array(pcmData);
+
+    // Convert Int16 PCM to Float32 for Web Audio API
+    const float32 = new Float32Array(pcm16.length);
+    for (let i = 0; i < pcm16.length; i++) {
+      float32[i] = pcm16[i] / (pcm16[i] < 0 ? 0x8000 : 0x7FFF);
+    }
+
+    // Create audio buffer
+    const audioBuffer = playbackContext.createBuffer(1, float32.length, SAMPLE_RATE);
+    audioBuffer.getChannelData(0).set(float32);
+
+    // Create buffer source
+    const source = playbackContext.createBufferSource();
+    source.buffer = audioBuffer;
+    source.connect(playbackContext.destination);
+
+    // Schedule playback with proper timing to avoid gaps
+    const now = playbackContext.currentTime;
+    const startTime = Math.max(now, nextPlaybackTime);
+    source.start(startTime);
+    
+    // Update next playback time to queue seamlessly
+    nextPlaybackTime = startTime + audioBuffer.duration;
+
+    isPlayingAudio = true;
+
+    source.onended = () => {
+      // Check if we're at the end of the queue
+      if (nextPlaybackTime <= playbackContext.currentTime + PLAYBACK_BUFFER_DURATION) {
+        isPlayingAudio = false;
+      }
+    };
+
+  } catch (err) {
+    UplinkLogger.error('Realtime: Audio playback failed:', err);
+  }
+}
+
+// ============================================
+// WEBSOCKET
+// ============================================
+
+function connectWebSocket() {
+  return new Promise((resolve, reject) => {
+    try {
+      // Determine WebSocket protocol based on page protocol
+      const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+      
+      // Add mode query parameter for agent mode
+      const modeParam = currentMode === 'agent' ? '?mode=agent' : '';
+      const wsUrl = `${protocol}//${location.host}/api/realtime${modeParam}`;
+
+      UplinkLogger.debug(`Realtime: Connecting to ${wsUrl}`);
+      ws = new WebSocket(wsUrl);
+
+      ws.onopen = () => {
+        UplinkLogger.debug('Realtime: WebSocket connected');
+        resolve(true);
+      };
+
+      ws.onmessage = (event) => {
+        handleWebSocketMessage(event.data);
+      };
+
+      ws.onerror = (error) => {
+        UplinkLogger.error('Realtime: WebSocket error:', error);
+        if (window.UplinkDeveloper) {
+          window.UplinkDeveloper.logError(new Error('WebSocket error'), 'Realtime WebSocket');
+        }
+      };
+
+      ws.onclose = (event) => {
+        UplinkLogger.debug(`Realtime: WebSocket closed (code: ${event.code})`);
+        if (isActive && event.code !== WS_CLOSE_NORMAL) {
+          showError('Connection lost');
+          stop();
+        }
+      };
+
+      // Timeout after 10 seconds
+      setTimeout(() => {
+        if (ws.readyState !== WebSocket.OPEN) {
+          ws.close();
+          reject(new Error('Connection timeout'));
+        }
+      }, 10000);
+
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+function handleWebSocketMessage(data) {
+  try {
+    const msg = JSON.parse(data);
+
+    // Handle bridge events (agent mode)
+    if (msg.type && msg.type.startsWith('bridge.')) {
+      handleBridgeEvent(msg);
+      return;
+    }
+
+    // Handle OpenAI Realtime events
+    switch (msg.type) {
+      case 'session.created':
+      case 'session.updated':
+        sessionReady = true;
+        UplinkLogger.debug('Realtime: Session ready, mic audio enabled');
+        break;
+
+      case 'response.audio.delta':
+        // Only play OpenAI audio in standalone mode
+        if (currentMode === 'standalone' && msg.delta) {
+          playAudioChunk(msg.delta);
+        } else if (currentMode === 'agent' && msg.delta) {
+          UplinkLogger.warn('Realtime: Ignoring OpenAI audio in agent mode');
+        }
+        break;
+
+      case 'response.audio.done':
+        UplinkLogger.debug('Realtime: Audio response complete');
+        if (currentMode === 'standalone') {
+          updateTranscript('', true); // Clear interim transcript
+        }
+        break;
+
+      case 'response.audio_transcript.delta':
+        // Update live transcript (standalone mode only)
+        if (currentMode === 'standalone' && msg.delta) {
+          updateTranscript(msg.delta, false);
+        }
+        break;
+
+      case 'response.audio_transcript.done':
+        // Finalize transcript (standalone mode only)
+        if (currentMode === 'standalone' && msg.transcript) {
+          updateTranscript(msg.transcript, true);
+        }
+        break;
+
+      case 'response.done':
+        UplinkLogger.debug('Realtime: Response complete');
+        break;
+
+      case 'error':
+        UplinkLogger.error('Realtime: Server error:', msg.error);
+        showError(msg.error?.message || 'Server error');
+        break;
+
+      default:
+        UplinkLogger.debug('Realtime: Unhandled message type:', msg.type);
+    }
+  } catch (err) {
+    UplinkLogger.error('Realtime: Failed to parse message:', err);
+  }
+}
+
+// ============================================
+// BRIDGE EVENT HANDLERS (AGENT MODE)
+// ============================================
+
+function handleBridgeEvent(msg) {
+  switch (msg.type) {
+    case 'bridge.transcript':
+      // User's transcribed speech
+      if (msg.text) {
+        currentUserTranscript = msg.text;
+        // Don't show in transcript bar — it's already posted to chat
+        
+        // Save to chat history if available
+        if (window.UplinkChat?.addMessage) {
+          window.UplinkChat.addMessage(msg.text, 'user');
+        }
+        
+        // Mute mic immediately — prevents echo from TTS playback
+        // and stops ghost transcripts from ambient noise during processing
+        muteMic();
+        
+        // Show waiting status while agent processes
+        updateVoiceStatus('waiting');
+      }
+      break;
+
+    case 'bridge.response.delta':
+      // Stream agent response into chat bubble
+      // Server sends as msg.text, not msg.delta
+      if (msg.text || msg.delta) {
+        currentAgentResponse += (msg.text || msg.delta);
+        
+        // Create streaming bubble on first delta
+        if (!streamingMessageDiv && window.UplinkChat?.createStreamingMessage) {
+          streamingMessageDiv = window.UplinkChat.createStreamingMessage();
+        }
+        
+        // Update streaming content
+        if (streamingMessageDiv && window.UplinkChat?.updateStreamingMessage) {
+          window.UplinkChat.updateStreamingMessage(streamingMessageDiv, currentAgentResponse);
+        }
+      }
+      break;
+
+    case 'bridge.response.done':
+      // Agent response complete — finalize the streaming bubble
+      {
+        const fullResponse = msg.text || currentAgentResponse;
+        
+        // Finalize streaming message with full formatted content
+        if (streamingMessageDiv && window.UplinkChat?.finalizeSyncStream) {
+          window.UplinkChat.finalizeSyncStream(streamingMessageDiv, fullResponse);
+          streamingMessageDiv = null;
+        } else if (fullResponse && window.UplinkChat?.addMessage) {
+          // Fallback if no streaming bubble was created
+          window.UplinkChat.addMessage(fullResponse, 'assistant');
+        }
+        
+        // Unmute mic after delay to let last audio chunk finish playing
+        // through speakers (prevents catching tail end of TTS)
+        // Only switch to "listening" once mic is actually back on
+        setTimeout(() => {
+          unmuteMic();
+          updateVoiceStatus('listening');
+        }, 1500);
+        
+        // Reset buffers
+        setTimeout(() => {
+          currentUserTranscript = '';
+          currentAgentResponse = '';
+        }, 1000);
+      }
+      break;
+
+    case 'bridge.audio':
+      // TTS audio chunk from agent response
+      if (msg.audio) {
+        // Mute mic to prevent speaker→mic echo feedback
+        muteMic();
+        // Agent is speaking — show replying status (mic still muted)
+        updateVoiceStatus('replying');
+        playAudioChunk(msg.audio);
+      }
+      break;
+
+    case 'bridge.status':
+      // Status updates (e.g., thinking indicator)
+      if (msg.status === 'thinking') {
+        showThinkingIndicator();
+        // Optional: play subtle audio cue
+        // playThinkingCue();
+      } else if (msg.status === 'speaking') {
+        hideThinkingIndicator();
+      }
+      break;
+
+    default:
+      UplinkLogger.debug('Realtime: Unhandled bridge event:', msg.type);
+  }
+}
+
+// ============================================
+// UI UPDATES
+// ============================================
+
+function updateUI() {
+  const indicator = document.getElementById('realtimeIndicator');
+  const timer = document.getElementById('realtimeTimer');
+  const transcript = document.getElementById('realtimeTranscript');
+  const badge = document.getElementById('realtimeBadge');
+
+  if (isActive) {
+    if (currentMode === 'agent') {
+      // Agent mode: voice.js handles status label ("Listening — Steven"),
+      // so hide the redundant realtime indicator overlay
+      if (indicator) {
+        indicator.style.display = 'none';
+        indicator.classList.remove('active', 'agent-mode');
+      }
+      if (timer) timer.style.display = 'none';
+      if (transcript) transcript.style.display = 'none';
+      if (badge) badge.style.display = 'none';
+    } else {
+      // Standalone mode: show the realtime indicator overlay
+      if (indicator) {
+        indicator.style.display = 'flex';
+        indicator.classList.add('active');
+        indicator.classList.remove('agent-mode');
+      }
+      
+      if (timer) {
+        timer.style.display = 'block';
+        timer.textContent = '0:00';
+      }
+      
+      if (transcript) {
+        transcript.style.display = 'block';
+        transcript.textContent = '';
+      }
+      
+      if (badge) {
+        badge.style.display = 'none';
+      }
+    }
+  } else {
+    if (indicator) {
+      indicator.style.display = 'none';
+      indicator.classList.remove('active', 'agent-mode');
+    }
+    if (timer) {
+      timer.style.display = 'none';
+    }
+    if (transcript) {
+      transcript.style.display = 'none';
+    }
+    if (badge) {
+      badge.style.display = 'none';
+    }
+    stopTimer();
+  }
+}
+
+function startTimer() {
+  stopTimer(); // Clear any existing timer
+  timerInterval = setInterval(() => {
+    if (!sessionStartTime) return;
+    
+    const elapsed = Math.floor((Date.now() - sessionStartTime) / TIMER_UPDATE_INTERVAL_MS);
+    const timer = document.getElementById('realtimeTimer');
+    if (timer) {
+      const minutes = Math.floor(elapsed / 60);
+      const seconds = elapsed % 60;
+      timer.textContent = `${minutes}:${seconds.toString().padStart(2, '0')}`;
+    }
+  }, TIMER_UPDATE_INTERVAL_MS);
+}
+
+function stopTimer() {
+  if (timerInterval) {
+    clearInterval(timerInterval);
+    timerInterval = null;
+  }
+  sessionStartTime = null;
+}
+
+let transcriptBuffer = '';
+let transcriptTimeout = null;
+
+/**
+ * Update transcript display
+ * @param {string} text - Text to display
+ * @param {boolean} isFinal - Whether this is final (clear after delay) or interim
+ * @param {string} role - 'user' or 'agent' (agent mode only)
+ */
+function updateTranscript(text, isFinal, role = null) {
+  const transcriptEl = document.getElementById('realtimeTranscript');
+  if (!transcriptEl) return;
+
+  if (isFinal) {
+    // For agent mode, show formatted text with role
+    if (currentMode === 'agent' && role) {
+      const prefix = role === 'user' ? 'You: ' : `${agentName}: `;
+      transcriptEl.textContent = prefix + text;
+    } else {
+      transcriptEl.textContent = text;
+    }
+    
+    transcriptBuffer = text;
+
+    // Auto-clear after delay if final
+    if (text) {
+      if (transcriptTimeout) clearTimeout(transcriptTimeout);
+      transcriptTimeout = setTimeout(() => {
+        transcriptBuffer = '';
+        transcriptEl.textContent = '';
+      }, 5000);
+    } else {
+      transcriptBuffer = '';
+      transcriptEl.textContent = '';
+    }
+  } else {
+    // Interim text
+    if (currentMode === 'agent' && role) {
+      const prefix = role === 'user' ? 'You: ' : `${agentName}: `;
+      transcriptEl.textContent = prefix + text;
+    } else {
+      transcriptBuffer = text;
+      transcriptEl.textContent = text;
+    }
+
+    // Auto-clear after 5 seconds of no updates
+    if (transcriptTimeout) clearTimeout(transcriptTimeout);
+    transcriptTimeout = setTimeout(() => {
+      transcriptBuffer = '';
+      transcriptEl.textContent = '';
+    }, 5000);
+  }
+}
+
+// ============================================
+// MIC MUTE (echo prevention during TTS playback)
+// ============================================
+
+function muteMic() {
+  if (isMicMuted) return;
+  isMicMuted = true;
+  if (micStream) {
+    micStream.getAudioTracks().forEach(track => { track.enabled = false; });
+  }
+  // Visual cue: dim the button when mic is off
+  const voiceBtn = document.getElementById('voiceBtn');
+  if (voiceBtn) voiceBtn.classList.add('mic-muted');
+  UplinkLogger.debug('Realtime: Mic muted (TTS playing)');
+}
+
+function unmuteMic() {
+  if (!isMicMuted) return;
+  isMicMuted = false;
+  if (micStream) {
+    micStream.getAudioTracks().forEach(track => { track.enabled = true; });
+  }
+  // Restore full brightness
+  const voiceBtn = document.getElementById('voiceBtn');
+  if (voiceBtn) voiceBtn.classList.remove('mic-muted');
+  UplinkLogger.debug('Realtime: Mic unmuted');
+}
+
+/**
+ * Update the voice status label in agent mode
+ * @param {string} state - 'listening' | 'waiting'
+ */
+function updateVoiceStatus(state) {
+  if (currentMode !== 'agent') return;
+  
+  const voiceStatus = document.getElementById('voiceStatus');
+  if (!voiceStatus) return;
+  
+  const name = agentName || 'Agent';
+  
+  switch (state) {
+    case 'waiting':
+      voiceStatus.textContent = 'Waiting for reply...';
+      break;
+    case 'replying':
+      voiceStatus.textContent = `${name} is replying...`;
+      break;
+    case 'listening':
+    default:
+      voiceStatus.textContent = `Listening — ${name}`;
+      break;
+  }
+}
+
+function showThinkingIndicator() {
+  const indicator = document.getElementById('realtimeThinking');
+  if (indicator) {
+    indicator.style.display = 'block';
+    indicator.textContent = '💭 thinking...';
+  }
+}
+
+function hideThinkingIndicator() {
+  const indicator = document.getElementById('realtimeThinking');
+  if (indicator) {
+    indicator.style.display = 'none';
+  }
+}
+
+function showError(message) {
+  const chat = window.UplinkChat;
+  if (chat?.addMessage) {
+    chat.addMessage(message, 'system');
+  }
+}
+
+// ============================================
+// CLEANUP
+// ============================================
+
+function cleanup() {
+  // Reset session state
+  sessionReady = false;
+  isMicMuted = false;
+  currentUserTranscript = '';
+  currentAgentResponse = '';
+  streamingMessageDiv = null;
+  
+  // Remove glow class from voice button
+  const voiceBtn = document.getElementById('voiceBtn');
+  if (voiceBtn) voiceBtn.classList.remove('realtime-active');
+
+  // Stop timer
+  stopTimer();
+
+  // Close WebSocket
+  if (ws) {
+    if (ws.readyState === WebSocket.OPEN) {
+      ws.close(WS_CLOSE_NORMAL);
+    }
+    ws = null;
+  }
+
+  // Stop microphone
+  if (audioWorkletNode) {
+    audioWorkletNode.disconnect();
+    audioWorkletNode = null;
+  }
+
+  if (audioContext) {
+    audioContext.close().catch(err => 
+      UplinkLogger.error('Realtime: AudioContext close failed:', err)
+    );
+    audioContext = null;
+  }
+
+  if (micStream) {
+    micStream.getTracks().forEach(track => track.stop());
+    micStream = null;
+  }
+
+  // Stop playback
+  if (playbackContext) {
+    playbackContext.close().catch(err => 
+      UplinkLogger.error('Realtime: Playback context close failed:', err)
+    );
+    playbackContext = null;
+  }
+
+  playbackQueue = [];
+  isPlayingAudio = false;
+  nextPlaybackTime = 0;
+  transcriptBuffer = '';
+  
+  if (transcriptTimeout) {
+    clearTimeout(transcriptTimeout);
+    transcriptTimeout = null;
+  }
+  
+  hideThinkingIndicator();
+}
+
+// ============================================
+// UTILITIES
+// ============================================
+
+function arrayBufferToBase64(buffer) {
+  const bytes = new Uint8Array(buffer);
+  let binary = '';
+  for (let i = 0; i < bytes.byteLength; i++) {
+    binary += String.fromCharCode(bytes[i]);
+  }
+  return btoa(binary);
+}
+
+function base64ToArrayBuffer(base64) {
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes.buffer;
+}
+
+// ============================================
+// PUBLIC API
+// ============================================
+
+export const UplinkRealtime = {
+  start,
+  stop,
+  isActive: isSessionActive,
+  isMuted: () => isMicMuted,
+  getMode
+};
+
+// Backward compat: assign to window
+window.UplinkRealtime = UplinkRealtime;
+
+UplinkLogger.debug('Realtime: Module loaded');