# OpenVoiceEverything: local CLI and agent guide

Availability: the personal installer has passed verification; public download
delivery is pending source-package and license review. No downloadable installer
is advertised by this site yet. The verified personal build is for macOS 15.0+
on Apple silicon, ad-hoc signed and not notarized. macOS may show a security
warning. Updates are manual; do not assume a notarized public release or automatic
update support.

OpenVoiceEverything supports two workflows:
- Dictation through a user-selected keyboard shortcut or mouse button, followed
  by insertion into the previously focused editable field.
- File transcription through a CLI that talks to the running app on the SAME Mac.

Do not attempt to run the macOS app on Linux or send paths from a remote agent
host. The app must be able to read every source path and temporary converted file.

## Prerequisites

1. Install and open a verified OpenVoiceEverything package when available.
2. Complete onboarding and select a speech model. Download it in the app if
   required. Health means API availability, not model readiness.
3. Use Python 3.9 or later for the bundled CLI.
4. Enable the local API with the bundled helper. It is disabled until enabled.
5. Optional: install ffmpeg separately and make it available on PATH for more
   containers/codecs. No remote install script is required by this guide.

The app's local API listens on loopback at http://127.0.0.1:47733 by default.
It is for trusted local agents/scripts running as the same user. Do not expose it
to a public interface. The CLI bypasses HTTP proxy variables for these requests.

## Use the bundled CLI directly

python3 --version
"/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" --help
"/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" ensure
"/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" health
"/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" settings
"/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" transcribe --help

If the app was already running with the API disabled, use "ensure --restart".
Do not use "ensure --force-restart" unless the user permits force-quitting it.
Inspect settings.selectedSpeechModel.installed before a batch. The first request
may take longer while the selected model loads. Resolve model preparation errors
in the app, then rerun the same batch to preserve completed outputs.

For a nondefault port, place --port BEFORE the command and use it consistently:
"/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" --port 47734 health

Optionally expose the command under ~/.local/bin:

mkdir -p "$HOME/.local/bin"
ln -s "/Applications/OpenVoiceEverything.app/Contents/Helpers/ove-agent" "$HOME/.local/bin/ove-agent"
export PATH="$HOME/.local/bin:$PATH"

The symlink command does not replace an existing command. Add the PATH line to
the user's shell configuration if they want it to persist.

## Plan first, then transcribe

ove-agent transcribe ~/Videos -r --dry-run
ove-agent transcribe ~/Videos -r
ove-agent transcribe ~/Videos -r --output-dir ~/Transcripts
ove-agent transcribe ~/Videos -r --format json
ove-agent transcribe "/path/to/My Videos" /path/to/interview.wav -r

--dry-run plans inputs/outputs without contacting the app or writing files.
-r/--recursive includes subfolders; directory symlinks are not followed. Each
input is processed once, sequentially. The CLI's default preset is "current",
using the selected speech model. Inspect settings.fileTranscriptionPresets before
choosing another preset: some require more models or Apple silicon.

Outputs use original stems: meeting.mov becomes meeting.txt or meeting.json.
--output-dir mirrors relative paths beneath the destination folder.
Existing outputs are SKIPPED by default so rerunning the same command resumes.
--overwrite explicitly replaces transcript outputs. Input media is protected.

Same-stem media targeting the same folder retain extensions to avoid collisions:
clip.mp4 -> clip.mp4.txt and clip.wav -> clip.wav.txt.
Ambiguous destinations across different input roots, including case or Unicode
normalization collisions, fail BEFORE transcription. Split such roots into
separate runs or save beside each source. Output symlinks and input hard links
are protected. Writes publish complete files atomically; failed transcription
leaves an earlier transcript intact.

## Native decoding and optional ffmpeg

ove-agent capabilities
ove-agent transcribe ~/Videos -r --ffmpeg always

capabilities.supportedFileExtensions describes the current Mac's native decoder.
Common MP4/MOV and WAV/MP3/M4A can decode natively; actual support depends on the
audio codec inside the container.

--ffmpeg auto (default): normalize MKV/WebM/AVI and selected other containers
through optional ffmpeg, using a private temporary 16 kHz mono WAV on disk.
--ffmpeg always: normalize every input, useful for uncommon native-container codecs.
--ffmpeg never: pass each source directly to the app's native decoder.

Conversion uses the first audio track, preserves leading gaps, and cleans up the
temporary file. Outputs and app history keep the original media filename. Missing
ffmpeg, missing audio tracks, or decode errors become per-file errors and other
files continue. The CLI does not silently switch speech providers.

## Output contract for scripts and agents

transcribe writes ONE JSON summary to stdout after a completed run. It sends
progress/readable diagnostics to stderr. --quiet suppresses those diagnostics.
Transcript content goes into output files, keeping stdout small. Summary paths
are absolute. Treat this as an illustrative summary shape, not a real result:

{
  "schemaVersion": 1,
  "command": "transcribe",
  "files": [
    {
      "input": "/Users/me/Videos/clip.mp4",
      "output": "/Users/me/Videos/clip.txt",
      "status": "written",
      "convertedWithFfmpeg": false,
      "characterCount": 27,
      "preset": "current"
    }
  ],
  "counts": {
    "total": 1, "written": 1, "skipped": 0,
    "failed": 0, "planned": 0, "unprocessed": 0
  }
}

Per-file status: written, skipped, failed, or planned.
Skipped entries include reason: "output_exists". Failed entries include error.
Planning errors have a top-level error and an empty files array. --dry-run reports
planned paths and whether outputs already exist. --format json saves the API
response plus the original absolute input path; result.text and available
timestamps/confidence/duration/speaker metadata are preserved.

Exit codes:
0: all files written/skipped, or a successful dry-run plan.
1: planning error or at least one per-file/API failure; inspect the JSON.
2: invalid arguments; usage is on stderr.
130: user interruption; completed files remain available for resume.

Failures normally do not stop a batch. --fail-fast stops at the first failure and
counts remaining inputs as unprocessed. --timeout is a positive per-API-request
and per-ffmpeg-conversion limit in seconds (default 7200). A timed-out API request
may still be finishing in the app: wait before retrying. An interrupted command
may exit before its final summary. Rerun the same command to skip completed files.

## Recommended agent task

Use the bundled OpenVoiceEverything CLI on this Mac to transcribe every
audio/video in the supplied folder recursively. Inspect transcribe --help and
settings, then present the --dry-run plan. Save text beside each source with the
same stem, preserve existing outputs, and report JSON counts plus failed inputs.
Use ffmpeg for containers/codecs the native decoder cannot read.

## Dictation setup

Grant Microphone and Accessibility access in onboarding. Choose the primary
dictation shortcut in Settings -> Shortcuts -> Primary dictation. Activation Mode
in Settings -> Dictation supports Toggle, Hold, or Automatic (Both). Focus an
editable field, use the shortcut, speak, and stop. Clipboard Paste uses a temporary
clipboard entry and restores the previous clipboard after delivery. Optional Copy
to Clipboard keeps a backup. File batches do not paste or modify the clipboard;
the transcribe-file command can opt in with --copy.

## Website release state

The same-origin /release.json is the download configuration. Pending/absent/invalid
configuration must not enable a download. A ready entry requires an actual verified
installer and corresponding source archive under the same-origin /downloads/ path,
with SHA-256 checksums for both. The program is licensed under GNU GPLv3; see
/license.txt. The source archive is not published while release state is pending. Do not
invent a URL, treat a CI artifact as public delivery, or enable downloads before
verification and Hetzner publication. This guide contains no remote executable
installer command.