Skip to main content
Quick Summary
The Headless Web SDK automatically manages transitions between online and offline states using a 15-second buffer. Brief network interruptions (≤15 seconds) are handled transparently without switching to offline mode.

Extended disconnections (>15 seconds) trigger offline mode, where audio chunks are stored in IndexedDB and queued for upload when the connection returns. This ensures your application handles network interruptions gracefully without interrupting the user experience.
Last updated:December 2025

​
Overview

The Headless Web SDK automatically manages transitions between online and offline states. Even if there is a brief network drop (up to around 15 seconds), Ambient will handle it automatically and continue as an online session. Understanding how this works helps you build reliable applications that handle network interruptions gracefully.

​
Online ↔ Offline Transitions

The SDK uses a smart buffering system (a 15 second buffer) to distinguish between brief network hiccups and actual offline periods. This prevents unnecessary interruptions to the user experience.

​
How Transitions Work

The SDK monitors network connectivity and makes decisions based on how long the connection is lost:
Network EventSDK BehaviorResult
Brief network interruption (≤15 seconds)SDK buffers audio automaticallySession stays ONLINE; audio automatically resumes when connection returns
Extended disconnection (>15 seconds)SDK switches to offline modeSession switches to OFFLINE; audio stored locally and queued for upload when connection returns
The SDK uses a 15-second buffer to distinguish between brief network hiccups and actual offline periods. This gives the network a grace window to recover before the session fully switches to offline mode.

​
What This Means For Your Application

  • Brief interruptions (≤15 seconds): Even if there is a brief network drop (up to around 15 seconds), Ambient will handle it automatically and continue as an online session. The SDK buffers audio in memory and automatically streams it when the connection returns. Your users won’t notice any interruption.
  • Extended disconnections (>15 seconds): The SDK switches to offline mode, stores audio chunks in IndexedDB, and queues the session for upload when your network connection returns.

​
Buffer Size

To understand how the buffer works, it helps to know what a “chunk” represents:

​
Chunk Size Calculation

The SDK processes audio in small chunks:
  • Recorder cadence: 100 milliseconds (0.1 seconds)
  • Samples per chunk: 16,000 Hz × 0.1 s = 1,600 PCM samples
  • Bytes per chunk: 1,600 samples × 2 bytes (16-bit) = 3,200 bytes ≈ 3 kB before compression

​
MAX AUDIO BUFFER SIZE

When we say “MAX_AUDIO_BUFFER_SIZE = 150”, we mean:
  • 150 chunks × 0.1 seconds = 15 seconds of audio
  • 150 chunks × 3 kB = ≈450 kB raw audio (≈250 kB compressed) held in RAM
In simple terms: “150 buffer size” = “store up to 150 consecutive 100 ms chunks”. This gives the network a 15-second grace window before the session flips to OFFLINE mode.
The buffer is stored in RAM, which allows for fast recovery when brief network issues resolve quickly. Once the buffer exceeds 150 chunks (15 seconds), the SDK switches to offline mode and uses IndexedDB for persistent storage.

​
Observing Offline Sessions

To track offline sessions and their status changes, use the useOfflineSessions hook: 
import { useOfflineSessions } from '@suki-sdk/platform-react';

​
Session Object Structure

Each session in the sessions array contains:
React
{
  sessionId: string,
  status: 'idle' | 'uploading' | 'processing' | 'complete' | 'error',
  progress?: number // 0-100, available when status is 'uploading'
}

​
Example Code: Monitoring Session Status

You can iterate through sessions and react to status changes:
React
const { sessions } = useOfflineSessions();

useEffect(() => {
  sessions.forEach(s => {
    if (s.status === 'uploading') {
      console.log(`Upload progress: ${s.progress}%`);
      // Show progress bar in your UI
    }
    
    if (s.status === 'complete') {
      fetchNote(s.sessionId);
      // Fetch the generated note/transcript
    }
  });
}, [sessions]);

​
Event-Based Approach (Alternative)

You can also subscribe to session updates using the on method:
React
const { on } = useOfflineSessions();

useEffect(() => {
  const unsubscribe = on('ambient:offlineSessionsUpdate', (updatedSessions) => {
    console.log('Sessions updated:', updatedSessions);
    // Handle updates here
  });
  
  return () => unsubscribe();
}, [on]);

​
Status Mappings

Here’s what you should do for each session status:

Uploading

Show a progress bar using the progress value (0-100)

Complete

Fetch the transcript/note using the sessionId

Session disappears

The SDK has automatically deleted the local copy after successful completion

​
Important Notes

15-second buffer: The SDK gives brief network interruptions time to recover before switching to offline mode.Automatic transitions: You don’t need to manually detect network changes, the SDK handles transitions automatically.Persistent storage: Once offline mode is activated, audio is stored in IndexedDB and automatically uploaded when connectivity returns.Track with hooks: Use useOfflineSessions() to monitor session status and update your UI accordingly.