How shreyanmitra/tabalchi works
1. What this repository is
- Tabalchi is primarily a Python library for tabla composition parsing, playback, notation export, generation, and transcription.
- It also includes a minimal browser UI (index.html) and a Python backend shim (Tabalchi/web_backend.py) for serving or wiring the UI to library capabilities.
2. Core input format
- The main artifact is a .tabla file, which the README says is JSON-compatible and describes a composition.
- These files define things like composition type, taal, speed, jati, playing style, and nested musical structure such as mainTheme, paltas, and tihai.
3. Central parsing and domain layer
- Tabalchi/main.py appears to be the heart of the library, centered on BolParser.
- Parsing converts a .tabla document into a domain model made of Bol, Beat, Phrase, and supporting musical classes.
- The parser also handles syntax rules like beat separators, grouped phrases, and inference markers described in the README.
4. Musical metadata model
- The repository models tabla-specific concepts explicitly:
- Taal for rhythmic cycles
- Jati for subdivision pattern
- Speed / SpeedClasses for tempo handling
- BeatRange for beat-interval logic
- CompositionType for validating composition schemas
- This is the main abstraction boundary between raw text input and musical behavior.
5. Playback and audio subsystem
- The playback path runs from parsed Bol down to Beat → Phrase → Sound.
- Sound and Fetcher provide the audio material for individual bols/phrases, and the README indicates the project ships with recorded tabla samples in the recordings/ directory.
- Playback is therefore sample-based, not MIDI-based.
6. Audio dependencies and external tools
- The README makes ffmpeg important for audio handling, especially tempo-adjusted playback.
- It also mentions acoustid-fingerprinter for transcription-related workflows.
- These are system-level dependencies that materially affect how the audio pipeline functions.
7. Notation export path
- The same parsed Bol can be rendered into textual notation through the abstract Notation layer.
- Concrete notation formats include Bhatkande and Paluskar.
- So the output path is: .tabla → parser/domain model → notation renderer → .txt/.pdf-style output files.
8. Generation subsystem
- CompositionGenerator is a separate capability for creating compositions from parameters such as type, taal, speed class, jati, and school.
- The README shows it can use either:
- a local model/endpoint first, or
- a hosted Hugging Face-backed flow
- This makes generation an optional AI-assisted subsystem, not part of the core parser.
9. Transcription subsystem
- AudioToBolConvertor is the reverse pipeline: audio recording → bol transcription.
- This likely depends on the audio tooling above and sits as a distinct feature next to parsing/playback rather than inside them.
10. Web/UI layer
- index.html is the standalone front-end entrypoint, and .github/workflows/pages.yml deploys it to GitHub Pages.
- Tabalchi/web_backend.py suggests a thin backend used to bridge browser interactions to Python-side parsing, playback, or generation.
- Architecturally, this is separate from the package’s core library and looks like an optional presentation layer.
11. Packaging and distribution
- The repo is packaged as a Python distribution using pyproject.toml, setup.py, and MANIFEST.in.
- This indicates the same codebase serves both as an importable library and as a published package.
12. Build and release automation
- .github/workflows/publish.yml handles PyPI release publishing from GitHub Actions.
- The workflow is connected to release creation and validates the built package before upload.
- This is the main CI/CD boundary for distribution.
13. Key data/assets
- template.tabla is the reference composition template and likely the simplest input artifact for the parser.
- recordings/*.m4a are essential runtime assets for sound playback, and they are part of the repository rather than fetched dynamically.
14. Architecture summary
- The dominant flow is: .tabla composition spec → parser/domain model → either playback, notation export, generation, or transcription.
- The repo therefore has three clear layers:
1. Core library and musical model
2. Audio/sample handling
3. UI/distribution tooling via GitHub Pages and PyPI
Main entry points: main.py Musical model · web_backend.py Web backend · publish.yml Publish workflow · index.html Browser UI
Components 15
Core library
Parsing, domain model, and feature pipelines for tabla compositions.
- Template · Reference composition document and example input format.
template.tabla - Main module · Primary Python module containing parsing, model, and feature logic.
Tabalchi/main.py - Bol Parser · Converts .tabla documents into the internal musical representation.
Tabalchi/main.py - Musical model · Tabla concepts such as Bol, Beat, Phrase, Taal, Jati, Speed, and BeatRange.
Tabalchi/main.py - Notation export · Abstract notation layer with concrete formats like Bhatkande and Paluskar.
Tabalchi/main.py - Playback · Sample-based playback path from parsed bols to sounds and phrases.
Tabalchi/main.py - Generator · Creates compositions from rhythmic parameters, optionally via hosted or local models.
Tabalchi/main.py - Transcription · Converts audio recordings into bol sequences.
Tabalchi/main.py
Audio assets
Recorded samples used by sample-based playback and related tooling.
- Samples · Recorded tabla samples used by playback and audio matching.
recordings
Web UI
Minimal browser entrypoint and backend bridge.
- Web backend · Thin Python shim for wiring browser interactions to library capabilities.
Tabalchi/web_backend.py - Browser UI · Standalone HTML entrypoint for the minimal web interface.
index.html
Packaging
Python distribution metadata and build inputs.
- Build config · Modern Python packaging configuration and dependencies.
pyproject.toml - Setup script · Legacy packaging entrypoint for building and distributing the library.
setup.py
CI/CD
GitHub Actions workflows for site and package publishing.
- Pages deploy · Deploys the browser UI to GitHub Pages.
.github/workflows/pages.yml - Publish workflow · Builds and publishes the Python package to PyPI.
.github/workflows/publish.yml
Connections 18
- Template → Bol Parser: input spec · Template composition documents are parsed by the core parser.
- Main module → Bol Parser: contains · The main module houses the parser entrypoint.
- Bol Parser → Musical model: builds · Parsing produces the internal tabla domain model.
- Musical model → Notation export: renders to · The shared model feeds notation rendering.
- Musical model → Playback: drives · The same model is used to sequence sample playback.
- Musical model → Generator: parameters for · Composition generation uses rhythmic and stylistic metadata.
- Musical model → Transcription: targets · Transcription outputs bols in the same domain language.
- Playback → Samples: uses samples · Playback resolves bols to recorded tabla sounds.
- Web backend → Main module: bridges · Backend shim exposes library features to the UI.
- Browser UI → Web backend: calls · Browser UI interacts with the Python backend bridge.
- Pages deploy → Browser UI: deploys · GitHub Pages publishes the standalone HTML UI.
- Build config → Main module: packages · Packaging configuration includes the Python library module.
- Setup script → Main module: packages · Legacy setup script builds the library distribution.
- Publish workflow → Build config: builds from · Release automation uses the package configuration.
- Publish workflow → Setup script: builds from · Release automation also supports the legacy setup path.
- Playback → Web backend: exposed via · Playback capabilities can be wired through the backend shim.
- Generator → Web backend: exposed via · Generation features can also surface through the backend shim.
- Transcription → Web backend: exposed via · Transcription workflows may be routed through the browser bridge.