# margotmassonresearch/phoneviz architecture

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

- Interactive diagram: https://gitdiagram.com/margotmassonresearch/phoneviz
- Repository: https://github.com/margotmassonresearch/phoneviz

## Overview

PhoneViz turns a reference transcript and audio into phonetic alignments, then presents those alignments in an interactive IPA-chart visualizer. Users can run this for one utterance or a dataframe; already-aligned data can be displayed directly. The documented runtime stages are reference-to-IPA conversion, Wav2Vec2 phone recognition, SCTK sclite alignment, and visualization with phonetic annotations. The excerpts show the pipeline’s calls and the visualizer’s mapping-file read; other subsystem links below are supported by README statements, not unsampled implementation details.

Main entry points: [`source/show_and_tell_pipeline.py`](https://github.com/margotmassonresearch/phoneviz/blob/main/source/show_and_tell_pipeline.py) (ShowTellPipeline), [`source/phoneviz.py`](https://github.com/margotmassonresearch/phoneviz/blob/main/source/phoneviz.py) (PhoneViz), [`source/alignment.py`](https://github.com/margotmassonresearch/phoneviz/blob/main/source/alignment.py) (SCLiteAlignment), [`source/phonetic_transcription.py`](https://github.com/margotmassonresearch/phoneviz/blob/main/source/phonetic_transcription.py) (Wav2Vec2 phones)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs and orchestration"]
  node_audio["Audio recordings"]
  node_transcript["Reference transcript"]
  node_dataframe["Alignment dataframe"]
  node_pipeline["ShowTellPipeline"]
end

subgraph group_processing["Phone processing"]
  node_text["Text to IPA<br/>[text.py]"]
  node_recognition["Wav2Vec2 phones"]
end

subgraph group_alignment["Alignment engine"]
  node_aligner["SCLiteAlignment<br/>[alignment.py]"]
  node_sclite["SCTK sclite<br/>[sctk-2.4.10]"]
  node_alignments["Phone alignments"]
end

subgraph group_display["Visualization"]
  node_visualizer["PhoneViz<br/>[phoneviz.py]"]
  node_mapping["IPA feature mapping"]
  node_chart["Interactive IPA chart<br/>[phoneviz.py]"]
end

node_user(("User"))
node_espeak["eSpeak"]

node_user -->|"runs"| node_pipeline
node_audio -->|"provides audio"| node_pipeline
node_transcript -->|"provides reference"| node_pipeline
node_dataframe -->|"provides rows"| node_pipeline
node_pipeline -->|"converts reference"| node_text
node_pipeline -->|"recognizes phones"| node_recognition
node_recognition -.->|"uses phonemizer"| node_espeak
node_pipeline -->|"requests alignment"| node_aligner
node_aligner -->|"runs scorer"| node_sclite
node_aligner -->|"returns aligned phones"| node_alignments
node_pipeline -->|"produces dataframe"| node_alignments
node_user -->|"opens alignments"| node_visualizer
node_alignments -->|"supplies aligned phones"| node_visualizer
node_visualizer -->|"reads annotations"| node_mapping
node_visualizer -->|"renders controls"| node_chart

click node_pipeline "https://github.com/margotmassonresearch/phoneviz/blob/main/source/show_and_tell_pipeline.py"
click node_text "https://github.com/margotmassonresearch/phoneviz/blob/main/source/text.py"
click node_recognition "https://github.com/margotmassonresearch/phoneviz/blob/main/source/phonetic_transcription.py"
click node_aligner "https://github.com/margotmassonresearch/phoneviz/blob/main/source/alignment.py"
click node_sclite "https://github.com/margotmassonresearch/phoneviz/tree/main/resources/sctk-2.4.10"
click node_visualizer "https://github.com/margotmassonresearch/phoneviz/blob/main/source/phoneviz.py"
click node_mapping "https://github.com/margotmassonresearch/phoneviz/blob/main/resources/phonemapsat_ipa.csv"
click node_chart "https://github.com/margotmassonresearch/phoneviz/blob/main/source/phoneviz.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_audio,node_transcript,node_dataframe,node_pipeline,node_user toneBlue
class node_text,node_recognition toneAmber
class node_aligner,node_sclite,node_alignments toneMint
class node_visualizer,node_mapping,node_chart toneRose
class node_espeak toneIndigo
```

## Components

### Inputs and orchestration

- **Audio recordings**
- **Reference transcript**
- **Alignment dataframe**
- [ShowTellPipeline](https://github.com/margotmassonresearch/phoneviz/blob/main/source/show_and_tell_pipeline.py): `source/show_and_tell_pipeline.py`

### Phone processing

- [Text to IPA](https://github.com/margotmassonresearch/phoneviz/blob/main/source/text.py): `source/text.py`
- [Wav2Vec2 phones](https://github.com/margotmassonresearch/phoneviz/blob/main/source/phonetic_transcription.py): `source/phonetic_transcription.py`

### Alignment engine

- [SCLiteAlignment](https://github.com/margotmassonresearch/phoneviz/blob/main/source/alignment.py): `source/alignment.py`
- [SCTK sclite](https://github.com/margotmassonresearch/phoneviz/tree/main/resources/sctk-2.4.10): `resources/sctk-2.4.10`
- **Phone alignments**

### Visualization

- [PhoneViz](https://github.com/margotmassonresearch/phoneviz/blob/main/source/phoneviz.py): `source/phoneviz.py`
- [IPA feature mapping](https://github.com/margotmassonresearch/phoneviz/blob/main/resources/phonemapsat_ipa.csv): `resources/phonemapsat_ipa.csv`
- [Interactive IPA chart](https://github.com/margotmassonresearch/phoneviz/blob/main/source/phoneviz.py): `source/phoneviz.py`

### Other components

- **User**
- **eSpeak**

## Connections

- User → ShowTellPipeline: runs
- Audio recordings → ShowTellPipeline: provides audio
- Reference transcript → ShowTellPipeline: provides reference
- Alignment dataframe → ShowTellPipeline: provides rows
- ShowTellPipeline → Text to IPA: converts reference (evidence: `source/show_and_tell_pipeline.py`)
- ShowTellPipeline → Wav2Vec2 phones: recognizes phones (evidence: `source/show_and_tell_pipeline.py`)
- Wav2Vec2 phones → eSpeak: uses phonemizer
- ShowTellPipeline → SCLiteAlignment: requests alignment (evidence: `source/show_and_tell_pipeline.py`)
- SCLiteAlignment → SCTK sclite: runs scorer (evidence: `source/alignment.py`)
- SCLiteAlignment → Phone alignments: returns aligned phones
- ShowTellPipeline → Phone alignments: produces dataframe (evidence: `source/show_and_tell_pipeline.py`)
- User → PhoneViz: opens alignments
- Phone alignments → PhoneViz: supplies aligned phones
- PhoneViz → IPA feature mapping: reads annotations (evidence: `source/phoneviz.py`)
- PhoneViz → Interactive IPA chart: renders controls (evidence: `source/phoneviz.py`)
