EchoField

Plug in a field recorder. Get a private, searchable record of your day.

EchoField is an open-source macOS companion for all-day audio recorders. It imports WAV files when a recorder mounts, processes recordings locally, separates speakers, cleans noisy text, and writes timestamped Markdown chapters that work in Obsidian or any notes folder.

Audio stays on your Mac by default. Cloud transcription remains an explicit CLI option.

1. Download EchoField.dmg from Releases.
2. Drag EchoField to Applications and open it. Community builds may require Control-click > Open once.
3. In the Setup Assistant, choose Install Requirements.
4. Select a notes folder, then connect the recorder.

The first transcription downloads the selected local speech model. Qwen3-ASR-1.7B requires roughly 4.4 GB of model storage.

git clone https://github.com/shroominic/echofield.git
cd echofield
./scripts/setup-runtime.command
./scripts/install_app.sh

Requirements: Apple Silicon, macOS 26 or newer, Xcode command-line tools, and about 10 GB of free space for runtimes and models.

• Starts processing each recording as soon as that file finishes copying.
• Runs multilingual Qwen3-ASR through MLX with Whisper large-v3 fallback.
• Uses speech-aware audio preparation and Silero VAD to avoid processing silence.
• Optionally labels speaker turns with pyannote.audio.
• Optionally cleans ASR artifacts through a local Ollama model.
• Builds timestamped chapters and daily Markdown notes.
• Resumes after interruption and skips verified cached stages.
• Shows copy, preparation, transcription, speaker, cleanup, diary, and recorder-clearing progress independently.
• Deletes source audio only after the local WAV, processing artifacts, diary notes, and SHA-256 checksum all verify.

The included profile targets a volume named H8 with recordings in RECORD/. Both values are editable. Any USB mass-storage recorder that exposes WAV files in one folder should work; device-specific filename or directory layouts may need an adapter.

See Device Profiles before filing a hardware issue.

Model outputs can be wrong. Keep the original recording and raw transcript for anything consequential.

flowchart LR
  A["Recorder WAV"] --> B["Verified local archive"]
  B --> C["Denoise + VAD"]
  C --> D["Local ASR"]
  D --> E["Speaker separation"]
  E --> F["Local cleanup"]
  F --> G["Markdown diary"]
  G --> H{"Checksums + artifacts valid?"}
  H -->|Yes| I["Optional recorder clear"]
  H -->|No| J["Keep source on recorder"]

Work is bounded by stage: copying is serial, preparation can overlap, model-heavy transcription is single-worker, and post-processing has its own lane. See Architecture for data contracts and extension points.

The included deterministic simulator compares worker pools, scheduling policies, and model speedups without loading a model or touching audio. It can emit regression-gate JSON and Chrome/Perfetto timelines; an optional read-only probe measures pyannote on real hardware. See Benchmarking.

uv run python -m benchmarks.pipeline_benchmark matrix

uv run --extra qwen echofield scan
uv run --extra qwen echofield prepare
uv run --extra qwen echofield transcribe
uv run echofield assemble
uv run --extra diarization echofield diarize
uv run echofield cleanup

Use uv run --extra qwen echofield run for scan through transcript assembly. Run uv run echofield --help for paths, model selection, language, VAD, and cloud-provider options. New environment variables use the ECHOFIELD_ prefix; the former H8_ names remain compatible.

EchoField has no account, analytics, telemetry, or EchoField server. Local stages do not upload recordings. Model packages are downloaded from their respective registries, and Obsidian integration writes ordinary files. Cloud providers are used only when explicitly selected from the CLI.

Read Privacy and Security before processing sensitive recordings. Always follow recording-consent laws where you live.

Start with CONTRIBUTING.md, the roadmap, and issues labeled good first issue. Tests use generated fixtures; never commit private recordings, transcripts, tokens, or model weights.

make bootstrap
make test
make lint

• Setup and troubleshooting
• Architecture
• Benchmarking
• Device profiles
• Privacy model
• Brand guide
• Third-party software and models
• Governance

Apache-2.0. See LICENSE and NOTICE. EchoField is not affiliated with Zoom, Obsidian, Hugging Face, NVIDIA, Alibaba, Apple, or OpenAI.