How miracatici/makambox works
Project Type and Purpose
• MakamBox is a standalone Java desktop application (not a web or full-stack service).
• It is an open-source interactive music tuition tool focused on Turkish Makam theory.
• Key functionality: real-time pitch detection, makam/tonic analysis, and visualization for user recordings vs. reference recordings.
High-Level Architectural Layers
A. Presentation Layer (UI)
• Package: src/graphics
• Components: About, HistogramChart, MakamChart, PitchChart, TonicChart, WaveChart, etc.
• Responsibilities: render charts, accept user input (file chooser, play/pause), display feedback in real time.
B. Application Orchestration Layer
• Package: src/applied
• Components: DataTool, HistogramExtractor, MakamBoxAnalysis, MultiAnalysis, SelectCulture, Tuner, Tuning.
• Responsibilities: coordinate user commands, select analysis routines, load cultural settings, invoke core logic.
C. Core Logic Layer
• Sub-layers:
1. Audio Processing (src/backEnd)
– Components: AudioInput (captures microphone or file), PitchDetection, Yin, PitchTracking, PitchShift, Wavefile, WaveWriter, Player, SineSynth, TemplateCreate, Histogram.
– Responsibilities: real-time audio I/O, pitch extraction, synthesis, template creation.
2. Analysis & Classification (src/analysis)
– Components: AnalysisForTonic, AnalysisForJoint, CompareForTonic, CompareForJoint, SingleMakamSoloRecordings, MBIDtoPath, TonicAnnotationMatch.
– Responsibilities: compute histograms, compare user vs. reference, classify makam/tonic.
D. Data Model Layer
• Package: src/datas
• Components: Makam, Note, Culture, Ahenk, TuningSystem, and factory classes.
• Responsibilities: hold domain objects (notes, intervals, cultural tuning data).
E. Utilities Layer
• Package: src/utilities
• Components: AudioUtilities, Plot, Write.
• Responsibilities: common helpers (file I/O, chart helpers, logging).
F. External Resources
G. External Dependencies (lib)
• TarsosDSP (Yin pitch detection), JFreeChart/JFreeSVG (charts), Commons-io/lang/math, javax.json, jl1.0.1 (MP3), etc.
Component Relationships & Data Flow
• User → UI: selects reference and live audio.
• UI → Application Orchestration: submits “analyze” commands.
• Orchestration → Audio Processing: starts AudioInput, PitchDetection, Yin.
• AudioProcessing → Data Model: produces streams of pitch/time data records.
• Orchestration → Analysis: passes pitch streams and reference templates.
• Analysis → Data Model: computes histograms, classification results.
• Analysis → Utilities: writes results to “results” folder.
• UI ← Analysis: fetches results to render in dynamic charts.
• Data Model ↔ Data Resources: loads tuning/makam definitions from makams/* and settings/*.ser.
Architectural Patterns & Principles
• Layered architecture (Presentation, Orchestration, Core Logic, Data).
• MVC-like separation: graphics = view, applied = controller, datas = model.
• Modular packages for testability (src/test).
• Pluggable data: external makam files and settings allow extensibility.
• Real-time stream processing pipeline for audio.
Essential Elements
• Notes on real-time stream vs. batch analysis paths.
• Grouping of “src” packages to reveal the MVC pattern.