Add speaker metadata

Published

August 22, 2026

This page describes the current Qt metadata manager. It is the recommended way to add or update a speaker entry. The manager edits the metadata database; it does not import raw measurement files or generate the website graphs.

What the metadata manager changes

Speaker metadata is stored in the datas/speaker_*.py files. The manager chooses the file from the first letter of the brand, validates the exported entry, preserves the project formatting, and creates a .bak copy before writing an existing file.

The manager can edit or create:

  • the speaker brand, model, type, shape, price, and amount;
  • the default measurement and each measurement’s origin, format, quality, and symmetry;
  • review URLs and publication dates;
  • optional data-acquisition details, extras, and specifications;
  • the speaker picture.

Raw measurement data remains in datas/measurements. Prepare those files with the appropriate importer or follow the digitisation tutorial before adding the corresponding measurement metadata.

Install the application

Run the commands from the repository root. The project currently supports Python 3.12 and 3.13 (>=3.12,<3.14), together with Git. The normal project setup also installs Node.js dependencies and the other tools used to build Spinorama.

Linux or macOS

Clone the repository if necessary and run the project setup script:

git clone https://github.com/pierreaubert/spinorama.git
cd spinorama
./scripts/setup.sh

The script creates .venv and installs requirements-meta.txt, which contains the PySide6 dependency used by the manager. Activate the environment and make the src packages importable:

source .venv/bin/activate
export PYTHONPATH="$PWD/src${PYTHONPATH:+:$PYTHONPATH}"

If the rest of the project is already installed, the smaller setup is enough for the UI dependency:

python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt -r requirements-meta.txt
export PYTHONPATH="$PWD/src${PYTHONPATH:+:$PYTHONPATH}"

Windows

Install Python 3.12, Git, and Node.js, then run the PowerShell setup script:

.\scripts\setup.ps1

For a minimal existing project environment:

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt -r requirements-meta.txt
$env:PYTHONPATH = "$PWD\src"

Configure and start the manager

Start it from the repository root with the virtual environment active:

python -m metaedit.app

The application reads the local datas metadata package, so running it from a different directory or without PYTHONPATH=src can result in an empty speaker list. To open an existing speaker directly in the edit step:

python -m metaedit.app --speaker "Brand Model"

The View menu provides Auto, Dark, and Light themes. The selected theme is saved in the operating system’s Qt application settings; there is no project configuration file to edit.

Before using Apply repository, configure Git credentials for the repository remote. The manager expects:

  1. the current branch to be develop;
  2. local develop to be exactly synchronized with origin/develop; and
  3. a working origin remote with permission to push.

If the GitHub CLI (gh) is installed and authenticated, the manager also opens the pull request automatically. Without gh, it still creates and pushes the metadata branch, and the pull request must be opened manually.

Add or edit a speaker

1. Select or create

On Step 1: Select or Create Speaker:

  • choose Existing speaker and use the search field to find an entry; or
  • choose New speaker, select an existing brand or enter a new one, and enter the model name.

Click Next. The manager loads existing values when editing an entry. For a new speaker, brand and model are required.

2. Edit the metadata

On Step 2: Edit Metadata, fill in the general fields. Select the speaker type (passive or active) and the closest available shape. Use Choose Picture to select a PNG, JPEG, JPG, or WebP image. The app copies the image to datas/pictures using the sanitized Brand Model name, so the copied file can be included with the metadata change.

Add at least one measurement with Add measurement. For every measurement:

  • give it a unique key, such as vendor or klippel;
  • enter its origin and choose the format that matches the source data;
  • set quality and symmetry when known;
  • add the review URL and publication date when the measurement came from a published review.

Use the expandable Data Acquisition, Extras, and Specifications sections when the information is available. Leave unknown optional values empty rather than guessing. Select the default measurement after all measurement tabs have been added.

The available measurement formats include Klippel, WebPlotDigitizer, Princeton, GLL, SPL/HV text, and REW text. The exact choices come from the current data model; choose the value corresponding to the files in datas/measurements.

Click Next to continue. The manager blocks a measurement with no key and validates the resulting entry before it is written.

3. Review and apply

On Step 3: Review & Export, inspect the generated JSON before changing the repository. For an existing speaker, Show Diff compares the loaded entry with the edited entry. Copy JSON to Clipboard is useful for reviewing or sharing the proposed data without writing anything.

When the entry is correct, click Apply to repository. The manager:

  1. checks the develop/origin/develop preflight;
  2. merges the entry into the appropriate datas/speaker_*.py file;
  3. reloads the local metadata list;
  4. creates a branch named like metadata-brand-model-YYYY-MM-DD, commits the changed metadata and picture, and pushes the branch; and
  5. creates a pull request when gh is available.

If the preflight fails, update the checkout manually and start the operation again. If the Git/PR step fails after the file was merged, inspect the file and the generated .bak backup, then complete the branch or pull request manually.

Measurement files and pictures

The metadata manager records where measurement data came from; it does not convert or copy measurement files. Keep source data in the repository’s normal layout under datas/measurements/<source>/<speaker>/. For a graph-only source, create the parsed WebPlotDigitizer project described in the digitisation tutorial. For GLL or Klippel data, use the corresponding importer and place its output in the same measurement tree.

Pictures can be added directly through Choose Picture. If adding one manually, place it under datas/pictures and use a filename based on the speaker’s brand and model. The manager recognizes .png, .jpg, .jpeg, and .webp files.

After adding measurement files or metadata, run the project checks from the repository root:

./scripts/check_meta.py

To regenerate and inspect a speaker’s graphs after the metadata and source files are in place:

./generate_graphs.py --speaker "Brand Model" --log-level INFO

Generated results are written below dist/<speaker>/. If generation fails, repeat it with --log-level debug; incorrect paths or incomplete metadata are the most common causes.