🎬 ScriptView - Teleprompter dla Windows

Teleprompter wyświetlający tekst jako overlay na ekranie

Features • Installation • Usage • Development • Contributing

📖 O Projekcie

ScriptView to aplikacja telepromptera dla Windows, która wyświetla tekst jako przezroczysty overlay na ekranie. Idealna do nagrywania video, prowadzenia video calli i prezentacji, gdzie potrzebujesz czytać skrypt patrząc jednocześnie w kamerę.

✨ Kluczowe Cechy

🎯 Zawsze na wierzchu - Okno zawsze widoczne nad innymi aplikacjami
👻 Przezroczyste tło - Regulowana przezroczystość dla lepszej czytelności
🎬 Auto-scroll - Automatyczne przewijanie tekstu z regulacją prędkości
⌨️ Globalne skróty - Sterowanie bez fokusa okna
🎨 Pełna personalizacja - Rozmiar czcionki, rodzina, prędkość scrollowania
📁 Import/Eksport - Wczytuj i zapisuj skrypty z plików .txt
🎛️ System Tray - Minimalistyczna kontrola przez tray icon
ℹ️ Okno About - Informacje o aplikacji dostępne z paska kontrolnego

🚀 Funkcjonalności

MVP (v1.0)

Podstawowe Okno

✅ Floating window zawsze na wierzchu
✅ Przezroczyste tło z regulowaną opacity (0.1-1.0)
✅ Zmiana rozmiaru i pozycji okna
✅ Brak ramki (frameless window)
✅ Drag & drop do przesuwania

Edycja Tekstu

✅ Prosty edytor tekstu (textarea)
✅ Zapisywanie skryptu lokalnie
✅ Import tekstu z pliku .txt
✅ Eksport do pliku .txt
✅ Live preview zmian w prompterze

Auto-Scroll

✅ Automatyczne przewijanie tekstu (60 FPS)
✅ Regulacja prędkości (0.5-10 px/frame)
✅ Pause on hover (najazd myszką pauzuje)
✅ Manual scroll (scroll wheel)
✅ Reset do początku

Globalne Skróty Klawiszowe

✅ Shift + ← - Zmniejszenie prędkości
✅ Shift + → - Zwiększenie prędkości
✅ Shift + Space - Play/Pause toggle
✅ Shift + ↑ - Reset do początku

Ustawienia

✅ Okno settings (osobne)
✅ Regulacja szerokości/wysokości okna (200-2000px / 50-1000px)
✅ Regulacja opacity tła (0.1-1.0)
✅ Wybór czcionki (Arial, Helvetica, Verdana, Segoe UI, Roboto)
✅ Regulacja rozmiaru czcionki (12-48px)
✅ Prędkość scrollowania (default: 2 px/frame)

TODO: Screen Share Detection

Wykrywanie gdy użytkownik sharuje ekran
Automatyczne ukrywanie okna podczas share
Przywracanie po zakończeniu share

System Tray

✅ Tray icon w notification area
✅ Menu kontekstowe (Show/Hide, Editor, Settings, About, Quit)
✅ Kliknięcie lewym przyciskiem - toggle widoczności

Okno About

✅ Informacje o aplikacji i wersji
✅ Dostępne z paska kontrolnego (ikona Info)
✅ Dostępne z menu tray

🛠️ Tech Stack

Frontend

Framework: Electron 39.2.7
UI Library: React 19.2.3
Styling: Tailwind CSS 4.1.18
PostCSS Plugin: @tailwindcss/postcss 4.1.18
State Management: Zustand 5.0.9
Icons: Lucide React 0.562.0

Backend/System

Runtime: Node.js 20+
File System: fs/promises (Node.js native)
Shortcuts: electron-globalShortcut
Window Management: Electron BrowserWindow API
Screen Capture: electron-desktopCapturer
Storage: electron-store 11.0.2

Build & Development

Build Tool: Vite 7.3.0
Electron Vite: electron-vite 5.0.0
React Plugin: @vitejs/plugin-react 5.1.2
Electron Builder: electron-builder 26.0.12
Package Manager: npm

📦 Instalacja

Wymagania

OS: Windows 10/11
Node.js: 20+ (tylko do development)
npm: 9+ lub pnpm 8+

Development Setup

Sklonuj repozytorium

git clone https://github.com/Qbeczek1/ScriptView.git
cd scriptview

Zainstaluj zależności
```
npm install
```
Uruchom w trybie deweloperskim
```
npm run dev
```

Build Produkcyjny

Zbuduj aplikację
```
npm run build
```
Utwórz installer dla Windows
```
npm run build:win
```
Instalator znajdziesz w folderze release/.

💻 Użycie

Pierwsze Uruchomienie

Uruchom aplikację - otworzy się okno telepromptera
Kliknij prawym przyciskiem na tray icon → "Otwórz Edytor"
Wpisz lub wklej swój skrypt
Przeciągnij okno telepromptera do pozycji kamery
Użyj Shift + Space aby rozpocząć auto-scroll

Podstawowe Operacje

Edycja Tekstu

Otwórz Edytor: Tray icon → "Otwórz Edytor" lub Ctrl + E (w przyszłości)
Wczytaj z pliku: Przycisk "Wczytaj z pliku" w edytorze
Zapisz do pliku: Przycisk "Zapisz do pliku" w edytorze
Live Preview: Zmiany w edytorze są widoczne natychmiast w prompterze

Sterowanie Scrollowaniem

Play/Pause: Shift + Space
Zwiększ prędkość: Shift + →
Zmniejsz prędkość: Shift + ←
Reset: Shift + ↑
Manual scroll: Scroll wheel myszy
Pause on hover: Najedź myszką na okno

Ustawienia

Otwórz Ustawienia: Tray icon → "Ustawienia" lub ikona Settings w pasku kontrolnym
Font Size: Slider 12-48px
Font Family: Dropdown z dostępnymi czcionkami
Scroll Speed: Slider 0.2-1.8 px/frame
Opacity: Slider 0.1-1.0 (10%-100%)
Window Size: Inputy dla szerokości i wysokości

Okno About

Otwórz About: Tray icon → "O aplikacji" lub ikona Info w pasku kontrolnym
Wyświetla informacje o wersji aplikacji i technologiach

Skróty Klawiszowe

Skrót	Akcja
`Shift + ←`	Zmniejsz prędkość scrollowania
`Shift + →`	Zwiększ prędkość scrollowania
`Shift + Space`	Play/Pause toggle
`Shift + ↑`	Reset do początku

Uwaga: Skróty działają globalnie, nawet gdy okno nie ma fokusa.

⚙️ Konfiguracja

Pliki Konfiguracyjne

Ustawienia aplikacji są przechowywane w:

Windows: %APPDATA%\scriptview\config.json
Skrypty: %USERPROFILE%\Documents\ScriptView\

Struktura Ustawień

{
  "lastScript": "",
  "scrollSpeed": 2,
  "fontSize": 24,
  "fontFamily": "Arial, sans-serif",
  "opacity": 0.9,
  "windowWidth": 600,
  "windowHeight": 150,
  "windowX": undefined,
  "windowY": undefined
}

Zmiana Domyślnych Ustawień

Edytuj plik src/main/constants.js:

export const DEFAULT_SETTINGS = {
  fontSize: 24, // Zmień domyślny rozmiar czcionki
  fontFamily: "Arial, sans-serif",
  scrollSpeed: 2, // Zmień domyślną prędkość
  opacity: 0.9,
  windowWidth: 600,
  windowHeight: 150,
};

🔧 Rozwój

Struktura Projektu

scriptview/
├── src/
│   ├── main/                    # Electron Main Process
│   │   ├── index.js            # Entry point
│   │   ├── windowManager.js    # Zarządzanie oknami
│   │   ├── shortcuts.js        # Globalne skróty
│   │   ├── screenShare.js      # Detekcja screen share
│   │   ├── fileManager.js      # Operacje na plikach
│   │   ├── editorWindow.js     # Okno edytora
│   │   ├── settingsWindow.js   # Okno ustawień
│   │   ├── aboutWindow.js      # Okno About
│   │   ├── tray.js             # System tray
│   │   ├── storage.js          # electron-store
│   │   ├── constants.js        # Stałe aplikacji
│   │   └── utils/              # Narzędzia pomocnicze
│   │       ├── logger.js       # Logging
│   │       ├── validators.js   # Walidacja danych
│   │       └── errorHandler.js # Error handling
│   │
│   ├── renderer/                # Electron Renderer (React)
│   │   ├── App.jsx             # Root component
│   │   ├── components/
│   │   │   ├── Prompter.jsx    # Główne okno telepromptera
│   │   │   ├── Editor.jsx      # Edytor tekstu
│   │   │   ├── Settings.jsx    # Okno ustawień
│   │   │   └── About.jsx       # Okno About
│   │   ├── hooks/
│   │   │   └── useScroll.js    # Logika auto-scrollu
│   │   ├── store/
│   │   │   └── useStore.js     # Zustand store
│   │   └── main.jsx            # Entry point
│   │
│   └── preload/
│       └── index.js            # Bridge między main i renderer
│
├── public/                      # Assets statyczne
├── docs/                        # Dokumentacja
├── package.json
├── electron.vite.config.js
├── tailwind.config.js
├── postcss.config.js
└── electron-builder.yml

Skrypty NPM

# Development
npm run dev              # Uruchom w trybie deweloperskim z hot-reload

# Build
npm run build            # Zbuduj aplikację
npm run preview          # Testuj build lokalnie

# Distribution
npm run build:win        # Utwórz installer dla Windows
npm run dist             # Build + pakowanie

Najlepsze Praktyki

Projekt stosuje najlepsze praktyki programistyczne:

✅ Bezpieczeństwo: Context Isolation, walidacja danych, safe IPC
✅ Wydajność: React.memo, useCallback, useMemo, debouncing
✅ Utrzymywalność: Modularna struktura, JSDoc, structured logging
✅ Niezawodność: Comprehensive error handling, fallback values
✅ Developer Experience: Structured logging, debugging tools

Debugging

Main Process

Logi są wyświetlane w konsoli terminala. W development mode wszystkie poziomy są widoczne.

Renderer Process

Otwórz DevTools:

Automatycznie w development mode
Lub dodaj prompterWindow.webContents.openDevTools() w kodzie

Logging

import { createLogger } from "./utils/logger.js";
const logger = createLogger("MyModule");

logger.info("Informacja");
logger.warn("Ostrzeżenie");
logger.error("Błąd", error);
logger.debug("Debug info");

🐛 Troubleshooting

Problem: Okno nie jest przezroczyste

Rozwiązanie:

Sprawdź czy używasz Windows 10/11
Upewnij się, że transparent: true jest ustawione w windowManager.js

Problem: Skróty klawiszowe nie działają

Rozwiązanie:

Sprawdź czy nie ma konfliktów z innymi aplikacjami
Uruchom aplikację jako administrator (jeśli wymagane)
Sprawdź logi w konsoli

Problem: Screen share detection nie działa

Rozwiązanie:

To jest znane ograniczenie Electron - detection może nie działać w 100%
Użyj ręcznego przełączania przez tray icon
Sprawdź czy aplikacja ma uprawnienia do screen capture

Problem: Aplikacja nie zapisuje ustawień

Rozwiązanie:

Sprawdź uprawnienia do zapisu w %APPDATA%\scriptview\
Sprawdź logi w konsoli
Sprawdź czy electron-store jest poprawnie zainstalowany

Problem: Build nie działa

Rozwiązanie:

# Wyczyść cache
rm -rf node_modules dist out release
npm install
npm run build

Problem: Błąd Tailwind CSS PostCSS

Rozwiązanie:

Tailwind CSS 4 wymaga pakietu @tailwindcss/postcss
Upewnij się, że masz zainstalowany: npm install @tailwindcss/postcss --save-dev
Sprawdź konfigurację w postcss.config.js i electron.vite.config.js

🗺️ Roadmap

v1.1 (Planowane)

Voice-activated scrolling (Web Speech API)
Eksport do PDF/Word
Statystyki czytania (czas, słowa/minutę)
Więcej skrótów klawiszowych

v1.2 (Planowane)

Multiple scripts/projekty
Cloud backup (opcjonalny)
Integracja z Notion/Google Docs
Markdown support

v2.0 (Długoterminowe)

📱 Android app z overlay - Teleprompter wyświetlany nad Instagram/TikTok podczas nagrywania
AI script generator
Collaboration features
Theme system (Dark/Light)

📱 Android Overlay: Planujemy wersję na Androida z funkcją overlay - tekst telepromptera będzie widoczny nad innymi aplikacjami (Instagram, TikTok, Camera), ale NIE będzie nagrywany przez kamerę. Szczegóły: docs/ANDROID_VERSION.md

🤝 Współpraca

Contributions są mile widziane!

Jak Współpracować

Fork repozytorium
Utwórz branch dla swojej funkcji (git checkout -b feature/AmazingFeature)
Commit zmiany (git commit -m 'Add some AmazingFeature')
Push do brancha (git push origin feature/AmazingFeature)
Otwórz Pull Request

Code Style

Używaj ESLint/Prettier (jeśli skonfigurowane)
Pisz JSDoc dla funkcji
Dodawaj komentarze tam gdzie potrzebne
Testuj swoje zmiany przed PR

Reporting Bugs

Użyj GitHub Issues i podaj:

Opis problemu
Kroki do reprodukcji
Oczekiwane vs rzeczywiste zachowanie
Screenshots (jeśli dotyczy)
System operacyjny i wersja

📄 Licencja

Ten projekt jest licencjonowany na licencji MIT - zobacz plik LICENSE dla szczegółów.

🙏 Podziękowania

Electron - Framework dla aplikacji desktopowych
React - Biblioteka UI
Tailwind CSS - Utility-first CSS framework
Zustand - Lekki state management
Lucide - Ikony
Vite - Build tool
Wszystkim contributorom i użytkownikom!

🔒 Bezpieczeństwo

Wszystkie zależności są zaktualizowane do najnowszych wersji z poprawkami bezpieczeństwa:

✅ Electron 39.2.7 - naprawione podatności ASAR
✅ Vite 7.3.0 - naprawione podatności esbuild
✅ electron-vite 5.0.0 - naprawione podatności esbuild
✅ Wszystkie moduły w najnowszych stabilnych wersjach

Szczegóły: docs/DEPENDENCIES_AUDIT.md

📞 Kontakt

Issues: GitHub Issues
Discussions: GitHub Discussions

Zrobione z ❤️ dla społeczności

⭐ Jeśli projekt Ci się podoba, zostaw gwiazdkę!

Name		Name	Last commit message	Last commit date
Latest commit History 16 Commits
docs		docs
src		src
.gitignore		.gitignore
README.md		README.md
electron-builder.yml		electron-builder.yml
electron.vite.config.js		electron.vite.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js

Folders and files

Latest commit

History

Repository files navigation

🎬 ScriptView - Teleprompter dla Windows

📖 O Projekcie

✨ Kluczowe Cechy

🚀 Funkcjonalności

MVP (v1.0)

Podstawowe Okno

Edycja Tekstu

Auto-Scroll

Globalne Skróty Klawiszowe

Ustawienia

TODO: Screen Share Detection

System Tray

Okno About

🛠️ Tech Stack

Frontend

Backend/System

Build & Development

📦 Instalacja

Wymagania

Development Setup

Build Produkcyjny

💻 Użycie

Pierwsze Uruchomienie

Podstawowe Operacje

Edycja Tekstu

Sterowanie Scrollowaniem

Ustawienia

Okno About

Skróty Klawiszowe

⚙️ Konfiguracja

Pliki Konfiguracyjne

Struktura Ustawień

Zmiana Domyślnych Ustawień

🔧 Rozwój

Struktura Projektu

Skrypty NPM

Najlepsze Praktyki

Debugging

Main Process

Renderer Process

Logging

🐛 Troubleshooting

Problem: Okno nie jest przezroczyste

Problem: Skróty klawiszowe nie działają

Problem: Screen share detection nie działa

Problem: Aplikacja nie zapisuje ustawień

Problem: Build nie działa

Problem: Błąd Tailwind CSS PostCSS

🗺️ Roadmap

v1.1 (Planowane)

v1.2 (Planowane)

v2.0 (Długoterminowe)

🤝 Współpraca

Jak Współpracować

Code Style

Reporting Bugs

📄 Licencja

🙏 Podziękowania

🔒 Bezpieczeństwo

📞 Kontakt

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages