# AAC Encoder/Decoder Assignment (Multimedia)

## About

This repository contains a staged implementation of a simplified AAC-like audio coder/decoder pipeline, developed in the context of the Multimedia course at Aristotle University of Thessaloniki (AUTh).
The project is organized into incremental levels, where each level introduces additional functionality and requirements (e.g., segmentation control, filterbanks, and progressively more complete encoding/decoding stages).
The purpose of this work is to implement the specified processing chain faithfully to the assignment specification, validate correctness with structured tests, and maintain a clean, reproducible project structure throughout development.

## Repository Structure

The repository is organized into source code, project requirements and report files:

- `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

  - `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 

- `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.


## Level Descriptions

### Level 1

**Goal:** Implement the core analysis/synthesis chain for Level 1 as defined in the assignment specification.

Implemented components (current status):
- SSC (Sequence Segmentation Control)
- Filterbank (MDCT analysis) and inverse filterbank (IMDCT synthesis)
- End-to-end encoder/decoder functions:
  - `aac_coder_1()`
  - `i_aac_coder_1()`
- Demo function:
  - `demo_aac_1()`

Tests (current status):
- Module-level tests for SSC
- Module-level tests for filterbank and inverse filterbank (including OLA-based reconstruction checks)
- Internal consistency tests for MDCT/IMDCT
- Module-level tests for `aac_coder_1` / `i_aac_coder_1`

### Level 2

**Goal:** ...


### Level 3

**Goal:** ...

## How to Run

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 <input.wav> <output.wav>
```
Example:
```bash
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 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 -v
```

To run only `level_1/tests` or a specific test file:
```bash
pytest -v level_1/tests
pytest -v level_1/tests/test_SSC.py
```

## Disclaimer

This project was developed solely for educational purposes.
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.
