{"id":13905493,"url":"https://github.com/slhck/ffmpeg-debug-qp","last_synced_at":"2026-04-03T08:37:49.002Z","repository":{"id":47112146,"uuid":"70816919","full_name":"slhck/ffmpeg-debug-qp","owner":"slhck","description":"FFmpeg Debug Script for QP Values","archived":true,"fork":false,"pushed_at":"2023-02-28T07:34:35.000Z","size":42256,"stargazers_count":75,"open_issues_count":0,"forks_count":24,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-07T23:43:24.492Z","etag":null,"topics":["ffmpeg","video-encoding"],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/slhck.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-10-13T14:47:23.000Z","updated_at":"2024-02-21T11:03:53.000Z","dependencies_parsed_at":"2023-02-08T07:16:35.757Z","dependency_job_id":null,"html_url":"https://github.com/slhck/ffmpeg-debug-qp","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slhck%2Fffmpeg-debug-qp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slhck%2Fffmpeg-debug-qp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slhck%2Fffmpeg-debug-qp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/slhck%2Fffmpeg-debug-qp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/slhck","download_url":"https://codeload.github.com/slhck/ffmpeg-debug-qp/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":226336548,"owners_count":17608859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ffmpeg","video-encoding"],"created_at":"2024-08-06T23:01:17.021Z","updated_at":"2026-04-03T08:37:48.994Z","avatar_url":"https://github.com/slhck.png","language":"C","funding_links":[],"categories":["HarmonyOS","Media Tools"],"sub_categories":["Windows Manager","Quality Analysis \u0026 Metrics"],"readme":"# `ffmpeg_debug_qp`\n\n\u003c!-- ALL-CONTRIBUTORS-BADGE:START - Do not remove or modify this section --\u003e\n[![All Contributors](https://img.shields.io/badge/all_contributors-7-orange.svg?style=flat-square)](#contributors-)\n\u003c!-- ALL-CONTRIBUTORS-BADGE:END --\u003e\n\nAuthors: Werner Robitza, Steve Göring, Pierre Lebreton, Nathan Trevivian, Valerio Triolo\n\n`ffmpeg-debug-qp` is based on ffmpeg and prints QP values of a video input on a per-frame, per-macroblock basis to STDERR.\n\nThe tool comes with an additional Python parser to help interpret the output.\n\n**Contents:**\n\n- [Download](#download)\n- [Building from Source](#building-from-source)\n  - [Requirements](#requirements)\n  - [Building](#building)\n  - [Installation](#installation)\n- [Usage](#usage)\n  - [Direct Usage](#direct-usage)\n  - [Python Usage](#python-usage)\n- [Developers: Static Build](#developers-static-build)\n- [Acknowledgements](#acknowledgements)\n- [Contributors](#contributors)\n- [License](#license)\n\n## Download\n\nPre-built static binaries are available for Linux and macOS (both x86_64 and ARM64):\n\n**[Download the latest release](https://github.com/slhck/ffmpeg-debug-qp/releases/latest)**\n\nThese binaries have FFmpeg statically linked and require no additional dependencies.\n\n## Building from Source\n\nIf you prefer to build from source, follow the instructions below.\n\n### Requirements\n\n- Python 3.9 or higher\n- ffmpeg 8.x or higher libraries\n\n### Linux\n\nFor building:\n\n- libavdevice, libavformat, libavfilter, libavcodec, libswresample, libswscale, libavutil\n- C compiler\n\nFor example on Ubuntu:\n\n    sudo apt -qq update \u0026\u0026 \\\n    sudo apt install libavdevice-dev libavformat-dev libavfilter-dev libavcodec-dev libswresample-dev libswscale-dev libavutil-dev build-essential pkg-config\n\n### macOS\n\nFor building:\n\n- [Homebrew](https://brew.sh/)\n\nThen:\n\n    brew install ffmpeg pkg-config\n\n### Building\n\nIn order to use this tool, you need to build the `ffmpeg_debug_qp` binary.\n\nIf you have FFmpeg libraries installed on your system, simply run:\n\n```bash\nmake\n```\n\nThe binary will be created under `ffmpeg_debug_qp` in the same folder.\n\n### Installation\n\nYou can add the binary to your `$PATH`, e.g. by copying it to `/usr/local/bin`:\n\n```bash\nsudo cp ./ffmpeg_debug_qp /usr/local/bin/\n# or for static build:\nsudo cp ./build/ffmpeg_debug_qp /usr/local/bin/\n```\n\nThis way, you can call it from anywhere on your system.\n\n## Usage\n\nRun this tool on any of the supported file types:\n\n- MPEG-2\n- MPEG-4 Part 2\n- H.264 / MPEG-4 Part 10 (AVC)\n\nSupported formats:\n\n- MPEG-4 Part 14\n- H.264 Annex B bytestreams\n\n### Direct Usage\n\nSimply call the binary with the path to a file:\n\n```console\n./ffmpeg_debug_qp test/test.mp4\n[h264 @ 0x124f043b0] New frame, type: I\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] \u003c\u003c frame_type: I; pkt_size: 213 \u003e\u003e\n[h264 @ 0x124f043b0] New frame, type: P\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n[h264 @ 0x124f043b0] 1111111111111111111111111111111111111111\n```\n\nYou will see the QP values for each macroblock of every frame. Each pair of two numbers is a QP value, hence, in the above example, the QP values are `11`, `11` and so on.\n\n### Python Usage\n\nYou can run the supplied Python tool that helps you parse the results from `ffmpeg_debug_qp`.\n\nFirst, build the binary and add it to your `$PATH`.\n\nThen, from the project directory, run via [uv](https://docs.astral.sh/uv/):\n\n```bash\nuv run ffmpeg-debug-qp-parser --help\n```\n\nOr install locally with pip:\n\n```bash\npip install .\nffmpeg-debug-qp-parser --help\n```\n\nThe tool options are as follows:\n\n```\nusage: ffmpeg-debug-qp-parser [-h] [-f] [-of OUTPUT_FORMAT] [-p PATH_TO_TOOL] [-l | -k]\n                              [-m | -a]\n                              video|logfile output\n\nParse QP values from ffmpeg-debug-qp\n\npositional arguments:\n  video|logfile         Video file to generate output for, or existing logfile\n  output                Output file\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -f, --force           Overwrite output\n  -of OUTPUT_FORMAT, --output-format OUTPUT_FORMAT\n                        Output format, one of: ld-json (default), json or csv\n  -p PATH_TO_TOOL, --path-to-tool PATH_TO_TOOL\n                        Path to ffmpeg_debug_qp executable (will search in $PATH by default)\n  -l, --use-logfile     Use precalculated logfile instead of the video\n  -k, --keep-logfile    Don't remove the temporary logfile 'video.debug'\n  -m, --include-macroblock-data\n                        Include macroblock-level data, such as: type, interlaced and segmentation\n  -a, --compute-averages-only\n                        Only compute the frame-average QPs\n```\n\n\n#### Python Example\n\nTo run a basic example:\n\n```\nffmpeg-debug-qp-parser input.mp4 output_file.json -m -of json\n```\n\nThis reads the file `input.mp4` and produces a JSON file `output_file.json`, with a list of frames and each of their macroblocks in the format:\n\n```json\n  [\n      {\n          \"frameType\": \"I\",\n          \"frameSize\": 7787,\n          \"qpAvg\": 26.87280701754386,\n          \"qpValues\": [\n              {\n                  \"qp\": 25,\n                  \"type\": \"i\",\n                  \"segmentation\": \"\",\n                  \"interlaced\": \"\"\n              },\n              {\n                  \"qp\": 26,\n                  \"type\": \"i\",\n                  \"segmentation\": \"\",\n                  \"interlaced\": \"\"\n              }, ...\n```\n\nThe frame and macroblock types are as per ffmpeg debug information. The same goes for segmentation and interlaced values.\n\nFor example outputs, see:\n\n* Line-delimited JSON\n  * [Averages only](examples/example-avgs.ldjson)\n  * [Macroblock data](examples/example-mbdata.ldjson)\n* JSON\n  * [Averages only](examples/example-avgs.json)\n  * [Macroblock data](examples/example-mbdata.json)\n* CSV\n  * [Averages only](examples/example-avgs.csv)\n  * [Macroblock data](examples/example-mbdata.csv)\n\n## Developers: Static Build\n\nTo build a portable binary with FFmpeg statically linked, use CMake:\n\n```bash\n# Download and build minimal FFmpeg (first time only)\n./util/build-ffmpeg.sh --download\n\n# Build ffmpeg_debug_qp\ncmake -B build -DUSE_VENDORED_FFMPEG=ON\ncmake --build build\n```\n\nThe binary will be created at `build/ffmpeg_debug_qp`. This binary only depends on system libraries and can be distributed without requiring FFmpeg to be installed.\n\nTo rebuild FFmpeg (e.g., after changes):\n\n```bash\n./util/build-ffmpeg.sh --clean    # Clean and reconfigure\n./util/build-ffmpeg.sh            # Just rebuild\n```\n\nThis is what is used inside GitHub Actions to provide prebuilt binaries for Linux and macOS.\n\n## Acknowledgements\n\nThis code is based on:\n\n- the code from [Fredrik Pihl](https://gist.github.com/figgis/ea9ac513cdd99a10abf1)\n- which is adapted from the code example `demuxing_decoding.c` by Stefano Sabatini\n\nSee also [this thread](https://ffmpeg.org/pipermail/libav-user/2015-May/008122.html) on the libav-user mailing list.\n\nTest video part of Big Buck Bunny (c) copyright 2008, Blender Foundation / www.bigbuckbunny.org\n\n## Contributors\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:START - Do not remove or modify this section --\u003e\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- markdownlint-disable --\u003e\n\u003ctable\u003e\n  \u003ctbody\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"http://slhck.info/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/582444?v=4?s=100\" width=\"100px;\" alt=\"Werner Robitza\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eWerner Robitza\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=slhck\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/ndtreviv\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/1530653?v=4?s=100\" width=\"100px;\" alt=\"Nathan Trevivian\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eNathan Trevivian\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=ndtreviv\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/lars18th\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/9989964?v=4?s=100\" width=\"100px;\" alt=\"Lars The\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eLars The\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=lars18th\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/plebreton\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/19344718?v=4?s=100\" width=\"100px;\" alt=\"plebreton\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eplebreton\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=plebreton\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/winking324\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/7922054?v=4?s=100\" width=\"100px;\" alt=\"winking324\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003ewinking324\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=winking324\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://stg7.github.io/\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/9373295?v=4?s=100\" width=\"100px;\" alt=\"Steve Göring\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eSteve Göring\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=stg7\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" valign=\"top\" width=\"14.28%\"\u003e\u003ca href=\"https://github.com/valeriot30\"\u003e\u003cimg src=\"https://avatars.githubusercontent.com/u/30567406?v=4?s=100\" width=\"100px;\" alt=\"Valerio Triolo\"/\u003e\u003cbr /\u003e\u003csub\u003e\u003cb\u003eValerio Triolo\u003c/b\u003e\u003c/sub\u003e\u003c/a\u003e\u003cbr /\u003e\u003ca href=\"https://github.com/slhck/ffmpeg-debug-qp/commits?author=valeriot30\" title=\"Code\"\u003e💻\u003c/a\u003e\u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tbody\u003e\n  \u003ctfoot\u003e\n    \u003ctr\u003e\n      \u003ctd align=\"center\" size=\"13px\" colspan=\"7\"\u003e\n        \u003cimg src=\"https://raw.githubusercontent.com/all-contributors/all-contributors-cli/1b8533af435da9854653492b1327a23a4dbd0a10/assets/logo-small.svg\"\u003e\n          \u003ca href=\"https://all-contributors.js.org/docs/en/bot/usage\"\u003eAdd your contributions\u003c/a\u003e\n        \u003c/img\u003e\n      \u003c/td\u003e\n    \u003c/tr\u003e\n  \u003c/tfoot\u003e\n\u003c/table\u003e\n\n\u003c!-- markdownlint-restore --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n\u003c!-- ALL-CONTRIBUTORS-LIST:END --\u003e\n\n## License\n\nMIT License\n\nCopyright (c) 2016-2025 Werner Robitza, Steve Göring, Fredrik Pihl, Stefano Sabatini, Nathan Trevivian, Valerio Triolo\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in\nall copies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL\nTHE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN\nTHE SOFTWARE.\n\nFFmpeg libraries are licensed under the GNU Lesser General Public License, version 2.1.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslhck%2Fffmpeg-debug-qp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fslhck%2Fffmpeg-debug-qp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fslhck%2Fffmpeg-debug-qp/lists"}