Version 0.1.2 — Debug logging, batch size argument

README.md

@@ -51,15 +51,39 @@ cd viteo
 pip install -v -e .
 ```
 
-#### Rebuilding
-
+To rebuild after changes:
 ```bash
-rm -rf dist/
 pip install -e . --force-reinstall --no-deps
 ```
 
-### Requirements
+## Configuration
+### Logging
+
+You can enable debug logging with the `VITEO_DEBUG` environment variable:
+```bash
+$ VITEO_DEBUG=1 python example.py video_1080p.mp4
+
+[viteo] Closed video resources
+[viteo] Loaded asset from: tests/test-data/video_1080p.mp4
+[viteo] Found 1 video track(s)
+[viteo] Video metadata: 1920x1080 @ 23.976 fps, 267 total frames
+[viteo] Allocated batch buffer for 16 frames
+[viteo] Created track output with hardware acceleration
+[viteo] Reader initialized successfully
+  ...
+```
+
+### Batch size
+
+Internally, `viteo` passes frames to Python in batches for performance.
+The default batch size is 8 frames, but you can change it by passing the `batch_size` argument:
+```python
+# Values between 2 and 16 are optimal
+with viteo.open("video.mp4", batch_size=2) as frames:
+    for frame in frames:
+        process(frame)
+```
+
+## Performance
 
-- macOS with Apple Silicon (M1/M2/M3/M4)
-- Python 3.8+
-- MLX framework
+<img width="3568" height="2068" alt="benchmark_comparison" src="https://github.com/user-attachments/assets/51a7c00c-8777-4ccc-a7fb-8ae69f156afe" />

src/native/include/frame_extractor.h

@@ -10,7 +10,7 @@ namespace viteo {
 /// High-performance video frame extractor for Apple Silicon
 class FrameExtractor {
 public:
-    FrameExtractor();
+    FrameExtractor(size_t batch_size = 8);
     ~FrameExtractor();
 
     /// Open video file for extraction

src/native/src/bindings.cpp

@@ -30,7 +30,7 @@ NB_MODULE(_viteo, m) {
     m.doc() = "Hardware-accelerated video frame extraction for Apple Silicon";
 
     nb::class_<FrameExtractor>(m, "FrameExtractor")
-        .def(nb::init<>(), "Create new frame extractor")
+        .def(nb::init<size_t>(), nb::arg("batch_size") = 8, "Create new frame extractor")
         .def("open", &FrameExtractor::open, nb::arg("path"),
             "Open video file for extraction")
         .def("next_frame",
@@ -40,6 +40,7 @@ NB_MODULE(_viteo, m) {
                     nb::gil_scoped_release release;
                     frame_data = self.next_frame();
                 }
+                if (!frame_data) return nb::none();
                 return create_mlx_array(frame_data, self.height(), self.width());
             },
             "Get next frame as MLX array (None when done)")