xeen

Screenshot capture → edit → crop → publish. One command.

pip install -e .
xeen

Problem

Chcesz szybko stworzyć krótki film ze screenshotów — demo produktu, tutorial, changelog. Ale Canva to za dużo kroków. xeen robi to w terminalu + przeglądarce.

Jak działa

┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐
│ Capture │──→│ 1.Select │──→│2.Annotate│──→│ 3.Center │──→│  4.Crop  │──→│5.Captions│──→│6.Publish │
│ xeen    │   │ klatki   │   │ strzałki │   │ fokus    │   │ presety  │   │ napisy   │   │ eksport  │
└─────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘   └──────────┘
 screenshoty   wybór/usuw.    rysowanie      click=center   SM formaty     ręczne/AI      MP4/GIF/
 + metadane    duplikaty      tekst, rect    interpolacja   zoom/pad       LLM gen.       WebM/ZIP
 kursor/kb     sortowanie     kolory         auto z myszy   smart crop     drag&drop      branding

Instalacja

# Z repozytorium
git clone https://github.com/softreck/xeen.git
cd xeen
pip install -e .

# Wymagania systemowe
# Linux/Mac: ffmpeg
sudo apt install ffmpeg   # Ubuntu/Debian
brew install ffmpeg        # macOS

# Capture wymaga środowiska GUI, ale xeen automatycznie wykrywa
# najlepszą metodę i przełącza się na przeglądarkę gdy brak ekranu:
#
#   1. mss (X11/Wayland) → najszybszy
#   2. Pillow ImageGrab   → alternatywa
#   3. scrot/grim/import  → narzędzia systemowe
#   4. Przeglądarka (Screen Capture API) → fallback headless
#   5. Upload ręczny      → zawsze działa

Użycie

1. Nagrywanie

# Domyślne (10s, co 1s, max 15 klatek) - komenda 'xeen' sama robi capture
xeen

# Lub jawnie
xeen capture

# Krótkie demo (5s)
xeen capture -d 5

# Gęstsze klatki
xeen capture -d 10 -i 0.5

# Nazwana sesja
xeen capture -n "ksefin-demo-v2"

# Konkretny monitor
xeen capture --monitor 1

Co zbiera xeen capture:

• Screenshoty z inteligentnym interwałem (pomija identyczne klatki)
• Pozycja myszy co 100ms — używana jako sugestia "środka uwagi"
• Klawisze — log co zostało wciśnięte (kontekst)
• % zmiany ekranu — między klatkami

2. Edycja w przeglądarce

# Uruchom serwer (otwiera przeglądarkę)
xeen

# Lub jawnie
xeen server -p 8080
xeen server --no-browser

6 zakładek:

3. Automatyczny fallback capture

Gdy xeen nie może przechwycić ekranu (headless, brak GUI), automatycznie:

1. Próbuje kolejne backendy: mss → Pillow → scrot/grim/import
2. Jeśli żaden nie działa — uruchamia serwer z trybem Browser Capture
3. Przeglądarka otworzy stronę http://127.0.0.1:7600/capture
4. Użyj Screen Capture API (getDisplayMedia) do nagrania ekranu z przeglądarki

# Automatyczny fallback — xeen sam wykryje co działa
xeen

# Lub ręcznie uruchom browser capture
xeen server
# → otwórz http://127.0.0.1:7600/capture

4. Upload ręczny

Alternatywnie, w edytorze (Tab 1):

• Przeciągnij pliki PNG/JPG bezpośrednio na stronę
• Kliknij "Wybierz pliki" aby wybrać screenshoty z komputera

5. Lista sesji

xeen list

Presety przycinania

Deploy na VPS (Docker + TLS)

# 1. Sklonuj na VPS
git clone https://github.com/softreck/xeen.git
cd xeen

# 2. Deploy z domeną
make deploy DOMAIN=xeen.twoja-domena.pl

# Lub ręcznie:
bash deploy.sh xeen.twoja-domena.pl

Skrypt automatycznie:

• Instaluje Docker + certbot
• Generuje cert TLS (Let's Encrypt lub self-signed)
• Buduje i uruchamia kontenery
• Konfiguruje auto-renewal

Docker ręcznie

# Dev z self-signed cert
make dev-certs
docker-compose up -d

# Logi
docker-compose logs -f

# Stop
docker-compose down

Struktura Docker

┌─────────────┐     ┌───────────┐
│   nginx     │────→│  xeen app │
│  :80/:443   │     │   :7600   │
│  TLS term.  │     │  FastAPI  │
└─────────────┘     └───────────┘
       │                   │
       │              ┌────┴────┐
       │              │  /data  │
       │              │ volume  │
       └──────────────┴─────────┘

Metadane

Każda sesja zapisuje session.json z:

{
  "name": "20250219_143022",
  "frames": [
    {
      "index": 0,
      "timestamp": 0.0,
      "filename": "frame_0000.png",
      "change_pct": 100.0,
      "mouse_x": 960,
      "mouse_y": 540,
      "suggested_center_x": 960,
      "suggested_center_y": 540,
      "input_events": [
        {"ts": 0.1, "kind": "mouse_move", "x": 955, "y": 538},
        {"ts": 0.2, "kind": "key_press", "key": "a", "x": 955, "y": 538},
        {"ts": 0.3, "kind": "mouse_click", "x": 960, "y": 540, "button": "Button.left"}
      ]
    }
  ],
  "input_log": [ ... ]  
}

Szybka prezentacja z 3-5 zrzutów ekranu

Najszybszy workflow do stworzenia demo/tutoriala:

# 1. Zrób 3-5 zrzutów ekranu (PrintScreen, Flameshot, itp.)
# 2. Uruchom xeen
xeen server

# 3. W przeglądarce:
#    Tab 1: Przeciągnij screenshoty → zaznacz potrzebne
#    Tab 3: Kliknij "Auto: kursor myszy" (lub ustaw ręcznie)
#    Tab 4: Wybierz preset np. twitter_post
#    Tab 6: Kliknij "Generuj wszystkie formaty"

Wskazówki:

• 3 zrzuty — idealnie na social media post (Twitter, LinkedIn)
• 5 zrzutów — dobra ilość na krótki tutorial/changelog
• Pomiń Tab 2 (Adnotacje) jeśli screenshoty są czytelne
• Pomiń Tab 5 (Napisy) jeśli nie potrzebujesz opisów
• Użyj "Pierwsze N" w Tab 1 aby szybko wybrać dokładnie tyle klatek ile potrzebujesz
• Ustaw focus=mouse + pad=20% aby wyciąć istotny fragment ekranu

FPS — ile klatek nagrywać?

Rekomendacja: 2-3 FPS (xeen capture -i 0.5 lub -i 0.33).

• Przy 1 FPS możesz przegapić krótkie interakcje
• Przy 3 FPS masz wystarczająco dużo materiału bez zalewania dysku
• Duplikaty można usunąć automatycznie w Tab 1 ("Znajdź duplikaty")

API

Licencja

MIT — Softreck

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com