Fret.

A full-stack AI-powered web application for finding and visualizing guitar chord progressions. Features intelligent song search using Google's Gemini AI, custom SVG chord diagrams, music theory analysis, and PDF export capabilities.

✨ Features

• 🤖 AI-Powered Search - Uses Gemini 2.0 Flash for intelligent chord extraction from web sources
• 🎨 Custom SVG Chord Diagrams - 200+ chord library with professional finger positioning
• 🎵 Music Theory Analysis - Automatic key detection and scale analysis
• 💬 Natural Language Interface - Chat-based query system for intuitive song searches
• 📄 PDF Export - Generate printable chord sheets with diagrams
• 🌙 Dark/Light Theme - Beautiful pastel-themed UI with theme switching
• 🔍 Report System - Report incorrect results for improved accuracy
• 📱 Responsive Design - Works seamlessly on desktop and mobile devices
• 🔄 Multiple Fallbacks - Ensures high success rate with layered approach

🏗️ Project Structure

Fret./
├── backend/                 # Flask API server
│   ├── app.py              # Main Flask application with API endpoints
│   ├── scraper.py          # Ultimate Guitar web scraping
│   ├── parser.py           # Chord analysis and music theory algorithms
│   ├── cli.py              # Command line interface
│   ├── requirements.txt    # Python dependencies
│   ├── GEMINI_SETUP.md     # Gemini AI setup guide
│   ├── README.md           # Backend documentation
│   └── logs/               # Application logs
├── frontend/               # Vue.js web application
│   ├── src/
│   │   ├── components/     # Vue components
│   │   │   ├── ChatInterface.vue    # Main chat interface
│   │   │   ├── ChordDiagram.vue     # Individual chord diagram
│   │   │   ├── ChordDiagramGrid.vue # Chord grid layout
│   │   │   ├── PdfExport.vue       # PDF export functionality
│   │   │   ├── ThemeToggle.vue     # Theme switcher
│   │   │   └── ResultsDisplay.vue  # Results presentation
│   │   ├── assets/         # Styles and assets
│   │   ├── App.vue         # Root component
│   │   └── main.js         # Application entry point
│   ├── package.json        # Node.js dependencies
│   └── README.md           # Frontend documentation
├── .gitignore              # Git ignore rules
└── README.md               # This file

🚀 Quick Start

Prerequisites

• Python 3.8+
• Node.js 14+ and npm
• Google Gemini API key (optional but recommended)
  • Get one from Google AI Studio

1. Clone the Repository

git clone <repository-url>
cd Fret.

2. Setup Backend

cd backend

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
# .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set Gemini API key (optional but recommended)
export GEMINI_API_KEY="your_api_key_here"
# Or create a .env file in the project root:
# echo "GEMINI_API_KEY=your_api_key_here" > ../.env

# Start the server
python app.py

The backend will run on http://localhost:5000

3. Setup Frontend

Open a new terminal:

cd frontend

# Install dependencies
npm install

# Start development server
npm run serve

The frontend will run on http://localhost:8080

4. Access the Application

Open your browser and navigate to http://localhost:8080

🎵 How It Works

1. User Query - Enter a natural language query like "Wonderwall by Oasis" in the chat interface
2. AI Processing - Backend uses Gemini AI to search the web and extract chord data
3. Music Theory Analysis - System analyzes chord progression to detect key and scale
4. Visualization - Custom SVG engine renders professional chord diagrams
5. Display - Results show song info, chord progression, music theory analysis, and interactive diagrams
6. Export - Users can export chord sheets as PDF for offline use

🎯 API Endpoints

Main Endpoints

• POST /chat - Main chat interface for song queries

  Request: { "message": "Wonderwall by Oasis" }
  Response: { "title": "...", "artist": "...", "chords": "...", "music_theory": {...} }

• POST /report - Report incorrect song and retry search

  Request: { "original_query": "...", "returned_title": "...", "returned_artist": "..." }

• POST /export-pdf - Generate PDF from chord data

  Request: { "title": "...", "artist": "...", "chords": [...] }
  Response: PDF file binary

Utility Endpoints

• GET /healthz - Health check endpoint
• GET /chords?query=song_name - Legacy chord search endpoint
• GET /test-gemini?query=song_name - Test Gemini AI functionality

🎨 Key Features Explained

AI-Powered Chord Extraction

The system uses Google's Gemini 2.0 Flash model to intelligently search the web and extract chord progressions. It can handle various query formats and automatically finds the correct song from multiple sources.

Custom Chord Diagrams

• 200+ Chord Library - Comprehensive collection of common chords
• Professional Rendering - SVG-based diagrams with accurate finger positioning
• Interactive Modal - View all chord diagrams in a popup modal
• Finger Numbers - Shows proper finger placement (1-4) instead of fret numbers
• Barre Chord Detection - Automatically detects and renders barre chords correctly

Music Theory Analysis

• Key Detection - Analyzes chord progression to determine musical key
• Scale Identification - Identifies major or minor scale
• Confidence Levels - Provides high/medium/low confidence ratings
• Scale Notes Display - Shows all notes in the detected key's scale

User Interface

• Chat-Based Interface - Natural conversation flow for queries
• Split-Panel Layout - Chat on left, results on right
• Dark/Light Themes - Beautiful pastel color palette
• Responsive Design - Works on all screen sizes
• Real-Time Feedback - Loading indicators and error messages

📚 Documentation

• Backend Documentation - Detailed backend API and setup
• Frontend Documentation - Frontend component details
• Gemini AI Setup Guide - Step-by-step AI integration

🔧 Development

Backend Development

cd backend
source .venv/bin/activate  # Activate virtual environment
python app.py               # Run Flask server

Frontend Development

cd frontend
npm run serve               # Start development server with hot reload

Building for Production

cd frontend
npm run build              # Build optimized production bundle

The built files will be in frontend/dist/

🛠️ Technology Stack

Backend

• Flask - Lightweight web framework
• Google Gemini AI - AI model for intelligent search
• BeautifulSoup4 - HTML parsing
• Playwright - Browser automation
• Flask-CORS - Cross-origin resource sharing

Frontend

• Vue.js 3 - Progressive JavaScript framework
• Tailwind CSS - Utility-first CSS framework
• Axios - HTTP client
• jsPDF - PDF generation

🔒 Security

• API keys are stored as environment variables (never hardcoded)
• .gitignore configured to exclude sensitive files
• CORS properly configured for development
• No credentials committed to repository

🐛 Troubleshooting

Backend Issues

"GEMINI_API_KEY not found"

• Set the environment variable: export GEMINI_API_KEY="your_key"
• Or create a .env file in the project root
• See Gemini Setup Guide for details

"No chord results found"

• Try different song names or include artist name
• Check if Gemini API key is set correctly
• Verify backend server is running on port 5000

Frontend Issues

"Failed to contact backend"

• Ensure backend server is running on http://localhost:5000
• Check browser console for CORS errors
• Verify API endpoint URLs in code

Chord diagrams not showing

• Check browser console for errors
• Verify chord names are in the supported format
• Try refreshing the page

📄 License

This project is for educational purposes. Please respect Ultimate Guitar's terms of service when using web scraping features.

🤝 Contributing

This is a personal project, but suggestions and feedback are welcome!

📝 Notes

• The application works without a Gemini API key but with limited functionality
• Chord diagrams support standard 6-string guitar tuning only
• Music theory analysis currently supports major and natural minor scales
• PDF export includes all chord diagrams and song metadata

---

Happy chord hunting! 🎸✨