# sh7shir/speech-restoration-deep-learning architecture

> Architecture diagram of the GitHub repository sh7shir/speech-restoration-deep-learning, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sh7shir/speech-restoration-deep-learning
- Repository: https://github.com/sh7shir/speech-restoration-deep-learning

## Overview

This is a research pipeline for decoding sEEG features into log-Mel speech spectrograms, comparing diffusion and baseline neural models. The main workflow conditionally extracts EEG/audio features, trains and predicts per participant, evaluates reconstruction quality, and optionally plots results. Source excerpts show preprocessing, model selection, persistence, and evaluation; README documents the broader study and metrics. Some reported capabilities are documented but not independently verified in the sampled code.

Main entry points: [`src/audio_constructor.py`](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py) (Participant reconstruction), [`main.py`](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/main.py) (Pipeline entry), [`src/vis.py`](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/vis.py) (Result visualizations), [`src/feature_extractor.py`](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/feature_extractor.py) (Feature extraction)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Feature preparation"]
  node_settings["Run settings<br/>[config.py]"]
  node_extractor["Feature extraction"]
  node_mel["Mel filter bank<br/>[MelFilterBank.py]"]
  node_feature_files[("Feature arrays")]
end

subgraph group_decode["Decoder pipeline"]
  node_reconstructor["Participant reconstruction"]
  node_architectures["Decoder architectures<br/>[models.py]"]
  node_trained_outputs[("Predicted spectrograms")]
end

subgraph group_report["Evaluation and reporting"]
  node_metrics["Reconstruction metrics"]
  node_result_files[("Evaluation results")]
  node_plots["Result visualizations<br/>[vis.py]"]
  node_figures["Generated figures<br/>[vis.py]"]
end

node_researcher(("Researcher"))
node_dataset[("sEEG and audio dataset")]
node_entry["Pipeline entry<br/>[main.py]"]

node_researcher -->|"runs"| node_entry
node_entry -->|"reads flags"| node_settings
node_entry -->|"runs when enabled"| node_extractor
node_dataset -->|"provides recordings"| node_extractor
node_extractor -->|"converts spectra"| node_mel
node_extractor -->|"writes arrays"| node_feature_files
node_entry -->|"runs when enabled"| node_reconstructor
node_settings -->|"configures run"| node_reconstructor
node_feature_files -->|"supplies inputs"| node_reconstructor
node_reconstructor -->|"selects and trains"| node_architectures
node_reconstructor -->|"saves predictions"| node_trained_outputs
node_reconstructor -->|"evaluates predictions"| node_metrics
node_metrics -->|"saves scores"| node_result_files
node_entry -->|"runs when enabled"| node_plots
node_result_files -->|"plots scores"| node_plots
node_trained_outputs -->|"plots spectrograms"| node_plots
node_settings -->|"sets plot locations"| node_plots
node_plots -->|"writes figures"| node_figures

click node_entry "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/main.py"
click node_settings "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/config.py"
click node_extractor "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/feature_extractor.py"
click node_mel "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/MelFilterBank.py"
click node_feature_files "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/feature_extractor.py"
click node_reconstructor "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py"
click node_architectures "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/models.py"
click node_trained_outputs "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py"
click node_metrics "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py"
click node_result_files "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py"
click node_plots "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/vis.py"
click node_figures "https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/vis.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_settings,node_extractor,node_mel,node_feature_files toneBlue
class node_reconstructor,node_architectures,node_trained_outputs,node_dataset toneAmber
class node_metrics,node_result_files,node_plots,node_figures toneMint
class node_researcher toneIndigo
class node_entry toneTeal
```

## Components

### Feature preparation

- [Run settings](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/config.py): `src/config.py`
- [Feature extraction](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/feature_extractor.py): `src/feature_extractor.py`
- [Mel filter bank](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/MelFilterBank.py): `src/MelFilterBank.py`
- [Feature arrays](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/feature_extractor.py): `src/feature_extractor.py`

### Decoder pipeline

- [Participant reconstruction](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py): `src/audio_constructor.py`
- [Decoder architectures](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/models.py): `src/models.py`
- [Predicted spectrograms](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py): `src/audio_constructor.py`

### Evaluation and reporting

- [Reconstruction metrics](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py): `src/audio_constructor.py`
- [Evaluation results](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/audio_constructor.py): `src/audio_constructor.py`
- [Result visualizations](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/vis.py): `src/vis.py`
- [Generated figures](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/src/vis.py): `src/vis.py`

### Other components

- **Researcher**
- **sEEG and audio dataset**
- [Pipeline entry](https://github.com/sh7shir/speech-restoration-deep-learning/blob/main/main.py): `main.py`

## Connections

- Researcher → Pipeline entry: runs (evidence: `README.md`)
- Pipeline entry → Run settings: reads flags (evidence: `main.py`)
- Pipeline entry → Feature extraction: runs when enabled (evidence: `main.py`)
- sEEG and audio dataset → Feature extraction: provides recordings (evidence: `src/feature_extractor.py`)
- Feature extraction → Mel filter bank: converts spectra (evidence: `src/feature_extractor.py`)
- Feature extraction → Feature arrays: writes arrays (evidence: `src/feature_extractor.py`)
- Pipeline entry → Participant reconstruction: runs when enabled (evidence: `main.py`)
- Run settings → Participant reconstruction: configures run (evidence: `src/audio_constructor.py`)
- Feature arrays → Participant reconstruction: supplies inputs (evidence: `src/audio_constructor.py`)
- Participant reconstruction → Decoder architectures: selects and trains (evidence: `src/audio_constructor.py`)
- Participant reconstruction → Predicted spectrograms: saves predictions (evidence: `src/audio_constructor.py`)
- Participant reconstruction → Reconstruction metrics: evaluates predictions (evidence: `src/audio_constructor.py`)
- Reconstruction metrics → Evaluation results: saves scores (evidence: `src/audio_constructor.py`)
- Pipeline entry → Result visualizations: runs when enabled (evidence: `main.py`)
- Evaluation results → Result visualizations: plots scores (evidence: `src/vis.py`)
- Predicted spectrograms → Result visualizations: plots spectrograms (evidence: `src/vis.py`)
- Run settings → Result visualizations: sets plot locations (evidence: `src/vis.py`)
- Result visualizations → Generated figures: writes figures (evidence: `src/vis.py`)
