Level_1: Readme changes

Readme.md

@@ -8,20 +8,35 @@ The purpose of this work is to implement the specified processing chain faithful
 
 ## Repository Structure
 
-The repository is organized under the `source/` directory and split into three incremental levels:
+The repository is organized into source code, project requirements and report files:
 
-- `source/level_1/`  
-  Baseline implementation of the required processing chain for Level 1.
+- `source` 
+  Under `source` directory there are:
+  - `level_1`   Containing the baseline implementation of the required processing chain for Level 1.
+  - `level_2`   Containing the baseline implementation of the required processing chain for Level 2.
+  - `level_3`   Containing the baseline implementation of the required processing chain for Level 3. 
+  
+  Each level contains:
+    - a module file (e.g., `level_1/level_1.py`)
+    - a dedicated `core/` directory
+    - a dedicated `material/` directory
 
-- `source/level_2/`  
-  Placeholder for Level 2 implementation (to be filled step-by-step).
+  - `core`
+      This directory contains the actual implementation, which is referenced in each one of the `level_x/core/` directories.
+  - `material`
+    This directory contains the actual given helper material files 
 
-- `source/level_3/`  
-  Placeholder for Level 3 implementation (to be filled step-by-step).
+- `report` Directory that contains the TeX files for the report
+- `root directory files` Like Readme.md, LICENSE, etc...
+
+
+### Notes on Repository structure and Development Workflow
+One of the project requirements was to deliver `level_x` directories containing all the necessary files, without referencing any other external files and libraries.
+This requirement introduces copies and is considered error-prone.
+In order to avoid that we centralized the development of the project inside `core` directory.
+Each level directory contains a references(hard-links) to the files of both `core` and `material` folders.
+This way we keep the instructor happy while avoiding the nightmare of code redundancy.
 
-Each level contains:
-- a module file (e.g., `level_1/level_1.py`)
-- a dedicated `tests/` directory for module-level tests (pytest)
 
 ## Level Descriptions
 
@@ -55,48 +70,41 @@ Tests (current status):
 
 ## How to Run
 
-All commands below assume you are inside the `source/` directory.
+In order to run the demo functionality you should be inside the `source/level_x` directory.
 
 ### Run Level 1 Demo
 
 Run the Level 1 demo by providing an input WAV file and an output WAV file:
 
 ```bash
-python -m level_1.level_1 <input.wav> <output.wav>
+python -m level_1 <input.wav> <output.wav>
 ```
 Example:
 ```bash
-python -m level_1.level_1 ../material/LicorDeCalandraca.wav ../material/LicorDeCalandraca_out.wav
+python -m level_1 material/LicorDeCalandraca.wav material/LicorDeCalandraca_out.wav
 ```
 The demo prints the overall SNR (in dB) between the original and reconstructed audio.
 
 ### How to Run Tests
 
-Tests are written using `pytest` and are organized per level.
+Tests are written and can get executed using `pytest` and are organized per level.
+In order to run the demo functionality you should be inside the `source/` directory.
+
+The repository includes a `pytest.ini` file inside the `source/` directory.
+This file explicitly sets the Python module search path so that imports such as the followings
+work consistently when running tests from the command line.
 
 From inside `source/`, run all tests:
 ```bash
-pytest
+pytest -v
 ```
 
-To run only level_1/tests
+To run only `level_1/tests` or a specific test file:
 ```bash
-pytest level_1/tests
+pytest -v level_1/tests
+pytest -v level_1/tests/test_SSC.py
 ```
 
-To run a specific test file:
-```bash
-pytest level_1/tests/test_SSC.py
-```
-
-
-
-## Notes on Development Workflow
-
-- The project is developed incrementally, level-by-level.
-- Tests are primarily module-level and specification-driven.
-- Internal helper testing is avoided in general, except for MDCT/IMDCT which are treated as reusable “library-like” primitives.
-
 ## Disclaimer
 
 This project was developed solely for educational purposes.
@@ -104,4 +112,4 @@ It is provided "as is", without any express or implied warranties.
 The author assumes no responsibility for any misuse, data loss, security incidents, or damages resulting from the use of this software.
 This implementation should not be used in production environments.
 
-All work, modifications, and results are the sole responsibility of the author.
+All work, modifications, and results are the sole responsibility of the author.