ffprobe JSON Format

filmalize uses ffprobe to extract metadata from multimedia container files in order to automatically generate instances using the Container.from_file factory. The api that filmalize queries is ffprobe’s json writer, to which the ‘-show_streams’ and ‘-show_format’ flags are passed. Unfortunately, unlike the xml writer, which comes with a handy full spec definition, the json writer’s output structure is undocumented. Fortunately, it is quite easy to explore and work with. In the interest of clarity (sanity), I have reproduced below the structure and values that are relevant to filmalize.

Note that there are many other entries that have not been included as they are not used by filmalize at this time. Furthermore, ffprobe will not include entries in its output if it doesn’t find the relevant info when probing a file. Therefore, filmalize is designed to be resiliant to recieving very minimal information. When creating an instance using the from_dict factory, Container only requires ‘filename’, ‘duration’ and ‘stream’ entries. Similarly, Stream only requires ‘index’ and ‘codec_type’ entries.

Example ffprobe json output

(Stripped of non-essential entries.)

{
    "streams": [
        {
            "index": 0,
            "bit_rate": "12000000",
            "codec_name": "vp8",
            "codec_type": "video",
            "width": 214,
            "height": 160,
            "coded_width": 214,
            "coded_height": 160,
            "disposition": {
                "default": 1
            },
            "tags": {
                "title": "Example Video Stream",
                "language": "eng"
            }
        },
        {
            "index": 1,
            "bit_rate": "256000",
            "codec_name": "vorbis",
            "codec_type": "audio",
            "channel_layout": "stereo",
            "disposition": {
                "default": 1
            },
            "tags": {
                "title": "Example Audio Stream",
                "language": "eng"
            }
        },
        {
            "index": 2,
            "bit_rate": "512000",
            "codec_name": "opus",
            "codec_type": "audio",
            "channel_layout": "5.1",
            "disposition": {
                "default": 0
            },
            "tags": {
                "title": "Example Audio Stream",
                "language": "spa"
            }
        },
        {
            "index": 3,
            "codec_name": "subrip",
            "codec_type": "subtitle",
            "disposition": {
                "default": 0
            },
            "tags": {
                "title": "Example Subtitle Stream",
                "language": "spa"
            }
        }
    ],
    "format": {
        "filename": "./examplefile.ogv",
        "format_long_name": "Matroska / WebM",
        "duration": "186.727000",
        "size": "5183802",
        "bit_rate": "222091",
        "tags": {
            "title": "Example Container"
        }
    }
}