knowit

Know your media files better.

Read the metadata of video files: codecs, resolution, HDR, audio channels, languages, and subtitles.

Why knowit

Different tools give video metadata in different formats and with different names. knowit reads the output of MediaInfo, ffprobe, mkvmerge, or enzyme. It gives the result in one format, with the same names and units for all of them. You can use knowit as a command or as a Python library.

Quick start

1. Install knowit:

   uv tool install "knowit[pint]"
   

2. Read a video:

   $ knowit movie.mkv
   {
       "title": "Big Buck Bunny",
       "path": "movie.mkv",
       "duration": "0:00:46",
       "size": "31.76 MB",
       "bit_rate": "5.4 Mbps",
       "container": "mkv",
       "video": [
           {
               "id": 1,
               "width": "1024 pixel",
               "height": "576 pixel",
               "resolution": "576p",
               "frame_rate": "24.0 FPS",
               "codec": "H.264",
               ...
           }
       ],
       "audio": [
           {
               "id": 2,
               "codec": "AAC",
               "channels": "2.0",
               "sampling_rate": "48.0 KHz",
               ...
           }
       ],
       "subtitle": [
           {
               "id": 3,
               "language": "English",
               "format": "SubRip",
               "default": true
           },
           ...
       ]
   }
   

To try knowit without installing it, use uvx knowit movie.mkv.

Installation

Install knowit

Use one of these commands:

The pint extra adds units to the values, for example 31.76 MB or 1024 pixel. Without it, knowit shows plain numbers.

To upgrade, use uv tool upgrade knowit or pipx upgrade knowit.

Install a provider

A provider is the program that knowit uses to read the file. knowit uses the first installed provider in this order:

On most systems, knowit installs the MediaInfo library with the pymediainfo package. You do not need to install more programs.

If your system has no MediaInfo library, or if you want other providers, install the programs:

Ubuntu, Debian, and WSL

sudo apt-get install mediainfo ffmpeg mkvtoolnix

Windows (with Chocolatey)

choco install mediainfo ffmpeg mkvtoolnix

macOS (with Homebrew)

brew install media-info ffmpeg mkvtoolnix

To see which providers knowit finds, run knowit --version.

Docker

The Docker image contains knowit, MediaInfo, FFmpeg, and MKVToolNix:

docker run -it --rm -v /medias:/medias ratoaq2/knowit /medias/movie.mkv

Usage

Read a video with a specific provider:

knowit -p ffmpeg movie.mkv

Show the result in YAML:

knowit -y movie.mkv

A profile changes how knowit shows the values. The same file with two profiles:

$ knowit -y -P human movie.mkv        $ knowit -y -P technical movie.mkv
  duration: 46 seconds                  duration: '0:00:46.665000'
  size: 31.76 MB                        size: 30.291 MiB
  bit_rate: 5.4 Mbps                    bit_rate: 5.193 Mibps

Main options

Run knowit --help for all options.

Python API

from knowit import know

info = know('/medias/movie.mkv')
print(info['video'][0]['codec'])  # H.264

info = know('/medias/movie.mkv', {'provider': 'ffmpeg', 'profile': 'code'})

know returns a dict. It raises KnowitException when knowit cannot read the file.

Report a problem

Do not send your media file. Run this command instead, and attach knowit-report.yml to an issue:

knowit --bug-report "/path/to/your/video.mkv"

The report contains the output of every provider. Titles, file names, and free-text tags are masked.

When the problem is the name of the file, use knowit --check-name "The Accountant² (2025).mkv". It tells you which provider fails because of the name.

Troubleshooting gives all the details.

Help to improve knowit

knowit is more correct when it sees many different files. Run this command on your library, and attach the files that it writes to an issue:

knowit --collect /path/to/your/media

Your media is not needed. Titles and file names are masked. See Help to improve knowit.

Used by

• Subliminal
• Bazarr
• Medusa

FAQ

Which provider should I use? Use MediaInfo if you can. It gives the most information. If knowit gives a wrong value, try another provider with -p, and report the problem.

Which files does knowit read? With MediaInfo or ffprobe, knowit reads all common video files, for example .mkv, .mp4, .avi, and .ts. With only mkvmerge or enzyme, knowit reads only Matroska files (.mkv).

Does knowit send my files or file names anywhere? No. knowit reads the files on your computer. It does not use the network. A bug report or a collect file leaves your computer only when you attach it to an issue.