bytebard101/urbanecho repository overview

⁠💥 UrbanEcho

UrbanEcho is a web-based audio classification project that predicts urban sound types from .wav files. It is built with Python, scikit-learn, and Flask, and uses a RandomizedSearchCV-tuned ML pipeline trained on tabular audio features extracted from the UrbanSound8K dataset.

⁠🚀 Features

• Accepts .wav audio file uploads via a simple web interface.
• Extracts 34 audio features per sample (MFCCs, Chroma, Spectral Contrast, Zero Crossing Rate, Spectral Centroid).
• Predicts 10 classes of urban sounds:
  • air_conditioner
  • car_horn
  • children_playing
  • dog_bark
  • drilling
  • engine_idling
  • gun_shot
  • jackhammer
  • siren
  • street_music
• Displays predicted class with class probabilities using visual progress bars.
• Automatically cleans uploaded files after prediction.
• Self-healing: if model files are missing, it retrains the pipeline automatically.

⁠🖼 Screenshots

Upload Page:

Prediction Result Page:

⁠📁 Project Structure

UrbanEcho/
├── datasets/                         # Datasets used for training
│ └── extracted_audio_features.csv
├── models/                           # .pkl files go here
│ ├── feature_names.pkl               # Not included with the repo
│ └── pipe.pkl                        # Not included with the repo
├── static/                           # Static files for the web app
│ └── uploads/   
│ └── style.css
├── templates/                        # HTML code for front-end
│ ├── index.html
│ └── result.html
├── utils/                            # Utility code for feature engineering
│ └── feature_extractor.py
├── app.py                            # Flask app
├── fit.py                            # Python script for training the model
├── requirements.txt                  # Libraries required for this project
└── research.ipynb                    # Notebook used for testing, visualization and many more

⁠🗂 Dataset

• Source: UrbanSound8K Tabular Form⁠
• Contains audio features extracted from real-world urban sounds.
• 34 features per sample:
  • MFCC_1 … MFCC_13
  • Chroma_1 … Chroma_12
  • SpectralContrast_1 … SpectralContrast_7
  • ZeroCrossingRate
  • SpectralCentroid
• 10 classes of urban sound.

⁠⚙ Installation

1. Clone the repository:

git clone https://github.com/yourusername/UrbanEcho.git
cd UrbanEcho

1. Install dependencies:

pip install -r requirements.txt

1. Run the Web App:

python app.py

⁠🏃 How to use

1. After running the app, open your browser and go to localhost:5000⁠
2. The interface should appear instantly. Upload a .wav file and hit Predict
3. The app will display:
   • Predicted class (human-readable label)
   • Probabilities for all classes in a progress-bar style visualization.

⁠🐳 Run the app directly via Dockerhub Image

This is my first project where I have implemented Docker containerization. I have created a Dockerhub repository⁠ where I have pushed the docker container.

The container is built on both ARM64 and AMD64 architectures, so that it can run on almost all major computers. You can run the app easily by using the Dockerhub Image. Here's how you can do it:

1. Install Docker Desktop⁠ and sign-in

2. Open Terminal and run this:

docker pull bytebard101/urbanecho:latest
docker run --rm -p 5000:5000 bytebard101/urbanecho:latest

1. If your machine does not have the port 5000 free, you need to run in a different port. Try to run this:

docker run --rm -p 5001:5000 bytebard101/urbanecho:latest

1. The app will be live at localhost:5000. Open your browser and navigate to http://127.0.0.1:5000⁠ (or http://127.0.0.1:5001⁠ if you followed Step 3).

Check Docker Documentation⁠ to learn more about Docker and it's commands.

⁠📊 Model Performance

• Algorithm: RandomForest (RandomizedSearchCV tuned)
• Cross-validated F1-score: 0.91

Classification report on test set:

⁠⚡️ Notes / Limitations

• Single .wav predictions can show messy probabilities due to PCA and class overlap.

• Model is trained on tabular features, not raw audio — deep learning could improve predictions significantly.

• If models/pipe.pkl or models/feature_names.pkl are deleted, the app will retrain the model automatically (may take a few minutes).

• Because of the lack of extra contributors and my lack of front-end expertise, I had to use AI tools (mostly LLM services like ChatGPT™, Grok™, Gemini™) in order to create a sophisticated front end for the web app. The HTML and CSS were written by those tools.

• The static/style.css file is currently blank. I have used <style/> tag and inline method in HTML files to generate the style. It will be updated in future if needed.

⁠📌 Author

Sakib ( ByteBard58 )

📍 GitHub Profile: ByteBard58⁠

⁠😃 Appreciation

Thank you for taking the time to review my work. I hope you enjoyed it and found it intriguing. It would mean a lot to me if you could star it on GitHub. 🌟 If you would like to contribute to this repository, please do so. It will be a great help!

If you have any questions, suggestions, or anything else you’d like to discuss, please don’t hesitate to reach out. You can find my contact information on my GitHub profile page⁠. I’m all ears! 😊

Have a great day!