Documentation — SamZee Voice

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:

Download the SamZeeVoice.dmg file
Double-click to mount the disk image
Drag SamZee Voice to your Applications folder
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:

Open SamZee Voice Preferences (⌘,)
Click "Voice Commands" tab
Click the "+" button to add a new command
Set the trigger phrase: signature
Set the action: Insert Text
Enter your signature text
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

Install Ollama from ollama.com
Pull a model: ollama pull llama3.2
In SamZee Voice Preferences, enable AI Integration
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:

Create an HTTP command that fetches data
Enable "Chain Response" in the command settings
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

You hold the push-to-talk key
System volume is reduced to 20% (configurable)
You dictate your text
You release the key
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 [email protected] with a description of the problem and any error messages you're seeing. We're here to help!