# karolpiczak/esc-50 architecture

> Architecture diagram of the GitHub repository karolpiczak/esc-50, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2024-12-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/karolpiczak/esc-50
- Repository: https://github.com/karolpiczak/esc-50

## Overview

Key Components to Include:

##### Data Organization Layer
- Audio Files Repository
- Hierarchical structure of WAV files (5-second, 44.1 kHz, mono)
- Naming convention pattern: {FOLD}-{CLIP_ID}-{TAKE}-{TARGET}.wav

- Metadata Layer
- CSV file structure (esc50.csv)
- Human evaluation data (esc50-human.xlsx)

##### Dataset Structure
- 5 Cross-validation Folds
- 50 Semantic Classes
- 2000 Audio Recordings
- ESC-10 Subset (10 selected classes)

##### Classification Categories
- Animals
- Natural soundscapes & water sounds
- Human, non-speech sounds
- Interior/domestic sounds
- Exterior/urban noises

##### Use a Layered Architecture
**┌─────────────────────────────────────────┐**
- ESC-50 Dataset              │
- ┤

- ┌─────────────┐        ┌────────────┐  │
- Audio Data │        │  Metadata  │  │
- ┘        └────────────┘  │

- ┌─────────────┐        ┌────────────┐  │
- 5 Folds   │        │    CSV     │  │
- ┘        └────────────┘  │

- ┤
- Classification Categories        │
- ┘

- Cardinality (1:n, n:1, etc.)

##### Additional Elements
- Data format specifications
- Cross-validation fold structure
- File naming conventions

##### Technical Specifications
- Audio format: WAV (5 seconds, 44.1 kHz, mono)
- Dataset size: 2000 recordings
- Cross-validation: 5 folds
- Class distribution: 40 examples per class

##### License Information
- Creative Commons Attribution Non-Commercial
- CC BY for ESC-10 subset

##### The distinction between ESC-50 and ESC-10 subsets

This system design will help developers understand:
- How to navigate the dataset
- The relationship between different components
- The data organization principles
- The classification structure
- How to properly use the cross-validation folds

Remember to maintain a balance between detail and clarity, as this is primarily a dataset project rather than a software system.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph ESC-50["ESC-50 Dataset"]
        direction TB
        
        subgraph DataLayer["Data Organization Layer"]
            direction TB
            AudioRepo["Audio Files Repository"]:::storage
            MetaLayer["Metadata Layer"]:::meta
            
            subgraph AudioDetails["Audio Specifications"]
                WavFormat["WAV Format<br/>5s, 44.1kHz, mono"]:::spec
                NamingConv["Naming Convention<br/>{FOLD}-{CLIP_ID}-{TAKE}-{TARGET}"]:::spec
            end
            
            subgraph MetaDetails["Metadata Components"]
                CSV["ESC50 CSV"]:::file
                HumanEval["Human Evaluation<br/>Data"]:::file
            end
        end
        
        subgraph Structure["Dataset Structure"]
            direction TB
            Folds["5 Cross-validation<br/>Folds"]:::struct
            Classes["50 Semantic<br/>Classes"]:::struct
            Recordings["2000 Audio<br/>Recordings"]:::struct
            ESC10["ESC-10 Subset<br/>(10 classes)"]:::subset
        end
        
        subgraph Categories["Classification Categories"]
            direction TB
            Animals["Animals"]:::cat
            Natural["Natural Soundscapes<br/>& Water"]:::cat
            Human["Human Non-speech<br/>Sounds"]:::cat
            Interior["Interior/Domestic<br/>Sounds"]:::cat
            Exterior["Exterior/Urban<br/>Noises"]:::cat
        end
        
        subgraph Infrastructure["Project Infrastructure"]
            direction TB
            Testing["Testing Framework"]:::infra
            CICD["CI/CD Config"]:::infra
            Config["Project Config"]:::infra
        end
    end
    
    %% Relationships
    AudioRepo --> Folds
    MetaLayer --> CSV
    MetaLayer --> HumanEval
    Folds --> Classes
    Classes --> Categories
    Classes --> ESC10
    
    %% Styling
    classDef storage fill:#3498db,stroke:#2980b9,color:white
    classDef meta fill:#2ecc71,stroke:#27ae60,color:white
    classDef spec fill:#95a5a6,stroke:#7f8c8d,color:white
    classDef file fill:#e74c3c,stroke:#c0392b,color:white
    classDef struct fill:#9b59b6,stroke:#8e44ad,color:white
    classDef subset fill:#e67e22,stroke:#d35400,color:white
    classDef cat fill:#f1c40f,stroke:#f39c12,color:black
    classDef infra fill:#1abc9c,stroke:#16a085,color:white
    
    %% Click events
    click AudioRepo "https://github.com/karolpiczak/ESC-50/tree/master/audio/"
    click MetaLayer "https://github.com/karolpiczak/ESC-50/tree/master/meta/"
    click CSV "https://github.com/karolpiczak/ESC-50/blob/master/meta/esc50.csv"
    click HumanEval "https://github.com/karolpiczak/ESC-50/blob/master/meta/esc50-human.xlsx"
    click Testing "https://github.com/karolpiczak/ESC-50/blob/master/tests/test_dataset.py"
    click CICD "https://github.com/karolpiczak/ESC-50/blob/master/.circleci/config.yml"
    click Config "https://github.com/karolpiczak/ESC-50/blob/master/requirements.txt"
```
