README.md

Nocturne

A 100% local, private, and zero-latency voice dictation client for macOS.
Inspired by Wispr Flow. Powered by CoreML, Apple Neural Engine, and embedded Ollama.

---

What is Nocturne?

Nocturne brings the magic of smart voice dictation directly to your macOS cursor, running entirely on-device. By holding down a single hotkey (default: Fn), you can dictate text in any active macOS application. Upon release, Nocturne transcribes your speech, leverages local AI to clean up filler words and grammar, and inserts the result instantly.

No cloud, no API keys, no subscriptions. Just pure, private dictation.

---

Why Nocturne?

Unlike cloud-based alternatives that upload your voice recordings to third-party servers, Nocturne does not send a single byte to the internet.

• Private: Your recordings, transcripts, dictionary terms, and history are saved strictly on your local disk.
• Zero Configuration for LLM: Features a built-in, self-managed Ollama server that automatically installs, runs, and downloads models in the background.
• High Performance: Transcription runs natively on Apple Silicon Neural Engine via CoreML for near-instant latency.

---

Key Features

• Local ASR (Speech-to-Text): Runs the Parakeet TDT 0.6B v3 model natively on CoreML for ultra-low latency transcribing. Autodetects 25 languages.
• Self-Managed Ollama: Automatically sets up and runs an internal Ollama instance. Download and switch between models (Qwen 3.5 (4B), Qwen 2.5 (3B), Qwen 2.5 (0.5B), Qwen 2.5 (7B)) directly inside the Settings tab.
• Apple Intelligence Integration: Option to run text polishing using native macOS local Foundation Models with zero downloads.
• System-Wide Text Transforms: Select any text in any Mac application and hit Option + 1 (Polish) or Option + 2 (Prompt Engineer) to rewrite or format it instantly. Custom prompts can be defined in the dashboard.
• Personal Vocabulary Dictionary: Prevent spelling mistakes by defining replacement rules (e.g. mapping jon to John or get user data to getUserData).
• Custom Voice Snippets: Set up shorthand voice shortcuts (e.g., dictate "my email" to instantly write "you@example.com").
• Dark Mode Dashboard: Track average Words Per Minute (WPM), day streaks, application usage, review history, write notes in the scratchpad, and chat with the Help AI.
• Localized UI: Native, high-quality translations for 12 languages (English, Spanish, French, German, Italian, Portuguese, Chinese, Japanese, Korean, Russian, Hindi, Arabic).

---

How it Works

graph TD
    A[Hold Trigger Key] --> B(Capture Microphone Audio)
    B --> C{CoreML Parakeet Engine}
    C -->|Local Transcription| D[Raw Text]
    D --> E{Selected Post-Processor}
    E -->|Rules Mode| F[Deterministic Regex Cleanup]
    E -->|AI Mode| G[Embedded Ollama / Apple Intelligence]
    E -->|Literal Mode| H[Bypass Cleanup]
    F --> I[Final Text]
    G --> I
    H --> I
    I --> J[Simulate Keystrokes / Paste]
    J --> K[Text Inserted at Cursor]

Loading

---

Gestures and Shortcuts

Gesture	Action
Hold Fn	Push-to-Talk: Record while held. Solt to transcribe and insert.
Fn + Space	Hands-Free Mode: Starts recording. Press Fn again to stop.
Hold Shift while recording	Literal Mode: Bypasses AI polishing and inserts raw transcription.
Say "assistant..." or "oye ia..."	Directs the AI to output an answer to your question instead of transcribing.

Note: The trigger key can be customized to right-Option, right-Command, right-Control, F13-F19, etc., in Settings.

---

Prerequisites and Setup

1. macOS Version: macOS 14+ is required.
2. Configure Keyboard Key: Go to System Settings -> Keyboard. Under "Press fn key to...", set it to "Do Nothing" to prevent macOS emoji/native dictation popups from interfering.
3. Permissions: Grant Microphone and Accessibility access when prompted on startup.

---

Installation

Method 1: Download Precompiled App

Go to Releases, download Nocturne.zip, unzip it, and drag Nocturne.app into your /Applications folder.

Note: Since it is not notarized by Apple, you must bypass macOS Gatekeeper on first launch:

• Right-click the app, select Open, and click Open again.
• Or go to System Settings -> Privacy & Security and click "Open Anyway".

Method 2: Compile from Source

To compile Nocturne locally on your machine:

# Run CLI transcription smoke test
make cli

# Compile, sign and run Nocturne
make run

# Install to /Applications
make install

---

Contributing

Contributions are welcome! Feel free to open issues or submit pull requests. If you like this project, please consider giving it a ⭐!

License

This project is licensed under the MIT License - see the LICENSE file for details.