Skip to main content
Source: Background Recorder repository. Read its LICENSE before using or modifying the extension. This extension records audio from the microphone, keeps recording when the app goes to the background, and uploads the file to your server when recording stops. It shows its state in a Lock Screen widget on iOS, and in a foreground service notification and a home screen widget on Android. The page only ever sees a recording id and its state. The audio never crosses the bridge.
Experimental. V3 only. You own and maintain this ready-made extension once it is in your app. First-party V4 support comes through the new package registry. Despia does not support customised code. Read V3 Extensions first.

Before installing the extension

Extension files must be compiled into a rebuilt native app. Uploading files does not change an installed binary. Automatic discovery of hosted /despia/extensions.json during a normal rebuild is under review and is not yet confirmed in deployed builds. See Troubleshooting extension builds.

Files

Copy every file to the path in its title. Paths are under public/despia/recorder/ in your web app, except extensions.json, which goes in public/despia/. Before you build, change these values to your own:
  • client_id (the id after /builder/ in your Despia editor URL), ios_bundle_id and android_package in public/despia/extensions.json;
  • the upload host upload.example.com in both hosts lists in manifest.json.
The build policy is part of the trusted build inputs and is not served from your site. Signed-source checks verify the exact files and dependency graph; artifact checks verify the build before signing. You own the behavior and maintenance of your native code.

Permissions and capabilities

The manifest declares everything the recorder needs. The build adds them to your app.
  • Microphone. NSMicrophoneUsageDescription, declared under requires.usage_descriptions. Set the purpose text in Despia.
  • Background modes. audio (keep recording in the background) and processing (finish uploads in a background processing task named upload).
  • App Group. The logical group nativeext, shared by the app and the RecorderStatusWidget target. It becomes group.<bundle id>.nx.nativeext. Register it in the Apple Developer portal and add it to both bundle IDs, as for Home Widgets.
  • Widget. RecorderStatusWidget, a WidgetKit target with a deployment target of iOS 16.6.

Using it from your web app

The upload URL receives an HTTP PUT, with Content-Type: audio/mp4 and an X-Recording-Id header. Its host must be in the route’s approved hosts list. Install the SDK with npm install despia-native. Import despia from despia-native and watch the route’s declared output variable. Run this function from a client event after obtaining any required microphone permission:
Register onRecorderState as described in Calling a route before starting if you need live changes. Read status after a page reload; event delivery is not durable.

Asking for the microphone on Android

On iOS, start shows the microphone prompt itself. On Android it does not. Ask for the microphone from the page first with the standard web API. Despia’s Android app turns a web microphone request into the system RECORD_AUDIO prompt, when the microphone permission is on for your app:
If the user denies it, getUserMedia throws and start answers permission_denied.

Routes

The state event calls the declared onRecorderState(data) handler on changes.

States

Answers and events carry recordingId, state, durationMs and bytes, plus httpStatus after an upload attempt and reason when the state is failed. While the recorder could not save its index, they also carry durable: false and storage.

Error codes

Besides the standard codes, the recorder answers:

Platform limits

  • iOS. Recording must start while the app is in the foreground. It continues in the background while the audio session stays active. A force-quit ends it. Uploads run while the app runs, in the limited background time iOS may give, and in a background processing task if iOS grants one. iOS guarantees neither. An upload that is cut off starts again from the beginning the next time the app runs.
  • Android. Android 14 and later only start a microphone foreground service while the app is visible, so call start from a page the user is looking at. Lock Screen widgets depend on the device; the foreground service notification is always shown. Uploads run through WorkManager.