CAMAT

CAMAT (Computer-Assisted Music Analysis Toolbox) is an MEI-centred Python toolbox for editorial and analytical work with symbolic music. MEI is the durable score document; conversion, note tables, statistical analysis, pattern search, and rendering all connect back to that file.

The three workflows can be used independently. An existing MEI edition can go straight to parsing, while a MusicXML or Humdrum source first passes through conversion as part of editing and preparing music with MEI.

Tables and matrices are working representations. They do not replace the edition; xml:id values are the bridge back to the score. Common-notation MEI is the supported path; mensural and timeline backends are experimental.

Guides, notebooks, and the API live in the documentation.

Install

Requires Python 3.11 or later.

python -m pip install camat

To run the showcase notebooks without cloning the whole repository:

camat-fetch-tutorials

That command copies notebooks/ and test_corpus/ into camat_tutorials/. See Cloud notebooks for Jupyter4NFDI and Google Colab.

To work on CAMAT itself:

git clone https://github.com/egorpol/camat_v2.git
cd camat_v2
python -m pip install -e ".[notebooks]"

Quick start

This example uses a tiny score shipped with CAMAT. After installation it runs offline, without a corpus download or Jupyter.

from importlib.resources import as_file, files
from camat import parse_files_quiet

example = files("camat").joinpath("examples", "facsimile_viewer_demo.mei")
with as_file(example) as score:
    results, _, _ = parse_files_quiet(
        [str(score)],
        backend="none",
        display_preview_df_pitch=False,
        display_preview_df_events=False,
        show_progress=False,
    )

notes = results[0]["df_pitch"]
print(f"Parsed {len(notes)} notes")

Expected output:

Parsed 8 notes

df_pitch holds note rows; df_events holds non-note events. Verovio is the default parser for common-notation MEI. Convert other formats first, then parse the resulting MEI.

Command-line tools such as camat-convert, camat-check-mei, and camat-fetch-tutorials are installed with the package.

What's in this repository

The PyPI wheel is the camat package: library code, a few packaged example scores, and the MEI 5.1 Common Music Notation schema. This git checkout also holds tutorials, documentation sources, tests, working corpora, and conference materials that are not shipped on PyPI.

camat_v2/
├── camat/            Installable package (conversion, parsers, analysis, rendering)
│   ├── examples/     Tiny MEI/SVG scores for offline demos
│   └── schemas/      MEI 5.1 CMN RELAX NG schema
├── notebooks/        Showcase tutorials, grouped into independent learning tracks
├── docs/             MkDocs sources published on Read the Docs
├── presentations/    Conference posters and talks (outside the installable package)
├── tests/            Pytest suite and synthetic fixtures
├── scripts/          Release checks, docs hooks, and maintainer probes
├── test_corpus/      Local MEI fixtures and corpus URL manifests
├── CAMAT_old/        Development archive (not a supported API)
└── exports/          Retained generated artifacts

Documentation

For bugs and suggestions, use GitHub Issues. See Contributing to work on the project.

The current checkout's general MEI validation guide documents camat-validate-mei, RELAX NG/Schematron, dependencies and execution records. These development changes are not yet part of a published release; install this checkout with python -m pip install -e '.[validation]' and provide xmllint separately. DdT publication policy is maintained in the corpus.

Authors and origins

Egor Polyakov — research and development; Martin Pfleiderer — principal investigator. Pia Steuck — research assistant.

The student assistants contributing to CAMAT's edition corpora are credited under About CAMAT.

The acronym was chosen in 2021–2022 for a basic MusicXML parsing tool; see the earlier project and tutorials. The current MEI-centred toolbox is a new implementation with a broader scope.

Funding, citation, and license

Funded by the German Research Foundation (DFG), programme Library and Information Services — E-Research Technologies (LIS), grant PF 669/18-1.

If you use CAMAT in research, cite the software and state the version. CITATION.cff supplies the metadata; GitHub exposes it through Cite this repository.

CAMAT's code is MIT licensed. Bundled material has separate notices.