Documentation

SamZee Voice Docs

Learn how to turn speech into action. Everything you need to get started with voice automation on your M-Series Mac.

Introduction

SamZee Voice is a powerful voice automation tool for macOS (Apple Silicon M-Series) that goes beyond simple dictation. It lets you:

  • Dictate text anywhere on your M-Series Mac with system-wide push-to-talk
  • Trigger custom voice commands that run actions
  • Integrate with local AI models (Ollama) for text processing
  • Send data to HTTP endpoints and chain responses
  • Run shell commands using voice triggers
  • Use Smart Volume Ducking for clean dictation
New to Voice Automation?

Start with basic dictation, then gradually add voice commands as you get comfortable. The power is in the customization—build workflows that match exactly how you work.

Installation

System Requirements

  • macOS 14.0 (Sonoma) or later
  • Apple Silicon Mac (M1, M2, M3, M4, M5)
  • Microphone access (built-in or external)
  • ~465MB disk space (includes all language models)

Download & Install

After purchasing, you'll receive a download link via email. The installation process is straightforward:

  1. Download the SamZeeVoice.dmg file
  2. Double-click to mount the disk image
  3. Drag SamZee Voice to your Applications folder
  4. Launch the app and grant necessary permissions
Permissions Required

SamZee Voice requires Accessibility and Microphone permissions to function. You'll be prompted to grant these on first launch. Go to System Preferences → Security & Privacy → Privacy to manage these permissions.

Quick Start

Once installed, getting started takes just a few steps:

1. Set Your Push-to-Talk Key

By default, SamZee Voice uses ⌥ Option (Alt) as the push-to-talk key. Hold it down to start dictating, release to stop. You can change this in Preferences.

2. Try Basic Dictation

Open any text field (Notes, Safari, your code editor), hold the push-to-talk key, and speak. Your words will appear where your cursor is.

3. Explore Voice Commands

SamZee Voice comes with several built-in commands. Try saying:

$ "new line" # Inserts a line break $ "period" # Types a period $ "comma" # Types a comma $ "delete that" # Deletes last phrase

Your First Command

Let's create a custom voice command that inserts your email signature:

  1. Open SamZee Voice Preferences (⌘,)
  2. Click "Voice Commands" tab
  3. Click the "+" button to add a new command
  4. Set the trigger phrase: signature
  5. Set the action: Insert Text
  6. Enter your signature text
  7. Click Save

Now whenever you say "signature" while dictating, your signature will be inserted automatically.

Dictation

SamZee Voice provides system-wide dictation that works in any app. Unlike macOS built-in dictation, it uses push-to-talk for precise control.

Push-to-Talk

Hold your configured key (default: ⌥ Option) to start recording. Release to stop. This gives you precise control over when you're dictating.

Dictation Modes

Mode Description Best For
Standard Balanced accuracy and speed General use
Fast Lower latency, slightly less accurate Quick notes
Accurate Higher accuracy, more latency Important documents

Voice Commands

Voice commands are the heart of SamZee Voice. They let you trigger actions by speaking specific phrases.

Command Types

Type Description Example
Insert Text Types predefined text "signature" → inserts email signature
Run Shortcut Executes macOS Shortcuts "create reminder" → runs shortcut
Shell Command Runs terminal commands "deploy site" → runs deploy script
HTTP Request Calls API endpoints "log to notion" → POST to API
AI Rewrite Processes text with local LLM "rewrite formal" → formal tone

Creating Commands

Commands are created in the Preferences window. Each command has:

  • Trigger Phrase: What you say to activate it
  • Action Type: What kind of action to perform
  • Action Details: Configuration for the action
  • Context: When the command is active (global or app-specific)

AI Integration

SamZee Voice integrates with local AI models through Ollama, giving you powerful text processing without sending data to the cloud.

Setting Up Ollama

  1. Install Ollama from ollama.com
  2. Pull a model: ollama pull llama3.2
  3. In SamZee Voice Preferences, enable AI Integration
  4. Select your Ollama model

AI Commands

Once configured, you can create AI-powered commands:

# Example: "rewrite formal" Prompt: Rewrite the following text in a formal, professional tone. Maintain the meaning but use business-appropriate language. Text: $VOICE_INPUT Response handling: Replace selected text

The $VOICE_INPUT variable contains the text you've selected or just dictated.

Pro Tip

Create multiple AI commands with different prompts: "rewrite casual", "summarize this", "make it shorter", "fix grammar". Customize each for your specific needs.

API Workflows

Connect SamZee Voice to any service with an HTTP API. Perfect for logging, creating tasks, or triggering webhooks.

HTTP Command Configuration

# Example: Log to Notion Method: POST URL: https://api.notion.com/v1/pages Headers: Authorization: Bearer $NOTION_TOKEN Notion-Version: 2022-06-28 Content-Type: application/json Body: { "parent": { "database_id": "your-db-id" }, "properties": { "Name": { "title": [{ "text": { "content": "$VOICE_INPUT" } }] } } }

Response Chaining

You can use the response from an HTTP request in a follow-up action:

  1. Create an HTTP command that fetches data
  2. Enable "Chain Response" in the command settings
  3. Configure the follow-up action to use $HTTP_RESPONSE
# Example: Weather lookup # Command 1: "what's the weather" HTTP Request: GET https://api.weather.com/v1/current Chain Response: Insert Text Text: The weather is $HTTP_RESPONSE.temperature° and $HTTP_RESPONSE.condition

Shell Automation

For developers and power users, shell commands unlock unlimited possibilities. Trigger any script or CLI tool with your voice.

Basic Shell Command

# Command: "deploy site" Command: cd ~/projects/my-site && ./deploy.sh Working Directory: ~/projects/my-site Show Output: Notification

Using Voice Input

Pass dictated text to your scripts using environment variables:

# Command: "git commit" Command: git commit -m "$VOICE_INPUT" Working Directory: $ACTIVE_PROJECT # Usage: Hold PTT, say "git commit", say "fix login bug", release PTT # Result: git commit -m "fix login bug"

Available Environment Variables

Variable Description
$VOICE_INPUT The text you just dictated
$ACTIVE_APP Bundle ID of the frontmost app
$ACTIVE_PROJECT Path to active project (if detected)
$CLIPBOARD Current clipboard contents

Smart Volume Ducking

Smart Volume Ducking automatically lowers your system volume while you're dictating, then restores it when you're done. This ensures clean voice capture even when music or videos are playing.

How It Works

  1. You hold the push-to-talk key
  2. System volume is reduced to 20% (configurable)
  3. You dictate your text
  4. You release the key
  5. Volume is restored to previous level

Configuration

In Preferences → Audio:

  • Enable Smart Ducking: Toggle on/off
  • Duck Level: Volume level during dictation (default: 20%)
  • Fade Duration: How quickly volume changes (default: 200ms)
  • Exclude Apps: Apps that should never be ducked (e.g., FaceTime)
Pro Tip

Add video conferencing apps (Zoom, FaceTime, Teams) to the exclude list so your call volume never gets reduced during dictation.

Command Reference

Built-in Commands

Command Action
new line Press Return
new paragraph Press Return twice
period / dot Type "."
comma Type ","
question mark Type "?"
exclamation mark Type "!"
colon Type ":"
semicolon Type ";"
open quote / close quote Type """ or """
open bracket / close bracket Type "[" or "]"
open paren / close paren Type "(" or ")"
delete that Delete last phrase
undo that Press ⌘Z
capitalize that Capitalize last word
all caps that Uppercase last word

Configuration

SamZee Voice stores its configuration in ~/.config/samzee-voice/. You can edit the JSON config file directly or use the Preferences UI.

Config File Location

$ ~/.config/samzee-voice/config.json

Key Settings

Setting Description Default
pushToTalkKey Key to hold for dictation "option"
dictationMode Standard, Fast, or Accurate "standard"
smartDucking.enabled Enable volume ducking true
smartDucking.level Volume % during dictation 0.2
ai.enabled Enable Ollama integration false
ai.model Ollama model name "llama3.2"
ai.host Ollama server URL "http://localhost:11434"

Keyboard Shortcuts

Shortcut Action
⌥ Option (hold) Push-to-talk (configurable)
⌘, Open Preferences
⌘⇧P Pause/Resume SamZee
⌘⇧M Mute/Unmute microphone
⌘⇧D Toggle dictation mode
⌃⌥⌘R Reload configuration

Troubleshooting

Common Issues

SamZee Voice isn't responding

  • Check that SamZee Voice is running (look for the icon in the menu bar)
  • Verify Accessibility permissions in System Preferences
  • Try restarting the app
  • Check if another app is using the push-to-talk key

Dictation isn't working

  • Check Microphone permissions in System Preferences
  • Test your microphone in another app (Voice Memos)
  • Try a different dictation mode in Preferences
  • Restart your M-Series Mac (sometimes macOS speech services need a reset)

AI integration not working

  • Verify Ollama is running: curl http://localhost:11434/api/tags
  • Check that the model is downloaded: ollama list
  • Try a smaller/faster model if responses are slow
  • Check SamZee Voice logs for error messages

Volume ducking not working

  • Ensure Smart Ducking is enabled in Preferences → Audio
  • Check that the current app isn't in the exclude list
  • Some apps (like Spotify) may require additional permissions
Still having issues?

Email us at support@samplezero.dev with a description of the problem and any error messages you're seeing. We're here to help!