# jihao2048/jieli-audio-whitepaper architecture

> Architecture diagram of the GitHub repository jihao2048/jieli-audio-whitepaper, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jihao2048/jieli-audio-whitepaper
- Repository: https://github.com/jihao2048/jieli-audio-whitepaper

## Overview

This is a JieLi audio-container recovery toolkit: users select or name device audio files, the application identifies each format, dispatches to its decoder, and produces PCM WAV output. The workflow is available through both a tkinter batch-conversion GUI and a command-line interface; the CLI also supports format inspection. Decoding has distinct F1A, IMA-ADPCM, and MP3 stages. The README additionally describes format-research documentation. Wiring for some unsampled modules is based on README claims; external decoder and FFmpeg integrations are kept distinct.

Main entry points: [`wav_tool/service.py`](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/service.py) (Conversion service), [`wav_tool/jie2wav.py`](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/jie2wav.py) (CLI), [`wav_tool/f1a_decoder.py`](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/f1a_decoder.py) (F1A decoding), [`wav_tool/gui.py`](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/gui.py) (Desktop GUI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_gui["Desktop GUI<br/>[gui.py]"]
  node_cli["CLI<br/>[jie2wav.py]"]
end

subgraph group_dispatch["Conversion core"]
  node_service["Conversion service<br/>[service.py]"]
  node_sniff["Format detection<br/>[common.py]"]
  node_pcm["PCM and WAV I/O<br/>[common.py]"]
end

subgraph group_formats["Format decoders"]
  node_f1a["F1A container<br/>[f1a.py]"]
  node_f1adec["F1A decoding<br/>[f1a_decoder.py]"]
  node_abe["A/B/E ADPCM<br/>[abe.py]"]
  node_ump3["UMP3 parsing<br/>[ump3.py]"]
end

subgraph group_integrations["External decoding"]
  node_vendor["Bundled vendor decoder<br/>[testf1a_dec.exe]"]
  node_ffmpeg["FFmpeg"]
end

node_user(("User"))
node_wav["WAV files"]
node_inputs["JieLi audio files"]
node_formatdocs["Format white paper"]

node_user -->|"selects files"| node_gui
node_user -->|"provides inputs"| node_cli
node_gui -->|"starts conversion"| node_service
node_cli -->|"runs tasks"| node_service
node_cli -->|"inspects format"| node_sniff
node_inputs -->|"input files"| node_service
node_service -->|"detects format"| node_sniff
node_service -->|"dispatches F1A"| node_f1adec
node_service -->|"dispatches ADPCM"| node_abe
node_service -->|"dispatches UMP3"| node_ump3
node_service -->|"writes WAV"| node_pcm
node_f1adec -->|"parses container"| node_f1a
node_f1adec -->|"runs decoder"| node_vendor
node_ump3 -->|"decodes MP3"| node_ffmpeg
node_pcm -->|"writes PCM"| node_wav

click node_gui "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/gui.py"
click node_cli "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/jie2wav.py"
click node_service "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/service.py"
click node_sniff "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/common.py"
click node_pcm "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/common.py"
click node_f1a "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/f1a.py"
click node_f1adec "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/f1a_decoder.py"
click node_abe "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/abe.py"
click node_ump3 "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/ump3.py"
click node_vendor "https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/tools/testf1a_dec.exe"
click node_formatdocs "https://github.com/jihao2048/jieli-audio-whitepaper/tree/main/docs"

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_gui,node_cli,node_user toneBlue
class node_service,node_sniff,node_pcm toneAmber
class node_f1a,node_f1adec,node_abe,node_ump3 toneMint
class node_vendor,node_ffmpeg toneRose
class node_wav,node_inputs toneIndigo
class node_formatdocs toneTeal
```

## Components

### User interfaces

- [Desktop GUI](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/gui.py): `wav_tool/gui.py`
- [CLI](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/jie2wav.py): `wav_tool/jie2wav.py`

### Conversion core

- [Conversion service](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/service.py): `wav_tool/service.py`
- [Format detection](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/common.py): `wav_tool/common.py`
- [PCM and WAV I/O](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/common.py): `wav_tool/common.py`

### Format decoders

- [F1A container](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/f1a.py): `wav_tool/f1a.py`
- [F1A decoding](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/f1a_decoder.py): `wav_tool/f1a_decoder.py`
- [A/B/E ADPCM](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/abe.py): `wav_tool/abe.py`
- [UMP3 parsing](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/ump3.py): `wav_tool/ump3.py`

### External decoding

- [Bundled vendor decoder](https://github.com/jihao2048/jieli-audio-whitepaper/blob/main/wav_tool/tools/testf1a_dec.exe): `wav_tool/tools/testf1a_dec.exe`
- **FFmpeg**

### Other components

- **User**
- **WAV files**
- **JieLi audio files**
- [Format white paper](https://github.com/jihao2048/jieli-audio-whitepaper/tree/main/docs): `docs`

## Connections

- User → Desktop GUI: selects files
- User → CLI: provides inputs
- Desktop GUI → Conversion service: starts conversion
- CLI → Conversion service: runs tasks
- CLI → Format detection: inspects format
- JieLi audio files → Conversion service: input files
- Conversion service → Format detection: detects format
- Conversion service → F1A decoding: dispatches F1A
- Conversion service → A/B/E ADPCM: dispatches ADPCM
- Conversion service → UMP3 parsing: dispatches UMP3
- Conversion service → PCM and WAV I/O: writes WAV
- F1A decoding → F1A container: parses container
- F1A decoding → Bundled vendor decoder: runs decoder
- UMP3 parsing → FFmpeg: decodes MP3
- PCM and WAV I/O → WAV files: writes PCM