Voice Vault

voice_vault records microphone and system audio, archives it as MP3, and optionally transcribes it. Existing audio and video files can be imported as well.

The recommended transcription provider is the standalone transcribe command, which uses WhisperX and supports speaker diarization. Existing local whisper.cpp and remote Whisper configurations remain supported.

Each recording is stored in a private timestamped directory:

~/recordings/2026-07-15_10-30-00/
├── recording.mp3
└── transcription.txt

If two recordings start in the same second, later directories receive a numeric suffix such as _2.

• All workflows require Ruby 2.7 or newer.
• Live recording requires pactl and FFmpeg with PulseAudio support. Voice Vault uses the modern get-default-* commands when available and falls back to pactl info on older PulseAudio versions.
• Importing anything other than an MP3 requires FFmpeg. Local whisper.cpp transcription also requires FFmpeg to normalize every input, including MP3 files, to PCM WAV.
• The recommended provider requires transcribe on $PATH.
• The local provider requires a whisper.cpp checkout and model.
• The remote provider requires an OpenAI-compatible Whisper service.

Clone Voice Vault and make its executable available:

git clone https://github.com/200ok-ch/voice_vault.git
cd voice_vault
chmod +x voice_vault.rb

For the recommended provider, install transcribe on $PATH:

cd ..
git clone https://github.com/200ok-ch/transcribe.git
cd transcribe
make install PREFIX="$HOME/.local"
export PATH="$HOME/.local/bin:$PATH"
cd ../voice_vault

Add the export line to ~/.profile or the appropriate shell startup file so new terminals and desktop-launched sessions inherit it. Verify the installation before continuing:

command -v transcribe
transcribe --version

Then configure transcribe according to its README. It stores its WhisperX endpoint and bearer token in a SOPS-encrypted configuration file.

Create Voice Vault’s private configuration before the first run:

install -d -m 700 ~/.config/voice_vault
install -m 600 /dev/null ~/.config/voice_vault/config.yml
${EDITOR:-vi} ~/.config/voice_vault/config.yml

For the recommended provider, enter:

archive_path: ~/recordings
whisper_provider: transcribe
whisper_diarize: true

Record the default PulseAudio source and default sink monitor. Press q in FFmpeg to stop:

./voice_vault.rb

Import an existing audio or video file:

./voice_vault.rb --file meeting.mp3

Archive audio without transcription:

./voice_vault.rb --no-transcription
./voice_vault.rb --file meeting.mkv --no-transcription

Run ./voice_vault.rb --help for all options.

Voice Vault reads ~/.config/voice_vault/config.yml. Every provider requires an archive root:

archive_path: ~/recordings

Use --config PATH to load another file.

The transcribe provider invokes the transcribe executable found on $PATH. Diarization is enabled by default for this provider:

archive_path: ~/recordings
whisper_provider: transcribe
whisper_diarize: true

The following existing Voice Vault settings are forwarded when present:

• whisper_model
• whisper_language
• whisper_num_speakers
• whisper_min_speakers
• whisper_max_speakers
• whisper_read_timeout

Set whisper_diarize: false to request a plain transcript. Credentials and the WhisperX endpoint remain owned by transcribe, not Voice Vault. Speaker counts are forwarded only when diarization is enabled. An exact whisper_num_speakers cannot be combined with the minimum or maximum bounds, and the minimum cannot exceed the maximum.

A diarized transcription.txt groups consecutive segments into speaker turns without timestamps:

SPEAKER_00: Welcome. Let's get started.

SPEAKER_01: Thanks. The first topic is...

Existing local configurations continue to work:

archive_path: ~/recordings
whisper_provider: local
whisper_path: ~/src/whisper.cpp
whisper_model: small
whisper_threads: 4

The historical main path, a root-level whisper-cli, and the current build/bin/whisper-cli build location are supported. Voice Vault passes a normalized 16 kHz PCM WAV with automatic language detection to whisper.cpp and archives the MP3.

Existing remote configurations also continue to work:

archive_path: ~/recordings
whisper_provider: remote
whisper_base_url: https://whisper.example.com
whisper_api_token: your-token
whisper_model: medium
whisper_diarize: true
whisper_min_speakers: 2
whisper_max_speakers: 5
whisper_open_timeout: 30
whisper_read_timeout: 3600
whisper_write_timeout: 300

Plain transcription uses /v1/audio/transcriptions. Diarization uses the native WhisperX /asr endpoint. Structured responses are retained as result.json and segment arrays as result_cleaned.json.

Optional remote fields remain supported:

• whisper_language
• whisper_prompt
• whisper_hotwords
• whisper_num_speakers
• whisper_min_speakers
• whisper_max_speakers

Speaker-count fields affect only diarized requests. Use either an exact count or minimum/maximum bounds, not both styles together.

For compatibility, omitting whisper_provider still selects remote when whisper_base_url exists and local otherwise.

Replicate is a separate command and is not a valid whisper_provider value.

Voice Vault moves recording.mp3 into its archive before transcription. If a provider fails, Voice Vault exits unsuccessfully, removes incomplete transcription artifacts, and reports the retained recording path. This allows transcription to be retried without losing audio.

Recording and transcript files use owner-only permissions. Imported source files are never modified or removed.

replicate.rb remains available for existing workflows but is deprecated. It still accepts the original options:

./replicate.rb \
  --file_url https://example.com/meeting.mp3 \
  --archive_path ~/recordings/2026-07-15_10-30-00

The replicate_api_token key remains supported in Voice Vault’s config. New setups should use the transcribe provider instead. For compatibility, result_cleaned.json remains a stream of JSON segment objects. A new result_segments.json contains the same cleaned segments as one valid JSON array. Failures now return a nonzero exit status.

• Existing local and remote configuration files require no changes.
• Existing CLI commands and --no-transcription behavior are preserved.
• Existing remote JSON and timestamped transcript artifacts are preserved.
• To adopt WhisperX through transcribe, install it on $PATH and set whisper_provider: transcribe.
• replicate.rb is deprecated but has not been removed.
• Archive directories now avoid timestamp collisions and preserve audio when transcription fails.
• Voice Vault 1.0 is tested with transcribe 1.0. Check versions with ./voice_vault.rb --version and transcribe --version.

See CHANGELOG.md for the complete release notes.

Meeting audio and transcripts can contain sensitive information. The transcribe, remote, and Replicate workflows upload audio to configured services. Review those services’ access controls and retention policies. Use the local provider when audio must remain on the recording machine.

The legacy remote provider accepts plain HTTP for compatibility and does not protect bearer tokens or audio in transit. Use HTTPS whenever traffic leaves a trusted local environment. Keep ~/.config/voice_vault/config.yml mode 0600 because it may contain remote or Replicate API tokens.

Replicate requires a URL reachable by Replicate’s service. Anyone who can access that URL may be able to retrieve the recording; use a short-lived, access-controlled link and revoke it after processing.

ruby test/voice_vault_test.rb
ruby test/replicate_test.rb