A React Native library for intelligent video processing with native performance. Supports video analysis, quality-preserving format conversion, and smart recompression with customizable settings.
npm install react-native-video-recompression


A React Native library for intelligent video processing with native performance. Features accurate bitrate analysis, smart MOVโMP4 rewrapping, and bitrate-aware compression decisions optimized for mobile chat applications and media sharing.
- ๐ง Smart Processing: Intelligent decision engine chooses optimal strategy (passthrough/rewrap/recompress)
- ๐ Accurate Bitrate Analysis: Real track-level bitrate detection, not file-size estimates
- ๐ฑ iOS Camera Roll Optimization: Fast MOVโMP4 rewrapping for iPhone videos
- โก Performance First: Container rewrapping vs slow transcoding when possible
- ๐ฏ Chat App Ready: Bitrate-aware decisions for messaging apps (2Mbps/192kbps thresholds)
- ๐น Enhanced Codec Detection: H.264, HEVC, VP8, VP9, AV1, AAC, MP3, Opus support
- ๐ Deep Video Analysis: Comprehensive metadata extraction with format details
- ๐ฑ Cross Platform: Consistent behavior across iOS and Android
``bash`
npm install react-native-video-recompressionor
yarn add react-native-video-recompression
`bash`
cd ios && pod install
No additional setup required - auto-linking handles everything!
bash
npm test
`$3
`bash
npm run build
npm run validate
`$3
Create a new React Native app and install the library:`bash
Create new RN app
npx react-native@0.72.7 init VideoTestAppInstall the library
cd VideoTestApp
npm install react-native-video-recompressioniOS setup
cd ios && pod install && cd ..Test on devices
npm run ios
npm run android
`For detailed testing instructions, see TESTING.md.
Usage
`javascript
import VideoRecompression from 'react-native-video-recompression';// Initialize and test the module
const initializeModule = async () => {
try {
const info = await VideoRecompression.init();
console.log('Module initialized:', info);
// Output: { platform: 'ios', version: '0.9.4', capabilities: ['video_analysis', 'smart_compression', ...] }
} catch (error) {
console.error('Module initialization failed:', error);
}
};
// Analyze video file with accurate bitrate detection
const analyzeVideo = async (videoPath) => {
try {
const videoInfo = await VideoRecompression.analyzeVideo(videoPath);
console.log('Video analysis:', videoInfo);
// Output: {
// container: 'mov',
// videoCodec: 'h264',
// audioCodec: 'aac',
// width: 1920, height: 1080, duration: 30.5,
// videoBitrate: 1800000, // Actual bitrate from track metadata
// audioBitrate: 128000, // Actual bitrate from track metadata
// frameRate: 30.0, fileSize: 45000000
// }
} catch (error) {
console.error('Video analysis failed:', error);
}
};
// Smart video processing for chat apps (iPhone MOV โ MP4 example)
const processVideoForChat = async (inputPath, outputPath) => {
try {
const result = await VideoRecompression.processVideo(
inputPath, // '/path/to/iPhone_video.mov'
outputPath, // '/path/to/chat_optimized.mp4'
{
// Chat optimization settings
videoBitrate: 800000, // 800kbps for messaging
audioBitrate: 128000, // 128kbps for messaging
videoCodec: 'h264', // Universal compatibility
audioCodec: 'aac', // Universal compatibility
maxWidth: 1280, // Limit resolution for chat
maxHeight: 720,
optimizeForNetwork: true
},
(progress) => {
console.log(
Processing: ${Math.round(progress * 100)}%);
}
);
console.log('Processing result:', result);
// For iPhone MOV with H.264+AAC and reasonable bitrate:
// {
// outputPath: '/path/to/chat_optimized.mp4',
// action: 'rewrap', // Fast container conversion!
// processingTime: 2500, // ~2.5 seconds vs 30+ for recompression
// originalInfo: { fileSize: 45000000, videoBitrate: 1800000 },
// finalInfo: { fileSize: 45000000, videoBitrate: 1800000 } // Same quality
// }
} catch (error) {
console.error('Video processing failed:', error);
}
};
`API
$3
Initializes the module and returns platform information.
Returns:
- Promise
platform: 'ios' | 'android'
- version: Module version
- capabilities: Array of supported features$3
Analyzes a video file and returns comprehensive information about its properties.
Parameters:
-
filePath (string): Absolute path to the video fileReturns:
- Promise: Detailed video information including:
-
container: File format (mp4, mov, avi, etc.)
- videoCodec: Video codec (h264, hevc, vp8, vp9, av1, etc.)
- audioCodec: Audio codec (aac, mp3, opus, vorbis, flac, etc.)
- width, height: Video dimensions
- duration: Duration in seconds
- videoBitrate, audioBitrate: Accurate bitrates from track metadata (not estimates)
- frameRate: Frames per second
- fileSize: File size in bytes$3
Intelligently processes video with optimal strategy selection (passthrough, rewrap, or recompress).
Parameters:
-
inputPath (string): Absolute path to input video
- outputPath (string): Absolute path for output video
- settings (optional): Compression settings object
- onProgress (optional): Progress callback function (0.0 to 1.0)Returns:
- Promise: Processing result including:
-
outputPath: Path to processed video
- action: Strategy used ('passthrough' | 'rewrap' | 'recompress')
- originalInfo: Input video information
- finalInfo: Output video information
- processingTime: Processing time in millisecondsProcessing Strategies:
- Passthrough: File already meets target requirements (codecs + bitrates optimal)
- Rewrap: Fast container conversion (MOVโMP4) preserving video/audio quality
- Recompress: Full transcoding when bitrates exceed thresholds or wrong codecs
Smart Decision Logic:
- Video Threshold: 2 Mbps (recompress if higher for chat optimization)
- Audio Threshold: 192 kbps (recompress if higher for chat optimization)
- iPhone MOV Files: H.264+AAC with reasonable bitrate โ rewrap to MP4 (seconds vs minutes)
- High Bitrate Videos: Automatic recompression with target settings
- Already Optimal: Instant passthrough with file copy
๐ฏ Chat Application Use Cases
Perfect for messaging apps like WhatsApp, Telegram, or custom chat applications:
`javascript
// iPhone camera roll video optimization
const optimizeForChat = async (cameraRollVideoPath) => {
const analysis = await VideoRecompression.analyzeVideo(cameraRollVideoPath);
// Typical iPhone video: MOV container, H.264 video, AAC audio
if (analysis.container === 'mov' &&
analysis.videoCodec === 'h264' &&
analysis.videoBitrate <= 2000000) {
// Result: Fast rewrap (2-5 seconds) instead of slow recompression (30+ seconds)
const result = await VideoRecompression.processVideo(input, output, {
videoBitrate: 800000, // 800kbps for chat
audioBitrate: 128000 // 128kbps for chat
});
console.log(result.action); // 'rewrap' - preserves quality, changes container
}
};
`Features
- ๐ง Smart Bitrate-Aware Processing: Decisions based on actual track bitrates, not file size estimates
- ๐ฑ iPhone MOV Optimization: Fast rewrapping for iOS camera roll videos (MOVโMP4)
- โก Performance Optimized: Container rewrapping (seconds) vs full transcoding (minutes)
- ๐ฏ Chat App Ready: Pre-configured thresholds for messaging applications (2Mbps/192kbps)
- ๐ Accurate Video Analysis: Real bitrate detection using MediaExtractor (Android) & AVAssetTrack (iOS)
- ๐ Enhanced Codec Detection: H.264, HEVC, VP8, VP9, AV1, AAC, MP3, Opus, Vorbis, FLAC
- โ
Quality Preservation: Lossless format conversion when recompression isn't needed
- โ๏ธ Custom Compression: Fine-tune quality, bitrate, resolution, and codec settings
- ๐ Progress Callbacks: Real-time progress updates for long-running operations
- ๐ฑ Cross Platform: Consistent behavior and feature parity across iOS and Android
- ๐ Background Processing: Non-blocking operations using background threads/queues
- ๐ Zero Configuration: Works out of the box with React Native autolinking
- ๐ TypeScript Support: Full TypeScript definitions included
- ๐น Multiple Formats: Support for MP4, MOV, AVI, WEBM, and other common video formats
Use Cases
- ๐ฑ Chat Applications: Optimize iPhone MOV videos for messaging with fast rewrapping
- ๐ Format Conversion: Convert between video formats while preserving quality
- ๐ File Size Optimization: Reduce video file sizes for storage or network transmission
- ๐ Video Analysis: Extract accurate metadata and bitrate information from video files
- โ๏ธ Quality Adjustment: Change video quality, resolution, or codec for specific requirements
- ๐ Batch Processing: Process multiple videos with consistent settings and smart decisions
Technical Details
$3
- Uses AVFoundation framework with AVAssetExportSession and AVAssetTrack
- Accurate Bitrate Detection: Uses estimatedDataRate property from tracks (not file-size estimation)
- Smart Strategy Selection:
- Passthrough: File already meets target codec and bitrate requirements
- Rewrap: Uses AVAssetExportPresetPassthrough for fast container conversion (MOVโMP4)
- Recompress: Uses quality presets when bitrates exceed thresholds (2Mbps video, 192kbps audio)
- Enhanced Codec Detection: CMFormatDescription analysis for H.264, HEVC, VP8, VP9, AV1, AAC, MP3, Opus
- Decision Logging: Comprehensive logging of bitrate analysis and processing decisions
- Background processing on dedicated queues to avoid UI blocking$3
- Uses MediaExtractor, MediaMuxer, and MediaMetadataRetriever for comprehensive analysis
- Accurate Bitrate Detection: MediaExtractor track-level analysis using MediaFormat.KEY_BIT_RATE
- Smart Strategy Selection:
- Passthrough: File meets target requirements (codecs + bitrates within thresholds)
- Rewrap: Container format change using MediaMuxer without reencoding (MOVโMP4)
- Recompress: Full transcoding with MediaCodec when bitrates exceed chat thresholds
- Enhanced Codec Detection: MIME-type analysis for H.264, HEVC, VP8, VP9, AV1, AAC, MP3, Opus, Vorbis, FLAC
- Decision Logging: Detailed bitrate analysis and processing strategy logging
- Kotlin coroutines for asynchronous background processing$3
- Smart Decision Engine: Bitrate-aware processing prevents unnecessary recompression
- Fast MOVโMP4 Rewrapping: Container conversion in seconds vs transcoding in minutes
- Lazy Loading: Efficient native module initialization
- Memory-Efficient Streaming: Optimized for large video files without memory spikes
- Automatic Resource Cleanup: Proper disposal of MediaExtractor, AVAsset, and codec resources
- Track-Level Analysis: Direct format inspection instead of full file processingRequirements
- React Native 0.60+
- iOS 11.0+
- Android API Level 21+
Testing
Before using in production, test the library with real video files:
`bash
Create test video files (requires FFmpeg)
./scripts/create-test-videos.shRun example app for interactive testing
yarn example:ios # iOS
yarn example:android # AndroidRun unit tests
yarn test
``See TESTING.md for comprehensive testing guide.
See the contributing guide to learn how to contribute to the repository and the development workflow.
MIT
---
Made with create-react-native-library