mez-validator

MEZ Validator

A command-line tool for validating fMP4 mezzanine segment files generated by the avpipe transcoding system.

Overview

The MEZ validator checks fMP4 (fragmented MP4) mezzanine files for compliance with expected patterns and standards. It validates:

• Uniform Sample Durations: All samples within each track have consistent duration
• Sequential MFHD Sequence Numbers: Movie Fragment Header sequence numbers start from 1 and increment sequentially
• TFDT Base Media Decode Time: First fragment starts at time zero, subsequent fragments follow cumulative sample duration pattern
• Bitrate Validation: Validates that the calculated average bitrate falls within specified minimum and maximum limits
• Average Bitrate Calculation: Automatically calculates and reports average bitrate based on file size and duration

Installation

Build the validator from the avpipe project root:

cd avpipe/
go build -o bin/mez-validator ./cmd/mez-validator

Usage

Basic Usage

# Validate a single file
./bin/mez-validator video-mez-segment-1.mp4

# Validate all MP4 files in a directory
./bin/mez-validator ./mez_output/

# Display help and options
./bin/mez-validator -h

Command-Line Options

mez-validator [options] <mp4file_or_directory>

Options:
  -min-bitrate int
        minimum bitrate in kbps (default 10)
  -max-bitrate int
        maximum bitrate in kbps (default 100000)

Examples with Bitrate Validation

# Validate with specific bitrate range
./bin/mez-validator -min-bitrate 500 -max-bitrate 2000 video-segment.mp4

# Validate directory with strict bitrate limits
./bin/mez-validator -min-bitrate 1000 -max-bitrate 5000 ./segments/

Output Format

The validator outputs JSON reports for each validated file:

{
  "pass": true,
  "filename": "video-mez-segment-1.mp4",
  "sample_count": 840,
  "common_sample_duration": 3600,
  "common_duration_seconds": 0.04,
  "timescale": 90000,
  "total_duration": 3024000,
  "total_duration_seconds": 33.6,
  "file_size": 506271,
  "average_bitrate_kbps": 121
}

Output Fields

• pass: true if file passes all validation checks, false if any issues are found
• filename: Path to the validated file
• sample_count: Total number of media samples in all tracks
• common_sample_duration: Expected duration for all samples (in timescale units)
• common_duration_seconds: Expected sample duration in seconds
• timescale: Media timescale (units per second) from the track header
• total_duration: Total media duration in timescale units
• total_duration_seconds: Total media duration in seconds
• file_size: File size in bytes
• average_bitrate_kbps: Average bitrate in kilobits per second, calculated as (file_size × 8) ÷ duration_seconds ÷ 1000

Validation Errors

When validation fails, additional fields show the specific issues:

{
  "pass": false,
  "filename": "bad-segment.mp4",
  "sample_count": 900,
  "common_sample_duration": 1001,
  "duration_variations": [
    {
      "sample_index": 450,
      "actual_duration": 1002
    }
  ],
  "sequence_number_errors": [
    {
      "fragment_index": 2,
      "actual_sequence": 4,
      "expected_sequence": 3
    }
  ],
  "tfdt_time_errors": [
    {
      "fragment_index": 1,
      "actual_base_time": 100000,
      "expected_base_time": 90090
    }
  ]
}

Concise Reporting

The validator uses a concise JSON format:

• Regular patterns are omitted: If sequence numbers and TFDT times follow expected patterns, they're not included in the output
• Only deviations are reported: Duration variations, sequence errors, and timing errors are only shown when issues are detected
• omitempty tags: Empty arrays and zero values are excluded from JSON output

Validation Rules

Sample Duration Uniformity

• All samples in a track must have the same duration
• Uses MP4 specification hierarchy: TRUN sample durations → TFHD default → TREX default

MFHD Sequence Numbers

• Must start from 1 and increment by 1 for each fragment
• No gaps or duplicates allowed

TFDT Base Media Decode Time

• First fragment must start at base time 0
• Subsequent fragments must start at cumulative duration of previous samples
• Ensures proper timeline continuity

Bitrate Validation

• Calculates average bitrate based on file size and duration
• Validates bitrate falls within specified minimum and maximum limits (configurable via command-line options)
• Default range: 10 kbps to 100,000 kbps

Exit Codes and Integration

The validator returns different exit codes based on validation results:

• Exit code 0: All files passed validation
• Exit code 1: One or more files failed validation or other errors occurred

Integration Examples

# Exit code 0 = all files valid, non-zero = validation failed  
./bin/mez-validator ./output/ && echo "All files valid"

# Parse JSON output for programmatic processing
./bin/mez-validator file.mp4 | jq '.pass'

# Check exit code in scripts
if ./bin/mez-validator -min-bitrate 500 -max-bitrate 2000 ./segments/; then
    echo "All segments valid"
else
    echo "Validation failed - check output for details"
    exit 1
fi

Testing

The validator includes comprehensive tests that verify both valid and invalid MEZ files:

# Run all tests
go test -v

# Run specific test
go test -v -run TestValidateVideoMezSegment1

Test Coverage

• TestValidateVideoMezSegment1: Validates against known good MEZ file with expected metrics
• TestValidateModifiedVideoMezSegment: Tests error detection by modifying sample durations in the MP4 structure

The test suite includes a helper function createModifiedMP4() that demonstrates how to programmatically modify MP4 files for testing validation error scenarios.

Dependencies

• Uses github.com/Eyevinn/mp4ff library for MP4 parsing
• Requires Go 1.22+ for building