qUltraKotoro — on-device STT + an emotional QuantTern code (iOS + macOS)
  • Swift 55.4%
  • Rust 40.1%
  • Shell 2.7%
  • Python 1.8%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-11-09 15:24:34 -05:00
.github fix: make signing failures leave a clear signature 2026-10-19 09:29:58 +09:00
scripts feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
Sources feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
src feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
Tests feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
.editorconfig qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00
.gitattributes qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00
.gitignore Default to Pro and add live on-device takes 2026-10-09 17:51:37 +09:00
Cargo.lock feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
Cargo.toml feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
CHANGELOG.md feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
CODE_OF_CONDUCT.md qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00
CONTRIBUTING.md qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00
LICENSE qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00
Package.swift Require local speech recognition and await final transcripts (#2) 2026-10-12 16:46:37 +09:00
PRIVACY.md Require local speech recognition and await final transcripts (#2) 2026-10-12 16:46:37 +09:00
README.md feat(rust): add zero-float Linux/CachyOS kotorocli & QuantTern STT engine, bump to v0.7.0 2026-11-09 15:24:34 -05:00
SECURITY.md qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00
TERMS.md qUltraKotoro v0.1.0 — appified 2026-10-09 06:30:14 +09:00

qUltraKotoro

superwhisper on steroids — on-device STT + an emotional QuantTern code

swift platforms offline-first CI license PRs welcome semver


Table of contents

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 KotoroUI target ships OnboardingView for the first-install flow and SettingsView for everything after that.
  • The offline gate: scripts/check-offline.sh flags 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.