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 hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page