Registration¶

Your registration key determines how many nodes you can register and how long the license is valid. All analysis features are included in the license.

Registering¶

Register once with the key you received from AVEQ:

surfmeter-media register --key <KEY>

You can add a label and tags, which are shown for this node in the Surfmeter Dashboard. Separate tags by comma.

surfmeter-media register --key <KEY> --label "Encoding lab, workstation 2" --tags lab,encoding

The key can also be given in the SURFMETER_MEDIA_KEY environment variable instead of --key.

By default, the toolkit registers with AVEQ's hosted Surfmeter server. If your organization uses a dedicated server, pass it with --server or set SURFMETER_SERVER. For a server hosted by AVEQ, the short name is enough (for example --server acme for https://surfmeter-server.acme.aveq.info). For an on-premises server, give the full URL:

surfmeter-media --server https://surfmeter.example.com register --key <KEY>

Checking the license¶

surfmeter-media license shows the registration and the license state, without contacting the server:

surfmeter-media license

Add --json for machine-readable output, for example for monitoring scripts.

License validity

We check the license every 24 hours. If the server cannot be reached, it keeps working for 7 days after the last successful check. If the server reports that the license has expired or the node was disabled, you need to register again with a valid key.

Profile file¶

The registration is stored in a profile file, by default ~/.config/surfmeter/media-toolkit.json.

To use a different location, for example for a service account, pass --profile <path> or set SURFMETER_MEDIA_PROFILE.

Unregistering¶

To return the license to your key, for example before you decommission a machine:

surfmeter-media unregister

This frees the slot on the server and deletes the local profile.

Using CI or short-lived environments

In containers or CI jobs that start from a clean state for every run, a permanent registration would use a new slot each time. Use --ephemeral instead: it registers at the start of the run and returns the license at the end.

export SURFMETER_MEDIA_KEY=<KEY>
surfmeter-media analyze --ephemeral -o results input.ts

Docker¶

In Docker, the profile is stored at /config/media-toolkit.json. Keep it in a named volume, so that the registration survives container restarts:

docker volume create surfmeter-media-config

docker run --rm -v surfmeter-media-config:/config \
  registry.aveq.info/surfmeter/surfmeter-media:latest \
  register --key <KEY>

docker run --rm -v surfmeter-media-config:/config -v "$PWD:/data" \
  registry.aveq.info/surfmeter/surfmeter-media:latest \
  analyze -o results input.ts

For one-off runs, use an ephemeral registration without a volume:

docker run --rm --user "$(id -u):$(id -g)" -v "$PWD:/data" \
  -e SURFMETER_MEDIA_KEY=<KEY> \
  registry.aveq.info/surfmeter/surfmeter-media:latest \
  analyze --ephemeral -o results input.ts