Guitariz

KO | EN

gitlite — search

#python #java #python3 #arduino #golang #machine-learning #rust #html #flask #javascript #seismology #nodejs

★ 25 Open GitHub ↗

Full-stack music learning web app featuring interactive guitar/piano tools and AI-assisted audio analysis (chord detection + vocal/instrumental separation)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

<h1>🎸 Guitariz Studio</h1>
 The Open-Source Digital Workbench for Modern Musicians
 AI-powered chord detection · Stem isolation · Interactive theory tools · All in one place.

<a href="https://guitariz.studio">🌐 Live Demo</a> · 
 <a href="https://github.com/Guitariz/Guitariz/issues/new?template=bug_report.md">🐛 Report Bug</a> · 
 <a href="https://github.com/Guitariz/Guitariz/issues/new?template=feature_request.md">✨ Request Feature</a>
 
</div>

---

## 📖 About

**Guitariz Studio** is a full-stack, professional-grade music platform that bridges the gap between traditional music theory and modern AI. It was founded and created by **Abhinav Vaidya** to bring together AI-powered source separation, real-time chord recognition, interactive instrument simulations, and gamified ear training—all within a single, beautifully crafted web application.

Whether you're a songwriter dissecting harmonies, a student mastering intervals, a producer isolating stems, or a developer pushing the boundaries of music tech—Guitariz is built for you.

> **🎯 Try it now →** [guitariz.studio](https://guitariz.studio)

> [!IMPORTANT]
> **Official Channels & Social Media:** Please note that Guitariz Studio does not have any official Instagram page or account. Any Instagram account using the name "Guitariz" is unaffiliated with this project. Official communication channels are limited to this GitHub repository, the website, and our official X (formerly Twitter) account: [@GuitarizStudio](https://x.com/GuitarizStudio).

---

## ✨ Features

### 🤖 Audio Intelligence

| Feature | Description |
|:--|:--|
| **Chord AI** | Upload any audio file for high-accuracy chord recognition, powered by **Librosa** (CQT chroma, HPSS, and tuning deviation cents estimation) and HMM backups. |
| **BPM Detector & Tap Tempo** | Detect beats per minute (BPM) from MP3/audio files or tap along manually in real-time (`/bpm-detector`). |
| **Audio Key Finder** | Extract musical key signatures and scale modes from any song with harmonic chromagram profiling (`/key-detector`). |
| **Vocal Remover** | One-click AI vocal & acapella extraction for karaoke backing tracks and remixing (`/vocal-remover`). |
| **Chord Generator** | Generate progressions by key and mood with audio playback and 1-click **MIDI Export** (`/chord-progression-generator`). |
| **MIDI Export** | Export detected or generated chord progressions directly into Standard MIDI files (`.mid`) for instant drag-and-drop import into Ableton, FL Studio, Logic, Cubase, or any DAW. |
| **Stem Separator** | Isolate vocals, drums, bass, and other instruments using Meta's state-of-the-art **Demucs** deep learning model (`/stem-separator`). |
| **Precision Tuner** | Advanced chromatic tuner with cent-level accuracy for guitar, bass, ukulele, and vocals. |

### 🎮 Interactive Learning

| Feature | Description |
|:--|:--|
| **Ear Training Arcade** | Gamified modules for **interval recognition**, **chord identification**, and **perfect pitch** training with streak tracking. |
| **Raga Theory Explorer** | Learn the bridge between Western modes (Dorian, Aeolian, etc.) and Indian Classical Thaats/Ragas (Kafi, Asavari, Bhairav, Yaman) with interactive audio neck visualization. |
| **Scale Explorer** | Visualize 50+ Western and Eastern scales across the Circle of Fifths, with modal breakdowns and theory context. |
| **Virtual Fretboard** | Fully interactive 24-fret guitar neck featuring a drag-and-drop Capo (with dynamic pitch-shifting and dead-fret disabling), note highlighting, and 3D view. |
| **Virtual Piano** | 88-key piano with chord/scale overlays and keyboard shortcut support. |

### 🛠️ Platform & DX

| Feature | Description |
|:--|:--|
| **Progressive Web App** | Fully installable with offline-ready service workers and advanced auto-healing cache recovery. |
| **Markdown Blog Engine** | Built-in SEO-optimized blog system converting simple `.md` files into rich, JSON-LD structured articles. |
| **Premium Dark Mode** | Strict, distraction-free glassmorphism aesthetic with Framer Motion micro-animations. |
| **Advanced SEO & Analytics** | Automated dynamic sitemaps, `llms.txt` for AI crawlers, PostHog, and Ahrefs Web Analytics integration. |
| **CI/CD Pipeline** | Automated linting, testing, prerendering, and build validation via GitHub Actions. |

---

## ⚡ Architecture

Guitariz uses a **hybrid architecture** to balance interactive client-side performance with heavy server-side AI computation.

```mermaid
graph TD
 subgraph Client ["🖥️ Client — React / Vite"]
 UI["Glassmorphism UI (Tailwind + Framer Motion)"]
 State["TanStack Query + Context API"]
 AudioEngine["Web Audio API Engine"]
 Proxy["Vite CORS Proxy Middleware"]

UI --> State --> AudioEngine
        AudioEngine --> Proxy
    end

subgraph Server ["🧠 AI Service — Python / FastAPI"]
 API["FastAPI + WebSocket Server"]
 Demucs["Meta Demucs (Source Separation)"]
 Librosa["Librosa (Chord & Key Analysis)"]

API --> Demucs
        API --> Librosa
    end

UI <-->|"REST / WebSocket (JSON + Audio Blobs)"| API
 Proxy <-->|"Fetch"| External["External APIs"]

style Client fill:#0d1117,stroke:#30363d,color:#c9d1d9
    style Server fill:#0d1117,stroke:#30363d,color:#c9d1d9
```

---

## 📂 Project Structure

```
guitariz/
├── src/
│   ├── content/blog/        # Markdown blog articles
│   ├── components/          # Reusable UI components (Fretboard, Piano, Tuner, etc.)
│   │   ├── ui/              # shadcn/ui primitives (Button, Dialog, Toast, etc.)
│   │   ├── chord-ai/        # Chord AI feature components
│   │   ├── ear-training/    # Ear Training game components
│   │   ├── fretboard/       # Fretboard + 3D view components
│   │   └── piano/           # Virtual Piano components
│   ├── hooks/               # Custom React hooks (audio, WebSocket, PWA, etc.)
│   ├── lib/                 # Core logic — harmonic analysis, audio processing
│   ├── pages/               # Route-level page components
│   └── main.tsx             # Application entrypoint
├── backend/
│   ├── main.py              # FastAPI server + REST endpoints
│   ├── analysis.py          # Audio feature extraction pipeline
│   ├── chord_fast.py        # Fast chord recognition engine
│   ├── websocket_chords.py  # Real-time WebSocket chord streaming
│   ├── youtube.py           # YouTube audio download utilities
│   ├── Dockerfile           # Container build for AI service
│   └── requirements.txt     # Python dependencies
├── .github/
│   ├── workflows/ci.yml     # GitHub Actions CI pipeline
│   └── ISSUE_TEMPLATE/      # Bug report & feature request templates
├── public/                  # Static assets, PWA manifest, sitemap
├── vite.config.ts           # Vite config with custom CORS proxy
├── tailwind.config.ts       # Tailwind CSS theme configuration
└── package.json             # Project metadata & scripts
```

---

## 🛠️ Tech Stack

<table>
 <tr>
 <th>Layer</th>
 <th>Technology</th>
 </tr>
 <tr>
 <td>Frontend</td>
 <td>React 18 · TypeScript 5.8 · Vite 5 · React Router 6</td>
 </tr>
 <tr>
 <td>UI</td>
 <td>Tailwind CSS · shadcn/ui · Radix Primitives · Framer Motion · Lucide Icons</td>
 </tr>
 <tr>
 <td>3D</td>
 <td>Three.js · React Three Fiber · Drei</td>
 </tr>
 <tr>
 <td>State</td>
 <td>TanStack Query (React Query) · React Context</td>
 </tr>
 <tr>
 <td>Audio</td>
 <td>Web Audio API · FFT.js (Client) · Librosa (Server)</td>
 </tr>
 <tr>
 <td>AI / ML</td>
 <td>Python · PyTorch · Meta Demucs · FastAPI · Librosa</td>
 </tr>
 <tr>
 <td>Music Theory</td>
 <td>Tonal.js — harmonic matrix, intervals, scales, chords</td>
 </tr>
 <tr>
 <td>Testing</td>
 <td>Vitest · React Testing Library · Ruff (Python linting)</td>
 </tr>
 <tr>
 <td>Infra & Analytics</td>
 <td>Vercel (Frontend) · Cloudflare (CDN Caching & Protection) · Docker (Backend) · GitHub Actions CI · PostHog · Ahrefs</td>
 </tr>
</table>

---

## 🚀 Getting Started

### Prerequisites

| Tool | Version |
|:--|:--|
| Node.js | `>= 18.0` |
| npm | `>= 9.0` |
| Python *(optional — for AI features)* | `>= 3.10` |

### 1. Clone & Install

```bash
git clone https://github.com/Guitariz/Guitariz.git
cd guitariz
npm install
```

### 2. Configure Environment

```bash
cp .env.example .env.local
```

Edit `.env.local` with your backend URL if running AI features locally.

### 3. Run the Dev Server

```bash
npm run dev
```

The app will be available at **`http://localhost:5173`**.

### 4. Backend Setup *(Optional)*

Required only for **Chord AI**, **Stem Separator**, and **Vocal Splitter** features.

```bash
cd backend

# Create and activate a virtual environment
python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Start the FastAPI server
python main.py
```

> **Note:** First launch will download the Demucs model (~300 MB). Subsequent starts are instant.

### Available Scripts

---

## 🤝 Contributing

Contributions are what make the open-source community such an incredible place to learn, inspire, and create. **Any contributions you make are greatly appreciated.**

Please read the [**Contributing Guide**](CONTRIBUTING.md) and our [**Code of Conduct**](CODE_OF_CONDUCT.md) before getting started.

```
1. Fork the repository
2. Create your feature branch    →  git checkout -b feature/amazing-feature
3. Commit your changes           →  git commit -m 'feat: add amazing feature'
4. Push to the branch            →  git push origin feature/amazing-feature
5. Open a Pull Request
```

Looking for a place to start? Check out issues tagged [`good first issue`](https://github.com/Guitariz/Guitariz/labels/good%20first%20issue) or [`help wanted`](https://github.com/Guitariz/Guitariz/labels/help%20wanted).

---

## 🗺️ Roadmap

- [x] MIDI export from Chord AI & Chord Generator (DAW drag-and-drop support)
- [x] Dedicated SEO Micro-Tools (`/bpm-detector`, `/key-detector`, `/vocal-remover`, `/chord-progression-generator`)
- [ ] Metadata-only YouTube search with local audio upload-matching workflow (copyright-safe)
- [ ] Collaborative jam rooms via WebRTC
- [ ] Mobile-native app (React Native / Capacitor)
- [ ] Additional instrument support (Ukulele, Bass tablature)
- [ ] User accounts with progress tracking

> See the [open issues](https://github.com/Guitariz/Guitariz/issues) for a full list of proposed features and known issues.

---

## 🎖️ Acknowledgements

Guitariz Studio stands on the shoulders of giants in the Music Information Retrieval (MIR) community. Special thanks to the authors of these pivotal libraries:

- **[Meta Demucs](https://github.com/facebookresearch/demucs)** — State-of-the-art deep learning source separation powering our Stem Separator.
- **[Librosa](https://librosa.org/)** — The backbone of server-side audio analysis and feature extraction.
- **[Tonal.js](https://github.com/tonaljs/tonal)** — Comprehensive music theory library for client-side harmonic analysis.
- **[shadcn/ui](https://ui.shadcn.com/)** — Beautiful, accessible component primitives built on Radix UI.

---

## 📜 License

Distributed under the **MIT License**. See [`LICENSE`](LICENSE) for more information.

---

**Guitariz Studio — Harmonizing Technology & Music.**

<a href="https://guitariz.studio">Website</a> · 
 <a href="https://github.com/Guitariz/Guitariz">GitHub</a> · 
 <a href="https://x.com/GuitarizStudio">Twitter</a> · 
 <a href="mailto:support@guitariz.studio">Contact</a>

</div>

Guitariz

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README