hoo2/Multimedia_AAC_Project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Compare commits

base: hoo2:master
Branches Tags
hoo2:master
hoo2:v1.0
..
compare: hoo2:v1.0
Branches Tags
hoo2:master
hoo2:v1.0

No commits in common. "master" and "v1.0" have entirely different histories.
master ... v1.0

1 changed files with 62 additions and 260 deletions
Show Stats Expand all files Collapse all files

322
Readme.md
View File

@ -1,312 +1,114 @@
# AAC Encoder/Decoder Assignment (Multimedia – AUTh) # AAC Encoder/Decoder Assignment (Multimedia)
## Overview ## About
This repository contains a staged implementation of a simplified AAC-like audio encoder/decoder pipeline, developed in the context of the **Multimedia** course at Aristotle University of Thessaloniki (AUTh). 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 project follows a progressive, level-based structure: 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.
- **Level 1:** Core analysis/synthesis pipeline
- **Level 2:** Full transform-domain encoding with quantization
- **Level 3:** Psychoacoustic modeling and perceptual coding enhancements
The goal of this work is to:
- Faithfully implement the processing chain specified in the assignment
- Validate correctness using structured and reproducible tests
- Maintain a clean and reproducible project architecture
- Ensure separation between development logic and submission packaging
---
## System Architecture
The implemented pipeline follows a simplified AAC-style structure:
```
Input WAV
↓
SSC (Segmentation Control)
↓
Filterbank (MDCT)
↓
[TNS / Psychoacoustic Model] (Level 3)
↓
Quantization & Coding (Level 2+)
↓
Bitstream Structuring
↓
-----------------------------------------
↓
Inverse Quantization
↓
Inverse Filterbank (IMDCT)
↓
OLA Reconstruction
↓
Output WAV
```
Each level progressively enables more blocks of this pipeline.
---
## Repository Structure ## Repository Structure
The repository is organized into source code, material, and report files. The repository is organized into source code, project requirements and report files:
``` - `source`
root/ Under `source` directory there are:
│ - `level_1` Containing the baseline implementation of the required processing chain for Level 1.
├── source/ - `level_2` Containing the baseline implementation of the required processing chain for Level 2.
│ ├── level_1/ - `level_3` Containing the baseline implementation of the required processing chain for Level 3.
│ ├── level_2/
│ ├── level_3/ Each level contains:
│ ├── core/ - a module file (e.g., `level_1/level_1.py`)
│ └── material/ - a dedicated `core/` directory
│ - a dedicated `material/` directory
├── report/
├── README.md
└── LICENSE
```
### `source/` - `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
Contains all implementation code. - `report` Directory that contains the TeX files for the report
- `root directory files` Like Readme.md, LICENSE, etc...
#### `level_x/`
Each level directory contains: ### 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_x.py` (main module entry point)
- `core/` (hard-links to shared implementation)
- `material/` (hard-links to required helper material)
- `tests/` (level-specific tests)
Each level is **self-contained** to satisfy submission requirements. ## Level Descriptions
#### `core/` ### Level 1
This directory contains the centralized implementation of: **Goal:** Implement the core analysis/synthesis chain for Level 1 as defined in the assignment specification.
- SSC Implemented components (current status):
- MDCT / IMDCT filterbank - SSC (Sequence Segmentation Control)
- Quantizer / dequantizer - Filterbank (MDCT analysis) and inverse filterbank (IMDCT synthesis)
- Psychoacoustic model - End-to-end encoder/decoder functions:
- TNS
- Bitstream handling
- Encoder/decoder pipelines
All development happens here.
Each `level_x/core/` directory references these files using **hard links**, ensuring:
- No code duplication
- No synchronization errors
- Clean development workflow
#### `material/`
Contains helper files provided by the assignment:
- Sample audio
- Reference data
- Required constants or auxiliary files
---
## Development Workflow Design
One of the project requirements was to deliver `level_x` directories containing all required files, without referencing external directories.
Naively copying files across levels would introduce:
- Code redundancy
- High maintenance cost
- Risk of inconsistencies
- Debugging complexity
To avoid this:
- All implementation lives in `source/core/`
- Each `level_x` directory contains hard-links to `core/` and `material/`
This ensures:
- Single source of truth
- Clean modular structure
- Instructor-compliant submission format
- Safe iterative development
---
# Level Descriptions
---
## Level 1 – Core Transform Pipeline
### Goal
Implement the baseline transform-domain analysis/synthesis chain.
### Implemented Components
- Sequence Segmentation Control (SSC)
- MDCT analysis filterbank
- IMDCT synthesis filterbank
- Overlap-Add (OLA) reconstruction
- End-to-end encoder/decoder:
- `aac_coder_1()` - `aac_coder_1()`
- `i_aac_coder_1()` - `i_aac_coder_1()`
- Demo: - Demo function:
- `demo_aac_1()` - `demo_aac_1()`
### Testing Coverage 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`
- SSC unit tests ### Level 2
- MDCT / IMDCT correctness tests
- Perfect reconstruction validation
- OLA consistency tests
- Encoder/decoder integration tests
This level ensures transform-domain correctness and signal integrity. **Goal:** ...
---
## Level 2 – Quantization and Coding ### Level 3
### Goal **Goal:** ...
Extend Level 1 by implementing transform-domain quantization and coding. ## How to Run
### Implemented Components In order to run the demo functionality you should be inside the `source/level_x` directory.
- Scalar quantization ### Run Level 1 Demo
- Dequantization
- Basic bitstream formatting
- Integration into encoder/decoder pipeline:
- `aac_coder_2()`
- `i_aac_coder_2()`
- Demo:
- `demo_aac_2()`
### Validation Run the Level 1 demo by providing an input WAV file and an output WAV file:
- SNR-based quality evaluation
- Consistency tests between quantizer and inverse quantizer
- End-to-end reconstruction tests
This level introduces compression and controlled signal degradation.
---
## Level 3 – Psychoacoustic Model & Perceptual Coding
### Goal
Incorporate perceptual modeling to improve compression efficiency.
### Implemented Components
- Psychoacoustic model
- Masking threshold estimation
- TNS (Temporal Noise Shaping)
- Adaptive quantization
- Full encoding/decoding pipeline:
- `aac_coder_3()`
- `i_aac_coder_3()`
- Demo:
- `demo_aac_3()`
### Validation
- Perceptual improvements compared to Level 2
- Stability tests
- End-to-end evaluation
This level approximates a simplified perceptual AAC-like encoder.
---
# How to Run
All commands assume you are inside:
```
source/
```
---
## Run Level Demo
Navigate to the desired level:
```
cd source/level_x
```
Run:
```bash ```bash
python -m level_x <input.wav> <output.wav> python -m level_1 <input.wav> <output.wav>
``` ```
Example: Example:
```bash ```bash
python -m 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.
The demo prints: ### How to Run Tests
- Overall SNR (dB) Tests are written and can get executed using `pytest` and are organized per level.
- Processing information 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
# Running Tests work consistently when running tests from the command line.
Tests are written using `pytest`.
A `pytest.ini` file is included in `source/` to ensure proper module resolution.
From inside `source/`:
From inside `source/`, run all tests:
```bash ```bash
pytest -v pytest -v
``` ```
Run specific level tests: To run only `level_1/tests` or a specific test file:
```bash ```bash
pytest -v level_1/tests pytest -v level_1/tests
pytest -v level_2/tests
pytest -v level_3/tests
```
Run a specific test file:
```bash
pytest -v level_1/tests/test_SSC.py pytest -v level_1/tests/test_SSC.py
``` ```
--- ## Disclaimer
# Reproducibility This project was developed solely for educational purposes.
It is provided "as is", without any express or implied warranties.
- Python version: 3.x
- Tests validated with `pytest`
- No external dependencies beyond assignment requirements
- Deterministic pipeline execution
---
# Disclaimer
This project was developed solely for educational purposes as part of the Multimedia course at AUTh.
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. 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. This implementation should not be used in production environments.