---
icon: lucide/radio
---

# transcribe-daemon

A continuous background transcription service with voice activity detection (VAD).

## Usage

```bash
agent-cli transcribe-daemon [OPTIONS]
```

## Description

Runs as a daemon, listening to your microphone and automatically segmenting speech using voice activity detection:

1. Starts listening immediately
2. Detects when you start and stop speaking
3. Automatically transcribes each speech segment
4. Logs results with timestamps
5. Optionally saves audio as MP3 files

Press `Ctrl+C` to stop the daemon.

Segments shorter than 0.3s are discarded even if `--min-segment` is set lower.
Saving MP3 files requires FFmpeg; if it's not available, audio saving is disabled with a warning.

## Installation

Requires the `vad` extra:

```bash
uv tool install "agent-cli[vad]" -p 3.13
# or
pip install "agent-cli[vad]"
```

## Examples

```bash
# Basic daemon
agent-cli transcribe-daemon

# With custom role
agent-cli transcribe-daemon --role meeting

# With LLM cleanup
agent-cli transcribe-daemon --llm

# Custom silence threshold
agent-cli transcribe-daemon --silence-threshold 1.5
```

## Options

<!-- CODE:START -->
<!-- from agent_cli.docs_gen import all_options_for_docs -->
<!-- print(all_options_for_docs("transcribe-daemon")) -->
<!-- CODE:END -->
<!-- OUTPUT:START -->
<!-- ⚠️ This content is auto-generated by `markdown-code-runner`. -->
### Options

| Option | Default | Description |
|--------|---------|-------------|
| `--role` | `user` | Role name for logging (e.g., 'meeting', 'notes', 'user'). |
| `--silence-threshold` | `1.0` | Seconds of silence to end a speech segment. |
| `--min-segment` | `0.25` | Minimum speech duration in seconds to trigger a segment. |
| `--vad-threshold` | `0.3` | VAD speech detection threshold (0.0-1.0). Higher = more aggressive filtering. |
| `--save-audio/--no-save-audio` | `true` | Save audio segments as MP3 files. |
| `--audio-dir` | - | Directory for MP3 files. Default: ~/.config/agent-cli/audio |
| `--transcription-log` | - | JSON Lines log file path. Default: ~/.config/agent-cli/transcriptions.jsonl |
| `--clipboard/--no-clipboard` | `false` | Copy each transcription to clipboard. |

### Provider Selection

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-provider` | `wyoming` | The ASR provider to use ('wyoming', 'openai', 'gemini'). |
| `--llm-provider` | `ollama` | The LLM provider to use ('ollama', 'openai', 'gemini'). |

### Audio Input

| Option | Default | Description |
|--------|---------|-------------|
| `--input-device-index` | - | Index of the audio input device to use. |
| `--input-device-name` | - | Device name keywords for partial matching. |
| `--list-devices` | `false` | List available audio input and output devices and exit. |

### Audio Input: Wyoming

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-wyoming-ip` | `localhost` | Wyoming ASR server IP address. |
| `--asr-wyoming-port` | `10300` | Wyoming ASR server port. |

### Audio Input: OpenAI-compatible

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-openai-model` | `whisper-1` | The OpenAI model to use for ASR (transcription). |
| `--asr-openai-base-url` | - | Custom base URL for OpenAI-compatible ASR API (e.g., for custom Whisper server: http://localhost:9898). |
| `--asr-openai-prompt` | - | Custom prompt to guide transcription (optional). |

### Audio Input: Gemini

| Option | Default | Description |
|--------|---------|-------------|
| `--asr-gemini-model` | `gemini-3-flash-preview` | The Gemini model to use for ASR (transcription). |

### LLM: Ollama

| Option | Default | Description |
|--------|---------|-------------|
| `--llm-ollama-model` | `gemma3:4b` | The Ollama model to use. Default is gemma3:4b. |
| `--llm-ollama-host` | `http://localhost:11434` | The Ollama server host. Default is http://localhost:11434. |

### LLM: OpenAI-compatible

| Option | Default | Description |
|--------|---------|-------------|
| `--llm-openai-model` | `gpt-5-mini` | The OpenAI model to use for LLM tasks. |
| `--openai-api-key` | - | Your OpenAI API key. Can also be set with the OPENAI_API_KEY environment variable. |
| `--openai-base-url` | - | Custom base URL for OpenAI-compatible API (e.g., for llama-server: http://localhost:8080/v1). |

### LLM: Gemini

| Option | Default | Description |
|--------|---------|-------------|
| `--llm-gemini-model` | `gemini-3-flash-preview` | The Gemini model to use for LLM tasks. |
| `--gemini-api-key` | - | Your Gemini API key. Can also be set with the GEMINI_API_KEY environment variable. |

### LLM Configuration

| Option | Default | Description |
|--------|---------|-------------|
| `--llm/--no-llm` | `false` | Use an LLM to process the transcript. |

### Process Management

| Option | Default | Description |
|--------|---------|-------------|
| `--stop` | `false` | Stop any running background process. |
| `--status` | `false` | Check if a background process is running. |

### General Options

| Option | Default | Description |
|--------|---------|-------------|
| `--log-level` | `WARNING` | Set logging level. |
| `--log-file` | - | Path to a file to write logs to. |
| `--quiet` | `false` | Suppress console output from rich. |
| `--config` | - | Path to a TOML configuration file. |
| `--print-args` | `false` | Print the command line arguments, including variables taken from the configuration file. |


<!-- OUTPUT:END -->

## Output Files

### Transcription Log

JSON Lines format at `~/.config/agent-cli/transcriptions.jsonl`:

```json
{"timestamp": "2024-01-15T10:30:45+00:00", "hostname": "my-host", "role": "user", "model": "wyoming", "raw_output": "Hello world", "processed_output": null, "audio_file": "/path/to/audio.mp3", "duration_seconds": 1.23}
```

`processed_output` is null when `--llm` is disabled.

### Audio Files

Organized by date at `~/.config/agent-cli/audio/YYYY/MM/DD/*.mp3`

## Use Cases

### Meeting Notes

```bash
agent-cli transcribe-daemon --role meeting --silence-threshold 2.0
```

### Personal Notes

```bash
agent-cli transcribe-daemon --role notes --llm
```

### Background Logging

```bash
agent-cli transcribe-daemon --no-clipboard &
```
