Skip to main content

Filters media files by testing criteria against header metadata extracted by ffprobe.

Project description

Filters media files by testing criteria against header metadata extracted by ffprobe.


pip install fffilter


  • FFfilter uses subprocess to access the system installation of ffprobe.
  • colorama will be automatically installed by pip.


Command-line tool

-s --show [key]

Returns a tab-separated list of all values of [key].

# Return the value(s) of display_aspect_ratio
fffilter /path/to/file --show display_aspect_ratio
# Return a list of files, surfacing all possible values of given keys
# (note that '-' must be first argument when receiving piped input if using --show)
find . -name '*.mp4' | fffilter - --show codec_name codec_type display_aspect_ratio

-m --match [key] [value]

Lists files which match all criteria:

  • matching files are listed on stdout
  • non-matching files are listed on stderr, printed over a red background

Simply pass key and value pairs to repeating occurrences of the --match parameter.

# Return absoulte path for file if its header declares 4:3 aspect
fffilter /path/to/file --match display_aspect_ratio 4:3
# Filter a list of files for h.264-encoded full-HD mp4s
find . -name '*.mp4' | fffilter --match codec_name h264 --match height 1080 --match width 1920 -


from fffilter import fffilter

path = 'media/some_file.mp4'

# The show() method requires a path and a list of keys
d =, ['codec_type', 'display_aspect_ratio'])

# The match() method requires a path and either key=value pairs or a packed dictionary: **{'key':'value'}
m = fffilter.match(path, codec_type='video', display_aspect_ratio='16:9')

{'display_aspect_ratio': [u'16:9'], 'codec_type': [u'audio', u'video']}

You can also call ffprobe(path) to access a dictionary of the complete headers:

headers = fffilter.ffprobe(path)
{u'streams': [{u'pix_fmt': u'yuv420p', u'sample_aspect_ratio': u'1:1', u'refs': 1, u'codec_type': u'video', u'coded_height': 720


This Python Package is not affiliated with FFmpeg or FFprobe.


FFfilter was written by Edward Anderson, British Film Institute.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for FFfilter, version 0.0.3
Filename, size File type Python version Upload date Hashes
Filename, size FFfilter-0.0.3.tar.gz (4.0 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page