AllSpark-ios

AllSpark Edge mobile app for iOS. This app provides real-time video capture, recording, and uploading capabilities with face detection and blurring features.

Important

AllSpark Edge consists of this iOS client and the AllSpark Edge Server. For compatibility reasons, please ensure that you run release versions of both repositories that share at least the same minor semantic version tag (e.g., v0.3.x of the iOS app with v0.3.x of the server).

Features

• Camera Capture: Real-time video capture from front or back camera
• Face Detection & Blurring: Automatic detection and pixelation of faces using Vision framework
• Continuous Recording: Automatically records video in chunks (default 30s) when camera view is active
• Storage Management: Automatically manages device storage by deleting oldest recordings when limit is reached
• Auto-Discovery: Automatically discovers available servers on the local network using Bonjour/mDNS
• Time-Range Upload: Server can request upload of video segments for specific time ranges
• Video Format Selection: Choose between MP4 (default) or MOV format for recordings
• Network Configuration: Configurable server host with support for discovered services

Architecture

• CameraViewController: Handles camera capture, face detection, continuous video recording, and user interaction
• ConnectionManager: Singleton managing WebSocket connections, Bonjour service discovery, and video uploads
• SettingsView: Network configuration, server discovery list, and connection diagnostics
• WebSocket Protocol: Two-phase upload (metadata → binary data) & JSON command interface

API & WebSocket Communication

The iOS app establishes HTTP and WebSocket connections to a configured server for real-time video upload and command reception.

For complete documentation on the expected WebSocket message protocol, JSON command interfaces, and HTTP endpoints, please see the Endpoints Documentation in the AllSpark Edge Server repository.

Network Configuration

Settings View

Located in SettingsView.swift, allows users to:

1. Configure Device Name (optional)

   • Custom name shown on server's web interface
   • Useful for identifying specific devices in the test host
   • Defaults to the iOS device name (e.g., "iPhone")

2. Configure Server Host

   • Auto-Discovery: Automatically updates with server found on local network (Bonjour/mDNS)
   • Manual Entry: Allows manual IP/Hostname entry if server is not discovered, edits will automatically attempt to connect to WebSocket
   • Default: localhost:8080
   • Supports: IP addresses, hostnames, with or without protocol prefix

3. Configure Server Discovery

   • Auto-Discovery: Automatically lists servers using _allspark._tcp found on local network (Bonjour/mDNS)
   • Manual Discovery: Allows manual selection of discovered servers to connect to

4. Set SSL Verfification

   • Default: true
   • If testing self-signed certificates, set to false

5. Control/Monitor WebSocket Connection Manual Connection: When Disconnected allows WebSocket connection attempts Manual Disconnection: When Connected allows WebSocket disconnection

   • Displays connection status (success/failure)
   • Shows connection protocol (ws:// or wss://) being used
   • Useful for diagnosing network or certificate issues

6. Edit Permissions

   • Opens Allspark's iOS app permissions settings
   • Local Network: May be required for WebSocket/HTTP connections depending on server configuration
   • Microphone: Required for audio recording
   • Camera: Required for video recording

Connection Status Indicator

The Camera tab displays a WiFi icon in the top-right corner that indicates connection status:

• Red WiFi with slash - Disconnected from server
• Orange WiFi - Attempting to connect
• Green WiFi - Connected to server
• Green WiFi + Green Lock - Connected via secure WSS protocol

The lock icon overlay appears automatically when using a secure WebSocket (WSS) connection, indicating encrypted communication with the server.

Server Disconnection Detection

When a previously established server connection becomes unavailable:

1. Automatic Detection: The app detects connection loss when WebSocket receive errors occur after successful connection
2. UI Update: The connection icon immediately changes from green to red
3. User Alert: A modal alert notifies the user that the server was lost with two options:
   • Reconnect: Manually initiate reconnection attempt
   • Dismiss: Close the alert
4. Automatic Recovery: The app automatically attempts to reconnect after 5 seconds, allowing the connection to be restored if the server comes back online
5. Continuous Attempts: Automatic reconnection attempts continue until the connection is restored or the user navigates away from the camera view

Continuous Recording Workflow

The app operates on a "always-recording" model when the Camera view is active:

1. View Appears: Camera initializes and recording starts immediately.
2. Chunking: Video is recorded in chunks (default 30 seconds) defined by videoChunkDurationMs.
3. Storage: Files are saved locally to the device.
4. Cleanup: Oldest files are automatically deleted when total storage exceeds videoBufferMaxMB.
5. Upload: Files are NOT uploaded automatically. They are only uploaded when:
   • User explicitly taps "Upload" button
   • Server sends an uploadTimeRange command matching the file's time range

This ensures a buffer of recent video is always available for on-demand retrieval without saturating network bandwidth.

Icons

Icons used are sourced internally in iOS from SF Symbols Online from a repository like this one: https://github.com/andrewtavis/sf-symbols-online.

Known Limitations

• Video recordings are stored in Documents directory
• Both MP4 and MOV formats require decoder support on the receiving server
• Face detection performance depends on device capabilities and lighting conditions