# finnvoor/yap architecture

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

- Interactive diagram: https://gitdiagram.com/finnvoor/yap
- Repository: https://github.com/finnvoor/yap

## Overview

yap is a macOS command-line tool for on-device speech transcription. Its default file workflow validates an audio/video input, prepares audio, runs Apple Speech recognition, then formats and prints or saves the transcript. Separate commands capture microphone audio, system audio, or both in real time; an MCP server exposes file transcription to compatible clients. Shared formatting supports text, timed subtitles, JSON, censoring, sentence splitting, and word timestamps. Live-command excerpts are partial, so their capture and recognition flow is shown only where documented or evidenced.

Main entry points: [`Sources/yap/Transcribe.swift`](https://github.com/finnvoor/yap/blob/main/Sources/yap/Transcribe.swift) (File command), [`Sources/yap/ListenAndDictate.swift`](https://github.com/finnvoor/yap/blob/main/Sources/yap/ListenAndDictate.swift) (Dual-source capture), [`Sources/yap/Yap.swift`](https://github.com/finnvoor/yap/blob/main/Sources/yap/Yap.swift) (Command router), [`Sources/yap/Listen.swift`](https://github.com/finnvoor/yap/blob/main/Sources/yap/Listen.swift) (System listen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI entry points"]
  node_yap["Command router<br/>[Yap.swift]"]
  node_transcribe["File command<br/>[Transcribe.swift]"]
  node_mcp["MCP server<br/>[MCP.swift]"]
end

subgraph group_file["File transcription"]
  node_engine["Transcription engine"]
  node_audiofile["Audio preparation"]
  node_speech["Apple Speech"]
end

subgraph group_live["Live transcription"]
  node_listen["System listen<br/>[Listen.swift]"]
  node_dictate["Microphone dictate<br/>[Dictate.swift]"]
  node_combined["Dual-source capture"]
  node_screen["System audio capture"]
  node_microphone["Microphone input"]
end

subgraph group_format["Transcript formatting"]
  node_attributed["Transcript segmentation"]
  node_outputformat["Output serializers<br/>[OutputFormat.swift]"]
end

node_user(("CLI user"))
node_mcpclient(("MCP client"))
node_stdout["Standard output"]
node_fileout["Output file"]

node_user -->|"runs"| node_yap
node_yap -->|"dispatches"| node_transcribe
node_yap -->|"dispatches"| node_listen
node_yap -->|"dispatches"| node_dictate
node_yap -->|"dispatches"| node_combined
node_yap -->|"dispatches"| node_mcp
node_transcribe -->|"prepares audio"| node_audiofile
node_transcribe -->|"transcribes"| node_speech
node_audiofile -->|"provides audio"| node_speech
node_transcribe -->|"segments transcript"| node_attributed
node_transcribe -->|"formats transcript"| node_outputformat
node_transcribe -->|"prints result"| node_stdout
node_transcribe -->|"writes result"| node_fileout
node_mcpclient -->|"requests tool"| node_mcp
node_mcp -->|"invokes transcription"| node_engine
node_engine -->|"prepares audio"| node_audiofile
node_engine -->|"transcribes"| node_speech
node_engine -->|"formats transcript"| node_outputformat
node_listen -->|"captures audio"| node_screen
node_listen -->|"streams audio"| node_speech
node_listen -->|"segments results"| node_attributed
node_listen -->|"formats segments"| node_outputformat
node_listen -->|"prints segments"| node_stdout
node_dictate -->|"captures audio"| node_microphone
node_dictate -->|"streams audio"| node_speech
node_dictate -->|"segments results"| node_attributed
node_dictate -->|"formats segments"| node_outputformat
node_dictate -->|"prints results"| node_stdout
node_combined -->|"captures audio"| node_microphone
node_combined -->|"captures audio"| node_screen
node_combined -->|"streams sources"| node_speech
node_combined -->|"segments results"| node_attributed
node_combined -->|"formats segments"| node_outputformat
node_combined -->|"prints results"| node_stdout

click node_yap "https://github.com/finnvoor/yap/blob/main/Sources/yap/Yap.swift"
click node_transcribe "https://github.com/finnvoor/yap/blob/main/Sources/yap/Transcribe.swift"
click node_listen "https://github.com/finnvoor/yap/blob/main/Sources/yap/Listen.swift"
click node_dictate "https://github.com/finnvoor/yap/blob/main/Sources/yap/Dictate.swift"
click node_combined "https://github.com/finnvoor/yap/blob/main/Sources/yap/ListenAndDictate.swift"
click node_mcp "https://github.com/finnvoor/yap/blob/main/Sources/yap/MCP.swift"
click node_engine "https://github.com/finnvoor/yap/blob/main/Sources/yap/TranscriptionEngine.swift"
click node_audiofile "https://github.com/finnvoor/yap/blob/main/Sources/yap/TranscriptionAudioFile.swift"
click node_attributed "https://github.com/finnvoor/yap/blob/main/Sources/yap/Extensions/AttributedString%2BExtensions.swift"
click node_outputformat "https://github.com/finnvoor/yap/blob/main/Sources/yap/OutputFormat.swift"

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_yap,node_transcribe,node_mcp,node_user,node_mcpclient toneBlue
class node_engine,node_audiofile,node_speech toneAmber
class node_listen,node_dictate,node_combined,node_screen,node_microphone toneMint
class node_attributed,node_outputformat toneRose
class node_stdout,node_fileout toneIndigo
```

## Components

### CLI entry points

- [Command router](https://github.com/finnvoor/yap/blob/main/Sources/yap/Yap.swift): `Sources/yap/Yap.swift`
- [File command](https://github.com/finnvoor/yap/blob/main/Sources/yap/Transcribe.swift): `Sources/yap/Transcribe.swift`
- [MCP server](https://github.com/finnvoor/yap/blob/main/Sources/yap/MCP.swift): `Sources/yap/MCP.swift`

### File transcription

- [Transcription engine](https://github.com/finnvoor/yap/blob/main/Sources/yap/TranscriptionEngine.swift): `Sources/yap/TranscriptionEngine.swift`
- [Audio preparation](https://github.com/finnvoor/yap/blob/main/Sources/yap/TranscriptionAudioFile.swift): `Sources/yap/TranscriptionAudioFile.swift`
- **Apple Speech**

### Live transcription

- [System listen](https://github.com/finnvoor/yap/blob/main/Sources/yap/Listen.swift): `Sources/yap/Listen.swift`
- [Microphone dictate](https://github.com/finnvoor/yap/blob/main/Sources/yap/Dictate.swift): `Sources/yap/Dictate.swift`
- [Dual-source capture](https://github.com/finnvoor/yap/blob/main/Sources/yap/ListenAndDictate.swift): `Sources/yap/ListenAndDictate.swift`
- **System audio capture**
- **Microphone input**

### Transcript formatting

- [Transcript segmentation](https://github.com/finnvoor/yap/blob/main/Sources/yap/Extensions/AttributedString%2BExtensions.swift): `Sources/yap/Extensions/AttributedString+Extensions.swift`
- [Output serializers](https://github.com/finnvoor/yap/blob/main/Sources/yap/OutputFormat.swift): `Sources/yap/OutputFormat.swift`

### Other components

- **CLI user**
- **MCP client**
- **Standard output**
- **Output file**

## Connections

- CLI user → Command router: runs
- Command router → File command: dispatches
- Command router → System listen: dispatches
- Command router → Microphone dictate: dispatches
- Command router → Dual-source capture: dispatches
- Command router → MCP server: dispatches
- File command → Audio preparation: prepares audio
- File command → Apple Speech: transcribes
- Audio preparation → Apple Speech: provides audio
- File command → Transcript segmentation: segments transcript
- File command → Output serializers: formats transcript
- File command → Standard output: prints result
- File command → Output file: writes result
- MCP client → MCP server: requests tool
- MCP server → Transcription engine: invokes transcription
- Transcription engine → Audio preparation: prepares audio
- Transcription engine → Apple Speech: transcribes
- Transcription engine → Output serializers: formats transcript
- System listen → System audio capture: captures audio
- System listen → Apple Speech: streams audio
- System listen → Transcript segmentation: segments results
- System listen → Output serializers: formats segments
- System listen → Standard output: prints segments
- Microphone dictate → Microphone input: captures audio
- Microphone dictate → Apple Speech: streams audio
- Microphone dictate → Transcript segmentation: segments results
- Microphone dictate → Output serializers: formats segments
- Microphone dictate → Standard output: prints results
- Dual-source capture → Microphone input: captures audio
- Dual-source capture → System audio capture: captures audio
- Dual-source capture → Apple Speech: streams sources
- Dual-source capture → Transcript segmentation: segments results
- Dual-source capture → Output serializers: formats segments
- Dual-source capture → Standard output: prints results