USAGE_GUIDE.md

# Madverse Music: AI Audio Classifier - Usage Guide

## Quick Start

### Option 1: Hugging Face Space (Recommended)
Use our deployed model on Hugging Face Spaces:

**Web Interface:**
1. Go to the Hugging Face Space URL
2. Upload your audio file
3. Click "Analyze Audio"
4. Get instant results

**API Access:**
```bash
# Health check
curl https://your-space-name.hf.space/health

# Analyze audio file
curl -X POST "https://your-space-name.hf.space/analyze" \
     -F "[email protected]"
```

### Option 2: Local Setup
```bash
# Install dependencies
pip install -r requirements.txt

# Start the API server
python api.py

# Or start web interface
streamlit run app.py
```

## Supported Audio Formats
- WAV (.wav)
- MP3 (.mp3) 
- FLAC (.flac)
- M4A (.m4a)
- OGG (.ogg)

## API Usage

### Hugging Face Space API

#### Health Check
```bash
GET /health
```

#### Analyze Audio
```bash
POST /analyze
```
Upload audio file using multipart/form-data

**Request:**
Upload file using form data with field name "file"

**Response Format:**
```json
{
  "classification": "Real",
  "confidence": 0.85,
  "probability": 0.15,
  "raw_score": -1.73,
  "duration": 30.5,
  "message": "Detected as real music"
}
```



### Usage Examples

#### Python
```python
import requests

# Upload file to HF Space
with open('your_song.mp3', 'rb') as f:
    response = requests.post('https://your-space-name.hf.space/analyze', 
                           files={'file': f})
result = response.json()
print(result)
```

#### JavaScript
```javascript
const formData = new FormData();
formData.append('file', fileInput.files[0]);

const response = await fetch('https://your-space-name.hf.space/analyze', {
    method: 'POST',
    body: formData
});
const result = await response.json();
```

## Understanding Results

The classifier will output:
- **"Real"** = Human-created music
- **"Fake"** = AI-generated music (from Suno, Udio, etc.)

### API Response Format:
```json
{
  "classification": "Real",
  "confidence": 0.85,
  "probability": 0.15,
  "raw_score": -1.73,
  "duration": 30.5,
  "message": "Detected as real music"
}
```

### Command Line Output:
```
Analyzing: my_song.wav
Result: Fake (AI-generated music)
Confidence: 0.96 | Raw output: 3.786
```

## Model Specifications
- Model: SpecTTTra-α (120 seconds)
- Sample Rate: 16kHz
- Performance: 97% F1 score, 96% sensitivity, 99% specificity
- Max Duration: 120 seconds (2 minutes)

## Technical Details

### How It Works:
1. Audio is loaded and resampled to 16kHz
2. Converted to mel-spectrograms
3. Processed by the SpecTTTra transformer model
4. Output logit is converted to probability using sigmoid
5. Classification: `prob < 0.5` = Real, `prob ≥ 0.5` = Fake

### Testing Your Music

1. Get AI-generated samples: Download from Suno, Udio, or other AI music platforms
2. Get real music samples: Use traditional human-created songs
3. Run the classifier: Compare results to see how well it detects AI vs human music

## Expected Performance
- High accuracy on detecting modern AI-generated music
- Works best with full songs (up to 120 seconds)
- Optimized for music from platforms like Suno and Udio

Note: This model was trained specifically for detecting AI-generated songs, not just AI vocals over real instrumentals. It analyzes the entire musical composition.