Metadata-Version: 2.4
Name: ashank-pitch
Version: 0.1.0
Summary: A CLI tool for real-time pitch detection while singing
Home-page: https://www.ashankbehara.com
Author: Ashank
Author-email: Ashank <ashank.behara@gmail.com>
Project-URL: Homepage, https://www.ashankbehara.com
Project-URL: Bug Reports, https://github.com/ashank/pitch/issues
Project-URL: Source Code, https://github.com/ashank/pitch
Keywords: music,pitch,detection,singing,audio,real-time,CLI
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: Topic :: Multimedia :: Sound/Audio :: Analysis
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pyaudio>=0.2.11
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# Sing Detector 🎤

A real-time pitch detection CLI tool for singers. Analyze your voice and see what note you're singing in real-time!

## Features

- 🎵 Real-time pitch detection while you sing
- 🎯 Shows musical note names (C, D, E, etc.) with octave
- 📊 Displays frequency in Hz
- 🎶 Shows how close you are to perfect pitch (in cents)
- ⚡ Two detection algorithms: Autocorrelation and FFT
- 🖥️ Simple command-line interface

## Installation

### From Source

1. Clone or download this repository
2. Install the package:

```bash
pip install -e .
```

### System Requirements

- Python 3.7 or higher
- A working microphone
- Audio drivers compatible with PyAudio

### Dependencies

The package will automatically install:
- `numpy` - For numerical computations
- `scipy` - For signal processing
- `pyaudio` - For audio input capture

## Usage

### Basic Usage

Simply run:

```bash
sing
```

This will start the real-time pitch detector using your default microphone.

### Advanced Options

```bash
# Use FFT method instead of autocorrelation
sing --method fft

# Change sample rate (default: 44100 Hz)
sing --rate 22050

# Change update rate (default: 20 Hz)
sing --update-rate 30

# Change audio frame size (default: 4096 samples)
sing --frame-size 2048

# Show help
sing --help
```

### Example Output

```
🎤 Sing Detector - Real-time Pitch Detection
==================================================
Start singing! Press Ctrl+C to stop.

🎵 A4 (440.0 Hz) - in tune
🎵 C5 (523.3 Hz) - +12 cents
🔇 No clear pitch detected...
```

## How It Works

The tool captures audio from your microphone in real-time and analyzes it using digital signal processing techniques:

1. **Audio Capture**: Uses PyAudio to capture audio from your default microphone
2. **Windowing**: Applies a Hanning window to reduce spectral leakage  
3. **Pitch Detection**: Uses either:
   - **Autocorrelation**: Finds repeating patterns in the audio signal
   - **FFT**: Analyzes frequency spectrum to find the fundamental frequency
4. **Note Conversion**: Converts frequency to musical note names using equal temperament tuning
5. **Cents Calculation**: Shows how close you are to perfect pitch (±50 cents = ±half semitone)

## Troubleshooting

### "No audio devices found" Error

This usually means PyAudio can't access your microphone. Try:

1. **macOS**: Grant microphone permissions to your terminal application
2. **Linux**: Install ALSA development headers: `sudo apt-get install libasound2-dev`
3. **Windows**: Make sure your microphone is set as the default recording device

### PyAudio Installation Issues

If PyAudio fails to install:

**macOS**:
```bash
brew install portaudio
pip install pyaudio
```

**Linux (Ubuntu/Debian)**:
```bash
sudo apt-get install portaudio19-dev python3-pyaudio
pip install pyaudio
```

**Windows**:
```bash
pip install pipwin
pipwin install pyaudio
```

### Poor Pitch Detection

If the tool isn't detecting your voice well:

1. Try singing louder and clearer
2. Reduce background noise
3. Try the alternative detection method: `sing --method fft`
4. Experiment with different frame sizes: `sing --frame-size 2048`

## Development

### Running from Source

```bash
python -m sing_detector.main
```

### Testing

You can test the package installation:

```bash
# Install in development mode
pip install -e .

# Test the command
sing --help
```

## Contributing

Feel free to open issues or submit pull requests!

## License

MIT License - feel free to use and modify as needed.

---

**Happy singing! 🎵** 
