v0.0.6

What's New

• buffer_size parameter for stream decoding — read_frames_from_stream now accepts a buffer_size parameter to control PyAV's internal read buffer size. Smaller values reduce latency when streaming frames in real-time. Default is 32768 (PyAV default).
• Version bump to 0.0.6

v0.0.5

What's New

• thread_type parameter: Added configurable PyAV thread type ("AUTO", "FRAME", "SLICE", or "NONE") to read_frames_exact and read_frames_from_stream for decoding performance tuning.
• Version bump to 0.0.5.

v0.0.4

What's New

• Python 3.8+ Support: Now supports Python 3.8, 3.9, 3.10, 3.11, 3.12, and 3.13
• Multi-version CI Testing: Test matrix covers all supported Python versions

Changes

• Use typing.Optional, Union, Tuple, Generator for Python 3.8 compatibility
• Remove zip(strict=) for Python 3.9 compatibility

v0.0.3

What's Changed

• Stream frames directly without buffering entire video
• Expose video_metadata_from_container as public API
• Remove unused import

Full Changelog: v0.0.2...v0.0.3

v0.0.2 - Time-based extraction and improved seeking

🎯 What's New

Time-Based Extraction

• New parameters: start_time and end_time (in seconds) for read_frames_exact()
• Supports both frame-based (start_frame/end_frame) and time-based extraction
• Parameters are mutually exclusive - use either frames or time, not both

Improved Seeking Accuracy

• Fixed critical bug: Corrected frame counting after seeking operations
• Conservative seeking: Only seeks if target is 3+ seconds from start
• Pixel-perfect accuracy: Verified against ffmpeg/ffprobe ground truth
• Efficient file handling: Seeks directly in file without processing earlier frames

Code Quality

• Refactored read_frames_exact with helper functions for better readability
• Reduced main function from 97 lines to 35 lines
• Comprehensive documentation explaining seeking behavior
• Proper FPS validation (errors instead of defaulting to 30 fps)

Testing

• Added 6 new tests for time-based extraction
• Added 5 regression tests comparing against ffmpeg/ffprobe
• All 39 tests passing with pixel-perfect frame matching

📦 Usage Examples

Time-based extraction

```python
from simple_video_utils.frames import read_frames_exact

Extract frames from 1.5 to 3.0 seconds

frames = list(read_frames_exact("video.mp4", start_time=1.5, end_time=3.0))
```

Frame-based extraction (existing)

```python

Extract frames 0-10

frames = list(read_frames_exact("video.mp4", start_frame=0, end_frame=10))
```

🔧 Technical Details

• Helper functions: _validate_parameters, _convert_time_to_frames, _normalize_frame_range, _calculate_seek_position
• Relative frame counting from seek position ensures accurate extraction
• Conservative seeking strategy avoids keyframe landing precision issues

✅ Validation

All implementations validated against ffmpeg/ffprobe for:

• Metadata extraction
• Frame extraction from start
• Frame extraction with seeking
• Time-based vs frame-based equivalence
• Single frame extraction

Full Changelog: v0.0.1...v0.0.2

v0.0.1 - Initial Release

Initial Release

Simple Video Utils provides lightweight utilities for extracting frames and metadata from videos, built for sign language processing workflows.

Features

• Video Metadata Extraction

  • video_metadata() - Extract metadata from video files or URLs
  • video_metadata_from_bytes() - Extract metadata from video bytes

• Frame Extraction

  • read_frames_exact() - Read specific frame ranges from videos
  • read_frames_from_stream() - Read frames from file-like objects

• Format Support

  • MP4, WebM, and other formats via PyAV
  • Remote URLs
  • Stream-based processing

Installation

pip install simple-video-utils

Testing

• 27 comprehensive tests covering all functionality
• Ruff linting passing
• Test assets included for various video formats