Background Execution & Streaming
Relevant source files
The following files were used as context for generating this wiki page:
Background Execution & Streaming manages persistent connections and active tasks when the Conduit application is not in the foreground. It ensures that token-by-token chat streaming and voice calls continue without interruption by the mobile operating system's resource management.
The system uses platform-specific implementations (Kotlin for Android, Swift for iOS) to request execution time from the host OS. It relies on a "lease" system where the Flutter layer requests background execution for specific stream IDs, which the native host then maintains using foreground services or background tasks.
System Architecture
The architecture consists of a Flutter API that communicates with native Host APIs via Pigeon-generated bridges. The native side manages the lifecycle of OS-level services required to keep the process alive.
Communication Flow
The following diagram illustrates the interaction between the Flutter application and the native platform handlers.
Core Components
| Component | Platform | Description |
|---|---|---|
BackgroundStreamingHandler | Android | Coordinates between Flutter and the Foreground Service. |
BackgroundStreamingService | Android | A Foreground Service that holds WakeLocks and shows notifications. |
BackgroundStreamingHandler | iOS | Manages UIBackgroundTaskIdentifier to prevent app suspension. |
PlatformBackgroundStreamLease | Both | Data structure representing an active task requiring background time. |
VadHandler | Both | Detects voice activity to trigger or maintain active streaming states. |
Sources: android/app/src/main/kotlin/app/cogwheel/conduit/BackgroundStreamingHandler.kt:66-78, ios/Runner/ConduitPlatformApis.g.swift:233-241, third_party/vad/UPSTREAM_README.md:281-295
Android Implementation
Android utilizes a ForegroundService to satisfy the OS requirement for user-visible background work.
Foreground Service Types
The system dynamically selects the service type based on the requirements of the active leases:
- DATA_SYNC: Used for standard chat streaming.
- MICROPHONE: Added when a voice call or microphone access is required.
Sources: android/app/src/main/kotlin/app/cogwheel/conduit/BackgroundStreamingHandler.kt:85-101, android/app/src/main/kotlin/app/cogwheel/conduit/BackgroundStreamingHandler.kt:233-248
WakeLock Management
The BackgroundStreamingService acquires a PARTIAL_WAKE_LOCK to prevent the CPU from entering a sleep state during active streaming.
- Timeout: The WakeLock is set with a 7-minute timeout for active streams.
- Release: It is released immediately if all leases are removed or if the timeout is reached without renewal.
Sources: android/app/src/main/kotlin/app/cogwheel/conduit/BackgroundStreamingHandler.kt:294-315, android/app/src/main/kotlin/app/cogwheel/conduit/BackgroundStreamingHandler.kt:335-345
Time Limits (Android 14+)
Android 14 (API 34) imposes a 6-hour limit on dataSync services. Conduit manages this by:
- Monitoring service uptime.
- Stopping the service at 5 hours (1-hour buffer).
- Notifying the Flutter layer via
ACTION_TIME_LIMIT_APPROACHING.
Sources: android/app/src/main/kotlin/app/cogwheel/conduit/BackgroundStreamingHandler.kt:351-364
iOS Implementation
iOS uses beginBackgroundTask(withName:expirationHandler:) to request execution time when the app moves to the background.
Task Management
- Background Tasks: The handler starts a background task when the app is backgrounded and leases are active.
- Expiration: If the OS signals imminent task termination, the handler invokes
backgroundTaskExpiring()to let the Flutter layer save state. - Lease Types: Supports
chatandvoicestream kinds.
Sources: ios/Runner/BackgroundStreamingHandler.swift:145-165, ios/Runner/ConduitPlatformApis.g.swift:228-231
Voice Activity Detection (VAD)
The system integrates VAD to intelligently manage streaming states, particularly for voice-based interactions.
VAD Configuration
The VadHandler provides real-time detection of speech to minimize unnecessary background execution.
| Parameter | Default | Description |
|---|---|---|
positiveSpeechThreshold | 0.5 | Probability threshold to detect speech start. |
negativeSpeechThreshold | 0.35 | Threshold to detect speech end. |
minSpeechFrames | 3 | Minimum frames required to confirm real speech. |
frameSamples | 1536 | Samples per frame (96ms at 16kHz for legacy model). |
Sources: third_party/vad/UPSTREAM_README.md:323-336, third_party/vad/UPSTREAM_README.md:338-350
Data Models
The following structures define the communication between Dart and Native layers for background tasks.
PlatformBackgroundStartRequest
Used to initiate background tracking for one or more streams.
streamIds: List of identifiers for active streams.requiresMicrophone: Boolean flag for audio recording needs.leases: List ofPlatformBackgroundStreamLeaseobjects containing start timestamps and kinds.
Sources: android/app/src/main/kotlin/app/cogwheel/conduit/ConduitPlatformApis.g.kt:283-294, ios/Runner/ConduitPlatformApis.g.swift:243-252
PlatformBackgroundStreamLease
id: Unique identifier for the stream.kind: Enumeration ofCHATorVOICE.requiresMicrophone: Specific flag for this lease.startedAtMillis: Epoch time when the stream began.
Sources: android/app/src/main/kotlin/app/cogwheel/conduit/ConduitPlatformApis.g.kt:238-248, ios/Runner/ConduitPlatformApis.g.swift:233-241
Conclusion
The Background Execution & Streaming system provides a robust framework for maintaining AI interactions across mobile platform constraints. By abstracting OS-specific mechanisms like Android Foreground Services and iOS Background Tasks into a unified lease-based API, the project ensures that chat and voice data continue to stream reliably even while the user performs other tasks or locks their device.