- Swift 55.4%
- Rust 40.1%
- Shell 2.7%
- Python 1.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| .github | ||
| scripts | ||
| Sources | ||
| src | ||
| Tests | ||
| .editorconfig | ||
| .gitattributes | ||
| .gitignore | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CODE_OF_CONDUCT.md | ||
| CONTRIBUTING.md | ||
| LICENSE | ||
| Package.swift | ||
| PRIVACY.md | ||
| README.md | ||
| SECURITY.md | ||
| TERMS.md | ||
Table of contents
- What it is
- Features
- Install
- Setup guide
- Usage
- Architecture
- Offline-first
- Security · Privacy
- Versioning
- Roadmap
- Contributing
- License · Citation
What it is
qUltraKotoro — superwhisper on steroids — on-device STT + an emotional QuantTern code. Part of the 8b-is constellation; built to run fully on device.
Features
| 🧠 | See the module docs in Sources/ and the landing site. |
| 🔒 | Offline-first. No networking APIs anywhere in the core; enforced in CI. |
| 📱 | iOS 17+ and macOS 14+. |
| ✅ | Tests pin behaviour; swift test is the contract. |
Install
git clone https://github.com/8b-is/qultrakotoro.git
cd qultrakotoro
swift build
swift test
swift run KotoroMac # run the macOS app directly
scripts/build-mac-app.sh # ...or a real .app bundle
open build/qUltraKotoro.app
swift run kotorocli help # the command-line tool
Add as a dependency:
.package(url: "https://github.com/8b-is/qultrakotoro.git", from: "0.1.0")
Setup guide
Meet Onboarding on first launch: it walks you from a cold install to a working, fully on-device session in a few taps.
- Guided setup: https://setup.vaked.dev — the ELI5, illustrated walkthrough (macOS + iPhone tabs) covering Osaurus, Apple Intelligence, HuggingFace models, Shortcuts, permissions, and offline mode.
- In-app onboarding: the
KotoroUItarget shipsOnboardingViewfor the first-install flow andSettingsViewfor everything after that. - The offline gate:
scripts/check-offline.shflags common networking API names. This is a lint check; the runtime also rejects unavailable local speech models.
Usage
import KotoroCore
// see Sources/KotoroCore for the public surface
Live takes. In the app, hit Live take to capture the headset mic and
transcribe on-device as you go — headset in, same headset out. Tap Stop to
keep the transcript and its QuantTern code. Pro (the default in this build)
removes the 60 s ceiling; takes run up to KotoroAppInfo.maxTakeSeconds. A
noise badge shows the room's level (silence / quiet / ambient / noisy, in
dB) so you can tell whether a take came out clean.
Models
The default engine is Apple's built-in on-device recogniser — no download. For maximum quality with the whisper.cpp engine, fetch the best multilingual model once (this is the only step that ever touches the network, and you run it yourself). One download covers English, Japanese, Chinese (Simplified and Traditional/Taiwan) and best-effort Taiwanese Hokkien:
scripts/fetch-model.sh # ggml-large-v3-turbo, into ./models/
The app keeps its offline-first promise: recognition is on-device, and no audio or text ever leaves the machine.
Command line
kotorocli is the same brain without the window — off-device audio files, emotion
tagging at the prompt, and a live mic take. It is offline-first too.
swift run kotorocli emotion "i love this warm beautiful hope" --json
swift run kotorocli noise recording.wav # level, peak, zcr, class
swift run kotorocli transcribe recording.wav --locale ja-JP
swift run kotorocli live 30 --locale zh-TW # 30 s headset take
| Command | What it does |
|---|---|
emotion <text> |
VAD + QuantTern code (--json for machines) |
noise <audio> |
noise profile: level, peak, zero-crossing rate, class |
transcribe <audio> |
on-device file transcription + emotion code |
live [seconds] |
mic take, streaming text and a live noise badge |
engines · locales |
list the STT engines and language tags |
Architecture
qultrakotoro/
├── Package.swift
├── Sources/KotoroCore/ # the library (offline-first core)
├── Sources/KotoroUI/ # SwiftUI: Onboarding, Transcribe, Settings
├── Sources/KotoroMac/ # macOS app shell (swift run KotoroMac)
├── Sources/KotoroIOS/ # iOS app shell (Xcode / SwiftPM iOS build)
├── Sources/KotoroCLI/ # command-line tool (swift run kotorocli)
├── Tests/ # swift test
├── scripts/check-offline.sh# the offline-first gate (runs in CI)
└── .github/ # templates, CODEOWNERS, CI
Offline-first
qUltraKotoro must work with the network off. The gate scripts/check-offline.sh scans
Sources/ for networking APIs (URLSession, URLRequest, NWConnection,
import Network) and fails the build if any appear. This scan is a lint check, not a privacy sandbox or proof of framework behavior. See PRIVACY.md.
Security
See SECURITY.md for how to report a vulnerability. Do not open a public issue for security problems.
Privacy
See PRIVACY.md. In one line: speech requests require an available on-device model; external links use your browser.
Versioning
Semantic Versioning. The current version is 0.7.0 — see
CHANGELOG.md. Releases are tagged v0.7.0.
Roadmap
See the issues and the CHANGELOG.
Contributing
See CONTRIBUTING.md and the Code of Conduct. Small, tested PRs are the fastest path.
License
Apache-2.0 © the 8b-is constellation.
Citation
@software{qultrakotoro,
title = {qUltraKotoro},
author = {8b-is},
year = {2026},
url = {https://github.com/8b-is/qultrakotoro}
}
Recognition readiness
Live and file recognition currently use Apple Speech only, and require an installed on-device model for the requested language. If local recognition is unsupported or unavailable, the request fails instead of permitting cloud fallback. Permission denial, recognition errors, and final-result timeouts are reported explicitly. Stop waits up to ten seconds for the final live transcript.
The Tag demo text action demonstrates emotion tagging of text you type; it
is not audio transcription. Whisper, Parakeet, and Osaurus adapters are not
integrated. fetch-model.sh downloads a file but does not enable these engines.
The emotion tagger is an English word-list heuristic, not a learned emotion model.
The offline source scan is a lint check, not proof of framework behavior or a sandbox. Real-device offline recognition must also be tested for each supported language before release. Synthetic regression tests cover local-only eligibility, final-result/error/timeout/cancellation handling, and audio-level calculations.