🎙️ VoiceFlow Teleprompter

A smart, speech-tracking teleprompter application built with Python and Tkinter. It listens to your voice through the microphone using Vosk (offline) and automatically scrolls the text to follow along as you speak.

Features

🎤 Speech Recognition

• Vosk offline engine: All speech recognition runs locally — no internet required
• Auto-download Turkish model: One-click download of the Turkish Vosk model from Settings
• Smart microphone selection: Auto-detects microphone arrays first, falls back to other input devices
• Real-time word tracking: Matches spoken words to text using fuzzy matching
• Configurable context window: Adjust look-ahead range for speech matching precision

📜 Text Display

• Smooth scrolling: Configurable easing speed for natural text flow
• Word highlighting: Current word is highlighted with a colored background
• Adjustable font size: 12–120pt, change on the fly
• Mirror mode: Flip text horizontally for use with a teleprompter glass/mirror
• Edge fade: Configurable top/bottom gradient fade for comfortable reading
• Center-focused layout: Active text stays in the visual center

🖥️ Fullscreen

• Multi-monitor aware: Fullscreen activates on the monitor where the window currently is, not the primary display
• Floating overlay toolbar: Move mouse to top edge to reveal Start/Stop/Reset/Font controls
• Auto-hiding cursor: Mouse cursor disappears after 2 seconds of inactivity, reappears on movement
• Keyboard shortcuts: F11 to toggle, Esc to exit

🌐 Internationalization

• Turkish and English UI languages
• Translation files use standard .po format in locale/
• Language can be changed in Settings (restart required)

⚙️ Settings

• Vosk model folder path (or auto-download Turkish model)
• Speech matching context window (look_ahead)
• Scroll easing speed
• Edge fade intensity
• UI language

💾 Persistence

• All settings saved automatically to voiceflow.cfg
• Window size and position remembered

Installation

Prerequisites

• Python 3.8+
• Windows (multi-monitor fullscreen uses Win32 API)

Install Dependencies

pip install vosk sounddevice

Vosk Model

You can either:

1. Auto-download: Open Settings → Vosk Model → click "📥 Download Turkish Model"
2. Manual download: Get a model from https://alphacephei.com/vosk/models, extract it, and set the path in Settings

Language	Model	Size
Turkish	vosk-model-small-tr-0.3	~45 MB
English	vosk-model-small-en-us-0.15	~40 MB

Usage

python main.py

Quick Start

1. Load a text: Click 📂 Load to open a .txt file, or 📋 Text to paste/type text
2. Select microphone: Choose from the dropdown or leave on "auto"
3. Press ▶ Start: Begin speaking — the text will follow your voice
4. Press ⏹ Stop: Pause speech tracking
5. Press ↺ Reset: Return to the beginning

Keyboard Shortcuts

Key	Action
F11	Toggle fullscreen
Esc	Exit fullscreen
← →	Step one word back/forward
↑ ↓	Step 5 words back/forward
Mouse Wheel	Step one word

Fullscreen Mode

• Press F11 or click ⛶ to enter fullscreen on the current monitor
• Move mouse to the top edge to reveal the floating control bar
• The control bar auto-hides after 3 seconds (stays visible while mouse hovers over it)
• Mouse cursor auto-hides after 2 seconds of inactivity

Project Structure

Telepromter/
├── main.py              # Entry point
├── modules/
│   ├── app.py           # Main VoiceFlow application class
│   ├── audio.py         # Vosk audio worker & model downloader
│   ├── config.py        # Configuration load/save, color theme, defaults
│   ├── dialogs.py       # Text Editor and Settings dialog windows
│   ├── i18n.py          # Internationalization (.po parser + _() function)
│   ├── layout.py        # Word wrapping and line layout engine
│   ├── matching.py      # Text normalization and fuzzy speech matching
│   ├── mic.py           # Microphone listing and auto-selection
│   └── monitor.py       # Win32 multi-monitor geometry & dark title bar
├── locale/
│   ├── tr.po            # Turkish translations
│   └── en.po            # English (source language)
├── example.txt          # Sample Turkish text for testing
├── icon.ico             # Application icon
├── icon.svg             # Application icon (SVG)
├── voiceflow.cfg        # User configuration (auto-generated)
└── .gitignore

Configuration

Settings are stored in voiceflow.cfg (JSON format). Key options:

Key	Default	Description
model_path	""	Path to Vosk model folder
mic_index	-1	Microphone device index (-1 = auto)
lang	"tr-TR"	Language code
ui_lang	"tr"	UI language ("tr" or "en")
font_size	36	Display font size
ease_speed	0.12	Scroll easing (0.04–0.40)
mirror	false	Mirror mode
fade_percent	18	Edge fade intensity (0–45%)
look_ahead	5	Context window for speech matching (2–30)

Adding a New Language

1. Create locale/<lang_code>.po (copy locale/en.po as template)
2. Add translations for each msgid
3. Add the language option to SettingsDialog._build() in modules/dialogs.py

License

This project is provided as-is for personal and educational use.