Celeritas

Celeritas (Latin: swiftness) — High-Performance Music Engine for .NET

Author: Vladimir V. Shein

📖 Documentation: sheinv78.github.io/Celeritas — getting started, a 10-minute tour, the concepts the API is built on, the full API reference, the cookbook, and the Python quickstart. Rebuilt from the sources on every push to main.

What is Celeritas?

Celeritas is a high-performance symbolic music analysis and generation engine focused on harmony, structure, and algorithmic composition. It leverages SIMD instructions (AVX-512, AVX2, SSE2, NEON) for maximum performance.

This is NOT:

❌ A DAW (Digital Audio Workstation)
❌ A VST plugin
❌ A synthesizer or audio engine

This IS:

✅ A symbolic music computation library
✅ A music theory analysis toolkit
✅ An algorithmic composition engine
✅ A research and educational tool

Project Status

🚧 Active Development — Experimental / Research Project
⚠️ API is not stable yet — Breaking changes may occur

Maintainer status (2026-08-23): v0.10.0 is the current stable release. Benchmarks refreshed May 2026.
Issues and PRs are welcome.

Current version: v0.10.0 (August 2026)
Extensive test suite: 950+ C# tests and 47 Python tests

Python API Coverage

Fast native bindings (default): a small, dependency-free ctypes layer backed by a NativeAOT library for core operations.
Full .NET API (complete coverage): an opt-in bridge via pythonnet so you can call the entire managed Celeritas API from Python.

Quick start (full .NET API):

pip install -e ./bindings/python
pip install pythonnet
dotnet build src/Celeritas/Celeritas.csproj -c Release

from celeritas import load_celeritas

Celeritas = load_celeritas().namespace

Intended Use Cases

✅ Primary Use Cases

Symbolic music analysis — Chord identification, key detection, harmonic analysis
Algorithmic composition — Auto-harmonization, melody generation, progression analysis
Music theory research — Modal analysis, voice leading, counterpoint, form analysis
Offline batch processing — MIDI file analysis and transformation
Educational tools — Music theory learning applications
DAW integration — Backend for compositional assistants via MIDI export
Notation software backends — Harmonic analysis for score editors

⚠️ Not (Yet) Intended For

Real-time audio synthesis
Live performance (latency-sensitive operations)
Audio signal processing (DSP)
Spectral analysis (audio → symbolic is out of scope)

🎯 Performance

Celeritas is designed for extreme performance.

Results vary by CPU, OS, .NET version, and workload. Run benchmarks yourself:

dotnet run --project src/Celeritas.Benchmarks -c Release

AMD Ryzen 9 9950X3D 4.30 GHz · 16 cores · AVX-512 · .NET 10.0.1 · May 2026:

| Method                    | Mean         | Allocated | Δ vs 7900X  |
|---------------------------|-------------:|----------:|------------:|
| Transpose_1M_Notes        |    28.6 µs   |         - |        −4%  |
| Transpose_10M_Notes       |   261.0 µs   |         - |       −66%  |  ← 3D V-Cache
| ScaleVelocity_1M_Notes    |    29.8 µs   |         - |        −2%  |
| ChordAnalysis_GetMask     |     0.81 ns  |         - |       −21%  |
| ChordAnalysis_Identify    |     1.26 ns  |         - |       −36%  |
| MusicNotation_ParseSingle |    11.2 ns   |         - |       −11%  |
| MusicNotation_Parse       |     2.69 µs  |   9.5 KB  |       −12%  |
| MusicNotation_Format      |    18.8 ns   |      32 B |        −2%  |
| Progression_Analyze †     |     6.54 µs  |  32.6 KB  |       n/a † |
| Quantize_1M_Notes         |     1.27 ms  |         - |        −1%  |

† Progression_Analyze is not comparable across versions: the report grew from ~10 fields in Dec 2025 to ~23. On the same machine it measures 7.14 µs ± 0.24 (32.9 KB) as of v0.10.0, about 9% slower than the 6.54 µs above — the correctness fixes in that release added work to this path, chiefly the profile correlation that lets key detection tell a key from its relative. Every other row was re-measured unchanged.

AMD Ryzen 9 7900X 4.70 GHz · 12 cores · AVX-512 · .NET 10.0.1 · December 2025:

⚠️ Note: These results were measured with an earlier version of the codebase (v0.9.0, December 2025). Progression_Analyze used a lighter ProgressionReport (~10 fields). The current version computes ~23 fields (tension curves, borrowed chords, secondary dominants, voice leading, cadences, etc.) — results are not directly comparable for that benchmark. All other rows are comparable.

| Method                    | Mean         | Allocated |
|---------------------------|-------------:|----------:|
| Transpose_1M_Notes        |    29.9 µs   |         - |
| Transpose_10M_Notes       |   773.6 µs   |         - |
| ScaleVelocity_1M_Notes    |    30.5 µs   |         - |
| ChordAnalysis_GetMask     |     1.03 ns  |         - |
| ChordAnalysis_Identify    |     1.96 ns  |         - |
| MusicNotation_ParseSingle |    12.6 ns   |         - |
| MusicNotation_Parse       |     3.05 µs  |   9.4 KB  |
| MusicNotation_Format      |    19.1 ns   |      32 B |
| Progression_Analyze †     |     2.27 µs  |  10.9 KB  |
| Quantize_1M_Notes         |     1.28 ms  |         - |

✨ Features

Core Engine

⚡ SIMD-Accelerated — Auto-detection and optimized code paths for AVX-512, AVX2, SSE2
🎵 NoteBuffer — Efficient note storage with rational time representation
📐 Rational Arithmetic — Precise fractional time without floating-point errors (auto-normalized)
🎼 Music Notation — Human-friendly parsing: "C4/4 [E4 G4]/4 G4/2." supports notes, chords, rests
🎹 Chord Notation — Multiple simultaneous notes: [C4 E4 G4]/4 or (C4 E4 G4):q
🧮 Note Arithmetic — PitchClass, ChromaticInterval, SpnNote for mod-12 pitch classes, intervals, and SPN notes
⏸️ Rest Support — Explicit rest notation with R/4, R:q, etc.
🔗 Tie Support — Merge notes across beats/measures with C4/4~ C4/4 → single note
🎶 Polyphony — Independent voices: << bass | melody >> for piano, SATB, counterpoint
🎯 Time Signatures — Support for 4/4, 3/4, 6/8, and any custom meter
📏 Measure Validation — Parse measures with | bars and validate durations match time signature
🎵 Directives — BPM, tempo character (Presto, Vivace), sections, parts, dynamics
⚡ Tempo Control — BPM with ramps: @bpm 120 -> 140 /2 (accelerando/ritardardo)
🔊 Dynamics — Volume levels (pp, mf, ff), crescendo/diminuendo with @dynamics, @cresc, @dim
🔄 Round-Trip Formatting — Export to notation: FormatNoteSequence, FormatWithDirectives with chord grouping
🚀 AOT-Ready — Native AOT compilation support for minimal overhead

Harmonic Analysis

🎹 Chord Recognition — Common chord qualities (triads, sevenths, sus, power/quartal, add9/add11, 7♭5), plus inversions
🧾 Chord Symbols (ANTLR) — Parse chord symbols into pitches: Dm7, C7(b9,#11), C7+5, C|G, C/E
🎼 Key Detection — Krumhansl-Schmuckler profiling, parallel keys, relative keys
🔄 Modulation Analysis — Distinguish tonicization from modulation (pivot chord, direct, sequential, chromatic, enharmonic, modal interchange)
🎭 Modal System — 19 modes (Ionian→Locrian, melodic/harmonic minor, blues scales)
📊 Progression Analysis — Roman numerals, tension curves, chord recommendations
🧭 Harmony Utilities — Circle of fifths + functional progressions (ii–V–I, turnaround, full circle, secondary dominants)
🎨 Chord Character — Emotional classification (Stable, Warm, Dreamy, Tense, Dark, Heroic...)
📝 Progression Reports — Detailed human-readable analysis with cadence detection

Melody Harmonization

🎹 Auto-Harmonization — Viterbi/DP algorithm for optimal chord selection
🔌 Pluggable Strategies — Custom chord candidates, transition scoring, harmonic rhythm
⚖️ Cost Optimization — Balances melody fit, voice leading, and harmonic function

Composition & Arrangement

🔢 Figured Bass — Realize figures (6, 6/4, 7) over a bass line into upper voices, with accidentals
🎹 Accompaniment — Turn a chord plan into a playable part: Block or Arpeggio patterns
🎻 Orchestration — Map a score onto instrument parts (Bass / Harmony) with per-instrument ranges

Ornamentation

🎵 Ornaments — Trill, Mordent, Turn, Appoggiatura, Grace Note, Glissando
🎯 Articulation — Staccato, Staccatissimo, Tenuto, Accent, Marcato, Legato
🧩 Applier — OrnamentApplier expands ornaments into note sequences in place

Counterpoint & Voice Leading

🎤 Voice Separation — Automatic polyphonic voice separation (SATB)
🔗 Voice Leading Solver — Parallel SATB voicing solver (dynamic programming + smoothness heuristic)
🎯 Roman Numeral Analysis — Chord function in key context (I, ii, V7, etc.)
⚠️ Rule Checking — Parallel 5th/octave detection, hidden perfects, spacing rules

Rhythm Analysis

🥁 Meter Detection — Auto-detect time signature (4/4, 3/4, 6/8...) with confidence
🎵 Pattern Recognition — 13 built-in patterns: straight quarters/eighths/sixteenths, dotted quarter-eighth, triplet, syncopated, Habanera, Tresillo, Clave 3-2, Charleston, Shuffle, Backbeat, Waltz
📈 Prediction — Markov chains for style-based rhythm generation (classical, jazz, rock, latin, waltz)
🔀 Syncopation — Syncopation and swing analysis
🎚️ Groove — Groove feel (Straight/Swing/Shuffle/Latin/Compound) and drive (0-1)

Melodic Analysis

📈 Contour — Ascending, Descending, Arch, Bowl, Wave, Static, Complex
🎯 Ambitus — Range analysis with characterization
🔍 Motif Detection — Automatic discovery of recurring patterns
📊 Interval Statistics — Steps vs leaps, interval histogram

Form Analysis

📝 Phrase Segmentation — Automatic phrase boundary detection
🎼 Cadence Detection — Authentic, Plagal, Deceptive, Half, Phrygian cadences
🏗️ Section Detection — A/B/A' formal structure recognition (Jaccard similarity)
📊 Period Detection — Antecedent-consequent phrase pairs

MIDI I/O

📥 Import — Load MIDI files into NoteBuffer
📤 Export — Save NoteBuffer to Standard MIDI files
🧩 Utilities — Clone, merge, split (track/channel), and statistics
⏱️ Timing Events — Tempo and time signature events read/write

MusicXML I/O

📥 Import — score-partwise and score-timewise: pitches, rests, chords, ties, multiple voices/parts
📤 Export — Write score-partwise, with import → export → import round-trip fidelity tests
🗜️ Compressed Scores — Read .mxl archives (with a decompression safety limit)
🔊 Dynamics — <dynamics> marks and <sound dynamics> set note velocity; single-voice export writes velocity back out

Pitch Class Set Analysis

🔢 Normal Order & Prime Form — Atonal music analysis
📊 Interval Vector — Interval class content
🔄 Transposition & Inversion — Tn and TnI operations
📚 Forte Catalog — Pluggable JSON catalog for set identification

🚀 Quick Start

Installation

Library (for developers)

dotnet add package Celeritas

Or via NuGet Package Manager:

Install-Package Celeritas

CLI Tool (for end users)

# Install globally
dotnet tool install --global Celeritas.CLI

# Use from anywhere
celeritas --version
celeritas analyze --notes C4 E4 G4

Update to latest version:

dotnet tool update --global Celeritas.CLI

📘 Documentation

Quick Start Examples

Parse music notation:

using Celeritas.Core;

// Simple notes
var notes = MusicNotation.Parse("C4 E4 G4 B4");

// With durations and chords
var melody = MusicNotation.Parse("C4/4 [E4 G4]/4 G4/2.");

// Time signatures and measures (validated against the meter)
var song = MusicNotation.Parse(
    "4/4: C4/4 E4/4 G4/4 C5/4 | D4/1", validateMeasures: true);

// With directives (tempo, dynamics)
var result = MusicNotation.ParseFull(
    "@bpm 120 @dynamics mf C4/4 E4/4 G4/4");

Analyze chords and keys:

using Celeritas.Core;
using Celeritas.Core.Analysis;

// Chord identification
var chord = ChordAnalyzer.Identify("C4 E4 G4 B4");
Console.WriteLine(chord);  // Output: C Major7

// Key detection
var melody = MusicNotation.Parse("C4/4 D4/4 E4/4 F4/4 G4/4");
var key = KeyAnalyzer.DetectKey(melody);
Console.WriteLine(key);  // Output: C Major

// Modal analysis
var scale = MusicNotation.Parse("D4 E4 F4 G4 A4 B4 C5 D5");
var (mode, confidence) = ModeLibrary.DetectModeWithRoot(scale);
Console.WriteLine(mode);        // Output: D Dorian
Console.WriteLine(confidence);  // Output: 0.19 - confidence is the margin over
                                // the runner-up mode, not a goodness-of-fit score

Parse chord symbols (ANTLR):

using Celeritas.Core.Analysis;

var pitches1 = ProgressionAdvisor.ParseChordSymbol("C7(b9,#11)");
var pitches2 = ProgressionAdvisor.ParseChordSymbol("C7+5");
var pitches3 = ProgressionAdvisor.ParseChordSymbol("C|G");   // polychord layering
var pitches4 = ProgressionAdvisor.ParseChordSymbol("C/E");   // slash bass

Console.WriteLine(string.Join(" ", pitches1));

Note arithmetic (pitch classes, intervals, scientific pitch notation):

using Celeritas.Core;

// Pitch-class arithmetic wraps modulo 12
var pc = PitchClass.C;
var d = pc + 2;
Console.WriteLine(d);              // D

// Differences return intervals
var asc = PitchClass.C - PitchClass.B;                    // +1 (ascending wrap)
var shortest = PitchClass.C.SignedIntervalTo(PitchClass.B); // -1 (shortest signed)
Console.WriteLine(asc.SimpleName);        // m2
Console.WriteLine(shortest.Semitones);    // -1

// Notes with octave (SPN) + transposition
var c4 = SpnNote.C(4);
var e4 = c4 + ChromaticInterval.MajorThird;
Console.WriteLine(e4); // E4

// Control enharmonic spelling when formatting
Console.WriteLine(SpnNote.CSharp(4).ToNotation(preferSharps: false)); // Db4

📚 Complete Documentation

Documentation site - The guide, concepts, cookbook and API reference, generated from the sources on every push
- Getting started - From an empty project to a first analysis
- 10-minute tour - Chords, keys, modes, progressions, voice leading, MIDI
- Upgrading to 0.10 - What changed for code written against 0.9.x
- API reference - Every public type and member, by namespace
- The same pages as Markdown, for reading in the repository: docs/
Examples - Working code samples organized by topic
- Notation Basics - Parsing, chords, rests, ties
- Round-Trip Formatting - Export back to notation
- Directives - Tempo, dynamics, sections
- Chord Analysis - Identification and inversions
- And more...
Cookbook - Common patterns and recipes
- Quick start recipes
- Chord and key analysis
- Harmonization workflows
- MIDI processing
- Performance optimization
Python Guide - Using Celeritas from Python

🔧 CLI Tool

# Chord analysis
celeritas analyze --notes C4 E4 G4 B4

# Key detection
celeritas keydetect --notes C4 E4 G4 B4 D5

# Mode detection
celeritas mode --notes C D Eb F G A Bb

# Progression analysis
celeritas progression --chords Dm7 G7 Cmaj7 Am7

# SATB voice leading
celeritas voicelead --chords Dm7 G7 Cmaj7

# Melodic contour, intervals, motifs
celeritas melody --notes C4 E4 G4 F4 D4

# Rhythm analysis + style-based prediction
celeritas rhythm --durations 1/4 1/8 1/8 1/4 1/4 --style jazz --predict 4

# Polyphonic texture and voice separation
celeritas polyphony --notes "4/4: [C4 E4 G4]/4 [D4 F4 A4]/4 [E4 G4 B4]/2"

# Pitch class set analysis (normal order, prime form, interval vector)
celeritas pcset --notes C4 E4 G4 B4

# MIDI file analysis
celeritas midi analyze --in song.mid
celeritas midi info --in song.mid
celeritas midi import --in song.mid

# Transpose notes or MIDI
celeritas transpose --semitones 5 --notes C4 E4 G4
celeritas midi transpose --in song.mid --out transposed.mid --semitones 2

# Export to MIDI
celeritas midi export --out output.mid --notes "4/4: C4/4 E4/4 G4/4"

# MusicXML: convert either way (direction inferred from extensions), or summarize
celeritas musicxml convert --in song.mid --out score.musicxml
celeritas musicxml convert --in score.musicxml --out score.mid
celeritas musicxml analyze --in score.musicxml

# System info
celeritas info

For complete CLI documentation, see celeritas --help.

🏗️ Building from Source

Requirements:

.NET 10.0 SDK or later
CPU with SSE2 (minimum), AVX2 or AVX-512 (recommended)

git clone https://github.com/sheinv78/Celeritas.git
cd Celeritas
dotnet build
dotnet test

Native AOT Compilation

dotnet publish src/Celeritas.CLI -c Release -r win-x64
dotnet publish src/Celeritas.CLI -c Release -r linux-x64
dotnet publish src/Celeritas.CLI -c Release -r osx-arm64

🧪 Testing

# C# tests
dotnet test

# Python tests
cd bindings/python
python test_celeritas.py

Current: 950+ C# tests and 47 Python tests, all passing

🎉 Recent Updates (v0.10.0 - August 2026)

A correctness release: a full audit of the library found and fixed a class of bugs that returned confident wrong answers instead of failing loudly. Highlights:

✅ Meter detection - 4/4 and 3/4 are reachable again (scoring made 2/4 and 6/8 always win)
✅ Voice separation - overlapping notes stay in separate voices, so polyphony analyzes as polyphony
✅ Progression analysis - chromatic chords are no longer treated as tonic I, removing false cadences
✅ Modulation detection - the confidence gate now matches how confidence is actually defined
✅ Figured bass - upper voices sound above the bass; the natural (n) figure works outside C major
✅ MusicXML - irregular meters (3/8, 7/8) round-trip exactly; per-voice tie tracking
✅ Parsing - ParseKey and the chord-symbol parser reject garbage instead of guessing

See CHANGELOG.md for the full list, including breaking changes.

🔭 Next Ideas

Expand MIDI transformations (track/channel workflows, musical merges, timing edits)
Add more CLI commands/examples around rhythm & groove analysis
Improve documentation coverage (Cookbook recipes, API notes, performance tips)
Add more test-data samples and stress tests for edge cases
Continue performance work (benchmarks, allocations, SIMD paths)

📊 SIMD Platform Support

Platform	SIMD	Status	`int` lanes per operation
x64 Intel/AMD	AVX-512	✅	16
x64 Intel/AMD	AVX2	✅	8
x64 Intel/AMD	SSE2	✅	4
ARM64	NEON	✅	4
WebAssembly	SIMD128	🧪 experimental, not yet CI-tested	4
Fallback	Scalar	✅	1

Lane counts are a property of the instruction set; throughput is not, so this table no longer guesses at one. The measured figure is the benchmark above: Transpose_1M_Notes runs 1M notes in 28.6 µs on AVX-512 — about 35 billion notes/sec — in steady state with the buffer resident in cache. A single cold run, such as celeritas benchmark or examples/11-performance-simd.cs, includes JIT and cold caches and will report roughly an order of magnitude less; that is a different measurement, not a contradiction.

📄 License

Licensed under the Business Source License 1.1 (BSL-1.1).

Change Date: 2030-01-01 (then: Apache-2.0)

Until the Change Date, commercial production use requires a commercial license.

✅ Free for non-commercial use
✅ Free for open source projects
⚠️ Commercial use requires a license

For commercial use, contact us.

License FAQ (short)

Can I use this for learning / research / personal projects? Yes.
Can I use this in an open-source project? Yes, if your project is distributed under an OSI-approved license.
Can I use this in a commercial product or service? Not without a commercial license (until the Change Date).
What happens on the Change Date? On 2030-01-01, Celeritas becomes available under Apache-2.0.
Not sure if your use is commercial? Please open an issue and describe your use case.

📚 Dependencies

Celeritas uses the following third-party libraries:

DryWetMIDI

Melanchall.DryWetMIDI 8.0.3
License: MIT License
Purpose: MIDI file import/export

ANTLR 4

Antlr4.Runtime.Standard 4.13.1
License: BSD-3-Clause License
Purpose: Music notation parser generation

All other functionality (SIMD acceleration, harmonic analysis, voice leading, rhythm analysis, etc.) is implemented natively in Celeritas.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Development Setup

git clone https://github.com/sheinv78/Celeritas.git
cd Celeritas
dotnet restore
dotnet build
dotnet test

Publishing (Maintainers)

Releases are automated via GitHub Actions:

Development builds - Automatic on push to main
Stable releases - Create a tag:
```
git tag v0.10.0
git push origin v0.10.0
```

This triggers:

✅ Build on Ubuntu, Windows, macOS
✅ Run all tests
✅ Create NuGet packages
✅ Publish to NuGet.org (on tag)
✅ Create GitHub Release with artifacts

Note: Set NUGET_API_KEY secret in GitHub repository settings.

📧 Contact

Documentation: sheinv78.github.io/Celeritas
GitHub Issues: Bugs and feature requests
Email: sheinv78@gmail.com

Made with ⚡ and 🎵

Name		Name	Last commit message	Last commit date
.config		.config
.github		.github
assets		assets
bindings/python		bindings/python
docs		docs
examples		examples
scripts		scripts
src		src
test-data		test-data
tests/Celeritas.Tests		tests/Celeritas.Tests
.editorconfig		.editorconfig
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
Celeritas.sln		Celeritas.sln
Directory.Build.props		Directory.Build.props
LICENSE.md		LICENSE.md
README.md		README.md
ROADMAP.md		ROADMAP.md
THIRD-PARTY-NOTICES.md		THIRD-PARTY-NOTICES.md

Latest commit

History

Folders and files

Repository files navigation