whisper-macos-cli 0.1.2

Transcribe audio files locally on Apple Silicon via whisper.cpp with Metal GPU acceleration, exposing a strict stdin/stdout JSON contract for AI agents and Unix pipelines.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130

[English version](AGENTS.md) | [Versão em Português Brasileiro](AGENTS.pt-BR.md)

# AGENTS — Agent Integration Guide

This document is written for AI agents and orchestration tools that
need to invoke whisper-macos-cli as a black-box transcription service.

## Contract

- One JSON object per file on stdout
- correlation_id is a UUID v7 generated per process invocation
- schema_version reflects the envelope version
- stderr carries tracing logs that can be suppressed with --quiet
- exit codes follow sysexits.h convention

## JSON Output Envelope

```json
{
  "schema_version": "0.1.0",
  "correlation_id": "0190a3b4-7c8d-7abc-9def-1234567890ab",
  "file": "voice.ogg",
  "language": "pt",
  "language_source": "os_locale",
  "model": "large-v3",
  "duration_seconds": 45.2,
  "text": "Full transcription text here",
  "vad_chunks": 3,
  "processing_time_ms": 8432
}
```

## Error Envelope

```json
{
  "schema_version": "0.1.0",
  "error": true,
  "code": 66,
  "message": "input not found: /tmp/missing.ogg",
  "category": "input",
  "retryable": false,
  "retry_after_ms": null,
  "hint": "check the file path and try again",
  "docs_url": "https://github.com/daniloaguiarbr/whisper-macos-cli/blob/main/docs/TROUBLESHOOTING.md",
  "correlation_id": "0190a3b4-7c8d-7abc-9def-1234567890ab"
}
```

## Quickstart for Agents

```bash
# 30-second setup
cargo install whisper-macos-cli
whisper-macos-cli models download

# Transcribe audio
whisper-macos-cli transcribe voice.ogg

# Transcribe video (requires ffmpeg)
brew install ffmpeg
whisper-macos-cli transcribe video.mp4
```

## Token Budget

- Invocation overhead: 200 tokens (envelope parsing)
- Per-file transcription: 50 tokens + transcribed text length
- Error handling: 100 tokens

## Exit Codes

| Code | Meaning                                  | Retryable |
|------|------------------------------------------|-----------|
| 0    | Success                                  | n/a       |
| 2    | Usage error                              | no        |
| 64   | No input provided                        | no        |
| 65   | Invalid audio/video data                 | no        |
| 66   | Input file not found                     | no        |
| 69   | Service unavailable (ffmpeg missing)     | yes       |
| 70   | Inference error                          | no        |
| 74   | I/O error                                | no        |
| 78   | Configuration error                      | no        |
| 130  | SIGINT (Ctrl+C)                          | no        |
| 141  | Broken pipe                              | no        |
| 143  | SIGTERM                                  | no        |

## Video Transcription (v0.1.2+)

Since v0.1.2, whisper-macos-cli supports video containers
(MP4, MOV, M4V, MKV, WebM, AVI) by extracting the audio track
via ffmpeg subprocess. Requires ffmpeg 4.0+ on PATH.

```bash
whisper-macos-cli transcribe video.mp4
```

OGG/Opus WhatsApp audio that fails the native decoder is
automatically re-routed via ffmpeg as a transparent fallback.

See [docs/VIDEO-EXTRACTION.md](docs/VIDEO-EXTRACTION.md) for full
details.

## Subcommands for Agent Discovery

```bash
# Full command tree as JSON
whisper-macos-cli commands --format json

# Full JSON Schema of output envelope
whisper-macos-cli schema

# Effective configuration
whisper-macos-cli config

# Self-describing skill scaffold
whisper-macos-cli init --target /path/to/agent/workspace
```

## Compatible AI Agents

Claude Code, OpenCode, Codex CLI, Gemini CLI, Cline, Cursor,
Windsurf, Aider, Continue, Cody, Tabnine, Replit Agent. Full list
in [INTEGRATIONS.md](INTEGRATIONS.md).

## Documentation for Deep Integration

See [docs/AGENTS.md](docs/AGENTS.md) for the complete agent-author
guide including agent integration patterns, crate-level contracts,
and CRUD operations.