ffmpeg_streamer 0.5.0

A cross-platform Flutter FFI plugin that embeds FFmpeg to decode audio & video and stream raw frames — works on Android, iOS, macOS, Windows & Linux.

0.0.1

• Initial release.
• Added FfmpegDecoder with video and audio rendering support.
• Supported platforms: Android, iOS, macOS, Windows, Linux.

0.1.0

• Added getFrameAtTimestamp method to retrieve a frame at a specific timestamp.
• Added getFrameAtIndex method to retrieve a frame at a specific index.
• Added native C implementation for seeking and frame extraction with thread safety.

0.2.0

• Breaking Changes: Removed callback-based streaming API in favor of synchronous frame retrieval.
• Removed startDecoding, pause, and resume methods - replaced with direct frame access.
• Separated frame retrieval methods into video and audio specific functions:
  • getVideoFrameAtTimestamp and getAudioFrameAtTimestamp
  • getVideoFrameAtIndex and getAudioFrameAtIndex
• Added freeVideoFrame and freeAudioFrame methods for proper memory management.
• Simplified API for more flexible frame-by-frame control.

0.3.0

• Major Update: Added asynchronous API with native threading for high-performance video decoding.
• Added getFrameAtIndexAsync method for non-blocking frame retrieval with callbacks.
• Added getFramesRangeByIndexAsync method for ultra-fast batch frame decoding (87% faster than sequential calls).
• Implemented native pthread-based worker thread for zero UI blocking.
• Added cancelRequest method to cancel pending asynchronous decode operations.
• Added progress callbacks for batch operations to track decoding progress in real-time.
• Performance improvement: Decoding 100 frames reduced from ~15s to ~2s using batch API.
• Updated example app with play/pause functionality and optimized playback mode.
• Added frame scrubbing with slider control in example app.
• Maintained backward compatibility with existing synchronous API.

0.3.1

• Fix Warnings

0.4.0

• New High-Level API: Added FFmpegService - a simplified service layer that abstracts away decoder complexity.
• Intelligent Batch Management: Introduced FrameBatchManager with automatic frame caching and smart preloading:
  • Automatic batch loading and memory management
  • LRU (Least Recently Used) cache eviction strategy
  • Predictive preloading of adjacent batches for smooth playback
  • Configurable batch sizes and cache limits
  • Real-time cache statistics (batches, frames, memory usage)
• Batch Configuration Presets: Added BatchConfigPresets with 7 predefined configurations:
  • standard - Balanced for most use cases (~1.25 GB for 1080p)
  • highPerformance - Optimized for smooth playback (~2.5 GB for 1080p)
  • memoryEfficient - For limited devices (~375 MB for 1080p)
  • video4K - Optimized for 4K videos (~1.5 GB)
  • scrubbing - For timeline navigation (~2 GB for 1080p)
  • editing - Workflow optimized (~1.5 GB for 1080p)
  • slowMotion - For frame analysis (~1 GB for 1080p)
• Automatic Configuration Selection: getRecommendedConfig() method automatically selects optimal settings based on video resolution and available memory.
• Enhanced Video Metadata: New VideoMetadata class with comprehensive video information.
• Memory Estimation Tools: Added methods to estimate memory usage for different configurations and resolutions.
• Simplified Example App: Completely refactored example app to use FFmpegService:
  • Reduced code complexity by 35% (~220 lines removed)
  • Automatic batch management with no manual configuration needed
  • Real-time cache statistics display
  • Cleaner, more maintainable code structure
• Batch Loading Events: Stream-based event system for monitoring batch operations (loading, progress, completion, failures).
• Better Resource Management: Automatic cleanup of distant batches based on current playback position.
• Export Organization: All new services properly exported in main library file for easy access.

0.5.0

• 🎵 MAJOR UPDATE: Full Audio Support in Batch Operations

  • Native C implementation now decodes both video AND audio in a single optimized range request
  • FrameBatchManager now maintains separate video and audio batch caches with perfect synchronization
  • MediaFrame objects returned by batch operations now contain both video and audio data
  • VideoFrameData class now includes optional audio field with complete audio frame data
  • Added hasAudio property to VideoFrameData for easy audio presence checking

• 🔧 Memory Management Improvements

  • CRITICAL FIX: Fixed memory leak in FfmpegDecoder where userData pointers were never freed after async callbacks
  • Added freeUserData() method to properly release allocated FFI pointers
  • All async requests (single frame, range requests, progress callbacks) now properly free their native memory
  • Improved error handling to ensure memory is freed even when requests are cancelled or fail
  • FrameBatchManager now properly tracks and cancels all active requests on disposal

• 🚀 Native Code Enhancements

  • process_video_range_task() now intelligently detects audio streams and decodes audio at matching timestamps
  • Added process_audio_range_task() for dedicated audio-only range decoding
  • Optimized audio/video synchronization with automatic timestamp alignment
  • Added position restoration in case of audio decode failures to prevent stream corruption
  • New TASK_AUDIO_RANGE task type for dedicated audio batch operations

• 📦 Batch System Architecture Improvements

  • Introduced VideoBatch and AudioBatch classes for separate cache management
  • Dual-cache system (_videoBatchCache and _audioBatchCache) for optimal memory layout
  • Frames indexed by native frameId ensuring perfect alignment between video and audio
  • Single optimized range request retrieves both streams simultaneously (one seek, sequential decode)
  • LRU eviction now cleans up both video and audio batches together

• 🎯 API Improvements

  • getFramesRangeByIndexAsync() now supports both video and audio in a single call
  • Added getAudioFramesRangeByIndexAsync() for audio-only batch operations (when needed)
  • VideoFrameData.fromMediaFrame() factory properly extracts and includes audio data
  • Enhanced progress callbacks now accurately track combined video+audio loading

• 🔍 Better Async Request Handling

  • Range requests now correctly wait for both video AND audio frames before invoking callbacks
  • Improved _checkAndInvokeCallback() logic to handle video-only, audio-only, and combined requests
  • Fixed race conditions in multi-frame batch loading with proper completion tracking
  • Added rangeComplete flag for proper cleanup of range request resources

• 🛠️ FFI Bindings Updates

  • Added NativeFfmpegGetAudioFramesRangeAsync and DartFfmpegGetAudioFramesRangeAsync type definitions
  • New getAudioFramesRangeAsync binding for native audio range decoding
  • All bindings properly linked to native C functions

• ✨ Quality of Life

  • Cache statistics now report both video and audio frame counts separately
  • Improved debug logging shows video and audio frame counts in batch operations
  • Better timeout handling with clear warnings when frames fail to load
  • Enhanced error messages for troubleshooting batch loading issues

• ⚠️ Breaking Changes

  • VideoFrameData constructor now accepts optional audio parameter
  • FrameBatch class split into VideoBatch and AudioBatch (internal API only)
  • FrameBatchManager.getFrame() now returns complete MediaFrame with audio (previously video-only)