🎵 MaqamDetector

Pendeteksi Maqam Musik Arab & Timur Tengah — Identifikasi maqam secara otomatis dari audio YouTube, file upload, atau rekaman suara. Dibangun untuk komunitas banjari Indonesia.

---

Overview

MaqamDetector membantu musisi, arranger, dan penggemar musik banjari untuk mengidentifikasi maqam (tangga nada modal) dari lagu-lagu Arab dan Timur Tengah. Output berupa nama maqam, confidence score, kandidat alternatif, dan penjelasan lengkap dalam Bahasa Indonesia.

Maqam yang Didukung (v1)

ID	Nama Latin	Nama Arab
hijaz	Hijaz	حجاز
rast	Rast	راست
bayati	Bayati	بياتي
nahawand	Nahawand	نهاوند
kurd	Kurd	كرد
saba	Saba	صبا
ajam	Ajam	عجم
jiharkah	Jiharkah	جهاركاه

---

Architecture

maqam-detector/
├── apps/
│   ├── platform/       ← React SPA (TanStack Router + Vite + Tailwind v4)
│   ├── api/            ← Go REST API (Echo + GORM + PostgreSQL)
│   └── analyzer/       ← Python FastAPI (CREPE + librosa + yt-dlp)
├── docs/               ← Dokumentasi produk (PRD, API Contract, dll)
├── docker-compose.yml  ← Orchestration semua service
├── nx.json             ← Nx build orchestrator
├── pnpm-workspace.yaml
└── .env

Data Flow

Audio Input (YouTube URL / File / Mikrofon)
    ↓
Golang API → validasi, session management
    ↓
Python Analyzer → yt-dlp + CREPE pitch extraction + maqam matching
    ↓
Claude API → penjelasan kontekstual Bahasa Indonesia
    ↓
Output: Nama Maqam + Confidence Score + Penjelasan

---

Tech Stack

Backend API (apps/api)

Kategori	Teknologi
Language	Go 1.25
Framework	Echo v4
ORM	GORM + PostgreSQL
Validation	go-playground/validator
API Docs	Swagger (auto-generated)
Hot Reload	Air
Logging	Logrus

Analyzer (apps/analyzer)

Kategori	Teknologi
Language	Python 3.11
Framework	FastAPI
Pitch Extraction	CREPE (tiny model)
Audio Processing	librosa
YouTube Download	yt-dlp

Frontend (apps/platform)

Kategori	Teknologi
Language	TypeScript 6.x
Framework	React 19
Build Tool	Vite 8
Routing	TanStack Router (file-based)
Data Fetching	TanStack Query
Styling	Tailwind CSS v4
Icons	Lucide React
API Codegen	Orval (Swagger → React Query hooks)
Linter	Biome

Monorepo Tooling

Kategori	Teknologi
Package Manager	pnpm (workspaces)
Build System	Nx
Containerization	Docker + Docker Compose

---

Prerequisites

• Node.js ≥ 20
• pnpm ≥ 9
• Go ≥ 1.25
• Python ≥ 3.11
• PostgreSQL ≥ 15
• Docker & Docker Compose (opsional, untuk deployment)
• ffmpeg (dibutuhkan oleh yt-dlp dan librosa)

---

Getting Started

1. Install Dependencies

pnpm install

2. Setup Environment

cp .env.example .env
# Edit .env → isi ANTHROPIC_API_KEY

3. Setup Database

createdb maqam_detector_db

Tabel akan otomatis di-migrate oleh GORM saat API pertama kali dijalankan.

4. Run Development

# Semua apps (API + Platform)
pnpm dev

# Masing-masing:
pnpm --filter api dev        # API (port 8080)
pnpm --filter platform dev   # Frontend (port 3000)

# Analyzer (Python):
cd apps/analyzer && uvicorn app.main:app --reload --port 8000

5. Docker (Production)

docker-compose up -d

---

API Endpoints

Method	Endpoint	Deskripsi
POST	/api/v1/analyze/youtube	Analisis dari YouTube URL
POST	/api/v1/analyze/upload	Analisis dari file audio
POST	/api/v1/analyze/record	Analisis dari rekaman browser
GET	/api/v1/analyses/:id	Status & hasil analisis (polling)
GET	/api/v1/history	Riwayat analisis
DELETE	/api/v1/history/:id	Hapus riwayat
GET	/api/v1/maqamat	Daftar maqam yang didukung
GET	/api/v1/maqamat/:id	Detail maqam

Swagger Documentation

http://localhost:8080/swagger/index.html

---

Available Scripts

Command	Deskripsi
pnpm dev	Jalankan semua apps (dev mode)
pnpm build	Build semua apps (production)
pnpm --filter platform generate:api	Generate API hooks dari Swagger

---

Documentation

Dokumentasi lengkap tersedia di docs/core/:

File	Deskripsi
PRD	Product Requirements Document
ERD	Entity Relationship Diagram
API Contract	Spesifikasi API endpoint
UI/UX Spec	Design tokens, komponen, screen specs
Implementation	Breakdown implementasi per fase

---

License

ISC — Anas (Cypress Consulting)