dsh-escutar

A voice note has two records: the audio and the transcript. When the transcript is wrong (wrong language, noise, text from another note), the mistake enters the conversation silently. This plugin measures how far the transcript is from the audio in the shared 768-dimensional space of EmbeddingGemma, and lets you search the audio by meaning even when the transcript cannot be trusted.

It never transcribes again, never deletes and never rewrites a transcript: it reads, measures and warns. Audio never leaves your machine.

Install

Works on Linux, macOS and Windows. Open a terminal (PowerShell is fine on Windows) and run:

# 1. pnpm — the harness manages profile plugins with it
npm install -g pnpm

# 2. add the plugin to your `web` profile
npx @deepseek-ai/dsh plugin --profile web add github:songjongdevsecops/dsh-escutar

# 3. restart the harness: the bundle layer is read at boot
#    stop `dsh web` (Ctrl+C) and start it again
npx @deepseek-ai/dsh web

If dsh is installed globally, step 2 is dsh plugin --profile web add github:songjongdevsecops/dsh-escutar.

The package declares dsh.bundle.patch, so dsh plugin add also appends the plugin row to the profile bundle list. That row is the only activation, and it is applied at every boot. Nothing else to configure to install.

Update and uninstall

# update: re-run the add command above (it resolves the repository again), then restart
npx @deepseek-ai/dsh plugin --profile web remove dsh-escutar   # then restart

Requirements

• Node.js ^22.19.0 || >=24.0.0 (the same range DeepSeek Harness supports).
• pnpm on PATH — the harness uses it to manage profile plugins.
• DeepSeek Harness itself.
• EmbeddingGemma CLI reachable as an executable. The plugin calls parecido <audio> <text> --simetrico and buscar <query> --indice <collection> --n <n>. Point it with the DSH_ESCUTAR_GEMMA_BIN environment variable or the gemma config key. If the binary is missing, the first measurement answers with an error naming that variable; the rest of the harness is unaffected.
• A voice corpus: one audio file and one transcript per note, sharing the id (001.ogg + 001.md), either side by side or split into audio/ and texto/.

The plugin itself has no native dependencies and no build step: plain ESM using only Node built-ins.

Usage

Who	How	What you get
the agent	conferir_transcricao tool	check one note (id) or search the audio by meaning (consulta)
you	/escutar command	recent notes with a suspicious transcript
the agent	agent/pre-step hook	a short warning at the end of the conversation when a recent note is suspicious; nothing is appended when there is no suspicion, so it costs zero tokens

conferir_transcricao { "id": "001" }                               # is this note trustworthy?
conferir_transcricao { "consulta": "what did I say about backup" } # search the audio
/escutar                                                           # recent suspicious notes

Verdicts

The verdict is the cosine between the audio vector and the transcript vector:

Verdict	When
suspeita	cosine < 0.78 − 0.03
incerta	inside the 0.03 band around the threshold
confiavel	cosine > 0.78 + 0.03
sem-medida	no number (CLI failure, corrupt cache)

A note on the edge of the threshold is reported as incerta on purpose: it is neither an alarm nor a pass.

Configuration

Every key falls back to a default, so a wrong config never breaks the plugin. Override the row by id in your profile patch (~/.dsh/profiles/web/cordis.patch.yml; on Windows, %USERPROFILE%\.dsh\profiles\web\cordis.patch.yml). A patch replaces the whole config of the row, so restate every key you want to keep:

- id: escutar
  config:
    corpus: '/path/to/voice-corpus'
    cache: '/path/to/discordancia.json'
    gemma: '/path/to/embeddinggemma'
    limiar: 0.78
    banda: 0.03
    maxAvisos: 2
    colecaoAudio: 'escutar-audio-gemma-v1'
    tempoLimiteMs: 120000

Key	Default	Meaning
workspace	package directory	base for the corpus and cache defaults
corpus	<workspace>/corpus	folder with the audio/transcript pairs
cache	<workspace>/estado/discordancia.json	cache read by /escutar and the hook
gemma	DSH_ESCUTAR_GEMMA_BIN, then ~/.local/bin/embeddinggemma (embeddinggemma.exe on Windows)	EmbeddingGemma CLI
limiar	0.78	cosine below which the transcript is suspicious
banda	0.03	uncertainty margin around the threshold
maxAvisos	2	maximum lines the hook appends; 0 disables it
colecaoAudio	escutar-audio-gemma-v1	index name used by consulta
tempoLimiteMs	120000	timeout for one CLI call

The DSH_ESCUTAR_GEMMA_BIN variable is used when gemma is not set in the config. The package carries no machine-specific path.

Index and cache

The plugin reads two artifacts; it does not build them:

1. Audio index (colecaoAudio, default escutar-audio-gemma-v1) — needed only by conferir_transcricao with consulta. Build it with the EmbeddingGemma CLI:

   embeddinggemma indexar /path/to/corpus/audio \
     --nome escutar-audio-gemma-v1 --ext ogg,opus,mp3,wav,m4a
   

   The audio encoder reads roughly the first 30 seconds of each file. If you need long notes sliced into windows, slice them before indexing.

2. Discordance cache (cache) — needed by /escutar and the hook. It is a JSON file written by your indexing pipeline:

   {
     "gerado_em": "2026-10-13T12:00:00+00:00",
     "notas": [
       {
         "id": "001",
         "cosseno": 0.84,
         "transcricao": "first 200 characters of the transcript",
         "mtime": "2026-10-13T11:59:00+00:00",
         "mtime_texto": "2026-10-13T11:59:00+00:00",
         "janelas": [0.84],
         "segundos": 12
       }
     ]
   }
   

   mtime and mtime_texto are the modification times of the audio and the transcript when the cosine was measured. The tool checks them on every read: a cache without them, or older than the files on disk, is not served as current — the note is measured again on the spot. The hook only warns about notes whose mtime is within the last 48 hours.

Without an index or a cache, conferir_transcricao with id still works: it measures the pair live (about 11 s to load the model, plus a few seconds per note). /escutar and the hook stay quiet and say what is missing.

Verification

After the restart, dump the profile config and look for the row:

npx @deepseek-ai/dsh --profile web --dump-config

# == dsh-escutar
- id: escutar
  name: dsh-escutar

Then ask the agent to call conferir_transcricao with {"id": "001"} (or run /escutar when the cache exists). A live measurement returns the cosine, the verdict and the transcript read from the cache.

From a source checkout, run the test suite:

npm test

The suite covers the verdict band, the CLI output parser, the cache freshness guards, the command, the hook and the missing-binary error. It uses shell stubs, so it runs on Linux and macOS; installing the plugin does not depend on it.

Limits

• The audio encoder reads about 30 seconds. A long note is judged by a window, not by the whole recording.
• A plausible but wrong transcript can pass. Swapping one word for another word on the same subject may not move the cosine below the threshold. The signal catches gross errors: wrong language, noise, text from another note.
• It does not judge the content. It only says whether the audio and the text talk about the same thing in the same semantic space.

License

MIT