# Structure

```bash
meetings/
├── bin/
│   ├── meeting-start          # starts recording + live transcription
│   ├── meeting-stop           # stops recording, asks for meeting name, renames files
│   ├── meeting-follow         # follow transcript while it is being written
│   └── summarize-meeting      # create post-meeting summaries (planned, not yet realized)
│
├── lib/
│   ├── paths.sh               # creates session dirs + defines file paths
│   └── whisper.sh             # whisper.cpp binary, model, ASR parameters
│
└── recordings/
    └── 2026-02-21T013852/     # session directory (created on meeting-start)
        ├── audio.wav          # raw system audio recording
        ├── transcript.txt     # live transcript (grows during meeting)
        ├── meta.env           # session metadata (PIDs, language, timestamps)
        ├── 2025-03-24T1930_project-sync_transcript.txt   # the actual renamed transcript
        ├── 2025-03-24T1930_project-sync_audio.wav        # (see data protection discussion)
        └── summary.md         # created by summarize-meeting (planned, not yet realized)
```

### Description of Paths and Scripts

#### Paths

**Path**: `meetings/bin/`

- Executable scripts.

**Path**: `meetings/lib/`

- Scripts to be used by the executable scripts.

**Path**: `meetings/recordings/`

- Subdirectories (ISO timestamp format) containing: 
    - Audio files (should be deleted after the transcript has been written)
    - `transcript.txt` (renamed and timestamped after the meeting's end by the `meeting-stop` script)
    - `meta.env` (Meeting information) 
        - PIDs
        - language used
        - the meeting's timestamps
    - `summary.md` (meeting summary in Markdown format)

#### Scripts (current architecture)  


TranscriptOMatic is implemented as a small set of composable shell scripts. Each script has a clearly defined responsibility within the session lifecycle. No script relies on implicit system state or hard-coded audio devices.

##### Library scripts (meetings/lib/)

`meetings/lib/paths.sh`

<span class="s2">Responsible for </span>**session creation and path management**<span class="s2">.</span>

On invocation, it:

- creates a new session directory

```bash
~/meetings/recordings/<ISO_TIMESTAMP>/
```

- defines canonical file locations:
    
    
    - `audio.wav`
    - `transcript.txt`
    - `meta.env`

- provides these paths to all other scripts

This script is the *only* place where session directories are created.

`meetings/lib/whisper.sh`

<span class="s1">Defines the </span>**speech recognition backend configuration**<span class="s1">.</span>

It contains:

- the path to the local `<span class="s1">whisper.cpp</span>` installation
- model selection (language-specific vs. multilingual)
- streaming parameters
- threading configuration suitable for a Raspberry Pi–class system

The setup is explicitly optimized for <span class="s2">**live transcription**</span> using `<span class="s3">whisper-stream</span>`, not for batch processing.

No audio devices are referenced here.

##### Executable scripts (meetings/bin/)

**meeting-start**

Starts a new live transcription session.

**Responsibilities**

1. **Session initialization**
    - creates a new session directory via `<span class="s1">paths.sh</span>`
    - writes the active session path to `~/meetings/recordings/.current`
2. **Audio graph setup (PipeWire)**
    
    
    - ensures a persistent null sink (`discord_sink`)
    - routes Discord audio into that sink
    - exposes the sink monitor as a virtual microphone (`whisper_mic`)
3. **Processing**
    - records audio from `whisper_mic` via `ffmpeg`
    - performs (almost) live transcription using `whisper-stream`
    - appends output to `transcript.txt`
4. **State tracking**
    - writes all relevant runtime information (PIDs, module IDs, paths) to `meta.env`

**Usage**

```bash
meeting-start --en    # force English
```

***Planned, not yet realized:***

```bash
meeting-start --de    # force German (planned, not yet realized)
meeting-start --auto  # auto-detect language (planned, not yet realized)
```

`<span class="s1">meeting-start</span>` is self-contained: it does not require any pre-existing audio configuration and can be run after a reboot.

**meeting-follow**

Passively follows the live transcript of the <span class="s1">**currently active session**</span>.

**Behaviour**

- waits for the presence of `~/meetings/recordings/.current`
- reads the active session path from that file
- waits until `transcript.txt` exists
- follows the transcript in real time

This allows meeting-follow to be started:

- before meeting-start
- over SSH
- in a shared terminal window

It will never attach to archived sessions.

**Usage**

```bash
meeting-follow # stop with ctrl+c
```

**meeting-stop**

Stops the active transcription session and finalises all session files.

**Responsibilities**

1. **Process teardown** kills the FFmpeg and whisper-stream processes via their stored PIDs
2. **State clean-up** removes `~/meetings/recordings/.current` unloads the `whisper_mic` remap-source module from PipeWire
3. **File finalisation** prompts for a meeting name and slugifies it 
    - renames transcript.txt and audio.wav to timestamped, named files (e.g. 2025-03-24T1930\_project-sync\_transcript.txt)

To prevent accidental deletions, `meeting-stop` does not delete files automatically. To maintain data protection, recording files have to be deleted by hand.

**Usage**

```bash
meeting-stop              # stops the most recent session
```