Background Audio

Background Audio enables native, continuous microphone recording in your Median-powered app, even when the app is in the background or the device is locked. The plugin offers seamless recording with persistent notifications on Android and system-level recording indicators on iOS, plus real-time state updates and optional on-device speech-to-text transcription.

The plugin supports start, stop, pause, and resume controls with real-time event callbacks for state changes and optional transcript delivery. Implement it using async JavaScript on top of the Median JavaScript Bridge.

Why use Background Audio

• Background and lock screen recording: Keep capturing audio when users leave the app or lock the device.
• Native platform UX: Surface a persistent Android foreground service notification and iOS system recording indicators without custom native code.
• Lifecycle controls: Start, stop, pause, and resume without releasing the background session when pausing.
• Realtime updates: Listen for recording state changes and handle completion or errors in your UI.

Prerequisites

• Enable JavaScript Bridge in your Median.co app
• Grant microphone permission before or during your recording flow (see checkPermission and requestPermission)
• Learn the basics of async JavaScript (async / await) and the optional callbacks used below

👍

Developer Demo

Display our demo page in your app to test during development https://median.dev/background-audio/

When to use this plugin

Background Audio is essential for apps that need to:

What you'll do

Use this section as a fast navigation map into the full setup and implementation details:

1. Confirm permissions: Check and request microphone access before starting a session using the methods documented in JavaScript bridge functions.
2. Configure recording options: See Plugin setup for startRecording options and recommended settings.
3. Implement bridge calls: Add checkPermission, requestPermission, startRecording, pause, resume, stopRecording, getStatus, and listeners from JavaScript bridge functions.
4. Understand platform UX: Review the Platform UX during recording note under startRecording to see what users will see on Android and iOS.
5. Validate flows and errors: Use Error handling, Testing Checklist, and Troubleshooting to verify your implementation.

Key terms

The following terms will help you implement Background Audio effectively:

AVAudioSession (iOS): The app activates the native audio session in background mode while recording. The system shows a recording indicator in the Dynamic Island (iPhone 14+) or status bar pill while the session is active.

Foreground service (Android): The Android component that runs while recording, showing a persistent notification with app icon, name, status text, and actions.

On-device speech-to-text (STT): The plugin can produce optional transcription during recording. Configure it with enableTranscription and sttLanguage. Availability can vary by locale.

Listener events: Real-time callbacks for lifecycle changes (idle, recording, paused, stopped, error).

📘

Important considerations

• iOS shows a system-level recording indicator (orange dot with waveform animation while actively recording); it hides when recording stops.
• Android shows status text such as "audio recording in progress" or "paused" and exposes Launch App and Stop Recording actions on the notification.
• WAV works only on iOS; Android automatically uses M4A if you request WAV.
• OS interruptions (for example, calls or Siri) can pause the session (SESSION_INTERRUPTED); handle error listener state and the error reference table.

Plugin setup

Enable the Background Audio plugin in your Median App Studio configuration, then rebuild your app. Once you enable it, you can call median.backgroundAudio.* functions from the JavaScript Bridge at runtime.

JavaScript bridge functions

Document each method available on median.backgroundAudio. Most functions return a promise; getStatus additionally supports a callback form.

Check permissions

Returns whether the user has already granted microphone permission. This method returns a promise.

↔️Median JavaScript Bridge

const permission = await median.backgroundAudio.checkPermission();

if (!permission.granted) {
  // Prompt the user to grant permission
}

Return value:

interface PermissionStatus {
    granted: boolean;
}

Request permissions

Prompts the user for microphone permission. If the user grants it, you can start recording. This method returns a promise.

↔️Median JavaScript Bridge

const permission = await median.backgroundAudio.requestPermission();

if (permission.granted) {
    const result = await median.backgroundAudio.startRecording();
}

Return value:

interface PermissionStatus {
    granted: boolean;
}

Start recording

Starts a background-aware recording session. Optional configuration controls format, duration, and transcription. This method returns a promise.

↔️Median JavaScript Bridge

// Minimal configuration
const result = await median.backgroundAudio.startRecording();

// Full configuration
const result = await median.backgroundAudio.startRecording({
    format: 'm4a',
    maxDuration: 3600,
    enableTranscription: true,
    sttLanguage: 'en-US'
});

Parameters:

Return value:

interface StartRecordingResult {
    success: boolean;
}

Platform UX during recording:

When startRecording succeeds, each platform surfaces native UI automatically. You do not need additional manifest or Info.plist changes beyond enabling the plugin and declaring standard microphone usage descriptions.

Pause recording

Pauses an active recording without releasing the background session. This method returns a promise.

↔️Median JavaScript Bridge

const status = await median.backgroundAudio.pause();
console.log('Recording paused');

Return value:

Returns a status object reflecting the updated recording state.

Resume recording

Resumes a paused session. This method returns a promise.

↔️Median JavaScript Bridge

const status = await median.backgroundAudio.resume();
console.log('Recording resumed');

Parameters:

This function takes no parameters.

Return value:

Returns a status object reflecting the updated recording state.

Stop recording

Stops the session and retrieves the file URI, duration, and optional transcript. This method returns a promise.

↔️Median JavaScript Bridge

const result = await median.backgroundAudio.stopRecording();

console.log('File URI:', result.fileUri);
console.log('Duration:', result.durationSeconds, 'seconds');

if (result.transcript) {
    console.log('Transcript:', result.transcript);
}

Parameters:

This function takes no parameters.

Return value:

interface StopRecordingResult {
    fileUri: string;
    durationSeconds: number;
    transcript?: string;
}

Get status

Returns the current recording state and elapsed time. Pass a callback function to use the callback form. Otherwise, this method returns a promise.

↔️Median JavaScript Bridge

// Using promises (recommended)
const status = await median.backgroundAudio.getStatus();
console.log(JSON.stringify(status));

// Using callback
median.backgroundAudio.getStatus({
    callback: function (status) {
        console.log('Current state:', status.state);
        console.log('Elapsed time:', status.elapsedSeconds, 'seconds');
    }
});

Parameters:

Return value:

interface RecordingStatus {
    state: 'idle' | 'recording' | 'paused' | 'stopped' | 'error';
    elapsedSeconds: number;
}

Example JSON:

{
    "state": "recording",
    "elapsedSeconds": 127
}

Add a listener

Registers a listener for real-time recording lifecycle updates. Returns a listener identifier that you pass to removeListener.

↔️Median JavaScript Bridge

const listenerId = median.backgroundAudio.addListener((event) => {
    console.log('State changed:', event.state);

    if (event.state === 'stopped') {
        console.log('Recording complete');
    } else if (event.state === 'error') {
        console.error('Error code:', event.errorCode);
    }
});

Parameters:

Return value:

Returns a listener identifier (opaque value) that you pass to removeListener.

Event states you may receive:

Remove a listener

Removes a previously added listener so it stops receiving further events.

↔️Median JavaScript Bridge

median.backgroundAudio.removeListener(listenerId);

Parameters:

Return value:

No return value.

Error handling

Best practices for error handling

try {
    const result = await median.backgroundAudio.startRecording({
        format: 'm4a',
        enableTranscription: true
    });

    if (!result.success) {
        console.error('Failed to start recording');
    }
} catch (error) {
    switch (error.code) {
        case 'PERMISSION_DENIED':
            // Prompt the user to enable the microphone in Settings
            break;
        case 'ALREADY_RECORDING':
            // Surface current session state instead of starting again
            break;
        case 'STT_UNAVAILABLE':
            // Fall back to file URI only
            break;
        default:
            console.error('Unexpected background audio error:', error);
    }
}

📘

Important

Use the listener error state and the errorCode it provides together with this reference table when presenting in-app guidance. Combine it with getStatus checks before issuing pause, resume, or stop commands to avoid NOT_RECORDING and ALREADY_RECORDING race conditions.

Example implementation

See the example implementation below for the basic recording flow

Basic Recording Flow

const permission = await median.backgroundAudio.checkPermission();

if (!permission.granted) {
  // Prompt user to grant permission
}

const permission = await median.backgroundAudio.requestPermission();

if (permission.granted) {
  // Start recording
  const result = await median.backgroundAudio.startRecording();
}

<button type="button" onclick="startRecording()">Start Recording</button>

<script>
async function startRecording() {
  const result = await median.backgroundAudio.startRecording({
    format: 'm4a',
    enableTranscription: true,
    sttLanguage: 'en-US'
  });
  
  if (result.success) {
    console.log('Recording started');
  }
}
</script>

Full Recipe

Follow the full recipe for the full implementation

Diagrams

1. Overview Flowchart

High-level view: permission gate → start recording → success or failure.

flowchart TD
    Trigger["User taps Start Recording"]
    CheckPerm["checkPermission()"]
    Granted{{"permission.granted?"}}
    RequestPerm["requestPermission()"]
    GrantedAfter{{"granted after request?"}}
    StartRec["startRecording(options)"]
    Success{{"result.success?"}}
    Recording["Recording active"]
    Denied["Show settings guidance"]
    Failed["Log error — session not started"]

    Trigger --> CheckPerm
    CheckPerm --> Granted
    Granted -->|"Yes"| StartRec
    Granted -->|"No"| RequestPerm
    RequestPerm --> GrantedAfter
    GrantedAfter -->|"Yes"| StartRec
    GrantedAfter -->|"No"| Denied
    StartRec --> Success
    Success -->|"true"| Recording
    Success -->|"false"| Failed

Testing Checklist

Use this checklist to ensure Background Audio is working correctly in your app:

Troubleshooting

📘

Still having trouble?

For issues related to platform-level microphone, background audio, or speech-to-text behavior outside Median.co, refer to the platform documentation for Apple AVAudioSession and Android foreground services.