!React Native Nitro Screen Recorder

react-native-nitro-screen-recorder

> ⚠️ This package is currently in alpha and under active development. Please report any issues that you run across on either platform.

A React Native library powered by NitroModules that provides comprehensive screen recording capabilities for both iOS and Android. Capture in-app content or global screen recordings with camera overlay support, audio recording, and extensive customization options.

Features

- In-App Recording (iOS only) - Record your app's content with camera overlay
- Global Screen Recording - System-wide screen capture (iOS & Android)
- Camera Integration - Front/back camera overlay with customizable positioning
- Audio Recording - Microphone support with permission management
- Event Listeners - Real-time recording status updates
- File Management - Automatic file handling and cache management
- Permission Management - Built-in camera and microphone permission handling
- React Hooks - Convenient hooks for permissions and global recording management

Demo

| iOS In-App Recording | iOS Global Recording | Android Global Recording |
| :--------------------------------------------------------------------: | :-------------------------------------------------------: | :---------------------------------------------------------------: |
| | | |

Installation

Using npm:

``sh
npm install react-native-nitro-screen-recorder react-native-nitro-modules
`

Using yarn:

`sh
yarn add react-native-nitro-screen-recorder react-native-nitro-modules
`

> react-native-nitro-modules is required as this library relies on Nitro Modules.

Configuration

This library includes an Expo config plugin for automatic native configuration.

Verification

After completing these steps:

1. Build and run your app on a physical device
2. Test global screen recording functionality
3. Verify that recorded files are properly saved and accessible
4. Check that permissions are properly requested when needed

$3

Here's a complete example using the new useGlobalRecording hook and updated stopGlobalRecording:

`tsx
import React from 'react';
import { View, Text, Button, Alert } from 'react-native';
import {
useGlobalRecording,
useMicrophonePermission,
startGlobalRecording,
stopGlobalRecording,
} from 'react-native-nitro-screen-recorder';

export default function ScreenRecorderExample() {
const { hasPermission, requestPermission } = useMicrophonePermission();

const { isRecording } = useGlobalRecording({
onRecordingStarted: () => {
Alert.alert('Recording started');
},
onRecordingFinished: async (file) => {
if (file) {
Alert.alert(
'Recording Complete!',
Saved: ${file.name}\nDuration: ${file.duration}s\nSize: ${file.size} bytes
);
// e.g., uploadRecording(file.path)
} else {
Alert.alert('Recording Complete', 'Failed to retrieve the file.');
}
},
settledTimeMs: 700, // optional delay before retrieving the file
});

const handleStartRecording = async () => {
if (!hasPermission) {
const granted = await requestPermission();
if (!granted) {
Alert.alert(
'Permission Required',
'Microphone permission is needed for audio recording'
);
return;
}
}

startGlobalRecording({
enableMic: true,
onRecordingError: (error) => {
Alert.alert('Global recording error', error.message);
},
});
};

const handleStopRecording = async () => {
const file = await stopGlobalRecording({ settledTimeMs: 1000 });
if (file) {
console.log('Stopped and retrieved file:', file);
}
};

return (


Screen Recorder Demo





{isRecording && (
Recording is active…
)}

);
}
`

Documentation

Table of Contents

- React Hooks
- useCameraPermission()
- useMicrophonePermission()
- useGlobalRecording()
- Permissions
- getCameraPermissionStatus()
- getMicrophonePermissionStatus()
- requestCameraPermission()
- requestMicrophonePermission()
- In-App Recording
- startInAppRecording()
- stopInAppRecording()
- cancelInAppRecording()
- Global Recording
- startGlobalRecording()
- stopGlobalRecording()
- retrieveLastGlobalRecording()
- Event Listeners
- addScreenRecordingListener()
- removeScreenRecordingListener(id): void
- Utilities
- clearRecordingCache()

React Hooks

$3

Returns whether the user has granted permission to use the Camera, or not. If the user doesn't grant Camera Permission, you cannot use camera overlay features.

Platform: iOS, Android

Returns: Object with hasPermission boolean and requestPermission function

Example:

`tsx
import { useCameraPermission } from 'react-native-nitro-screen-recorder';

const { hasPermission, requestPermission } = useCameraPermission();

if (!hasPermission) {
return ;
} else {
return ;
}
`

$3

Returns whether the user has granted permission to use the Microphone, or not. If the user doesn't grant Audio Permission, you can still record but without audio.

Platform: iOS, Android

Returns: Object with hasPermission boolean and requestPermission function

Example:

`tsx
import { useMicrophonePermission } from 'react-native-nitro-screen-recorder';

const { hasPermission: canRecordAudio, requestPermission } =
useMicrophonePermission();

// Use in recording configuration
const recordingOptions = {
enableMic: canRecordAudio,
enableCamera: true,
// ... other options
};
`

$3

React hook for monitoring and responding to global screen recording events.

Platform: iOS, Android

Parameters:

- onRecordingStarted?: () => void — Called when a global recording begins.
- onRecordingFinished?: (file?: ScreenRecordingFile) => void — Called after recording ends (with a delay to allow the file to settle).
- onBroadcastPickerShown?: () => void — Called when the broadcast picker on ios is shown.
- onBroadcastPickerDismissed?: () => void — Called with the broadcast picker on ios is dismissed.
- ignoreRecordingsInitiatedElsewhere?: boolean - iOS-onlyallows the listener to only callback when thestartGlobalRecording is called.
- settledTimeMs?: number — Milliseconds to wait after recording end before attempting to retrieve the file. Defaults to 500.

Returns: { isRecording: boolean } — whether a global recording is currently active.

Example:

``tsx
import { useGlobalRecording } from 'react-native-nitro-screen-recorder';

const { isRecording } = useGlobalRecording({
onRecordingStarted: () => console.log('started'),
onRecordingFinished: (file) => {
if (file) {
console.log('finished:', file.path);
}
},
onBroadcastPickerShown: () => {
console.log('Perform some action');
},
onBroadcastPickerDismissed: () => {
console.log('Perform some other action');
},
ignoreRecordingsInitiatedElsewhere: false,
settledTimeMs: 600,
});
`

Permissions

$3

Gets the current camera permission status without requesting permission.

Platform: iOS, Android

Returns: The current permission status for camera access

Example:

`ts
import { getCameraPermissionStatus } from 'react-native-nitro-screen-recorder';

const status = getCameraPermissionStatus();
if (status === 'granted') {
// Camera is available
}
`

$3

Gets the current microphone permission status without requesting permission.

Platform: iOS, Android

Returns: The current permission status for microphone access

Example:

`ts
import { getMicrophonePermissionStatus } from 'react-native-nitro-screen-recorder';

const status = getMicrophonePermissionStatus();
if (status === 'granted') {
// Microphone is available
}
`

$3

Requests camera permission from the user if not already granted. Shows the system permission dialog if permission hasn't been determined.

Platform: iOS, Android

Returns: Promise that resolves with the permission response

Example:

`ts
import { requestCameraPermission } from 'react-native-nitro-screen-recorder';

const response = await requestCameraPermission();
if (response.status === 'granted') {
// Permission granted, can use camera
}
`

$3

Requests microphone permission from the user if not already granted. Shows the system permission dialog if permission hasn't been determined.

Platform: iOS, Android

Returns: Promise that resolves with the permission response

Example:

`ts
import { requestMicrophonePermission } from 'react-native-nitro-screen-recorder';

const response = await requestMicrophonePermission();
if (response.status === 'granted') {
// Permission granted, can record audio
}
`

In-App Recording

$3

Starts in-app screen recording with the specified configuration. Records only the current app's content, not system-wide screen content.

Platform: iOS only

Parameters:

- enableMic: boolean - Whether to enable microphone audio
- enableCamera: boolean - Whether to enable camera overlay
- cameraPreviewStyle: RecorderCameraStyle - Camera positioning and styling
- cameraDevice: CameraDevice - Front or back camera
- onRecordingFinished: (file: ScreenRecordingFile) => void - Callback when recording completes

Example:

`ts
import { startInAppRecording } from 'react-native-nitro-screen-recorder';

await startInAppRecording({
enableMic: true,
enableCamera: true,
cameraPreviewStyle: { width: 100, height: 150, top: 30, left: 10 },
cameraDevice: 'front',
onRecordingFinished: (file) => {
console.log('Recording saved:', file.path);
},
});
`

$3

Stops the current in-app recording and returns the recorded video file. The recording file is also provided through the onRecordingFinished callback.

Platform: iOS only

Returns: Promise that resolves with the recording file or undefined if no recording was active

Example:

`ts
import { stopInAppRecording } from 'react-native-nitro-screen-recorder';

const file = await stopInAppRecording();
if (file) {
console.log('Recording stopped and saved:', file.path);
}
`

$3

Cancels the current in-app recording without saving the video. No file will be generated and onRecordingFinished will not be called.

Platform: iOS only

Example:

`ts
import { cancelInAppRecording } from 'react-native-nitro-screen-recorder';

await cancelInAppRecording(); // Recording discarded, no file saved
`

Global Recording

$3

Starts global screen recording that captures the entire device screen. Records system-wide content, including other apps and system UI.

Platform: iOS, Android

Parameters:

- enableMic: boolean - Whether to enable microphone audio
- onRecordingError: (error: RecordingError) => void - Error callback

Throws:

- Error: If microphone permission is not granted on Android when enableMic is true.

Example:

`ts
import { startGlobalRecording } from 'react-native-nitro-screen-recorder';

startGlobalRecording({
enableMic: true, // enableMic
onRecordingError: (error) => {
console.error('Global recording error:', error.message);
},
});
`

$3

Stops the current global screen recording and returns the saved video file. Because the system may take a short moment to finalize the asset writer output, you can pass an optional delay before retrieval.

Platform: iOS, Android

Parameters:

- options.settledTimeMs?: number — Milliseconds to wait after the broadcast ends before attempting to retrieve the file. Defaults to 500.

Example:

`ts
import { stopGlobalRecording } from 'react-native-nitro-screen-recorder';

const file = await stopGlobalRecording({ settledTimeMs: 1000 });
if (file) {
console.log('Global recording saved:', file.path);
}
`

$3

Retrieves the most recently completed global recording file. Returns undefined if no global recording has been completed.

Platform: iOS, Android

Returns: The last global recording file or undefined if none exists

Example:

`ts
import { retrieveLastGlobalRecording } from 'react-native-nitro-screen-recorder';

const lastRecording = retrieveLastGlobalRecording();
if (lastRecording) {
console.log('Duration:', lastRecording.duration);
console.log('File size:', lastRecording.size);
}
`

Event Listeners

$3

Adds a listener for screen recording events (began, ended, etc.). Returns a cleanup function to remove the listener when no longer needed.

Platform: iOS, Android

Parameters:

- listener: Callback function that receives screen recording events
- ignoreRecordingsInitiatedElsewhere?: boolean - iOS-only allows the listener to only callback when thestartGlobalRecording is called.

Returns: Cleanup function to remove the listener

Example:

``ts
import { useEffect } from 'react';
import { addScreenRecordingListener } from 'react-native-nitro-screen-recorder';

useEffect(() => {
const removeListener = addScreenRecordingListener({
ignoreRecordingsInitiatedElsewhere: false,
listener: (event) => {
console.log('Event type:', event.type, 'Event reason:', event.reason);
},
});

// Clean up listener when component unmounts
return removeListener;
}, []);
`

$3

Adds a listener for iOS broadcast picker status changes (showing & dismissed). Returns a cleanup function to remove the listener when no longer needed. This helps when trying to perform some action on iOS as soon as the broadcast picker is dismissed.

Platform: iOS only (returns no-op cleanup function on Android)

Parameters:

- listener: Callback function that receives broadcast picker presentation events

Returns: Cleanup function to remove the listener

Example:

`ts
import { useEffect } from 'react';
import { addBroadcastPickerListener } from 'react-native-nitro-screen-recorder';

useEffect(() => {
const removeListener = addBroadcastPickerListener((event) => {
console.log('Picker status:', event);

switch (event) {
case 'showing':
console.log('Broadcast picker is showing');
break;
case 'dismissed':
console.log(
'Broadcast picker was dismissed without starting recording'
);
break;
}
});

// Clean up listener when component unmounts
return removeListener;
}, []);
`

Event Types:

- showing: The broadcast picker modal is displayed to the user
- dismissed: The broadcast modal was dismissed without starting recording

Utilities

$3

Clears all cached recording files to free up storage space. This will delete temporary files but not files that have been explicitly saved.

Platform: iOS, Android

Example:

`ts
import { clearRecordingCache } from 'react-native-nitro-screen-recorder';

clearRecordingCache(); // Frees up storage by removing temporary recording files
`

Types

The library exports comprehensive TypeScript types for all functionality:

`ts
// Permission types
export type PermissionStatus = 'denied' | 'granted' | 'undetermined';

export type PermissionResponse = {
canAskAgain: boolean;
granted: boolean;
status: PermissionStatus;
expiresAt: never | number;
};

// Hook types
export interface PermissionState {
hasPermission: boolean;
requestPermission: () => Promise;
}

export type GlobalRecordingHookInput = {
onRecordingStarted?: () => void;
onRecordingFinished?: (file?: ScreenRecordingFile) => void;
settledTimeMs?: number;
};

export type GlobalRecordingHookOutput = {
isRecording: boolean;
};

// Recording configuration
export type RecorderCameraStyle = {
top?: number;
left?: number;
width?: number;
height?: number;
borderRadius?: number;
borderWidth?: number;
};

export type CameraDevice = 'front' | 'back';

// Recording file information
export interface ScreenRecordingFile {
path: string;
name: string;
size: number;
duration: number;
enabledMicrophone: boolean;
}

// Event types
export interface ScreenRecordingEvent {
type: 'global' | 'withinApp';
reason: 'began' | 'ended';
}

export interface RecordingError {
name: string;
message: string;
}
``

Platform Differences

$3

- In-App Recording: Full support with camera overlay
- Global Recording: Full programmatic control including start and stop functionality
- Permissions: Camera and microphone permissions handled automatically
- App Extensions: Uses broadcast extensions for global recording

$3

- In-App Recording: Not supported (use global recording instead)
- Global Recording: Full programmatic control including stop functionality
- Permissions: Microphone permission required for audio recording
- Media Projection: Uses Android's MediaProjection API

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT

---

Made with create-react-native-library