diff options
Diffstat (limited to 'GLOSSARY.md')
| -rw-r--r-- | GLOSSARY.md | 49 |
1 files changed, 49 insertions, 0 deletions
diff --git a/GLOSSARY.md b/GLOSSARY.md new file mode 100644 index 0000000..4d05b8b --- /dev/null +++ b/GLOSSARY.md @@ -0,0 +1,49 @@ +# GLOSSARY.md — canonical vocabulary + +> **One term per concept. Never coin a synonym silently.** If you think a new +> term is needed, propose it and wait for approval before using it in code. + +## Core concepts + +| Term | Definition | Avoid calling it... | +|------|-----------|-------------------| +| **PlayerState** | The single struct holding all mutable runtime state: loaded audio, playback status, silence regions, study mode flag | "app state", "context", "global state" | +| **speaking portion** | A contiguous segment of audio between two silence regions (i.e. the "meaningful content"). 0-based index. | "section", "segment", "clip", "part" | +| **silence region** | A detected gap in audio where amplitude stays below threshold for ≥ minDuration. Normalized 0–1. | "pause", "gap", "quiet zone" | +| **study mode** | Boolean toggle (`PlayerState.studyMode`). When ON, auto-pauses at silence boundaries. | "auto-pause mode", "learning mode" | +| **seek** | Jump playback position to a specific time (seconds). `player_seek(PlayerState*, float)`. | "scrub", "jump", "skip" | +| **auto-pause** | The study-mode mechanism that pauses playback when entering a silence region. | "auto-stop", "silence break" | +| **padding zone** | The 0.25s "breathing room" added around speaking portions (silence shrunk by 0.25s on each side) to avoid auto-pausing during natural speech pauses. | "grace period", "buffer zone" | +| **portion navigation** | Jumping between speaking portions via keys (V/B) or section buttons. | "chapter skip", "section nav" | +| **embedded font** | A `.otf`/`.ttf` font file converted to `build/font_data.h` via `xxd`, compiled into the binary. Guarded by `#if FONT_EMBEDDED`. | "baked font", "built-in font" | + +## Module names + +| Module | Files | Owns | +|--------|-------|------| +| **types** | `src/types.h` | `PlayerState`, `SilenceRegion`, all enums, defines, constants | +| **player** | `src/player.h`, `src/player.c` | Audio loading, playback control, seek, time formatting | +| **study** | `src/study.h`, `src/study.c` | Silence detection, study mode logic, portion navigation | +| **ui** | `src/ui.h`, `src/ui.c` | All rendering, font/color initialization, input handling | +| **main** | `src/main.c` | Entry point, main loop, platform glue | + +## Build terms + +| Term | Meaning | +|------|---------| +| **desktop build** | Host-native build via `gcc`, produces `build/study-player` (Linux) | +| **Windows build** | Cross-compile via `x86_64-w64-mingw32-gcc`, produces `build/study-player.exe` | +| **web build** | WASM via `emcc` + Emscripten, produces `build-web/index.{html,js,wasm}` | +| **font header** | `build/font_data.h` generated by `xxd -i` from a font in `resources/` | + +## Platform defines + +| Define | When set | +|--------|----------| +| `PLATFORM_DESKTOP` | Building for desktop — both Linux native and Windows cross-compile. Set in Makefile. | +| `PLATFORM_LINUX` | Defined by `-DPLATFORM_LINUX` when building for Linux. | +| `PLATFORM_WEB` | Building for web (Emscripten). Set in web build script. | +| `_GLFW_X11` | GLFW X11 backend (Linux). Set in Makefile for Linux builds. | +| `_GLFW_WIN32` | GLFW Windows backend. Set in Makefile for Windows cross-compile. | +| `GRAPHICS_API_OPENGL_ES2` | WebGL 2 backend. Set in web build script. | +| `FONT_EMBEDDED` | Defined in `font_data.h` by `xxd`. Guards `#if FONT_EMBEDDED` blocks. | |