🎙️ Swabble

Speech.framework wake-word hook daemon for macOS 26.

swabble is a Swift 6.2, macOS 26-only rewrite of the brabble voice daemon. It listens on your mic, gates on a wake word, transcribes locally using Apple's new SpeechAnalyzer + SpeechTranscriber, then fires a shell hook with the transcript. No cloud calls, no Whisper binaries.

• Docs: https://swabble.ai/
• Local transcription: Audio stays on-device; macOS may download Apple's speech model assets on first use.
• Wake word: Default clawd (aliases claude), optional --no-wake bypass.
• Hooks: Run any command with prefix/env, cooldown, min_chars, timeout.
• Services: launchd helper stubs for start/stop/install.
• File transcribe: TXT or SRT with time ranges (using AttributedString splits).

Quick start

# Install deps
brew install swiftformat swiftlint

# Build
swift build

# Inspect commands and options
swift run swabble --help

# Write default config (~/.config/swabble/config.json)
swift run swabble setup

# Run foreground daemon
swift run swabble serve

# Test your hook
swift run swabble test-hook "hello world"

# Transcribe a file to SRT
swift run swabble transcribe /path/to/audio.m4a --format srt --output out.srt

Use as a library

Add swabble as a SwiftPM dependency and import the Swabble product to reuse the Speech pipeline, config loader, hook runner, and transcript store in your own app:

// Package.swift
dependencies: [
    .package(url: "https://github.com/openclaw/swabble.git", branch: "main"),
],
targets: [
    .target(name: "MyApp", dependencies: [.product(name: "Swabble", package: "swabble")]),
]

CLI

• serve — foreground loop (mic → wake → hook)
• transcribe <file> — offline transcription (txt|srt)
• test-hook "text" — invoke configured hook
• mic list|set <index> — enumerate inputs and save a preferred device index (live selection not wired yet)
• setup — write default config JSON
• doctor — check Speech auth & device availability
• health — prints ok
• tail-log — last 10 transcripts
• status — show wake state + recent transcripts
• service install|uninstall|status — user launchd plist (stub: prints launchctl commands)
• start|stop|restart — placeholders until full launchd wiring

Use swabble <command> --help for command options. health and status support --json/--json-output; commands that read config support --config where listed.

Config

~/.config/swabble/config.json (auto-created by setup):

{
  "audio": {"deviceName": "", "deviceIndex": -1, "sampleRate": 16000, "channels": 1},
  "wake": {"enabled": true, "word": "clawd", "aliases": ["claude"]},
  "hook": {
    "command": "",
    "args": [],
    "prefix": "Voice swabble from ${hostname}: ",
    "cooldownSeconds": 1,
    "minCharacters": 24,
    "timeoutSeconds": 5,
    "env": {}
  },
  "logging": {"level": "info", "format": "text"},
  "transcripts": {"enabled": true, "maxEntries": 50},
  "speech": {"localeIdentifier": "en_US", "etiquetteReplacements": false}
}

• Config path override: --config /path/to/config.json on relevant commands.
• setup refuses to replace an existing config unless passed --force.
• Config and transcript files are written with owner-only permissions.
• Transcripts persist as JSON lines at ~/Library/Application Support/swabble/transcripts.log.

Hook protocol

When a wake-gated transcript passes min_chars & cooldown, swabble runs:

<command> <args...> "<prefix><text>"

Environment variables:

• SWABBLE_TEXT — stripped transcript (wake word removed)
• SWABBLE_PREFIX — rendered prefix (hostname substituted)
• plus any hook.env key/values

Speech pipeline

• AVAudioEngine tap → BufferConverter → AnalyzerInput → SpeechAnalyzer with a SpeechTranscriber module.
• Requests volatile + final results; wake gating is string match on partial/final.
• Authorization requested at first start; requires macOS 26 + new Speech.framework APIs.

Development

• Format: ./scripts/format.sh (uses ../peekaboo/.swiftformat if present)
• Lint: ./scripts/lint.sh (uses ../peekaboo/.swiftlint.yml if present)
• Tests: swift test (uses swift-testing package)

Roadmap

• launchd control (load/bootout, PID + status socket)
• JSON logging + PII redaction toggle
• Stronger wake-word detection and control socket status/health