FAQ & Troubleshooting

This page collects short answers to common setup and runtime issues when using Symusic.

Installation problems

pip install symusic falls back to a source build

Symusic publishes CPython wheels for Python 3.9 through 3.14 across the supported Linux, macOS, and Windows targets, including Windows ARM64. PyPy wheels are currently published for pp311 on manylinux_x86_64, macosx_x86_64, and macosx_arm64. If pip starts compiling from source:

  • Check that your Python version is supported (python -m pip debug --verbose is helpful).

  • Upgrade pip, setuptools, and wheel in your environment.

  • On PyPy, musllinux, or less common platform combinations, a source build can still be expected.

  • On ARM or other less common platforms, prefer a recent CPython release before trying to build from source.

If a wheel is not available for your platform, follow the source build instructions in Quickstart.

Compiler or toolchain errors when building from source

Symusic requires a C++20-capable toolchain:

  • GCC 11 or newer

  • Clang 15 or newer

  • MSVC 2022 on Windows

When builds fail with compiler errors:

  • Verify the compiler version with g++ --version / clang++ --version / cl and upgrade if needed.

  • On Linux without sudo, install gcc from conda and set CC/CXX as shown in Introduction.

  • Ensure the repository was cloned with submodules: git clone --recursive ....

Importing symusic fails after installation

If python -c "import symusic" raises an ImportError or complains about missing extension modules:

  • Confirm you are running the same Python interpreter that you used for pip install.

  • Check for multiple installations: python -m pip show symusic and pip show symusic should point to the same environment.

  • Reinstall inside a clean virtual environment to rule out conflicts:

python -m venv .venv-symusic
source .venv-symusic/bin/activate
pip install symusic
python -c "import symusic; print(symusic.__version__)"

Common runtime issues

File cannot be opened or parsed

Errors such as FileNotFoundError, IOError, or format errors when creating a Score usually trace back to one of:

  • Wrong path (relative vs. absolute). Use Path objects or pathlib.Path.resolve() for clarity.

  • Unsupported or corrupted files. Symusic focuses on MIDI and ABC; other formats may not be accepted.

  • Permission issues when reading from network drives or temporary directories.

Printing Path(path).resolve() before loading often makes path issues obvious.

Confusion around time units

Symusic works in three time domains: tick, quarter, and second. Mixing them accidentally can lead to surprising results (e.g., unexpected durations or densities).

  • Decide on a time unit at the start of a workflow and stick to it.

  • Use Score(..., ttype="second") when computing rates or densities over wall-clock time.

  • Convert explicitly with score.to("second") or score.to("quarter") before heavy analysis.

See Time Units for a deeper discussion.

Slow analysis over large datasets

If a pipeline over thousands of MIDI files is slower than expected:

  • Avoid re-reading the same file repeatedly; reuse Score objects when possible.

  • Use multiprocessing as shown in Data Processing.

  • Prefer structured NumPy exports (track.notes.numpy()) over Python loops inside tight inner loops.

Getting help

If you run into an issue that is not covered here:

  • Check the open and closed issues on the GitHub repository.

  • Open a new issue with:

    • OS, Python, and compiler versions

    • symusic.__version__

    • A minimal script and, if possible, a small MIDI file that reproduces the problem.

Clear, minimal reproductions make it much easier to fix bugs and improve the documentation.