Enterprise-grade storage performance validation tool designed to accurately measure I/O performance for video workloads, media production, and data center infrastructure.
Evolved from the original Tuxera/SGI implementation into a modern, multi-platform solution with comprehensive error tracking, filesystem detection, and professional CI/CD infrastructure.
- Video-Centric Benchmarking: Tests actual video frame I/O patterns, not generic block I/O
- Cross-Platform: Single tool for macOS, Linux, and Windows
- Production-Ready: Error tracking, filesystem detection, comprehensive diagnostics
- Easy to Use: Pre-built binaries, Homebrew installation, simple CLI
- Well-Documented: 2000+ lines of comprehensive documentation
- Community-Focused: Open governance, clear contribution path, professional standards
macOS (Homebrew)
brew tap ssotoa70/vframetest https://github.com/ssotoa70/vframetest
brew install vframetest
vframetest --versionLinux & Windows - Download pre-built binaries
# Create test directory
mkdir -p test-data
# Run 100 FULLHD frames on 4 threads
vframetest -w FULLHD-24bit -t 4 -n 100 test-data
# Expected output:
# Frames failed: 0
# Frames succeeded: 100
# Success rate: 100.00%
# Filesystem: LOCAL
# [Performance metrics...]- ✅ Frame-Based Testing - Accurate video workload simulation
- ✅ Multi-Threading - Configurable parallel testing (1-16+ threads)
- ✅ Multiple Profiles - SD, HD, FULLHD, 4K, 8K, DPX, EXR + custom resolutions
- ✅ Rich Metrics - FPS, throughput (MiB/s), completion times
- ✅ Real-Time TUI - Live dashboard with progress, latency histogram, and metrics
- ✅ Interactive Mode - Configuration menu for test parameters
- ✅ Comprehensive Error Capture - errno tracking, frame-level detail
- ✅ Success Rate Metrics - Per-frame success/failure counting
- ✅ Filesystem Detection - LOCAL, SMB, NFS, OTHER types
- ✅ Remote FS Warnings - Alerts for network storage limitations
- ✅ Direct I/O Checking - Availability detection per platform
- ✅ Graceful I/O Fallback - Automatic Direct I/O → Buffered I/O fallback
- ✅ Per-Frame I/O Tracking - Track which frames used Direct vs Buffered I/O
- ✅ Enhanced Error Reporting - Error statistics and per-operation breakdown
- ✅ CSV/JSON Error Export - Detailed error data with timestamps
- ✅ Fallback Statistics - Direct I/O success rate and fallback metrics
- ✅ Automatic NFS/SMB Optimization - Skip Direct I/O on remote filesystems
- ✅ Performance Trend Analysis - Track improving/stable/degrading performance
- ✅ Network Timeout Handling - Configurable timeouts for network filesystems
- ✅ Performance Metrics - Min/max/avg frame times with trend analysis
- ✅ Enhanced Output - CSV and JSON include optimization metrics
- ✅ DPX Profiles - 10/12-bit professional uncompressed (DPX-2K, DPX-FULLHD, DPX-4K, DPX-8K)
- ✅ EXR Profiles - Half/float-precision professional formats (EXR-FULLHD, EXR-4K, EXR-8K)
- ✅ Profile Filtering -
--list-profiles-filterfor finding profiles by name - ✅ Byte Size Display - Raw and aligned sizes in
--list-profilesoutput
- ✅ Multi-Platform - macOS (arm64/x86_64), Linux, Windows (x86_64/i686)
- ✅ CI/CD Automation - GitHub Actions with multi-platform builds
- ✅ Integration Tests - Real filesystem I/O tests (27 test cases)
- ✅ Package Management - Homebrew on macOS, pre-built binaries elsewhere
- ✅ Output Formats - Text, CSV, JSON, histograms
- ✅ Extensive Documentation - 2000+ lines of guides and references
| Aspect | Details |
|---|---|
| Platforms | macOS 10.13+, Linux (x86_64), Windows 10+ |
| Architectures | arm64, x86_64, i686, universal (macOS) |
| Frame Sizes | SD (720×480), HD (1280×720), FULLHD (1920×1080), 4K, 8K, custom |
| Threading | 1 to 16+ concurrent threads |
| Filesystems | LOCAL, SMB/CIFS, NFS, others (with detection) |
| Output Formats | Text, CSV, JSON, histograms, per-frame timing |
Start Here:
- Quick Start - Get up and running in 2 minutes
- Installation Guide - All installation methods
- Usage Guide - Complete feature documentation
Learn More:
- Architecture & Design - Technical deep dive
- Project Evolution - History from original to modern
- Feature Guide - Complete feature reference (600+ lines)
- FAQ - Common questions and troubleshooting
Project Info:
- Contributing - How to contribute
- Code of Conduct - Community guidelines
- Governance - Decision-making framework
- Roadmap - Future features and vision
- Security - Security considerations
Reference:
- Repository Structure - File organization
- Changelog - Version history
- Phase 1 Completion - Technical report
- Phase 3 Completion - NFS/SMB Optimization report
# Comprehensive test: 1000 FULLHD frames, 4 threads, all metrics
vframetest -w FULLHD-24bit -t 4 -n 1000 /mnt/storage# Save baseline
vframetest -c -w FULLHD-24bit -t 2 -n 500 /mnt/storage > baseline.csv
# Compare against current (use diff or graphical tools)
vframetest -c -w FULLHD-24bit -t 2 -n 500 /mnt/storage > current.csv# Test SMB share (vframetest auto-detects and warns about remote FS)
vframetest -w FULLHD-24bit -t 2 -n 100 //nas-server/share
# Output will include:
# WARNING: Test path is on a remote filesystem
# Direct I/O may not be available. Results may not be accurate.# Export results for dashboards and analysis
vframetest -j -w FULLHD-24bit -t 4 -n 100 /mnt/storage > results.json
# Parse and process with Python/Node.js for custom analytics- C99 compiler (gcc, clang)
- POSIX threads (pthread)
- Make (GNU make preferred)
- Git (for version tracking)
git clone https://github.com/ssotoa70/vframetest.git
cd vframetest
make clean && make -j4
./build/vframetest --version# macOS
make clean && make -j4
# Linux
make clean && make -j4
# Windows (requires MinGW)
make win64 # 64-bit
make win # 32-bitFor detailed build instructions, see BUILD.
# Unit tests (mocked I/O)
make test
# Integration tests (real filesystem I/O)
make test-integration
# Run both
make test-allProfile: FULLHD-24bit
Results write:
frames: 100
bytes : 6254368000
time : 2900600000 ns
fps : 344.5
B/s : 2155000000
MiB/s : 2055.34
Completion times:
min : 2.1 ms
avg : 5.8 ms
max : 12.3 ms
Frames failed: 0
Frames succeeded: 100
Success rate: 100.00%
Filesystem: LOCAL
We welcome contributions! See CONTRIBUTING.md for:
- Development setup
- Code standards
- Pull request process
- Reporting issues
- Suggesting features
Community Standards: All contributors must follow our Code of Conduct
- ✅ Real-Time Dashboard - Live progress, metrics, and latency visualization
- ✅ Interactive Configuration Menu - Keyboard-driven test setup with all 17 profiles
- ✅ Multi-Tab Interface - Dashboard, History, Latency, Config views
- ✅ Smart Metrics - Elapsed/ETA/Total time, throughput (dual MiB/s + MB/s), data rates
- ✅ Performance Trends - Visual indicators (↗ Improving, → Stable, ↘ Degrading)
- ✅ I/O Visualization - Bar charts showing Direct vs Buffered I/O breakdown
- ✅ Frame Profile Support - All 17 profiles with category filtering (Standard/DPX/EXR)
- ✅ Help System - Comprehensive keyboard shortcut reference overlay
- ✅ Cross-Platform - Works on macOS, Linux, Windows; compatible with SSH
- ✅ HTTP Server - Socket-based implementation, zero external dependencies
- ✅ Data Access Layer - Thread-safe metrics collection with circular buffers
- ✅ Data Export - JSON and CSV formatters for structured output
- ✅ API Stubs - 12 planned endpoint handlers ready for Phase 5 implementation
- ✅ Cross-Platform - Windows, Linux, macOS compatible
- ✅ Code Quality - Cross-platform compatibility fixes and refinements
- ✅ Windows Build - Fixed snprintf truncation warnings, all platforms green
- ✅ Testing Framework - Integration tests with real filesystem I/O
- ✅ CI/CD Pipeline - GitHub Actions validating all platforms
| Phase | Status | Features |
|---|---|---|
| Phase 1 | ✅ Complete | Error tracking, filesystem detection, success metrics |
| Phase 2 | ✅ Complete | Graceful I/O fallback, error export, detailed reports |
| Phase 3 | ✅ Complete | NFS/SMB optimization detection, performance analysis |
| v25.13.1 | ✅ Complete | DPX/EXR profiles, profile filtering, byte size display |
| Phase 4A | ✅ Complete | TUI real-time dashboard, interactive monitoring, SSH-compatible |
| Phase 4B | ✅ Complete | REST API foundation, data layer, JSON/CSV export |
| Phase 4C | ✅ Complete | Cross-platform testing, Windows fixes, integration tests |
| Future | 🔮 Vision | Web dashboard, distributed testing, cloud integration |
Current Version: 25.17.4 (Phase 4: Complete - TUI, REST API, Integration) Latest Release: v25.17.4
- Issues & Bugs: GitHub Issues
- Discussions: GitHub Discussions
- Documentation: Complete Guides
- Wiki: Community Wiki
GNU General Public License v2 - See COPYING for details.
Origin: Extended from original Tuxera Inc. / SGI implementation Modern Fork: Enhanced with multi-platform support, comprehensive error tracking, and professional infrastructure
- Original: Tuxera Inc. / SGI for foundational frame-based testing approach
- Phase 4A Architecture: Special thanks to AnxietyLab for architecting the TUI Real-Time Dashboard that powers v25.15.0 and shaped Phase 4's vision
- Contributors: Community members who have contributed fixes, features, and ideas
- Users: Thank you for using and improving vframetest
See CONTRIBUTORS.md for detailed recognition of architectural and design contributions.
Repository: ssotoa70/vframetest Latest Release: v25.17.4 Documentation: Complete Guides | Wiki | FAQ