Skip to content

ssotoa70/vframetest

BranchesTags

Repository files navigation

vframetest - Professional Frame-Based Storage I/O Benchmark

CI/CD GitHub Release License

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.

🎯 Why vframetest?

  • 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

🚀 Quick Start

Installation

macOS (Homebrew)

brew tap ssotoa70/vframetest https://github.com/ssotoa70/vframetest
brew install vframetest
vframetest --version

Linux & Windows - Download pre-built binaries

Basic Test

# 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...]

📊 Key Features

Core Benchmarking

  • ✅ 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

Phase 1: Error Tracking & Diagnostics

  • ✅ 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

Phase 2: I/O Fallback & Enhanced Reporting

  • ✅ 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

Phase 3: NFS/SMB Optimization Detection

  • ✅ 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

Professional Frame Formats (v25.13.1+)

  • ✅ 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-filter for finding profiles by name
  • ✅ Byte Size Display - Raw and aligned sizes in --list-profiles output

Professional Infrastructure

  • ✅ 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

📈 Supported Configurations

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

📚 Documentation

Start Here:

Learn More:

Project Info:

Reference:

💡 Common Use Cases

Storage Validation

# Comprehensive test: 1000 FULLHD frames, 4 threads, all metrics
vframetest -w FULLHD-24bit -t 4 -n 1000 /mnt/storage

Performance Regression Detection

# 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

Network Storage Analysis

# 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.

JSON Export for Automation

# 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

🔧 Building from Source

Requirements

  • C99 compiler (gcc, clang)
  • POSIX threads (pthread)
  • Make (GNU make preferred)
  • Git (for version tracking)

Quick Build

git clone https://github.com/ssotoa70/vframetest.git
cd vframetest
make clean && make -j4
./build/vframetest --version

Platform-Specific

# macOS
make clean && make -j4

# Linux
make clean && make -j4

# Windows (requires MinGW)
make win64        # 64-bit
make win          # 32-bit

For detailed build instructions, see BUILD.

Running Tests

# Unit tests (mocked I/O)
make test

# Integration tests (real filesystem I/O)
make test-integration

# Run both
make test-all

📊 Example Output

Profile: 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

🤝 Contributing

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

Phase 4A: Real-Time TUI Dashboard (v25.15.0-25.16.0)

  • ✅ 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

Phase 4B: REST API Foundation (v25.16.0)

  • ✅ 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

Phase 4C: Testing & Integration (v25.16.0)

  • ✅ 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

📈 Project Status

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

📞 Support & Community

📜 License

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

🙏 Acknowledgments

  • 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

About

No description or website provided.

Topics

benchmark vast-data vast-tool

Resources

Readme

License

GPL-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 14

v25.17.4 - Critical Latency Calculation Fix Latest
Feb 11, 2026
+ 13 releases

Packages

 
 
 

Contributors

Languages