============================================================
  TRANSKRYPCJA I TLUMACZENIE
  Whisper + NLLB / Google + edge-tts
  GUI dla Windows
============================================================


CO TO ROBI
----------

AUDIO / WIDEO
  nagranie -> transkrypcja -> tlumaczenie -> plik txt + mp3 z lektorem

PLIKI TEKSTOWE
  dokument -> tlumaczenie -> dokument w tym samym formacie
  Formatowanie, timing napisow i struktura zostaja zachowane.

Obslugiwane formaty tekstowe:

  PELNE ODTWORZENIE (wynik w tym samym formacie)
    .txt .md      zwykly tekst, markdown
    .srt .vtt     napisy - timing zachowany co do milisekundy
    .docx         Word - style, naglowki, tabele
    .pptx         PowerPoint - slajdy, tabele, notatki prelegenta
    .xlsx .xlsm   Excel - formuly i liczby NIE sa ruszane
    .odt          LibreOffice Writer
    .ods          LibreOffice Calc
    .csv .tsv     separator wykrywany automatycznie
    .json         tlumaczy wartosci, klucze zostaja
    .html .htm    script/style/pre pomijane

  TYLKO ODCZYT (wynik zapisywany jako .txt)
    .pdf          layoutu nie da sie odtworzyc
    .rtf
    .epub         kazdy rozdzial osobno

Obslugiwane formaty audio/wideo:
  .ogg .opus .mp3 .m4a .wav .flac .aac .wma
  .mp4 .mkv .avi .mov .webm


SZYBKI START
------------

1. Rozpakuj caly folder w dowolne miejsce
   (np. C:\Narzedzia\transkrypcja)
   WAZNE: rozpakuj, nie uruchamiaj z wnetrza ZIP-a.

2. Uruchom:  Instalacja.bat
   - poprosi o uprawnienia administratora (UAC)
   - jesli nie masz Pythona, sam go pobierze i zainstaluje
   - pobierze biblioteki i model rozpoznawania mowy
   - ZAPYTA czy zainstalowac tlumacza lokalnego (NLLB)
   - zrobi skrot na pulpicie

3. Uruchom skrot "Transkrypcja audio" z pulpitu
   (albo Start.bat z tego folderu)

4. W okienku:
   - "Wybierz pliki..." -> mozesz mieszac audio i teksty naraz
   - zakladka "Tlumaczenie": jezyk docelowy i silnik
   - zakladka "Audio": model mowy, mp3
   - START

Wyniki zapisuja sie OBOK plikow zrodlowych, ze stemplem czasu -
nic sie nie nadpisuje.


DWA SILNIKI TLUMACZENIA
-----------------------

GOOGLE TRANSLATE (domyslny)
  + bardzo dobra jakosc, szybki, zero miejsca na dysku
  - wymaga internetu
  - tekst wychodzi na serwery Google

NLLB LOKALNY (opcjonalny, pytanie w instalatorze)
  + dziala calkowicie offline, nic nie wychodzi z komputera
  + dobry do dokumentow poufnych
  - ok. 2.5 GB na dysku (wariant 600M)
  - wolniejszy, zwlaszcza bez karty NVIDIA
  - jakosc troche nizsza niz Google, ale przyzwoita

  W GUI mozna wybrac wariant 1.3B - lepszy, ale ok. 5.5 GB
  i pobierze sie przy pierwszym uzyciu.

ARGOS (awaryjny)
  Lekki, offline, najnizsza jakosc. Uzywany automatycznie
  gdy dwa powyzsze zawioda.

Jesli wybrany silnik padnie (brak netu, brak modelu), program
sam schodzi na kolejny zamiast przerywac prace.


JAK DZIALA TLUMACZENIE AUDIO
----------------------------

Whisper tlumaczy tylko na angielski, wiec sciezka jest taka:

  nagranie -> tekst oryginalny -> [angielski] -> jezyk docelowy

Przy jezyku innym niz polski ostatni krok robi wybrany silnik.
Jesli nagranie jest juz w jezyku docelowym, tlumaczenie jest
pomijane.


WYBOR MODELU MOWY
-----------------

  tiny      ~75 MB    bardzo szybki, slaba jakosc
  base      ~145 MB   szybki
  small     ~500 MB   dobry kompromis  <- instalowany domyslnie
  medium    ~1.5 GB   dokladny, wolniejszy
  large-v3  ~3 GB     najlepsza jakosc, na CPU bardzo wolno

Modele inne niz "small" pobieraja sie przy pierwszym uzyciu.

Orientacyjnie na przecietnym laptopie (CPU), nagranie 1 minuta:
  small     ok. 30-60 sekund
  large-v3  ok. 4-8 minut

Karta NVIDIA + sterowniki CUDA -> ustaw "Urzadzenie: cuda".
Przyspiesza i transkrypcje, i tlumaczenie NLLB kilkanascie razy.


PLIKI WYNIKOWE
--------------

Nagranie "wiadomosc.ogg":
  wiadomosc_de_20260723_143012.txt   transkrypcja oryginalu
  wiadomosc_pl_20260723_143012.txt   tlumaczenie
  wiadomosc_pl_20260723_143012.mp3   lektor

Dokument "umowa.docx":
  umowa_pl_20260723_143012.docx      z zachowanym formatowaniem

Napisy "film.srt":
  film_pl_20260723_143012.srt        timing nietkniety

PDF "raport.pdf":
  raport_pl_20260723_143012.txt      (layoutu nie da sie odtworzyc)


UWAGI PRAKTYCZNE
----------------

- Mozesz wrzucic naraz audio i dokumenty - program sam rozpozna
  co jest czym i obsluzy odpowiednio.

- Tryb "Tylko transkrypcja" pomija pliki tekstowe (nie ma czego
  transkrybowac) i nie tlumaczy audio.

- Glosy lektora sa polskie. Przy tlumaczeniu na inny jezyk mp3
  bedzie brzmiec dziwnie - najlepiej wtedy odznaczyc mp3.

- Duze dokumenty na NLLB potrafia zajac kilkanascie minut.
  Pasek postepu w logu pokazuje procenty.

- HTML: tresc w <script>, <style>, <pre>, <code> jest celowo
  pomijana, zeby nie zepsuc strony.

- Excel/CSV/JSON: program NIE tlumaczy liczb, kwot, dat, godzin,
  adresow e-mail ani URL-i. Formuly w arkuszach zostaja nietkniete,
  liczby pozostaja liczbami (nie zmieniaja sie w tekst).

- PowerPoint: tlumaczy tresc slajdow, tabel i notatek prelegenta.
  Formatowanie (pogrubienia, kolory, rozmiary) zostaje zachowane,
  bo podmieniany jest tekst wewnatrz istniejacych fragmentow, a nie
  cale pole tekstowe.

- Po tlumaczeniu tekst czesto jest dluzszy niz oryginal. W slajdach
  i tabelach warto potem rzucic okiem, czy gdzies nie wychodzi poza
  ramke.


PROBLEMY
--------

Instalator prosi o admina i nic sie nie dzieje
  -> prawym na Instalacja.bat -> "Uruchom jako administrator"

Instalator konczy i kaze uruchomic sie ponownie
  -> to normalne przy swiezej instalacji Pythona, Windows
     potrzebuje chwili na PATH. Za drugim razem przejdzie.

"Nie udalo sie pobrac Pythona"
  -> firewall/proxy blokuje python.org
  -> zainstaluj recznie z https://www.python.org/downloads/
     (zaznacz "Add Python to PATH"), potem Instalacja.bat

Okienko nie startuje / znika od razu
  -> uruchom Start_z_konsola.bat, bedzie widac blad

Blad "tkinter"
  -> masz Pythona ze Sklepu Microsoft. Odinstaluj,
     instalator pobierze wlasciwa wersje z python.org

"Brak biblioteki do tego formatu"
  -> uruchom Instalacja.bat ponownie

Blad przy odczycie audio
  -> brakuje ffmpeg. Pobierz z https://www.gyan.dev/ffmpeg/builds/
     (wersja "essentials"), rozpakuj tak, zeby powstalo:
     <ten folder>\ffmpeg\bin\ffmpeg.exe
     Program sam go wtedy znajdzie.

mp3 sie nie generuje
  -> edge-tts wymaga internetu; sprawdz firewall/proxy

NLLB: "out of memory"
  -> przelacz "Urzadzenie" na cpu, albo wybierz model 600M
     zamiast 1.3B

Za proxy firmowym
  -> przed instalacja, w tym samym oknie cmd:
     set HTTPS_PROXY=http://user:haslo@proxy:8080
     set HTTP_PROXY=http://user:haslo@proxy:8080
     potem Instalacja.bat

Antywirus blokuje
  -> to zwykly Python, dodaj folder do wyjatkow

Chcesz zaczac od zera
  -> skasuj folder .venv i uruchom Instalacja.bat ponownie
     (stare srodowiska sa archiwizowane jako .venv_backup_*)


CO GDZIE JEST
-------------

  Instalacja.bat         instalator (uruchom raz)
  Start.bat              uruchomienie programu
  Start_z_konsola.bat    to samo, ale widac bledy
  transkrypcja_gui.py    okienko i logika
  czytniki.py            odczyt/zapis formatow dokumentow
  tlumacz.py             silniki tlumaczenia
  .venv\                 srodowisko Pythona (tworzone przez instalator)
