front final update

README.md

@@ -84,6 +84,28 @@ Ai-sounds-detection/
 └── MLtraining/            # Machine learning training notebooks and scripts
 ```
 
+## Dataset preparation
+
+The `data/` folder is organized by sound category and is used to store training and validation clips.
+- `drilling/`, `vacuum/`, `keyboard/`, `washing/` contain labeled audio clips.
+- Use `model/cutter.py` to split long recordings into fixed-length segments.
+- Use `model/cleaner.py` to clean and filter audio samples.
+- Use `model/dataset_into_hf.py` to upload the prepared dataset to HuggingFace if needed.
+
+## Reproduce the model
+
+The app loads the pre-trained model from HuggingFace Hub:
+- Dataset: `https://huggingface.co/datasets/kadzioriron/Sounds`
+- Model: `https://huggingface.co/kadzioriron/Sounds-CNN`
+
+To reproduce the app locally:
+```bash
+pip install -r requirements.txt
+streamlit run main.py
+```
+
+To retrain or prepare new audio data, use the utility scripts in `model/` and the feature extraction functions in `utilits.py`.
+
 ## File Documentation
 
 ### main.py

main.py

@@ -7,58 +7,114 @@ from huggingface_hub import hf_hub_download
 # classes
 CLASSES = ["drilling", "vacuum", "keyboard", "washing"]
 
-# cash suggested from AI
+# AI model loader
 @st.cache_resource
 def load_ai_model():
-
-    REPO_ID = "kadzioriron/Sounds-CNN" 
-
+    REPO_ID = "kadzioriron/Sounds-CNN"
     model_path = hf_hub_download(repo_id=REPO_ID, filename="ai_sounds_model.keras")
-    
     return tf.keras.models.load_model(model_path)
 
 model = load_ai_model()
 
-# Main page
+st.set_page_config(
+    page_title="AI Sounds Detection",
+    page_icon="🔊",
+    layout="wide",
+)
+
 st.title("AI Sounds Detection")
-st.write("Upload a file to see its spectrogram and get AI prediction")
+st.markdown(
+    "This app detects common household sounds and displays audio visualizations before it predicts the sound category. Upload a short `.wav` or `.mp3` clip and the AI model will classify it as one of the supported sounds."
+)
+
+st.subheader("How this works")
+st.markdown(
+    "- The app loads a pre-trained AI model from HuggingFace Hub.\n"
+    "- It converts your audio into features the model was trained on, including MFCCs and mel-spectrogram data.\n"
+    "- The model then predicts the most likely sound category and shows confidence."
+)
+
+st.subheader("About the model")
+st.markdown(
+    "- Pre-trained convolutional neural network (CNN) for sound classification.\n"
+    "- Uses MFCC and mel-spectrogram features extracted from audio.\n"
+    "- Trained on labeled household sound clips from the HuggingFace Sounds dataset."
+)
+
+st.subheader("Supported sound categories")
+st.markdown(
+    "The model currently recognizes these sounds:"
+)
+st.write("- **Drilling** — electric drill or similar tool noise")
+st.write("- **Vacuum** — vacuum cleaner motor or suction noise")
+st.write("- **Keyboard** — typing and key press sounds")
+st.write("- **Washing** — washing machine cycle or spin noise")
+
+st.subheader("Upload instructions")
+st.markdown(
+    "- Use a clear audio file with minimal background noise.\n"
+    "- Best results come from short recordings (2–10 seconds).\n"
+    "- Supported file formats: `.wav`, `.mp3`.\n"
+    "- The file should contain one primary sound category at a time."
+)
+
+with st.sidebar:
+    st.header("Resources")
+    st.markdown(
+        "- [HuggingFace Dataset](https://huggingface.co/datasets/kadzioriron/Sounds)\n"
+        "- [HuggingFace Model](https://huggingface.co/kadzioriron/Sounds-CNN)\n"
+        "- [Live Demo Space](https://huggingface.co/spaces/kadzioriron/AI_Sounds_detection)\n"
+    )
+    st.markdown("---")
+    st.header("Quick tips")
+    st.write("- Upload a single sound type per file.")
+    st.write("- Use a quiet room and hold the recording device near the sound source.")
+    st.write("- Avoid music or multiple devices running at once.")
 
-# File upload
-uploaded_file = st.file_uploader("Choose the type of the file", type=['wav', 'mp3'])
+uploaded_file = st.file_uploader("Upload your sound file", type=["wav", "mp3"])
 
 if uploaded_file is not None:
-    # Playing the sounds on the website
-    st.audio(uploaded_file, format='audio/wav')
-    
-    st.write("Reading your file and predicting...")
-    
-    # Get data using our utils function
+    st.audio(uploaded_file, format="audio/wav")
+
     y, sr = get_audio_data(uploaded_file)
-    
-    #checking the data
-    processed_audio = prepare_audio_for_model(y, sr)
-    
-    # predicting
-    predictions = model.predict(processed_audio)
-    predicted_index = np.argmax(predictions[0]) # intex of class
-    confidence = predictions[0][predicted_index] * 100 # precentage
-    
-    #result
+    duration = len(y) / sr if sr > 0 else 0
+    file_size_kb = uploaded_file.size / 1024 if hasattr(uploaded_file, "size") else None
+
+    st.subheader("File details")
+    st.write(f"**Name:** {uploaded_file.name}")
+    if file_size_kb is not None:
+        st.write(f"**Size:** {file_size_kb:.1f} KB")
+    st.write(f"**Duration:** {duration:.2f} seconds")
+    st.write(f"**Sample rate:** {sr} Hz")
+
+    with st.spinner("Extracting features and predicting..."):
+        processed_audio = prepare_audio_for_model(y, sr)
+        predictions = model.predict(processed_audio)
+
+    top_predictions = sorted(
+        [(CLASSES[i], float(predictions[0][i]) * 100) for i in range(len(CLASSES))],
+        key=lambda x: x[1],
+        reverse=True,
+    )[:3]
+    predicted_index = np.argmax(predictions[0])
+    confidence = float(predictions[0][predicted_index]) * 100
+
     st.success(f"🤖 AI Prediction: **{CLASSES[predicted_index].upper()}**")
     st.info(f"Confidence: {confidence:.2f}%")
+    st.caption("Higher confidence means the sound matches the trained category more clearly.")
     st.divider()
-    
-    """Visuals"""
+
+    st.subheader("Top 3 predictions")
+    for label, score in top_predictions:
+        st.write(f"- **{label}**: {score:.1f}%")
+
     st.subheader("Waveform")
-    st.write("Loudness and amplitude of sounds")
+    st.write("The waveform shows amplitude over time and helps you inspect the sound structure.")
     fig_wave = plot_waveform(y, sr)
-    st.pyplot(fig_wave) 
-    
+    st.pyplot(fig_wave)
+
     st.subheader("Mel-spectrogram")
-    st.write("Shows what and how AI actually sees")
+    st.write("The mel-spectrogram is what the AI model uses to recognize sound patterns.")
     fig_mel = plot_mel_spectrogram(y, sr)
-    st.pyplot(fig_mel) 
+    st.pyplot(fig_mel)
 
-    st.subheader("Sample rates")
-    st.write("Shows the sample rates of the audio file")
-    st.write(f"Sample rate: {sr} Hz")