Getting Started

Everything you need to install, configure, and start using Samsara.

Installation

Requirements

• Windows 10 or 11
• Python 3.10+ (if running from source)
• A microphone (USB, headset, or built-in)
• Optional: NVIDIA GPU with CUDA for faster transcription
• Optional: Ollama installed for Ava voice assistant

Download

Download the latest release from GitHub Releases:

• Samsara-Windows-v0.9.9.7z — CPU version, works on any machine
• Samsara-CUDA-Pack-v0.9.9.zip — Optional GPU acceleration (extract into the same folder)

From Source

git clone https://github.com/Morne-Ingstar/Samsara.git
cd Samsara
pip install -r requirements.txt
python dictation.py

First Run

On first launch, a setup wizard walks you through:

• Selecting your microphone
• Choosing a Whisper model size (small.en recommended for most users)
• Setting your record hotkey (default: Ctrl+Shift, hold to talk)
• Choosing a wake word (default: "Jarvis")
• Configuring streaming dictation hotkey (default: CapsLock)

All settings can be changed later from the Settings window.

Basic Usage

Push-to-Talk Dictation

Hold Ctrl+Shift and speak. Release when done. Your speech is transcribed and pasted at the cursor position.

Wake Word Commands

Say your wake word (default: "Jarvis") followed by a command. For example:

• "Jarvis, open Chrome"
• "Jarvis, scroll down"
• "Jarvis, take a screenshot"
• "Jarvis, mute"

Samsara listens for the wake word passively. When it hears it, it captures the following command and executes it.

Streaming Dictation

Press CapsLock to start streaming mode. Speak continuously — text appears in real time as you talk. Press CapsLock again to stop.

Voice Modes

Samsara has six voice modes. All can run simultaneously — wake word mode and continuous mode share a single audio stream internally, so there are no conflicts.

All hotkeys are configurable in Settings. See the Hotkeys & Modes section for details on each.

Settings

Samsara's settings are organised into eight tabs. Open settings from the system tray icon or say "Jarvis, open settings."

General

Hotkeys & Modes

All hotkeys are configurable in Settings. This table shows the defaults.

Wake Word Configuration

Command Mode

A walkie-talkie style mode. Hold the button, speak a command, release to execute. Ideal for rapid command sequences without saying the wake word each time.

Commands

The Commands tab lets you browse, enable, and disable command packs. Each pack is a named group of related commands.

Sounds

Text-to-Speech

Samsara can speak. TTS is used by Ava for responses, and optionally for confirmations and status updates.

TTS Categories

Control which types of speech Samsara produces:

Audio Coordinator

The AudioCoordinator manages the relationship between TTS, your microphone, and background audio:

• Ducking — lowers mic sensitivity while Samsara is speaking, preventing echo
• Interrupt — if you start talking while Samsara is speaking, TTS stops immediately
• Pre-buffer discard — audio captured during TTS is discarded, so Samsara doesn't transcribe its own voice

Alarms

Configurable reminders for health and productivity. Built for people who need regular prompts to move, stretch, hydrate, or rest their eyes.

Built-in Alarms

• Hydration — every 60 minutes. "Time to drink some water."
• Break — every 45 minutes. "Take a short break — stretch and rest your eyes."
• Stretch — every 120 minutes. "Time to stretch your hands, wrists, and neck."
• 20-20-20 Rule — every 20 minutes. "Look at something 20 feet away for 20 seconds."

Smart Actions

Smart Actions allow Samsara to interact with external services through a webhook bridge.

Advanced

Ava Voice Assistant

Ava is Samsara's built-in AI assistant. She runs on a local LLM (phi3.5 via Ollama) and can answer questions, execute commands, schedule tasks, and learn your personal vocabulary.

Talking to Ava

Hold Right Alt and speak naturally. Ava will respond via TTS.

• "Hey Ava, what's the capital of France?" — she answers conversationally
• "Hey Ava, how are you?" — she responds briefly and doesn't loop
• Say "no thanks" or "I'm good" — she stops, doesn't keep offering help

Requirements

• Ollama installed and running
• A model pulled: ollama pull phi3.5 (recommended, ~2.2GB)
• TTS enabled in Settings → Text-to-Speech

Ava + Commands

Ava can execute Samsara commands through natural language. Use action-oriented phrasing:

• "Hey Ava, can you open Spotify?"
• "Hey Ava, take a screenshot"
• "Hey Ava, go full screen"
• "Hey Ava, mute this tab"

Most commands execute immediately. Potentially destructive commands (close window, delete file, lock screen) require confirmation — Ava will ask you to say "yes" before executing.

How It Works

Ava translates your natural language into the exact Samsara command name, then Samsara executes it through the normal command pipeline. She has access to all 320+ commands that are marked as visible to her.

Scheduling Actions

Ask Ava to repeat an action on a timer:

• "Hey Ava, refresh this page every 5 minutes"
• "Hey Ava, scroll down every 30 seconds"
• "Hey Ava, press F5 every minute"

Ava confirms the schedule and waits for "yes" before starting. Say "stop schedule" to cancel a running schedule. Only one schedule can be active at a time.

Teaching Aliases

Teach Ava your personal vocabulary so she understands your shortcuts:

• "Hey Ava, when I say browser I mean open Firefox"
• "Hey Ava, remember that the meeting doc means open https://docs.google.com/..."
• "Hey Ava, from now on project means open VS Code"

Aliases persist across restarts. They're stored in ~/.samsara/ava_corrections.json.

Managing Aliases

• Forget: "Hey Ava, forget browser"
• Query: "Hey Ava, what does browser mean?"
• List all: "Hey Ava, list my aliases"

If you teach an alias that already exists, Ava asks for confirmation before replacing it. Aliases are injected into Ava's context as structured knowledge — she applies them intelligently rather than doing blind text substitution.

Your Profile

Teach Ava basic information about yourself:

• "Hey Ava, my name is Morne"
• "Hey Ava, I live in Cape Town"
• "Hey Ava, I'm a developer"
• "Hey Ava, remember about me that I have chronic hand pain"

Profile information is stored in ~/.samsara/ava_profile.json and injected into every conversation with Ava. She'll use your name naturally and adapt responses to your context.

Managing Your Profile

• "Hey Ava, what do you know about me?" — reads back everything
• "Hey Ava, forget my location" — clears one field
• "Hey Ava, forget what you know about me" — clears everything

Cloud LLM Mode

For users who want a more capable AI, Ava can route requests through a cloud LLM instead of local Ollama. You provide your own API key and pay your own usage costs.

Supported Providers

Setup

Cloud LLM configuration is currently done through config.json. A settings UI for this is planned.

1. Open config.json and find the cloud_llm section
2. Set your API key: "api_key": "sk-your-key-here"
3. Optionally change the provider: "provider": "deepseek"
4. Save the file and restart Samsara
5. Say "Jarvis, ava cloud" to enable cloud mode
6. Say "Jarvis, ava local" to switch back to offline mode at any time

If the cloud provider is unreachable, Ava automatically falls back to local Ollama. You'll never be left without a response.

Commands

Samsara ships with 320+ voice commands organised into packs. All commands are deterministic — they execute the same way every time.

Overview

Commands are triggered by saying the wake word followed by the command name:

"Jarvis, open chrome"
"Jarvis, scroll down fast"
"Jarvis, mark here"
"Jarvis, again"

Commands are defined in two places:

• commands.json — hotkeys, macros, press commands, launch commands, web shortcuts
• Plugin files in plugins/commands/ — Python-implemented commands using the @command decorator

Command Packs

Packs are named groups of commands that can be enabled or disabled from Settings → Commands. This keeps the command vocabulary focused on what you actually use.

Disabled packs don't load their commands at all — they won't be recognised by the wake word listener or appear in the cheat sheet.

Custom Commands

Using the Settings Menu (recommended)

The easiest way to add a command is through Settings → Commands. Click "Add Command", choose a type (hotkey, launch, macro), fill in the fields, and save. No file editing required.

Editing commands.json (advanced)

For more control, you can edit commands.json directly. Open it in any text editor and add entries:

Adding a Hotkey Command

Add an entry to commands.json:

{
  "my custom shortcut": {
    "type": "hotkey",
    "keys": ["ctrl", "shift", "n"],
    "description": "Open new window",
    "pack": "core"
  }
}

Adding a Launch Command

{
  "open blender": {
    "type": "launch",
    "target": "C:\\Program Files\\Blender\\blender.exe",
    "description": "Launch Blender 3D",
    "pack": "core"
  }
}

Adding a Web Shortcut

{
  "open my project": {
    "type": "launch",
    "target": "https://github.com/your-repo",
    "description": "Open project on GitHub",
    "pack": "core"
  }
}

Adding a Macro

{
  "select line": {
    "type": "macro",
    "steps": [
      {"action": "press", "key": "home"},
      {"action": "press", "key": "shift+end"}
    ],
    "description": "Select the current line",
    "pack": "text-editing"
  }
}

Command Types

Command Reference

A selection of commonly used commands. For the full list, say "Jarvis, show commands" to open the floating cheat sheet.

Plugins

Plugins extend Samsara with new voice commands written in Python. Every plugin is a single .py file in plugins/commands/.

How Plugins Work

On startup, Samsara scans plugins/commands/ and loads every .py file. Each file can register voice commands using the @command decorator. Plugins have full access to the app instance, so they can control audio, UI, system calls, and hardware.

Creating a Plugin

Create a new file in plugins/commands/, for example my_plugin.py:

from samsara.plugin_commands import command

@command("say hello", aliases=["greet me"], pack="core")
def say_hello(app, remainder="", **kwargs):
    """Says hello via TTS."""
    if hasattr(app, 'audio_coordinator') and app.audio_coordinator:
        app.audio_coordinator.speak("Hello there!", category="agent_response")
    else:
        print("Hello there!")

The @command Decorator

Accessing the App

Every command function receives app as its first argument. Through it you can access:

• app.config — the full config dictionary
• app.command_executor — execute other commands programmatically
• app.audio_coordinator — TTS, ducking, audio state
• app.root — the Tkinter root window (for UI operations)

Using ctypes for System Control

For Windows-level operations (mouse control, key injection, audio APIs), use ctypes directly rather than pyautogui. This avoids dependencies and gives you full Win32 access. See plugins/commands/volume.py and plugins/commands/text_marker.py for examples.

Built-in Plugins

Features

Detailed guides for Samsara's key features.

Streaming Dictation

Press CapsLock to start streaming. Text appears at your cursor as you speak, updating in real time. Press CapsLock again to stop.

Under the hood, Samsara uses a rolling Ctrl+Z approach: each update undoes the previous paste and replaces it with the expanded text. This works in any text field that supports undo.

Configuration

• streaming_hotkey — the toggle key (default: CapsLock)
• streaming_direct_paste — when true, pastes directly instead of typing character by character

Text Selection Markers

Selecting large blocks of text by click-dragging is painful. Samsara replaces it with two voice commands:

1. Click where you want the selection to start
2. Say "Jarvis, mark here" — sets an invisible anchor at the cursor position
3. Scroll freely (by voice or mouse) to where you want the selection to end
4. Say "Jarvis, select to here" — everything between the anchor and the current position is highlighted

The anchor is tied to the window that was focused when you set it. If you switch to a different window, Samsara warns you and clears the anchor rather than selecting in the wrong app.

Voice Scrolling

Five speed tiers, all using mouse wheel simulation so they work in every application:

Scroll amounts are configurable in config.json under the scroll key. Values are in wheel "clicks" (each click = 120 wheel delta units).

Repeat / Again

Say "again" or "repeat" to re-fire the last command. Chain them: "scroll up a little, again, again, again" scrolls four times.

Destructive commands (close tab, delete file, etc.) are blacklisted from repeat to prevent accidental damage.

Overlays

Command Cheat Sheet

Say "show commands" to open a floating overlay listing all active commands. It stays on top of other windows and has an adjustable opacity slider. Filter by typing in the search box or scrolling.

Show Numbers

Say "show numbers" and every clickable element on screen gets a numbered label. Say the number to click that element. Fully hands-free UI navigation.

Listening Indicator

A small pill-shaped overlay appears when Samsara is actively listening. Position it anywhere on screen from Settings → Advanced.

Window Manager

Control window positioning by voice:

• "Move to left monitor" / "move to right monitor" — shifts the active window between screens
• "Snap left" / "snap right" — snaps to half-screen
• "Save layout" — saves the current arrangement of all windows
• "Restore layout" — restores a saved arrangement
• "Bring back lost windows" — recovers windows that are off-screen