{"id":13613560,"url":"https://github.com/Eyevinn/autovmaf","last_synced_at":"2025-04-13T15:33:16.703Z","repository":{"id":39996109,"uuid":"420126845","full_name":"Eyevinn/autovmaf","owner":"Eyevinn","description":"Toolkit to automatically encode multiple bitrates and perform automated VMAF measurements on all of them.","archived":false,"fork":false,"pushed_at":"2024-10-04T14:24:41.000Z","size":1529,"stargazers_count":22,"open_issues_count":11,"forks_count":5,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-03-28T17:21:18.373Z","etag":null,"topics":["tools","vmaf"],"latest_commit_sha":null,"homepage":"https://autovmaf.docs.eyevinn.technology/index.html","language":"TypeScript","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/Eyevinn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"2021-10-22T14:18:59.000Z","updated_at":"2024-09-16T09:58:14.000Z","dependencies_parsed_at":"2022-09-10T15:02:22.055Z","dependency_job_id":"fa0027e6-6cb2-438e-be13-31d0910de426","html_url":"https://github.com/Eyevinn/autovmaf","commit_stats":{"total_commits":62,"total_committers":8,"mean_commits":7.75,"dds":0.6612903225806452,"last_synced_commit":"e17167dff563b5d80e60eb8dcc26973d1ab52140"},"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fautovmaf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fautovmaf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fautovmaf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Eyevinn%2Fautovmaf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Eyevinn","download_url":"https://codeload.github.com/Eyevinn/autovmaf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248736222,"owners_count":21153554,"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":["tools","vmaf"],"created_at":"2024-08-01T20:00:50.378Z","updated_at":"2025-04-13T15:33:15.353Z","avatar_url":"https://github.com/Eyevinn.png","language":"TypeScript","funding_links":[],"categories":["HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"\u003cdiv align=\"center\"\u003e\n\n# [\u003cimg src=\"https://raw.githubusercontent.com/Eyevinn/autovmaf/main/AutoVMAF.svg\" alt=\"autovmaf\" height=\"100\"\u003e](https://github.com/eyevinn/autovmaf)\n\nautovmaf - A toolkit to automatically encode multiple bitrates and perform automated VMAF measurements on all of them.\n\n📖 **[Read the documentation](https://eyevinn.github.io/autovmaf/)** 👀\n\n[Report a Bug](https://github.com/eyevinn/autovmaf/issues/new?assignees=\u0026labels=bug\u0026template=01_BUG_REPORT.md\u0026title=bug%3A+)\n·\n[Request a Feature](https://github.com/eyevinn/autovmaf/issues/new?assignees=\u0026labels=enhancement\u0026template=02_FEATURE_REQUEST.md\u0026title=feat%3A+)\n\n[![license](https://img.shields.io/npm/v/@eyevinn/autovmaf?style=flat-square)](https://www.npmjs.com/package/@eyevinn/autovmaf)\n[![license](https://img.shields.io/github/v/release/Eyevinn/autovmaf?style=flat-square)](https://github.com/Eyevinn/autovmaf/releases)\n[![license](https://img.shields.io/github/license/eyevinn/autovmaf.svg?style=flat-square)](LICENSE)\n\n[![PRs welcome](https://img.shields.io/badge/PRs-welcome-ff69b4.svg?style=flat-square)](https://github.com/eyevinn/autovmaf/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22)\n[![made with hearth by Eyevinn](https://img.shields.io/badge/made%20with%20%E2%99%A5%20by-Eyevinn-59cbe8.svg?style=flat-square)](https://github.com/eyevinn)\n\n\u003c/div\u003e\n\nBy optimizing ABR-ladders for specific content, you will make sure to not have wasteful rungs and this has been shown to [cut bandwidth usage in half](https://dev.to/video/automating-video-analysis-to-cut-your-streaming-bandwidth-usage-in-half-5hk1).\n\n## Usage\n\nTranscoding and VMAF analysis can either be run in AWS or locally. When running in aws, you will need a running ECS cluster with a task definition configured to run [easyvmaf-s3](https://github.com/Eyevinn/easyvmaf_s3).\n\n### Installation\n\n```bash\nnpm install --save @eyevinn/autovmaf\n```\n\n### Environment Variables\n\nA few environment variables can be set. These are:\n\n```bash\nLOAD_CREDENTIALS_FROM_ENV=true   //Load AWS credentials from environment variables\nAWS_REGION=eu-north-1\nAWS_ACCESS_KEY_ID=ABCD...\nAWS_SECRET_ACCESS_KEY=EFGH...\n```\n\n### Generate VMAF measurements\n\nTo generate VMAF measurements, you will need to define a job which can be created with the `createJob()`-function.\n\n```typescript\nconst { createJob } = require('@eyevinn/autovmaf');\n\nconst vmafScores = await createJob({\n  name: 'MyVMAFmeasurements',\n  pipeline: 'pipeline.yml',\n  encodingProfile: 'profile.json',\n  reference: 'reference.mp4',\n  models: ['HD', 'PhoneHD'], // optional\n  resolutions: [\n    {\n      // optional\n      width: 1280,\n      height: 720,\n      range: {\n        // optional\n        min: 500000,\n        max: 600000\n      }\n    }\n  ],\n  bitrates: [\n    // optional\n    500000, 600000, 800000\n  ],\n  method: 'bruteForce' // optional\n});\n```\n\nWhen creating a job, you can specify:\n\n- **Name**\n  - This will name the folder in which to put the files.\n- **Pipeline**\n  - Path to a YAML-file that defines the pipeline. See [`examples/pipeline.yml`](https://github.com/Eyevinn/autovmaf/blob/main/examples/aws/pipeline.yml) for an example AWS-pipeline.\n  - When running locally, pipeline data can be inlined in the job definition.\n- **Encoding Profile**\n  - Path to a JSON-file that defines how the reference should be encoded. When using AWS, this is a MediaConvert configuration. See an example for AWS at [`examples/aws/encoding-profile.json`](https://github.com/Eyevinn/autovmaf/blob/main/examples/encoding-profile.json).\n    For local pipelines, this is key-value pairs that will be passed as command line arguments to FFmpeg. If pipeline\n    data is inlined in the job definition, encodingProfile can be omitted and key-value pairs can instead be set\n    in the `ffmpegOptions` property of the pipeline object.\n- **Reference**\n  - Path to the reference video to analyze. Normally a local path, but when using AWS, this can also be an S3-URI.\n- **Models** (optional)\n  - A list of VMAF-models to use in evaluation. This can be HD, MobileHD and UHD. HD by default.\n- **Resolutions** (optional)\n  - A list of resolutions to test. By default it will test all resolutions in the example ABR-ladder provided by Apple in the [HLS Authoring Spec](https://developer.apple.com/documentation/http_live_streaming/hls_authoring_specification_for_apple_devices).\n  - **Range** (optional)\n    - A min and max bitrate for testing a specific resolution. Adding a range will filter out bitrates that are outside of the given range. It is disabled by default.\n- **Bitrates** (optional)\n  - A list of bitrates to test. By default a list of bitrates between 150 kbit/s to 9000 kbit/s.\n- **Method** (optional)\n  - The method to use when analyzing the videos. Either `bruteForce` or `walkTheHull`. By default `bruteForce`. NOTE: `walkTheHull` is not implemented at the moment.\n\n### Create job using yaml\n\n```typescript\nconst { createJob } = require('@eyevinn/autovmaf');\nconst YAML = require('yaml');\nconst fs = require('fs');\nconst parseResolutions = (resolutions) =\u003e {\n  resolutions.map((resolutionStr) =\u003e ({\n    width: parseInt(resolutionStr.split('x')[0]),\n    height: parseInt(resolutionStr.split('x')[1])\n  }));\n};\nconst jobFile = fs.readFileSync('job.yml', 'utf-8');\nconst jobData = YAML.parse(jobFile);\nconst job = {\n  ...jobData,\n  resolutions:\n    jobData['resolutions'] !== undefined\n      ? parseResolutions(jobData['resolutions'])\n      : undefined\n};\ncreateJob(job);\n```\n\n**An example of creating a job from a YAML-file can be seen in the [`examples-folder`](https://github.com/Eyevinn/autovmaf/tree/main/examples/).**\n\n### Read VMAF-scores\n\nUsing `getVmaf()`, you can read VMAF-scores from a JSON-file or a directory of JSON-files. This works on both local paths as well as S3-URIs with a \"s3://\"-prefix.\n\nExample:\n\n```javascript\nconst vmafFiles = await getVmaf('s3://path/to/vmaf/');\n\nvmafFiles.forEach((file) =\u003e {\n  console.log(file.filename + ': ' + file.vmaf);\n});\n```\n\n## CLI Usage\n\nWhen running with the cli, all transcoding and vmaf analysis will be run locally.\n\n### Requirements\n\n- [easyVmaf](https://github.com/gdavila/easyVmaf)\n- [FFmpeg](https://www.ffmpeg.org/) \u003e= 5.0, compiled with libvmaf\n- [Python](https://www.python.org) \u003e= 3.0\n\n### Global installation\n\nInstalling globally with `npm -g` will make the `autovmaf` command available in your path\n\n```bash\nnpm install -g @eyevinn/autovmaf\n```\n\n### Environments variables\n\nThese are only needed if you are running transcodes and VMAF measurements locally\n\n- `EASYVMAF_PATH` - needs to point to the file `easyVmaf.py` from your\n  easyVmaf installation.\n- `FFMPEG_PATH` - only needs to be set if ffmpeg is not in your path.\n- `PYTHON_PATH` - only needs to be set if python is not in your path.\n\n### Command line options\n\nAvailable command line options for the cli can be listed with the `--help` argument\n\n```bash\nautovmaf [source]\n\nrun transcode and vmaf analysis for videofile source\n\nCommands:\n  autovmaf [source]                 run transcode and vmaf analysis for\n                                    videofile source                   [default]\n  autovmaf suggest-ladder \u003cfolder\u003e  Suggest bitrate ladder given vmaf results\n  autovmaf export-csv \u003cfolder\u003e      Export Vmaf results as csv\n  autovmaf vmaf                     Use pipeline to run VMAF for the given\n                                    distorted and reference files\n\nPositionals:\n  source  SOURCEFILE                                                    [string]\n\nOptions:\n  --version         Show version number                                [boolean]\n  --help            Show help                                          [boolean]\n  --resolutions     List of resolutions, ie 1920x1080,1280x720...       [string]\n  --bitrates        List of bitrates, ie 800k,1000k,...                 [string]\n  --name            Name for this autovmaf run                          [string]\n  --models          List of VMAF Models to use                          [string]\n  --job             File with job definition                            [string]\n  --saveAsCsv       Save VMAF measurements as a .csv file in addition to a JSON\n                    file                              [boolean] [default: false]\n  --skipTranscode   Skip transcode and run vmaf on already transcoded files\n                                                      [boolean] [default: false]\n  --skipExisting    Skip transcode for already transcoded files\n                                                       [boolean] [default: true]\n  --probeBitrate    Read bitrate of transcoded file with ffprobe\n                                                      [boolean] [default: false]\n  --ffmpeg-options  List of options to pass to ffmpeg, on the form\n                    key1=value1:key2=value2                             [string]\n```\n\n### Running transcode and analysis\n\nOutput files will be stored in a folder corresponding to the argument given to the `--name` option.\nIf resolutions and/or bitrates are not specified default values will be used, [See above](#generate-vmaf-measurements).\n\n#### Providing job definition in a json or yaml file\n\nWith the `--job` option, a path to a yaml or json file with a job definition can be passed to to the cli. The values\ndefined in the file can be overridden with other commandline options. For instance the `reference` video defined\nin the job file can be overridden by passing a source file on the command line.\n\n##### Using variables in the job definition\n\nIt is possible to iterate over other variables than bitrate and resolutions when running a local encode. For\ninstance, to run transcode and vmaf analysis with x265 in CRF mode for a number of CRF values, a job definition\nlike below can be used (also available in [examples/local/local-job-crf.yaml](examples/local/local-job-crf.yaml))\n\n```yaml\nmodels:\n  - HD\nresolutions:\n  - width: 1920\n    height: 1080\nbitrates:\n  - 0\npipeline:\n  ffmpegEncoder: libx265\n  singlePass: true\n  skipDefaultOptions: true\n  ffmpegOptions:\n    '-pix_fmt': 'yuv420p'\n    '-preset': 'veryslow'\n    '-x265-params': 'crf=${CRF}:scenecut=0:keyint=50:min-keyint=50:open-gop=0'\n  easyVmafExtraArgs:\n    '-threads': 20\npipelineVariables:\n  CRF:\n    - 22\n    - 26\n    - 30\n    - 34\n```\n\nThis will run transcode and vmaf analysis for CRF values 22,26,30, and 34. Variables are used in the ffmpeg options\nby inserting `${VARIABLENAME}`. This string will then be substituted with a value from the list of values from\n`pipelineVariables.VARIABLENAME`. Note that when running CRF encode or other non-ABR mode, `skipDefaultOptions` must\nbe set to avoid injecting bitrate options to ffmpeg. Also note that the cli needs to be run with the `--probe-bitrate`\noption to get the correct bitrate from the transcoded files.\n\nIt is also possible to use pipelineVariables with the AWSPipeline. The following example will run transcode and vmaf analysis using the AWS MediaCOnvert QVBR levels 6, 7, 8 and 9.\n\n```yaml\nname: job-name\npipeline: pipeline.yml\nencodingProfile: encoding-profile.json\nreference: reference.mp4\nmodels:\n  - HD\nresolutions:\n  - width: 1920\n    height: 1080\nbitrates:\n  - 0\npipelineVariables:\n  QVBR:\n    - 6\n    - 7\n    - 8\n    - 9\n```\n\n#### Generate VMAF measurements example\n\n```bash\nautovmaf --resolutions 1920x1080,1280x720,960x540 --bitrates 500k,800k,1200k,1600k,2000k,3000k,4000k --name my-autovmaf-test1 my-source-video.mp4\n```\n\nWith the above command, when the run is finished transcoded files will be available in the folder `my-autovmaf-test1`, and vmaf-data in the folder `my-autovmaf-test1/HD`.\n\n### Exporting results to csv\n\nTo export results to csv, use the `export-csv` command.\n\n```\nautovmaf export-csv \u003cfolder\u003e\n\nExport Vmaf results as csv\n\nPositionals:\n  folder  Folder with vmaf measurement results               [string] [required]\n\nOptions:\n  --version       Show version number                                  [boolean]\n  --help          Show help                                            [boolean]\n  --probeBitrate  Read bitrate of transcoded file with ffprobe\n                                                      [boolean] [default: false]\n  --variables     List of variables to include as columns in csv        [string]\n```\n\nIf your job uses variables ([See above](#using-variables-in-the-job-definition)), the variables that should\nbe included in the csv data should be specified with the `--variables` option.\n\n### Run VMAF only\n\nThis command allows using a configured pipeline to run VMAF measurements on any files without a related autovmaf job.\nIn case of an aws pipeline, output will be written to the `outputBucket` configured in the pipeline.\n\n```\nautovmaf vmaf\n\nUse pipeline to run VMAF for the given distorted and reference files\n\nOptions:\n  --version    Show version number                                     [boolean]\n  --help       Show help                                               [boolean]\n  --pipeline   Path to pipeline file                         [string] [required]\n  --reference  Uri or path to reference file                 [string] [required]\n  --distorted  Uri or path to distorted file                 [string] [required]\n  --model      VMAF model to use                        [string] [default: \"HD\"]\n```\n\n## Development\n\n### Run tests\n\n```bash\nnpm test\n```\n\n# About Eyevinn Technology\n\nEyevinn Technology is an independent consultant firm specialized in video and streaming. Independent in a way that we are not commercially tied to any platform or technology vendor.\n\nAt Eyevinn, every software developer consultant has a dedicated budget reserved for open source development and contribution to the open source community. This give us room for innovation, team building and personal competence development. And also gives us as a company a way to contribute back to the open source community.\n\nWant to know more about Eyevinn and how it is to work here. Contact us at \u003cwork@eyevinn.se\u003e!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEyevinn%2Fautovmaf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FEyevinn%2Fautovmaf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FEyevinn%2Fautovmaf/lists"}