Cithara is a comprehensive music theory toolkit and exploration platform designed to help users understand and interact with musical concepts such as notes, intervals, scales, and chords. The project combines a Python core library, a Django REST API backend, and a React/Next.js frontend to provide an interactive and educational experience.
The Cithara Project consists of three main parts:
-
Core Library (
cithara/core): A Python library implementing music theory logic — notes, intervals, scales, chords, and related utilities. This is designed to be robust, type-annotated, and modular for easy reuse. -
Backend API (
backend): A Django REST Framework-based API that exposes the core library functionalities through HTTP endpoints. This enables external clients, such as the frontend, to query and interact with musical data. -
Frontend Application (
frontend): A React/Next.js web application that provides a user-friendly, mobile-first interface for exploring musical scales, chords, and theory relationships, powered by the backend API.
cithara-project/
├── cithara/ # Core Python music theory library
│ ├── core/
│ └── utils/
├── backend/ # Django REST API backend
│ ├── apps/
│ ├── config/
│ └── manage.py
├── frontend/ # Next.js frontend
│ ├── app/
│ ├── components/
│ └── public/
├── README.md
├── requirements.txt
└── package.json- Note and Interval Representation: Precise handling of musical notes, accidentals, pitch classes, and intervals.
- Scale and Chord Generation: Ability to create major, minor, diminished, augmented scales and chords.
- Diatonic and Chromatic Relationships: Supports exploring relationships between notes and chords within scales.
- API Access: Exposes music theory computations as RESTful endpoints.
- Interactive Demo: Allows users to select notes, accidentals, and scales/chords to explore their structure dynamically.
- Python 3.12+
- Node.js (for frontend)
- pnpm or npm/yarn package manager
cd .
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runservercd frontend
pnpm install
pnpm dev- Visit the frontend at http://localhost:3000 (or your deployed URL).
- Use the interface to select root notes, accidentals, and scale types.
- Submit selections to fetch scale data dynamically from the backend.
- Explore generated scales and chords with interactive visual components.
- Follow test-driven development practices; tests live primarily in the backend tests/ directory.
- Backend API is built with Django REST Framework.
- Frontend uses React with Next.js and Tailwind CSS for styling.
- Core library is standalone Python code designed for reuse or extension.
- Use GitHub Actions for CI/CD including linting and type checks.
- Python 3.12, Django, Django REST Framework
- TypeScript, React, Next.js, Tailwind CSS
- Docker (planned)
- GitHub Actions for CI/CD
Contributions are welcome! Please fork the repository and submit pull requests with clear descriptions and tests where applicable :3
- Core Library: Add more scale and chord types, refine enharmonic logic, improve documentation, MIDI support.
- Backend API: Expand endpoint coverage and feature set, add authentication and rate limiting, implement caching.
- Frontend: Build comprehensive UI with more interactive components, better error handling and display, mobile optimisation, and potential user onboarding for full online Cithara app.
- Deployment: Set up CI/CD for backend and make backend deployment for site interactivity.
- CLI Tool: (Planned) Add a command-line interface for users to interact with the library directly.
- Documentation Site: Develop detailed user and developer documentation, tutorials, and example projects.
This project is licensed under the GNU General Public License v3.0 (GNU GPLv3).
Created and maintained by Ralph Mettle