Developer guide
This guide is written so that one person, with basic Python and no help beyond the internet and a library card, can pick up Alto and keep developing it. It explains how the program works, and also the ideas underneath it that a Python programmer may never have met: how computers make sound, how music notation is drawn, how a flash-card program decides what to ask you next, how to make a Qt program look and move the way you want.
It does not replace the shorter pages. For developers is the quick reference for commands and tooling, ARCHITECTURE.md is a one-page map of the code, and the API reference lists every public class and function. This guide is the explanation that ties them together.
How to use this guide
Read Getting oriented first, whatever else you do. Then read what you need:
| If you want to … | Read |
|---|---|
| Get the program running, find your way around, and follow the project’s rules | Getting oriented |
| Understand the Python features the code leans on (dataclasses, type hints, keyword-only arguments, closures) | Python beyond the basics |
| Understand Qt: the event loop, signals, painting, ownership, and the traps in each | Qt and PySide6 |
| Change how the program looks (colours, themes, stylesheets, icons, custom widgets) | Styling beyond QtWidgets |
| Change how music is drawn (clefs, noteheads, key signatures, fonts) | Rendering music notation |
| Change or add sounds (instruments, pitch shifting, timing) | Computer audio |
| Change what gets asked and when | Spaced repetition and adaptive practice |
| Add or change movement on screen | Animation |
| Add an exercise, from idea to published docs | Building an exercise |
| Change what is stored, or add a column | Data and persistence |
| Run the checks, understand CI, and release | Testing, quality and release |
| Work out why something strange is happening | Pitfalls and debugging |
| Look up a term, or find a book to read | Glossary and further reading |
The mental model in one page
Alto is four layers. Only the top one knows that Qt exists.
alto/ui windows, drawing, animation, saved settings (Qt)
|
alto/audio.py sample playback, pitch shifting, synthesis (Qt Multimedia)
|
alto/learning profiles, SQLite, the scheduler, statistics (no Qt)
|
alto/exercises Exercise and Question, the eight exercises (no Qt)
|
alto/settings the user's choices as plain objects (no Qt)
|
alto/theory spelled notes, intervals, scales, chords (no Qt)
Three ideas carry the whole design. If you remember nothing else, remember these.
- A
Questionis plain data. An exercise’s only job is to turn a random number generator and the current settings into aQuestion: a prompt, some buttons, what to draw, which answer is right. The screen, the scheduler and the database know nothing about any particular exercise. They only handleQuestions. That is why adding an exercise needs no new interface code. - Each question has a strain. The database keeps one number for every question a person has met: how much practice it still needs. Wrong answers and slow answers raise it, quick right answers lower it. The chance of a question being asked is an exponential function of that number. There are no due dates and no schedules.
- Everything is drawn, not assembled. Staffs, keyboards, charts, switches, even the pictures in the settings panes are
painted with
QPainterfrom numbers. That is why they follow the theme, scale cleanly and animate, and also why a drawing bug is a geometry bug, not a layout bug.
If you can no longer use an LLM
The code base was written with an assistant’s help, and was shaped so that you do not need one to maintain it. These habits are what make that true, and the guide assumes you keep them.
- Every function explains itself. Each module, class and function has a NumPy-style docstring with every parameter, the
return value and a runnable example. Read the docstring before the code.
pytestruns the examples, so they are never out of date. - Types are complete. Every signature is annotated and Pyright checks them. When you are unsure what a value is, the signature tells you.
- The tests are the safety net. More than a thousand tests and doctests run in a minute. Make a change, run
pytest, and fix what turns red. The tests drive widgets with Qt’s offscreen platform, so no screen is needed. - The rules are mechanical. Ruff, Pyright, the pre-commit hooks and the tests check the style for you. You do not have to remember the rules, only to run the checks. Getting oriented lists them.
- Hard parts have a chapter. Audio, notation, spaced repetition, styling and animation each have a chapter that starts from first principles and ends with a reading list.
A workflow that works without an assistant:
- Find the code. Search the API reference or run
grep -rn "name" alto/. - Read the docstring and its example. Open a Python shell and run the example with small changes until the behaviour is clear.
- Write a failing test for the change first, in
tests/. It tells you when you are done. - Make the change. Run
pytest -x -qoften, since most mistakes show up in seconds. - Run the full checks listed in Getting oriented before you commit.
- If you change a docstring or a public signature, run
python scripts/api_docs.py. If you change anything the user can see, regenerate the screenshots withpython scripts/screenshots.py.
Words that come up again and again
You will meet these terms in the chapters. Each has a short entry in the glossary.
Event loop. Signal and slot. Painter. Palette. Style sheet. Staff space. SMuFL. Glyph. Engraving. Sample. Sample rate. PCM. MIDI note number. Equal temperament. Resampling. Strain. Spacing effect. Retrieval practice. Softmax. Easing. Property animation. Offscreen platform. Doctest. Fixture. Monkeypatch.
A word on the reading lists
Each chapter ends with further reading. They favour books, peer-reviewed papers, standards and official documentation over blog posts. Where a source is on the author’s own site (as the Stanford audio books are), it is there because it is the primary source. Web addresses change, so the lists give authors, titles, publishers and years, which are enough to find a book or paper even when a link has gone. Treat the addresses as hints.