USAGE_GUIDE.md

# Music Classification Dataset - Usage Guide

<!--
/**
* Project: Music Classification Dataset
* Author: Molla Samser
* Company: RSK World
* Designer & Tester: Rima Khatun
* Website: https://rskworld.in
* Email: help@rskworld.in, support@rskworld.in
* Phone: +91 93305 39277
*/
-->

## 🚀 Quick Start Guide

This guide will help you get started with the Music Classification Dataset.

### Prerequisites

Before you begin, ensure you have:
- Python 3.8 or higher installed
- pip package manager
- At least 2GB of free disk space
- Basic knowledge of Python and machine learning

---

## 📦 Installation

### Step 1: Clone or Download the Repository

```bash
# If using git
git clone <repository-url>
cd music-classification

# Or download and extract the ZIP file
```

### Step 2: Create a Virtual Environment (Recommended)

```bash
# Windows
python -m venv venv
venv\Scripts\activate

# Linux/Mac
python3 -m venv venv
source venv/bin/activate
```

### Step 3: Install Dependencies

```bash
pip install -r requirements.txt
```

---

## 📊 Working with the Dataset

### Loading the Dataset

```python
"""
Author: Molla Samser (RSK World)
Website: https://rskworld.in
"""

import pandas as pd

# Load training data
train_df = pd.read_csv('data/train_data.csv')
print(f"Training samples: {len(train_df)}")

# Load test data
test_df = pd.read_csv('data/test_data.csv')
print(f"Test samples: {len(test_df)}")

# View genre distribution
print("\nGenre distribution:")
print(train_df['genre'].value_counts())
```

### Processing Audio Files

```python
"""
Audio Processing Example
Author: Molla Samser
Company: RSK World
Email: help@rskworld.in
"""

from utils.audio_processor import AudioProcessor

# Initialize processor
processor = AudioProcessor(sample_rate=22050, duration=30.0)

# Load an audio file
audio_path = 'data/audio/jazz/jazz_001.wav'
audio = processor.load_audio(audio_path)

# Normalize audio
audio_normalized = processor.normalize_audio(audio)

print(f"Audio shape: {audio.shape}")
print(f"Duration: {len(audio) / 22050} seconds")
```

### Extracting Features

```python
"""
Feature Extraction Example
Author: Molla Samser (RSK World)
Website: https://rskworld.in
Phone: +91 93305 39277
"""

from utils.feature_extractor import FeatureExtractor

# Initialize extractor
extractor = FeatureExtractor(sample_rate=22050)

# Extract all features
features = extractor.extract_all_features(audio)

print("Extracted features:")
print(f"- MFCC: {features['mfcc'].shape}")
print(f"- Spectral Centroid: {features['spectral_centroid']:.2f}")
print(f"- Tempo: {features['tempo']:.2f} BPM")
print(f"- Zero Crossing Rate: {features['zero_crossing_rate']:.6f}")
```

---

## 🤖 Training Models

### Using the Training Script

```bash
# Train a Random Forest model
python models/train_model.py --model random_forest

# Train an SVM model
python models/train_model.py --model svm

# Train a KNN model
python models/train_model.py --model knn
```

### Custom Training Example

```python
"""
Custom Model Training
Author: Molla Samser
Company: RSK World
Designer & Tester: Rima Khatun
Website: https://rskworld.in
"""

from models.train_model import MusicClassifier

# Initialize classifier
classifier = MusicClassifier(model_type='random_forest')

# Extract features
X_train, y_train = classifier.extract_features_from_csv('data/train_data.csv')
X_test, y_test = classifier.extract_features_from_csv('data/test_data.csv')

# Train model
classifier.train(X_train, y_train)

# Evaluate
classifier.evaluate(X_test, y_test)

# Save model
classifier.save_model('models/saved_models')
```

---

## 🔮 Making Predictions

### Using the Prediction Script

```bash
# Predict genre for an audio file
python models/predict.py --audio path/to/your/music.wav --model random_forest
```

### Custom Prediction Example

```python
"""
Music Genre Prediction
Author: Molla Samser (RSK World)
Email: help@rskworld.in
Phone: +91 93305 39277
"""

from models.predict import MusicPredictor

# Initialize predictor
predictor = MusicPredictor(
model_dir='models/saved_models',
model_type='random_forest'
)

# Make prediction
result = predictor.predict('path/to/music.wav')

print(f"Predicted Genre: {result['predicted_genre']}")
print(f"Confidence: {result['confidence']:.2f}%")

# View all probabilities
for genre, prob in result['all_probabilities'].items():
print(f"{genre}: {prob:.2f}%")
```

---

## 📓 Using Jupyter Notebooks

### Exploratory Analysis

```bash
# Start Jupyter
jupyter notebook

# Open notebooks/exploratory_analysis.ipynb
```

The exploratory analysis notebook includes:
- Dataset statistics and visualization
- Genre distribution analysis
- Feature correlation studies
- Sample audio analysis

### Audio Visualization

```bash
# Open notebooks/audio_visualization.ipynb
```

Visualize:
- Audio waveforms
- Spectrograms
- MFCC features
- Chroma features

---

## 🎯 Common Use Cases

### Use Case 1: Building a Music Recommendation System

```python
"""
Music Recommendation Example
Author: Molla Samser
Company: RSK World
Website: https://rskworld.in
"""

from models.predict import MusicPredictor
import os

predictor = MusicPredictor()

def recommend_similar_music(target_genre, music_library):
"""Find songs matching the target genre"""
recommendations = []

for song_path in music_library:
result = predictor.predict(song_path)
if result['predicted_genre'] == target_genre:
recommendations.append({
'path': song_path,
'confidence': result['confidence']
})

# Sort by confidence
recommendations.sort(key=lambda x: x['confidence'], reverse=True)
return recommendations[:10] # Top 10
```

### Use Case 2: Automatic Music Library Organization

```python
"""
Music Library Organization
Author: Molla Samser (RSK World)
Email: help@rskworld.in
"""

import os
import shutil
from models.predict import MusicPredictor

def organize_music_library(source_dir, target_dir):
"""Organize music files by predicted genre"""
predictor = MusicPredictor()

for filename in os.listdir(source_dir):
if filename.endswith(('.wav', '.mp3')):
file_path = os.path.join(source_dir, filename)

# Predict genre
result = predictor.predict(file_path)
genre = result['predicted_genre']

# Create genre folder if not exists
genre_folder = os.path.join(target_dir, genre)
os.makedirs(genre_folder, exist_ok=True)

# Move file
shutil.copy(file_path, os.path.join(genre_folder, filename))
print(f"Moved {filename} to {genre}/")
```

### Use Case 3: Real-time Genre Detection

```python
"""
Real-time Genre Detection
Author: Molla Samser
Company: RSK World
Designer & Tester: Rima Khatun
Website: https://rskworld.in
Phone: +91 93305 39277
"""

from models.predict import MusicPredictor
import time

predictor = MusicPredictor()

def monitor_audio_stream(audio_source):
"""Monitor and classify audio stream in real-time"""
while True:
# Get audio chunk from source
audio_chunk = audio_source.get_next_chunk()

# Save temporarily
temp_path = 'temp_audio.wav'
audio_source.save_chunk(audio_chunk, temp_path)

# Predict
result = predictor.predict(temp_path)

print(f"Current Genre: {result['predicted_genre']} "
f"({result['confidence']:.1f}%)")

time.sleep(1) # Update every second
```

---

## 🛠️ Advanced Features

### Custom Feature Extraction

```python
"""
Custom Feature Extraction
Author: Molla Samser (RSK World)
Website: https://rskworld.in
"""

import librosa
import numpy as np

def extract_custom_features(audio, sr=22050):
"""Extract custom audio features"""
features = {}

# Mel spectrogram
mel_spec = librosa.feature.melspectrogram(y=audio, sr=sr)
features['mel_spec_mean'] = np.mean(mel_spec)
features['mel_spec_var'] = np.var(mel_spec)

# Spectral contrast
contrast = librosa.feature.spectral_contrast(y=audio, sr=sr)
features['contrast_mean'] = np.mean(contrast)

# Tonnetz
tonnetz = librosa.feature.tonnetz(y=audio, sr=sr)
features['tonnetz_mean'] = np.mean(tonnetz)

return features
```

### Batch Processing

```python
"""
Batch Audio Processing
Author: Molla Samser
Company: RSK World
Email: help@rskworld.in
"""

from models.predict import MusicPredictor
from tqdm import tqdm
import pandas as pd

def batch_classify_music(audio_files, output_csv):
"""Classify multiple audio files"""
predictor = MusicPredictor()
results = []

for audio_file in tqdm(audio_files, desc="Processing"):
try:
result = predictor.predict(audio_file)
results.append({
'filename': audio_file,
'genre': result['predicted_genre'],
'confidence': result['confidence']
})
except Exception as e:
print(f"Error processing {audio_file}: {str(e)}")

# Save to CSV
df = pd.DataFrame(results)
df.to_csv(output_csv, index=False)
print(f"Results saved to {output_csv}")
```

---

## 🐛 Troubleshooting

### Common Issues

**Issue 1: Module not found error**
```bash
# Solution: Ensure you're in the project directory and virtual environment is activated
pip install -r requirements.txt
```

**Issue 2: Audio file not loading**
```python
# Check file path and format
import os
print(os.path.exists('path/to/audio.wav')) # Should return True
```

**Issue 3: Model not found**
```bash
# Train the model first
python models/train_model.py --model random_forest
```

---

## 📞 Support & Contact

### Need Help?

**Author:** Molla Samser
**Company:** RSK World
**Designer & Tester:** Rima Khatun

**Contact Information:**
- 📧 Email: help@rskworld.in, support@rskworld.in
- 📱 Phone: +91 93305 39277
- 🌐 Website: [https://rskworld.in](https://rskworld.in)
- 📞 Contact Page: [https://rskworld.in/contact.php](https://rskworld.in/contact.php)

### Reporting Issues

Please include:
1. Python version
2. Operating system
3. Error message (if any)
4. Steps to reproduce the issue

---

## 📚 Additional Resources

- [Librosa Documentation](https://librosa.org/)
- [Scikit-learn Guide](https://scikit-learn.org/)
- [Audio Signal Processing](https://www.audiocontentanalysis.org/)
- [Music Information Retrieval](https://musicinformationretrieval.com/)

---

**© 2026 RSK World - Free Programming Resources & Source Code**

*Founded by Molla Samser with Designer & Tester Rima Khatun*

---

For questions, suggestions, or contributions, please visit:
**https://rskworld.in/contact.php**