​
Overview

The Probe Report provides canonicalized, ML-enhanced metadata by analyzing and reconciling outputs from both FFprobe and MediaInfo. This reference documents all available parameters in the Probe Report response.

Probe Report uses machine learning heuristics trained on over 1 billion media assets to correct inconsistencies and provide authoritative metadata.

​
Parameter Reference

PathData typeOptionalDescriptionExample
codec->iduintNoNumeric codec ID1983148141
codec->four_ccstring (4 char)YesCodec FourCC (four-character code used to uniquely identify media codec/formats)“mp4v” - mpeg4 video
codec->namestringYesHuman readable video codec name. Multiple four_cc can mean the same codec name.

For example “h264” and “avc1”, “mpg4” and “mp4v”, etc.		”mpeg4”
size->widthintYesVideo frame width1920
size->heightintYesVideo frame height1080
size->display_aspect_ratiofloatYesDisplay aspect ratio. Rounded to 3 decimal points.1.778 (for 16:9)
size->sample_aspect_ratiofloatYesSample aspect ratio. Rounded to 3 decimal points.1.333 (for 4:3)
frame_rate->numeratoruintNoFrame rate numerator30000
frame_rate->denominatoruintNoFrame rate denominator. Cannot be 01001
pixel_format->color_modelstringYesFrame color model”RGBA”
pixel_format->components_orderstringYesComponent order for the color model.”GBRA”
pixel_format->chroma_subsamplingstringYesChroma subsampling”4:2:2”
pixel_format->bit_depthuintYesBit depth8
pixel_format->has_alphaboolYesIs alpha channel existsfalse
start_timefloatYesStart time aka delay. Rounded to 3 decimal points.0.033
durationfloatYesVideo duration. Rounded to 3 decimal points.12.079
frames_countuintYesVideo frames count362
bitrate->averageuintNoAverage bitrate. Typically - Steam size / duration301878
bitrate->nominaluintYesNominal bitrate. Aka target bitrate.300000
bitrate->minimumuintYesMinimal stream bitrate298646
bitrate->maximumuintYesMaximum (peak) stream bitrate305943
color->primariesstringYesChromaticity coordinates of the source primaries”bt709”
color->transferstringYesOpto-electronic transfer characteristic of the source picture”bt2020-12”
color->matrixstringYesMatrix coefficients used in deriving luma and chroma signals from the green, blue, and red primaries”ycgco”
color->rangestringYesColor range (for YUV color space)“tv”

​
Parameter Categories

​
Codec Information

Essential codec identification and format details:

​
Video Dimensions

Frame size and aspect ratio information:

​
Temporal Information

Frame rate and timing details:

​
Pixel Format

Color and pixel structure information:

​
Bitrate Analysis

Comprehensive bitrate statistics:

​
Color Space

Advanced color space and HDR information:

​
Example Response

{
  "probe_report": {
    "success": true,
    "response": {
      "codec": {
        "id": 1983148141,
        "four_cc": "avc1",
        "name": "h264"
      },
      "size": {
        "width": 1920,
        "height": 1080,
        "display_aspect_ratio": 1.778,
        "sample_aspect_ratio": 1.0
      },
      "frame_rate": {
        "numerator": 30000,
        "denominator": 1001
      },
      "pixel_format": {
        "color_model": "YUV",
        "components_order": "YUV",
        "chroma_subsampling": "4:2:0",
        "bit_depth": 8,
        "has_alpha": false
      },
      "start_time": 0.0,
      "duration": 120.45,
      "frames_count": 3614,
      "bitrate": {
        "average": 5000000,
        "nominal": 5000000,
        "minimum": 4800000,
        "maximum": 5200000
      },
      "color": {
        "primaries": "bt709",
        "transfer": "bt709",
        "matrix": "bt709",
        "range": "tv"
      }
    }
  }
}

​
Data Types

​
Numeric Precision

  • uint: Unsigned integer (always ≥ 0)
  • int: Signed integer
  • float: Floating point, rounded to 3 decimal places where specified
  • bool: Boolean true/false value

​
String Values

  • four_cc: Exactly 4 characters (may contain nulls)
  • codec names: Standardized codec identifiers
  • color values: Standardized color space names

​
Common Use Cases

Format Validation

Verify codec compatibility and format specifications

if (probe.codec.name === 'h264' && 
    probe.size.width <= 1920) {
  // Compatible format
}

Quality Analysis

Analyze encoding quality and bitrate efficiency

const efficiency = probe.bitrate.average / 
                  (probe.size.width * probe.size.height);

Compatibility Check

Check device/platform compatibility

const isWebCompatible = 
  probe.codec.name === 'h264' &&
  probe.pixel_format.chroma_subsampling === '4:2:0';

Transcoding Decisions

Determine if transcoding is needed

const needsTranscode = 
  probe.codec.name !== 'h264' ||
  probe.size.width > 1920 ||
  probe.bitrate.average > 8000000;

​
Machine Learning Enhancements

The Probe Report applies ML-trained heuristics to:

  • Correct inconsistencies between FFprobe and MediaInfo outputs
  • Validate suspicious values using learned patterns
  • Fill missing data using statistical models
  • Normalize formats across different tool outputs
  • Detect encoding artifacts and quality issues

These enhancements are based on analysis of over 1 billion media assets and continuously improved through ongoing training.