{"id":13618377,"url":"https://github.com/gdavila/easyVmaf","last_synced_at":"2025-04-14T10:31:57.027Z","repository":{"id":38256817,"uuid":"243396674","full_name":"gdavila/easyVmaf","owner":"gdavila","description":"Python script to easily compute VMAF using FFmpeg. It allows to deinterlace, scale and sync Ref and Distorted video automatically","archived":false,"fork":false,"pushed_at":"2024-04-04T12:09:01.000Z","size":15399,"stargazers_count":163,"open_issues_count":3,"forks_count":33,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-08-01T20:53:19.670Z","etag":null,"topics":["ffmpeg","video","video-quality","vmaf"],"latest_commit_sha":null,"homepage":"https://ottverse.com/vmaf-easyvmaf/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gdavila.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-02-27T00:39:32.000Z","updated_at":"2024-07-29T18:54:40.000Z","dependencies_parsed_at":"2024-01-06T12:03:04.480Z","dependency_job_id":"f4a5435a-6e88-46d4-aac5-69d9f5877c50","html_url":"https://github.com/gdavila/easyVmaf","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdavila%2FeasyVmaf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdavila%2FeasyVmaf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdavila%2FeasyVmaf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gdavila%2FeasyVmaf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gdavila","download_url":"https://codeload.github.com/gdavila/easyVmaf/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223627497,"owners_count":17175717,"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","video-quality","vmaf"],"created_at":"2024-08-01T20:01:59.903Z","updated_at":"2024-11-08T03:31:10.103Z","avatar_url":"https://github.com/gdavila.png","language":"Python","funding_links":[],"categories":["HarmonyOS","Media Processing","Media Tools"],"sub_categories":["Windows Manager","Rust","VMAF PSNR SSIM Tools"],"readme":"# easyVmaf\n\nPython tool based on ffmpeg and ffprobe to deal with the video preprocesing required for VMAF inputs:\n* Deinterlacing\n* Upscaling/downscaling\n* Frame-to-Frame Syncing\n* Frame rate adaptation\n\nDetails about **How it Works** can be found [here](https://ottverse.com/vmaf-easyvmaf/).\n\n## Updates\n\nSince `easyVmaf` `2.0` only FFmpeg versions \u003e= `5.0` will be supported. For using `easyVmaf` with FFmpeg \u003c `5.0`, please consider rollingback to `easyVmaf` `1.3`.\n\nNew feaures and updates:\n\n* [Cambi feature](https://github.com/Netflix/vmaf/blob/master/resource/doc/cambi.md#options) - Netflix banding detector, supported. \n\n* Command line ussage updated according to [libvmaf docs](https://ffmpeg.org/ffmpeg-filters.html#libvmaf)\n\n* [Cambi heatmap](https://github.com/Netflix/vmaf/issues/936) support added.  The outputs may be visualized with [ffplay](https://github.com/Netflix/vmaf/issues/1016#issuecomment-1099591977)\n\n* Built-in VMAF models are only supported since they are included in FFmpeg  \u003e= `v5.0`. \n\n* Docker image - better handling of dependencies and built instruccions\n\n* 'HD Neg' and 'HD phone' models are computed by default \n\n## Requirements\n\n* `Linux`/`OSX`\n\n* Python `\u003e= v3.0`\n\n* Python module [ffmpeg_progress_yield](https://github.com/slhck/ffmpeg-progress-yield)\n\n* FFmpeg \u003e= `5.0` build with `libvmaf`. More details [here](http://underpop.online.fr/f/ffmpeg/help/libvmaf.htm.gz)\n\n## Installation\n\n* Just clone the repo and run it from the source folder.\n\n```bash\n$ git clone https://github.com/gdavila/easyVmaf.git\n$ cd easyVmaf\n```\n\n* Run from [docker image](https://hub.docker.com/repository/docker/gfdavila/easyvmaf). More info at the [end of this document](#Docker-Image-usage).\n\n## Usage\n\n```console\n$ python3 easyVmaf.py\nusage: easyVmaf [-h] -d D -r R [-sw SW] [-ss SS] [-fps FPS] [-subsample N] [-reverse] [-model MODEL]\n                [-threads THREADS] [-verbose] [-progress] [-endsync] [-output_fmt OUTPUT_FMT]\n                [-cambi_heatmap]\n\nScript to easy compute VMAF using FFmpeg. It allows to deinterlace, scale and sync Ref and Distorted video samples automatically:                         \n\n \t Autodeinterlace: If the Reference or Distorted samples are interlaced, deinterlacing is applied                        \n\n \t Autoscale: Reference and Distorted samples are scaled automatically to 1920x1080 or 3840x2160 depending on the VMAF model to use                        \n\n \t Autosync: The first frames of the distorted video are used as reference to a sync look up with the Reference video.                         \n \t \t The sync is doing by a frame-by-frame look up of the best PSNR                        \n \t \t See [-reverse] for more options of syncing                        \n\n As output, a json file with VMAF score is created\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -sw SW                Sync Window: window size in seconds of a subsample of the Reference video. The sync lookup will be done between the first frames of the Distorted input and this Subsample of the Reference. (default=0. No sync).\n  -ss SS                Sync Start Time. Time in seconds from the beginning of the Reference video to which the Sync Window will be applied from. (default=0).\n  -fps FPS              Video Frame Rate: force frame rate conversion to \u003cfps\u003e value. Autodeinterlace is disabled when setting this\n  -subsample N          Specifies the subsampling of frames to speed up calculation. (default=1, None).\n  -reverse              If enable, it Changes the default Autosync behaviour: The first frames of the Reference video are used as reference to sync with the Distorted one. (Default = Disable).\n  -model MODEL          Vmaf Model. Options: HD, 4K. (Default: HD).\n  -threads THREADS      number of threads\n  -verbose              Activate verbose loglevel. (Default: info).\n  -progress             Activate progress indicator for vmaf computation. (Default: false).\n  -endsync              Activate end sync. This ends the computation when the shortest video ends. (Default: false).\n  -output_fmt OUTPUT_FMT\n                        Output vmaf file format. Options: json or xml (Default: json)\n  -cambi_heatmap        Activate cambi heatmap. (Default: false).\n  -sync_only            Sync measurement only. No Vmaf processing (Default: false).\n\nrequired arguments:\n  -d D                  Distorted video\n  -r R                  Reference video \n```\n\n## Examples\n\n### Syncing: Reference Video delayed in regard with the first frame of Distorted one.\n\n![](readme/easyVmaf1.svg)\n\nVMAF computation for two video samples, `reference.ts` and `distorted-A.ts`. Both videos are not synced: `reference.ts` is delayed in comparition with `distorted-A.ts`, i.e.,  the first frame of `distorted-A.ts` matchs with the frame located at 0.7007 seconds since the begining of `reference.ts` (blue arrow on the figure). To sync both videos automatically using `easyVmaf`, the next command line is used:\n\n    ```bash\n    $ python3 easyVmaf.py -d distorted-A.ts -r reference.ts -sw 2\n\n\n    ...\n    ...\n    [Ignored outputs]\n    ...\n    ...\n\n    Sync Info:\n    offset:  0.7007000000000001 psnr:  48.863779\n    VMAF score:  89.37913542219542\n    VMAF json File Path:  distorted-A_vmaf.json\n    ```\n\nThe previus command line takes a synchronisation window `sw` of *2 seconds* , this means that the sync lookup will be done between the first frame of `distorted-A.ts` (actually, in practise it takes into account several frames) and a subsample of `reference.ts` of *2 seconds* lenght since its begin.\n\n    ```bash\n    $ python3 easyVmaf.py -d distorted.ts -r reference.ts -sw 2\n    ...\n    ...\n    [Ignored FFmpeg outputs]\n    ...\n    ...\n    Sync Info:\n    offset:  0.7007000000000001 psnr:  48.863779\n    VMAF score:  89.37913542219542\n    VMAF json File Path:  distorted.json\n    ```\n\n### Syncing: Distorted Video delayed in regard with the first frame of Reference one.\n![](readme/easyVmaf2.svg)\n\nThis time,  `distorted-B.ts` is delayed in comparition with `reference.ts`, i.e.,  The first frame of `reference.ts` matchs with the frame located at 8.3003 seconds since the begining of `distorted-B.ts`. To sync the videos automatically, the next command line is used:\n\n    ```bash\n    $ python3 easyVmaf.py -d distorted-B.ts -r reference.ts -sw 3 -ss 6 -reverse\n\n\n    ...\n    ...\n    [Ignored FFmpeg outputs]\n    ...\n    ...\n\n    Sync Info:\n    offset:  8.300300000000000 psnr:  34.897866\n    VMAF score:  92.34452778643345\n    VMAF json File Path:  distorted-B_vmaf.json\n    ```\n\n The previous command line applies a syncronization window `sw` of *3 seconds*,  a *sync start time* `ss` *of 6 seconds* and the `reverse` flag.  \n \nNote the use of the  `reverse`  flag (that was not used on the first example). This flag allows to interchange to which video the `syncWindow` will be applied (reference or distorted).\n\n\n\n## Docker Image usage\n\nA [docker image](https://hub.docker.com/repository/docker/gfdavila/easyvmaf) is available on docker hub to run easyVmaf in a straightforward way.\n\nThe Docker Image is basically an ubuntu image with `ffmpeg` and `libvmaf` already installed. You can check the [Dockerfile](https://hub.docker.com/r/gfdavila/easyvmaf/dockerfile) for more details.\n\nThe easiest way to run easyVmaf through Docker is mounting a shared volume between your host machine and the container. This volume should have inside it all the video files you want to analyze. The outputs (vmaf information files) will be putting in this shared folder also.\n\nExample\n\n```bash\ndocker run --rm -v \u003clocal-path-to-your-video-files\u003e:/\u003ccustom-name-folder\u003e gfdavila/easyvmaf -r /\u003ccustom-name-folder\u003e/video-1.mp4 -d /\u003ccustom-name-folder\u003e/video-2.mp4\n```\n\nSome video samples located on the docker image:\n\n```bash\nNAME                        TIME\n\n                           t=0\n                            |\nBBB_reference_10s.mp4       */-----------------------------*/\nBBB_sampleA_distorted.mp4           */---------------------*/\nBBB_sampleB_distorted.mp4       */-------------------------*/\n\n```\n\nRun docker container to get VMAF between `BBB_reference_10s.mp4` and `BBB_sampleA_distorted.mp4`:\n\n```bash\n:~$ docker run --rm  gfdavila/easyvmaf -r video_samples/BBB_reference_10s.mp4 -d video_samples/BBB_sampleA_distorted.mp4 -sw 1 -ss 1\n```\n\nRun docker container to get VMAF between `BBB_sampleA_distorted.mp4` and `BBB_sampleB_distorted.mp4`:\n\n```bash\n:~$ docker run --rm  gfdavila/easyvmaf -r video_samples/BBB_sampleA_distorted.mp4 -d video_samples/BBB_sampleB_distorted.mp4 -sw 2 -ss 0 -reverse\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgdavila%2FeasyVmaf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgdavila%2FeasyVmaf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgdavila%2FeasyVmaf/lists"}