{
  "schemaVersion": 1,
  "contentVersion": "ca42e61ede0a24f789d7287a0001244ad22f4abf",
  "id": "docs/tools/utilities/vship",
  "collection": "docs",
  "title": "Vship and FFVship",
  "description": "Vship computes SSIMULACRA2, Butteraugli and CVVDP on the GPU through the FFVship command-line tool, a VapourSynth plugin or a C API.",
  "canonicalUrl": "https://encode.wiki/tools/utilities/vship/",
  "apiUrl": "https://encode.wiki/api/v1/documents/docs/tools/utilities/vship.json",
  "markdownUrl": "https://encode.wiki/api/v1/markdown/docs/tools/utilities/vship.md",
  "status": "current",
  "tags": [
    "quality-metrics",
    "gpu",
    "vapoursynth",
    "charts"
  ],
  "license": "CC BY-SA 4.0",
  "dates": {
    "lastVerified": "2026-10-08T00:00:00.000Z"
  },
  "authors": [],
  "sources": [
    {
      "title": "Vship repository and README",
      "url": "https://codeberg.org/Line-fr/Vship",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "Vship releases (5.1.2, 5.1.1, 5.1.0, 5.0.1 notes)",
      "url": "https://codeberg.org/Line-fr/Vship/releases",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "FFVship v5.1.2 usage",
      "url": "https://codeberg.org/Line-fr/Vship/src/tag/v5.1.2/doc/FFVship.md",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "FFVship v5.1.2 argument parser",
      "url": "https://codeberg.org/Line-fr/Vship/src/tag/v5.1.2/src/ffvship_utility/ffmpegmain.hpp",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "Vship v5.1.2 VapourSynth API (SSIMULACRA2, Butteraugli, CVVDP)",
      "url": "https://codeberg.org/Line-fr/Vship/src/tag/v5.1.2/doc/Home.md",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    },
    {
      "title": "Vship v5.1.2 licence",
      "url": "https://codeberg.org/Line-fr/Vship/src/tag/v5.1.2/LICENSE",
      "accessedAt": "2026-10-08T00:00:00.000Z"
    }
  ],
  "headings": [
    {
      "depth": 2,
      "text": "Install",
      "anchor": "install"
    },
    {
      "depth": 2,
      "text": "FFVship",
      "anchor": "ffvship"
    },
    {
      "depth": 2,
      "text": "VapourSynth plugin",
      "anchor": "vapoursynth-plugin"
    },
    {
      "depth": 2,
      "text": "Licence",
      "anchor": "licence"
    }
  ],
  "sections": [
    {
      "id": "_preamble",
      "title": "Page introduction",
      "depth": 0,
      "canonicalUrl": "https://encode.wiki/tools/utilities/vship/",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/_preamble.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/_preamble.md",
      "checksum": "79bdc8c2749a2d8d49751c1457c6011d2395ba084c83e74b8f259dc6d5076583",
      "bytes": 1193
    },
    {
      "id": "install",
      "title": "Install",
      "depth": 2,
      "anchor": "install",
      "canonicalUrl": "https://encode.wiki/tools/utilities/vship/#install",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/install.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/install.md",
      "checksum": "4cdd6a7d3b5b4987dba28df1a7b674f1d48cc7ac42d68859558c5ac666674d59",
      "bytes": 1469
    },
    {
      "id": "ffvship",
      "title": "FFVship",
      "depth": 2,
      "anchor": "ffvship",
      "canonicalUrl": "https://encode.wiki/tools/utilities/vship/#ffvship",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/ffvship.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/ffvship.md",
      "checksum": "a56f18b0dda08765eda1fb62642964062b2b75c13d68fa5f1a38470f3f1f4249",
      "bytes": 3183
    },
    {
      "id": "vapoursynth-plugin",
      "title": "VapourSynth plugin",
      "depth": 2,
      "anchor": "vapoursynth-plugin",
      "canonicalUrl": "https://encode.wiki/tools/utilities/vship/#vapoursynth-plugin",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/vapoursynth-plugin.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/vapoursynth-plugin.md",
      "checksum": "39db8e5c6eaf28ab2a95493296b64d5a5dc285f9f98e9ee79bbe2dfed281c16a",
      "bytes": 1860
    },
    {
      "id": "licence",
      "title": "Licence",
      "depth": 2,
      "anchor": "licence",
      "canonicalUrl": "https://encode.wiki/tools/utilities/vship/#licence",
      "apiUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/licence.json",
      "markdownUrl": "https://encode.wiki/api/v1/sections/docs/tools/utilities/vship/licence.md",
      "checksum": "52647f642d4a93a5e3bb7e5e43160594afe6e958c4cdb6844d64c039b8226e8d",
      "bytes": 205
    }
  ],
  "outboundReferences": [
    "/reference/metrics/butteraugli/",
    "/reference/metrics/cvvdp/",
    "/reference/metrics/ssimulacra2/",
    "/tools/utilities/av1an/",
    "https://codeberg.org/Line-fr/Vship",
    "https://codeberg.org/Line-fr/Vship/releases",
    "https://codeberg.org/Line-fr/Vship/releases/tag/v5.1.2"
  ],
  "checksum": "c870cf521d942195af984b57655c2babde0384786db3792b42e8dc00b39da743",
  "contentFormat": "markdown",
  "markdown": "> **Repository:** [Line-fr/Vship](https://codeberg.org/Line-fr/Vship). A Library for GPU-accelerated visual fidelity metrics, featuring SSIMULACRA2, Butteraugli and CVVDP. Latest release: [v5.1.2](https://codeberg.org/Line-fr/Vship/releases/tag/v5.1.2), Oct 6, 2026. Last commit: Oct 6, 2026. Stars: 28.\n\nVship is a GPU implementation of three perceptual metrics: [SSIMULACRA2](/reference/metrics/ssimulacra2/), [Butteraugli](/reference/metrics/butteraugli/) and [CVVDP](/reference/metrics/cvvdp/). These are the metrics the encoding community prefers for comparing encodes, and they are slow on a CPU, so Vship is what makes scoring whole videos practical. Tools such as [Av1an](/tools/utilities/av1an/) and auto-boost scripts use it for target-quality encoding.\n\nIt comes in three forms:\n\n- **FFVship**, a command-line tool that decodes the two videos itself and prints or saves the scores;\n- a **VapourSynth plugin** (namespace `vship`) for use inside scripts;\n- a **C API** (libvship) for other programs.\n\nThe current release is 5.1.2 (October 2026). 5.1.1 fixed wrong decoding of full-range YUV and a CVVDP accuracy bug, so rescore anything measured with older versions before comparing.\n\n## Install\n\nWindows builds of FFVship and the library are on the [releases page](https://codeberg.org/Line-fr/Vship/releases), in CUDA (NVIDIA) and Vulkan versions. On Linux, build from source:\n\n```sh\nmake build BACKEND=Vulkan\nmake buildFFVSHIP\nsudo make install PREFIX=/usr\n```\n\nUse `BACKEND=Cuda` (needs the CUDA toolkit) or `BACKEND=HIP` (needs ROCm/HIP) for the native NVIDIA and AMD paths. FFVship also needs FFMS2, the libavutil headers and `pkg-config`. `make install` also links the library into `$PREFIX/lib/vapoursynth`, where VapourSynth loads plugins; the default `/usr/local` prefix may not be on its search path.\n\n| Backend  | GPUs                  | Notes                                                                                                                            |\n| -------- | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |\n| `Cuda`   | NVIDIA                | Fastest on NVIDIA in the author's benchmarks, especially for SSIMULACRA2 and CVVDP                                              |\n| `HIP`    | AMD                   | The author currently recommends Vulkan on AMD because of an AMD driver bug; `MITIGATE_MALLOC_ASYNC=on` builds a slower workaround |\n| `Vulkan` | Any GPU with a Vulkan driver | Most portable; close to CUDA for Butteraugli, slower for the other two. Even runs on a CPU through Mesa's lavapipe, slowly |\n\n## FFVship\n\n```sh\nFFVship --source reference.mkv --encoded distorted.mkv -m SSIMULACRA2 --json scores.json --svg scores.svg\n```\n\nIt prints the mean, standard deviation, median, 5th and 95th percentiles, minimum and maximum of the per-frame scores. For CVVDP it prints a single video score instead.\n\n| Option                                  | Use                                                                                                    |\n| --------------------------------------- | ------------------------------------------------------------------------------------------------------ |\n| `--source`/`-s`, `--encoded`/`-e`       | Reference and distorted video                                                                          |\n| `-m`, `--metric`                        | `SSIMULACRA2` (default), `Butteraugli` or `CVVDP`                                                      |\n| `--json FILE`                           | Per-frame scores; Butteraugli gives `[q-norm, 3-norm, max-norm]` per frame, CVVDP a running video score |\n| `--svg FILE`                            | Graph of the per-frame scores                                                                          |\n| `--start`, `--end`, `--every N`         | Score a range, or every Nth frame for a quick estimate                                                 |\n| `--encoded-offset N`                    | Shift the encode by N frames if the files don't start on the same frame                               |\n| `--cropTopSource` and similar           | Crop either input before scoring                                                                       |\n| `-g`, `--gpu-threads`                   | Frames in flight on the GPU (default 3); lower it to save VRAM                                         |\n| `-t`, `--threads`                       | Decoder processes (default 1); raise to 2–3 if decoding can't keep the GPU busy                        |\n| `--gpu-id`, `--list-gpu`                | Pick a GPU on multi-GPU systems                                                                        |\n| `--intensity-target`, `--qnorm`         | Butteraugli display brightness in nits (default 203) and extra norm (default 2)                        |\n| `--displayModel`, `--resizeToDisplay`   | CVVDP display model (default `standard_fhd`) and scaling to its resolution                             |\n| `--cache-index`                         | Keep the FFMS2 index files so repeat runs start faster                                                 |\n| `--verbose`                             | Print the size, range, matrix, transfer and primaries FFVship used for each file                       |\n\nNote that `-e` means `--encoded`, not `--every`. If the two videos have different sizes, FFVship resizes the encode to match the reference; crop first if the difference is borders rather than scaling.\n\nFFVship converts to RGB using each file's colour tags and guesses any that are missing, so an untagged file can score very differently from the same file tagged correctly. Check with `--verbose`, and tag the reference and encodes (for example BT.709, limited range) when the source is untagged.\n\n## VapourSynth plugin\n\n| Function                                 | Main arguments                                                                       | Per-frame properties                                                 |\n| ---------------------------------------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------- |\n| `core.vship.SSIMULACRA2(ref, dist)`      | `numStream`, `gpu_id`                                                                | `_SSIMULACRA2`                                                       |\n| `core.vship.BUTTERAUGLI(ref, dist)`      | `qnorm=2`, `intensity_multiplier=203`, `distmap=0`, `numStream`, `gpu_id`            | `_BUTTERAUGLI_QNorm`, `_BUTTERAUGLI_3Norm`, `_BUTTERAUGLI_INFNorm`   |\n| `core.vship.CVVDP(ref, dist)`            | `model_name=\"standard_fhd\"`, `resizeToDisplay=0`, `distmap=0`, `disableTemporal=0`   | `_CVVDP` (running score for frames 0 to *n*)                         |\n\nBoth clips must have the same dimensions and length. `numStream` limits how many frames are on the GPU at once and so the VRAM used; it defaults to the number of VapourSynth threads. `distmap=1` returns a greyscale difference map instead of scores, which you can step through in a previewer. For CVVDP, request the frames in order and read `_CVVDP` from the last one.\n\nRun scripts that print scores with `python`, not `vspipe`:\n\n```python\nimport vapoursynth as vs\ncore = vs.core\n\nref = core.bs.VideoSource(\"reference.mkv\")\ndist = core.bs.VideoSource(\"distorted.mkv\")\nclip = core.vship.SSIMULACRA2(ref, dist)\nscores = [f.props[\"_SSIMULACRA2\"] for f in clip.frames()]\nprint(sum(scores) / len(scores))\n```\n\nThe metric pages show complete scripts that summarise the scores with a mean, a low percentile and the worst frames.\n\n## Licence\n\nVship's README calls it MIT-licensed, but the `LICENSE` file is a modified \"MIT NON-AI License\" that forbids using the code, or including it in datasets, for training machine-learning systems.\n"
}