vmafx-server gRPC service¶

vmafx-server is a single Go binary that exposes VMAF scoring over both gRPC (default :9090) and HTTP/JSON (default :8080). This page covers the gRPC interface; see rest.md for the HTTP endpoints (/v1/score, /healthz, /readyz, /metrics, ...).

Quick start¶

1. Run the server locally. It needs a vmaf binary, for example from core/build-cpu. Configuration is by VMAFX_ environment variables only; the pre-fx CLI flags were removed in ADR-1119.

   VMAFX_VMAF_BINARY=core/build-cpu/tools/vmaf \
   VMAFX_MODEL_DIR=model/ \
   VMAFX_HTTP_ADDR=:8080 \
   VMAFX_GRPC_LISTEN=:9090 \
   go run ./cmd/vmafx-server
   

2. Or run the published release image (multi-architecture amd64/arm64). Use a release tag such as v1.0.0-rc.2 or latest. Images published after v1.0.0-rc.2 have zstd layers and need Docker Engine 23.0 or later, Docker Desktop 4.19 or later, Podman or containerd 1.5 or later (what can pull them).

   docker run --rm \
       -p 8080:8080 -p 9090:9090 \
       ghcr.io/vmafx/vmafx-server:v1.0.0-rc.2
   

3. Verify the release version without starting listeners.

   docker run --rm ghcr.io/vmafx/vmafx-server:v1.0.0-rc.2 --version
   

4. To test a local build, build the image and inject the version explicitly when you test release behaviour.

   docker build -f Dockerfile.go-server \
       --build-arg VMAFX_VERSION=dev \
       -t vmafx-server:dev .
   

Proto definition¶

The services are defined in api/vmafx-platform.toml, from which the generator writes proto/vmafx/v1/vmafx.proto (the scoring service) and proto/vmafx/controller/v1/controller.proto (the controller). The scoring options (ScoreOptions) and the provenance record (Provenance) come from proto/vmafx/v1/vmafx_api.proto, which is generated from core/api/vmafx.toml; the scoring API contract lists every option and says how the API may change. Go stubs live under gen/go/ and are vendored in-tree; see API generation for how they are regenerated.

service VmafxScoring {
  rpc Score(ScoreRequest)   returns (ScoreResponse);                       // unary, file-path
  rpc ScoreStream(stream ScoreStreamRequest)                              // bidirectional, in-memory
      returns (stream ScoreStreamResponse);                               //   per-frame (ADR-0933)
  rpc Health(HealthRequest) returns (HealthResponse);
}

message ScoreRequest {
  string reference = 1;          // absolute path to reference YUV/Y4M
  string distorted = 2;          // absolute path to distorted YUV/Y4M
  string model     = 3;          // model name, e.g. "vmaf_v0.6.1"; empty defaults to vmaf_v1.0.16_3d0h
  ScoreOptions options = 4;      // geometry, backend, threads, precision, ... (generated)
}

message ScoreResponse {
  double              score      = 1;  // aggregate VMAF score
  map<string, double> features   = 2;  // per-feature pooled-mean values
  ScoreProvenance     provenance = 3;  // how the score was made; in every response
}

Scores are lossless (options.precision max) unless the request names another precision. A raw .yuv pair needs width, height, pixel_format and bitdepth in options; an option value the contract refuses is INVALID_ARGUMENT.

Regenerate stubs after changing either proto file (the generated messages come from python3 scripts/codegen/vmafx-api.py --write first):

buf generate proto   # requires buf ≥ v1.30 and the buf CLI on PATH
python3 scripts/proto/postprocess_gen_go.py

Example: grpcurl¶

grpcurl -plaintext \
    -d '{"reference":"/data/ref.yuv","distorted":"/data/dis.yuv","model":"vmaf_v0.6.1",
         "options":{"width":576,"height":324,"pixelFormat":"420","bitdepth":8}}' \
    localhost:9090 vmafx.v1.VmafxScoring/Score

Expected response (Netflix golden pair; grpcurl prints proto JSON names in lowerCamelCase):

{
  "score": 76.66783149135578,
  "features": {
    "vmaf":            76.66783149135578,
    "integer_adm2":    0.9345057762923995,
    "integer_motion2": 3.894360826611791
  },
  "provenance": {
    "library": {"abiMinor": 1, "abiPatch": 4, "activeBackend": "cpu", "nExtractors": 3,
                "version": "v1.0.0-rc.2-529-gb8b3af281"},
    "model": "vmaf_v0.6.1",
    "modelSha256": "5950d61fa1f861bd45d8149d80539ed9f3376cfc2495b8f0fa8e9f57cb131ee3",
    "backendUsed": "cpu",
    "featureBackends": [{"extractor": "adm", "backend": "cpu"}],
    "precision": "max"
  }
}

Streaming: ScoreStream¶

ScoreStream is a bidirectional RPC for per-frame scoring of in-memory raw frames, with no file round-trip. The message flow:

1. The client sends one StreamConfig (width, height, pixel format, optional model).
2. The client sends a sequence of FramePair messages: frame_index strictly increasing from 0, raw_reference / raw_distorted as planar Y-U-V bytes.
3. The client half-closes.
4. The server flushes the engine and streams back one FrameScore per frame, then a terminal AggregateScore (pooled VMAF, per-feature pool, frame count, elapsed wall time).

Supported pixel formats: YUV 4:2:0 / 4:2:2 / 4:4:4 in 8-bit and 10-bit-LE. Each FramePair payload must be exactly the configured frame size in bytes; mismatches are rejected with codes.InvalidArgument. The same RPC is served by vmafx-node (ADR-1109).

See grpc-streaming.md for the message-shape table, the pkg/score client wrapper, and a worked client loop.

Configuration¶

The server runs on the golusoris fx framework (ADR-1119). Runtime configuration is environment-only: golusoris' koanf layer reads 12-factor variables under the VMAFX_ prefix, and _ in the env name maps to the . config-key separator (so VMAFX_HTTP_ADDR sets http.addr).

• Source precedence, the underscore rule and the default HTTP and gRPC limits are on Server configuration.
• The framework owns the listen sockets, so the HTTP and gRPC settings take full listen addresses (:8080), not bare port numbers.
• The sole process switch is --version. It prints the build-time version and exits without constructing the fx application or binding listeners.

Prometheus metrics¶

The /metrics endpoint exposes the following counters and histograms in Prometheus exposition format, plus Go runtime and process metrics.

Logging¶

The log format follows VMAFX_LOG_FORMAT (auto, tint or json; default auto). With the json handler each line is a single-line JSON object, for example:

{"time":"2026-05-28T12:00:00.000Z","level":"INFO","msg":"http Score completed","request_id":"4bf92f3577b34da6","route":"POST /v1/score","model":"vmaf_v0.6.1","score":"76.6683","duration_s":0.823}

Request-scoped lines use one set of field names (pkg/observability/logfields.go):

The legacy POST /v1/score path logs this set today; the gRPC and OpenAPI REST paths adopt it as their log calls move onto the same helpers.

Graceful shutdown¶

The server listens for SIGTERM and SIGINT. On receipt it:

1. Stops accepting new connections.
2. Waits up to 30 seconds for in-flight requests to drain.
3. Exits with code 0.

Relationship to the Python HTTP server (ADR-0701)¶

The Python vmaf-mcp --transport http server (PR #1583, ADR-0701) remains the default transport for MCP/stdio IDE integrations and is not removed by the Go server. The Go server is an additive Phase-4 deliverable targeting Kubernetes deployments where startup time and gRPC are material. See MCP HTTP transport for the Python server.

Further reading¶

• ADR-0703 — decision record for this service.
• ADR-0701 — Python HTTP transport foundation.
• REST adapter — /healthz, /readyz, /metrics, /v1/score.
• Python MCP HTTP transport — the separate Python REST mode.
• k8s deployment guide — Helm chart configuration.