Scanbass

ScanBass is a web-based tool that extracts basslines from audio files and exports them as MIDI files. It uses advanced AI-powered pitch detection to identify and isolate bass frequencies, making it easy to transcribe bass parts from your favorite songs.

✨ Features

• 🎵 Audio Upload: Support for WAV, MP3, OGG, and FLAC formats
• 🤖 AI-Powered Extraction: Uses Spotify's Basic Pitch for accurate pitch detection
• 🎹 MIDI Export: Generates standard MIDI files compatible with any DAW
• 🎨 Modern UI: Clean, responsive interface with dark/light mode toggle
• 🔊 In-Browser Playback: Preview MIDI files directly in the browser using Tone.js
• ⚡ Fast Processing: Efficient audio analysis and conversion
• 🔒 Secure: File validation and automatic cleanup
• 📊 Statistics: View extraction details (notes detected, duration, etc.)
• 📱 Responsive Design: Works perfectly on desktop and mobile devices

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• pip (Python package manager)
• Virtual environment (recommended)

Installation

1. Clone the repository:

   git clone https://github.com/RasikhAli/ScanBass.git
   cd ScanBass
   

2. Create and activate virtual environment:

   Windows:

   python -m venv venv
   venv\Scripts\activate
   

   macOS/Linux:

   python3 -m venv venv
   source venv/bin/activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Run the application:

   python app.py
   

   Or using uvicorn directly:

   uvicorn app:app --reload --host 0.0.0.0 --port 8000
   

5. Open your browser:

   http://localhost:8000
   

📖 Usage

1. Upload Audio File:

   • Click the upload area or drag and drop an audio file
   • Supported formats: WAV, MP3, OGG, FLAC
   • Maximum file size: 50MB

2. Extract Bassline:

   • Click "Extract Bassline" button
   • Wait for processing (typically 30-120 seconds depending on file size)
   • View extraction statistics

3. Preview MIDI (NEW!):

   • Click the Play button in the "Preview MIDI" section
   • Listen to the extracted bassline directly in your browser
   • Click Stop to stop playback

4. Download MIDI:

   • Click "Download MIDI File" to save the bassline
   • Import into your favorite DAW (Ableton, FL Studio, Logic Pro, etc.)

5. Toggle Theme:

   • Click the sun/moon icon in the top-right corner
   • Switch between light and dark modes

🏗️ Project Structure

scanbass/
├── app.py                  # Main FastAPI application
├── requirements.txt        # Python dependencies
├── README.md              # Project documentation
├── IMPROVEMENTS_SUMMARY.md # Feature improvements summary
├── MIDI_PLAYBACK_GUIDE.md # MIDI playback guide
├── QUICK_START.md         # Quick start guide
├── templates/
│   └── index.html         # Frontend HTML template (with dark mode & MIDI player)
├── static/
│   ├── styles.css         # Enhanced CSS styles with dark mode
│   └── script.js          # Frontend JavaScript (theme toggle & MIDI playback)
├── docs/                  # Additional documentation
│   ├── DEPLOYMENT.md      # Deployment guide
│   ├── SETUP.md           # Detailed setup guide
│   ├── TESTING.md         # Testing procedures
│   ├── PROJECT_SUMMARY.md # Technical overview
│   ├── GETTING_STARTED.md # Beginner guide
│   ├── CHECKLIST.md       # Verification checklist
│   └── DOCUMENTATION_INDEX.md # Documentation guide
├── uploads/               # Temporary audio file storage (auto-created)
├── outputs/               # Generated MIDI files (auto-created)
├── Procfile               # Heroku deployment config
├── render.yaml            # Render.com deployment config
└── runtime.txt            # Python version specification

🛠️ Technology Stack

Backend

• FastAPI: Modern, fast web framework for building APIs
• Librosa: Audio analysis and processing
• Basic Pitch: Spotify's audio-to-MIDI conversion model
• Mido: MIDI file creation and manipulation
• Uvicorn: ASGI server for running FastAPI

Frontend

• HTML5: Semantic markup
• Tailwind CSS: Utility-first CSS framework
• Vanilla JavaScript: No framework dependencies
• Tone.js: Web Audio API for MIDI playback
• @tonejs/midi: MIDI file parsing for browser playback

AI/ML

• TensorFlow: Machine learning framework (used by Basic Pitch)
• NumPy: Numerical computing
• SciPy: Scientific computing

🎯 How It Works

1. Audio Loading: The uploaded audio file is loaded using Librosa at 22.05kHz sample rate
2. Pitch Detection: Basic Pitch analyzes the audio and detects all pitches with optimized parameters
3. Bass Filtering: Notes are filtered to bass range (MIDI notes 28-59, approximately E1 to B3)
4. MIDI Generation: Filtered notes are converted to MIDI format with accurate timing and velocity
5. File Export: MIDI file is saved and made available for download
6. Browser Playback: Tone.js synthesizes the MIDI for immediate preview

📊 API Endpoints

GET /

Returns the main HTML interface with enhanced UI

POST /extract-bassline

Extracts bassline from uploaded audio file

Request:

• Method: POST
• Content-Type: multipart/form-data
• Body: Audio file

Response:

{
  "success": true,
  "midi_filename": "song_bassline.mid",
  "statistics": {
    "total_notes": 450,
    "bass_notes": 120,
    "duration": 180.5,
    "sample_rate": 22050
  },
  "message": "Successfully extracted 120 bass notes from 450 total notes"
}

GET /download/{filename}

Downloads the generated MIDI file

GET /health

Health check endpoint for monitoring

Response:

{
  "status": "healthy",
  "service": "ScanBass",
  "version": "1.0.0"
}

🚢 Deployment

Deploy to Render.com

See docs/DEPLOYMENT.md for detailed deployment instructions.

Quick Deploy:

1. Push code to GitHub
2. Connect repository to Render.com
3. Configure build and start commands:
   • Build: pip install -r requirements.txt
   • Start: uvicorn app:app --host 0.0.0.0 --port $PORT
4. Deploy!

Deploy to Other Platforms

• Heroku: Use Procfile with web: uvicorn app:app --host 0.0.0.0 --port $PORT
• Railway: Auto-detects Python and FastAPI
• Google Cloud Run: Use Dockerfile with uvicorn
• AWS Elastic Beanstalk: Configure Python 3.11 environment
• HuggingFace Spaces: Upload as Gradio or Streamlit app

⚙️ Configuration

Environment Variables

• PORT: Server port (default: 8000)
• MAX_FILE_SIZE: Maximum upload size in bytes (default: 52428800 = 50MB)
• PYTHON_VERSION: Python version for deployment (default: 3.11)

Customization

Adjust bass frequency range (in app.py):

# Current range: MIDI notes 28-59 (E1 to B3)
if 28 <= pitch <= 59:
    bass_notes.append(...)

# For lower bass: 20-50
# For higher bass: 35-65

Change detection sensitivity (in app.py):

model_output, midi_data, note_events = predict(
    audio_path,
    onset_threshold=0.3,    # Lower = more sensitive (0.3-0.7)
    frame_threshold=0.2,    # Lower = more notes detected
    minimum_note_length=50.0, # Shorter for faster bass lines
    ...
)

🐛 Troubleshooting

Issue: "No bass notes detected"

• Solution: Try audio with clearer bass, adjust detection thresholds, or check if bass is in the expected frequency range

Issue: "File too large"

• Solution: Compress audio file or increase MAX_FILE_SIZE in app.py

Issue: "Processing takes too long"

• Solution: Use shorter audio clips, reduce sample rate, or deploy to a server with more CPU

Issue: Import errors

• Solution: Ensure all dependencies are installed: pip install -r requirements.txt

Issue: MIDI playback not working

• Solution: Check browser console for errors, ensure browser allows audio playback, try clicking the page first

🎵 MIDI Playback Guide

The application now includes built-in MIDI playback! After extracting a bassline:

1. Look for the "Preview MIDI" section in the results
2. Click the green Play button to hear your bassline
3. Click the red Stop button to stop playback

For more playback options, see MIDI_PLAYBACK_GUIDE.md.

🌓 Dark/Light Mode

Toggle between themes using the sun/moon icon in the top-right corner. Your preference is automatically saved.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Spotify Basic Pitch - Audio-to-MIDI conversion
• Librosa - Audio analysis library
• FastAPI - Web framework
• Tailwind CSS - CSS framework
• Tone.js - Web Audio synthesis

📧 Contact

For questions, issues, or suggestions, please open an issue on GitHub.

🔮 Future Enhancements

• [ ] Support for multiple instrument extraction
• [ ] Batch processing of multiple files
• [ ] Advanced MIDI editing before download
• [ ] Support for more audio formats
• [ ] Tempo detection and BPM adjustment
• [ ] Cloud storage integration
• [ ] User accounts and history
• [ ] Real-time audio recording and processing

📚 Documentation

• QUICK_START.md - Quick start guide
• IMPROVEMENTS_SUMMARY.md - All new features
• MIDI_PLAYBACK_GUIDE.md - MIDI playback options
• docs/GETTING_STARTED.md - Beginner guide
• docs/DEPLOYMENT.md - Deployment instructions
• docs/TESTING.md - Testing procedures

---

Made with ❤️ for musicians and producers

Version: 1.0.0
Status: Production Ready ✅