# 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. |