Skip to content

BUILD_AND_RUN_GUIDE.md

Latest commit

 

History

History
150 lines (111 loc) · 3.69 KB

BUILD_AND_RUN_GUIDE.md

File metadata and controls

150 lines (111 loc) · 3.69 KB

Beacon Portable Executable - Quick Start Guide

For Developers: Building the Portable Executable

Prerequisites

  • Python 3.9+ installed
  • All dependencies from requirements.txt installed
  • Models folder with Vosk and Whisper models
  • Whisper.cpp executable

Build Steps

  1. Install PyInstaller (if not already installed):

    pip install pyinstaller==6.17.0

  2. Run the build script:

    build_portable.bat

    Or manually:

    pyinstaller beacon.spec

  3. Find your portable executable:

    • Location: dist\Beacon\
    • Main file: Beacon.exe
    • Size: ~150-200 MB (includes all models)

Distribution

To distribute to users:

  1. Copy the entire dist\Beacon folder
  2. Zip it or share as-is
  3. Include the PORTABLE_README.txt (already copied)

For End Users: Running Beacon

System Requirements

  • Windows 10 or later (64-bit)
  • Microphone
  • Internet connection (for AI responses)
  • ~200 MB disk space

First-Time Setup

  1. Extract/Copy the Beacon folder to your desired location

  2. Run Beacon.exe

    • Double-click Beacon.exe
    • Look for the Beacon icon in your system tray (bottom-right)

  3. Enter API Key (first run only):

Using Beacon

  1. Activate: Say "Hey Beacon"
  2. Listen: Wait for the voice response or beep
  3. Speak: You have 3 seconds to give your command
  4. Respond: Beacon will analyze your screen and respond

Example Commands

  • "What's on my screen?"
  • "Read this document to me"
  • "Summarize this webpage"
  • "What time is it?"

Quitting Beacon

  • Right-click the Beacon icon in the system tray
  • Select "Quit"

Troubleshooting

"Hey Beacon" doesn't work

  • Check your microphone is working
  • Speak clearly at normal volume
  • Try saying it slightly louder

No API key dialog appears

  • Delete gemini_key.txt and restart Beacon.exe
  • Make sure you're running the correct executable

Application won't start

  • Make sure all files in the Beacon folder are present
  • Try running as Administrator
  • Check Windows Event Viewer for errors

No voice response

  • Check your speakers/volume
  • Verify Windows Text-to-Speech is working
  • Go to Settings > Time & Language > Speech

File Structure

Beacon/
├── Beacon.exe              # Main executable (run this)
├── PORTABLE_README.txt     # Detailed user guide
├── gemini_key.txt          # Your API key (created on first run)
└── _internal/              # Dependencies (don't modify)
    ├── models/             # AI models
    ├── whisper.cpp/        # Speech recognition
    └── [other files]       # Python runtime and libraries

Privacy & Security

  • Wake word detection: Processed locally (offline)
  • Speech recognition: Processed locally (offline)
  • AI responses: Sent to Google Gemini API (requires internet)
  • Screenshots: Sent to Google Gemini API for analysis
  • API key: Stored locally in gemini_key.txt
  • No telemetry: Beacon doesn't collect or send usage data

Support

For issues or questions:

  • Check PORTABLE_README.txt for detailed troubleshooting
  • Review the implementation plan and walkthrough (for developers)
  • Ensure you're using the latest version

Version Information

  • Build Tool: PyInstaller 6.17.0
  • Python Version: 3.9.13
  • Wake Word Engine: Vosk (offline)
  • Speech Recognition: Whisper.cpp
  • AI Model: Google Gemini 1.5 Flash
  • TTS: Windows SAPI

Enjoy using Beacon! 🚀