🎬 MFilmDB - Uživatelský návod

📦 Instalace

Požadavky

• Python 3.10+ (nebo zkompilovaný .exe)
• Windows 10/11, Linux nebo macOS
• Min. 100 MB volného místa na disku
• Připojení k internetu (volitelné, pro stahování metadat)

Postup instalace (ze zdrojového kódu)

🔧 Nástroje v APP_DATA (pokročilé)

Tato část popisuje doplňkové utility a grafické nástroje v adresáři APP_DATA/. Jsou určeny pro pokročilejší úpravy, hromadné zpracování a tvorbu podpůrných dat pro aplikaci.

APP_DATA/extract_film_metadata.py

Hromadný extraktor technických metadat ze souborů (délka, rozlišení, kodek, bitrate). Používá ffprobe / ffmpeg pokud je dostupný v PATH.

• Spuštění: python APP_DATA/extract_film_metadata.py <cesta_ke_složce> nebo bez argumentu pro kontrolu konfigurace.
• Výstup: CSV nebo přímá aktualizace databáze (záleží na parametrech skriptu).
• Pokud nemáte ffmpeg, skript se pokusí použít dostupné Python knihovny, ale výsledky budou omezené.

APP_DATA/ISP_Generator_GUI.py

GUI nástroj pro tvorbu náhledů / sprite-sheetů a menších preview obrázků používaných v HTML exportech.

• Spuštění: python APP_DATA/ISP_Generator_GUI.py
• Možnosti: vložení zdrojové složky s videi, volba počtu snímků na video, rozměr náhledů a formát výstupu.
• Výstup ukládejte do složky používané exportem (např. html_export/ nebo vlastní cesta nastavená v exportní šabloně).

APP_DATA/localize_data.py

Obsahuje seznam podporovaných jazyků a lokalizační řetězce. Pro přidání nebo úpravu jazyka:

1. Otevřete APP_DATA/localize_data.py a přidejte nový záznam v seznamu LANGUAGES (kód + název).
2. Přidejte překlady do příslušné datové struktury, resp. do souboru s lokalizacemi.
3. Restartujte aplikaci, aby se změny projevily.

APP_DATA/logic.py — parser názvů souborů

Obsahuje funkce pro extrakci metadat z názvu souboru, primárně parse_filename_metadata(). Můžete zde upravit nebo přidat nové vzory (regex) pro lepší rozpoznání vlastních pojmenování.

Příklad použití v Pythonu:

from APP_DATA.logic import parse_filename_metadata
meta = parse_filename_metadata('Moje.Filmovka.2024.1080p.BluRay.mkv')
print(meta)

APP_DATA/ThemeAdder_GUI.py a APP_DATA/themes.py

Editor témat — vytvořené motivy se ukládají do projektové konfigurace a následně jsou dostupné v Nastavení → Vybrat motiv.

• Spuštění: python APP_DATA/ThemeAdder_GUI.py
• Umožňuje vytvořit barevné schéma (barvy pozadí, textu, akcentu) a uložit ho pod uživatelským názvem.
• Uložená témata se najdou v APP_DATA/themes.py nebo v uživatelské konfiguraci (záleží na implementaci).

Jak přidat vlastní provider (např. specializovaný scraper)

Pokud chcete doplnit nový zdroj metadat, postupujte opatrně:

1. Vytvořte nový modul v APP_DATA, např. APP_DATA/enrich_myprovider.py, a implementujte funkci typu enrich_film_myprovider(title, year, file_path), která vrací slovník s poli odpovídajícími databázovým sloupcům.
2. Zaregistrujte nový zdroj v MfilmDB.py v konfiguraci DEFAULT_CONFIG['sources'] (přidejte klíč s defaultní hodnotou True/False) a v seznamu popisů v dialogu zdrojů metadat.
3. Přidejte volání do orchestrátoru enrichmentu nebo upravte pořadí providerů podle priority (viz sekce Enrichment).
4. Otestujte lokálně na několika vzorcích – web scraping může být citlivý na změny struktury cílového webu.

Obecné poznámky k nástrojům

• Většinu nástrojů spustíte příkazem python APP_DATA/<script>.py z kořenové složky projektu.
• GUI utilitám stačí mít nainstalovaný tkinter a requisite knihovny uvedené v requirements.txt.
• Neprovádějte změny v hlavních modulech bez zálohy — doporučujeme pracovat s kopií.

Ukázkové výstupy

Níže jsou příklady typických výstupů nástrojů — slouží jako reference pro validaci výsledků.

1) Příklad CSV výstupu z extract_film_metadata.py

file_path,duration,video_codec,width,height,bitrate
/media/Film/Example.Movie.2024.mkv,01:42:15,h264,1920,1080,3500k
/media/Film/Clip.Video.2023.mp4,00:03:45,h264,1280,720,800k

2) Příklad JSON výsledku z parse_filename_metadata()

{
  "title": "Moje Filmovka",
  "year": 2024,
  "quality": "1080p",
  "source": "BluRay",
  "language": "CZ",
  "extra": {"resolution": "1920x1080"}
}

3) Příklad CSV pro HTML export (ukázkový řádek)

id;title;original_title;year;duration;rating;cover_path
1;Moje Filmovka;My Movie;2024;102;8.5;covers/moje_filmovka_2024.jpg

Screenshoty (placeholdery)

Do manuálu můžete vložit skutečné screenshoty. Níže jsou placeholdery, které můžete nahradit reálnými snímky ve složce navod_cz/images/ (vedle souboru navod_cz.html).

Jak vložit reálný screenshot:

1. Uložte snímek do docs/navod_cz/images/ (vytvořte složku, pokud neexistuje).
2. Přejmenujte soubor podle popisku (např. main_window.png nebo main_window.svg).
3. Otevřete tento soubor docs/navod_cz.html a změňte src v tagu <img> na novou cestu (např. navod_cz/images/main_window.png).

Podrobné texty a tipy

Praktické tipy pro práci s exporty

• Při exportu HTML+ZIP se ujistěte, že veškeré externí cesty (covertime) jsou relativní k výstupnímu archivu.
• CSV export používá středník (;) jako oddělovač ve výchozím nastavení pro české prostředí — pokud importujete do Excelu, vyberte správné kódování (UTF-8) a oddělovač.
• Při dávkovém update DB pomocí CSV vždy nejprve otestujte na malé sadě, abyste předešli nechtěným hromadným změnám.

Tipy k tvorbě screenshotů

• Snímky pořizujte v nativním rozlišení aplikace, ořízněte pouze nadbytečné okraje a uložte jako PNG pro ostré texty.
• Přidejte krátký popisek a šipky/boxy zvýrazňující důležitá tlačítka (můžete použít nástroje jako Greenshot nebo ShareX).

🎯 První spuštění

Při prvním spuštění aplikace vytvoří:

• config.json - konfigurační soubor
• mfilmdb.db - SQLite databáze filmů
• covers/ - složka pro stažené plakáty

Rozložení hlavního okna

⚙️ Základní nastavení

Přístup k nastavení

Menu: Nastavení → různé položky

Výběr tématu vzhledu

Nastavení → Vybrat motiv

• ttkbootstrap motivy - 20+ profesionálních témat
• Vlastní témata - uživatelem vytvořená

Změna jazyka

Nastavení → Lokalizace / Language

• 🇨🇿 Čeština
• 🇬🇧 English

Zdroje metadat

Nastavení → Zdroje metadat...

Zde můžete zapnout/vypnout jednotlivé zdroje:

• TMDb, OMDb, ČSFD, FDb, Edison Online, Netflix, Google Images

➕ Přidání filmů

Způsoby přidání

Ruční přidání filmu

🔍 Skenování složek

Přístup

Menu: Nástroje → Skenovat složku...

Režimy skenování

Co se extrahuje z názvu souboru

• Název filmu - první část názvu souboru
• Rok - číslo v závorce (2024) nebo za tečkou .2024.
• Kvalita - 1080p, 720p, 480p, 4K, UHD
• Zdroj - BluRay, WEB-DL, HDTV, DVDRip, BRRip
• Dabing/titulky - CZ, SK, EN, dabing, titulky

✏️ Editace záznamu

Způsoby editace

• Double-click na řádek v tabulce
• Menu: Úpravy → Upravit vybraný...
• Pravý klik → Upravit

Dostupná pole

🗑️ Mazání filmů

Smazání jednoho filmu

1. Vyberte film v tabulce
2. Menu: Úpravy → Smazat vybraný
3. Potvrďte dialog

🌐 Zdroje metadat

Aplikace podporuje stahování metadat z těchto zdrojů:

🔑 API klíče

Získání TMDb API klíče

1. Zaregistrujte se na themoviedb.org
2. Přejděte do Settings → API
3. Požádejte o API klíč (vývojář)
4. Zkopírujte klíč do aplikace: Nastavení → Zdroje metadat

Získání OMDb API klíče

1. Přejděte na omdbapi.com
2. Zvolte tier (Free = 1000 požadavků/den)
3. Potvrďte email a zkopírujte klíč

✨ Enrichment (obohacení dat)

Enrichment je proces automatického doplnění metadat z online zdrojů.

Automatický enrichment

Probíhá při Full Scan nebo při použití Watchdog s auto_import: true.

Ruční enrichment

1. Vyberte film(y) v tabulce
2. Pravý klik → Obnovit metadata
3. Aplikace stáhne aktuální data ze zdrojů

Priorita zdrojů

Pořadí, v jakém se data kombinují (nastavitelné):

1. TMDb (preferovaný zdroj)
2. OMDb / IMDb
3. ČSFD
4. FDb.cz
5. Ostatní

📥 Import dat

Import ze starších verzí

Menu: Soubor → Import ze starších verzí...

Podporované formáty:

• CSV export ze starších verzí MFilmDB
• JSON export
• HTML export (omezená podpora)

Standardní import

Menu: Soubor → Importovat...

Import z aktuálních formátů (CSV, JSON) exportovaných touto verzí.

📤 Export dat

Přístup

Menu: Soubor → Exportovat...

Dostupné formáty

🎨 HTML šablony exportu

Při exportu do HTML můžete vybrat z několika šablon:

👁️ Watchdog - automatické sledování

Co je Watchdog?

Watchdog je funkce, která automaticky sleduje vybrané složky a při přidání nového video souboru ho automaticky importuje do databáze.

Nastavení

Menu: Nástroje → Nastavení watchdog...

Konfigurace

• Enabled - zapnutí/vypnutí watchdog
• Folders - seznam sledovaných složek
• Auto import - automatické přidání do DB
• Check interval - interval kontroly (sekundy)
• File types - sledované přípony (.mp4, .mkv, .avi...)

🎭 Témata vzhledu

Změna tématu

Menu: Nastavení → Vybrat motiv

ttkbootstrap témata

Tmavá: darkly, superhero, cyborg, vapor, solar

Světlá: flatly, litera, minty, lumen, sandstone, yeti

Ostatní: cosmo, journal, cerculean, pulse, morph...

Vlastní témata

Můžete vytvořit vlastní barevné schéma:

1. Nastavení → Vybrat motiv → 🎨 Vlastní témata
2. ➕ Vytvořit nové téma...
3. Definujte barvy (bg, fg, accent, header, table...)
4. Uložte téma

🔎 Vyhledávání a filtrování

Rychlé vyhledávání

Pole v panelu nástrojů - prohledává název, originální název, rok, režiséra.

Pokročilé vyhledávání

Menu: Nástroje → Pokročilé vyhledávání...

• Filtr podle roku (rozsah)
• Filtr podle žánru
• Filtr podle kvality
• Kombinace více kritérií

Víceúrovňové třídění

Menu: Nástroje → Víceúrovňové třídění...

• Primární: např. Rok (sestupně)
• Sekundární: např. Název (vzestupně)
• Terciární: např. Hodnocení (sestupně)

⌨️ Klávesové zkratky

❓ Často kladené otázky (FAQ)

Kde se ukládá databáze?

Ve stejné složce jako aplikace, soubor mfilmdb.db (SQLite).

Můžu používat aplikaci offline?

Ano, základní funkce fungují offline. Pro enrichment metadat je potřeba internet.

Jak zálohovat databázi?

Zkopírujte soubory mfilmdb.db a config.json. Případně složku covers/.

Podporuje aplikace seriály?

Částečně - můžete přidat epizody jako samostatné záznamy. Plná podpora seriálů je plánována.

Jak přidat nový zdroj metadat?

Vyžaduje úpravu zdrojového kódu - přidání funkce enrich_film_* a registrace v konfiguraci.

🔧 Řešení problémů

❌ Aplikace se nespustí

• Ověřte verzi Pythonu: python --version (vyžaduje 3.10+)
• Nainstalujte závislosti: pip install -r requirements.txt
• Zkuste smazat config.json (vytvoří se nový)

❌ Metadata se nestahují

• Ověřte připojení k internetu
• Zkontrolujte API klíče v nastavení
• Některé zdroje mohou být dočasně nedostupné

❌ Covery se nezobrazují

• Zkontrolujte cestu ke coveru v detailu filmu
• Ověřte, že soubor coveru existuje
• Podporované formáty: JPG, PNG, WebP

❌ Watchdog nefunguje

• Ověřte, že je watchdog zapnutý v nastavení
• Zkontrolujte oprávnění ke sledovaným složkám
• Restartujte aplikaci po změně nastavení

📘 Detailní uživatelský manuál

Rychlý start

1. Spusťte aplikaci `python MfilmDB.py` nebo použijte zkompilované `.exe`.
2. V menu Nastavení → Watchdog nastavte složky ke sledování a stiskněte Uložit.
3. Ve Výchozím nastavení zkontrolujte API klíče pro TMDb/OMDb/ČSFD pokud chcete online enrichment.
4. Import souborů: přetáhněte je do okna aplikace nebo použijte Import → Skenovat složku.

Hlavní obrazovka

Tabulka filmů zobrazuje základní metadata (titulek, rok, délka, zdroj, dabing). Kliknutím na řádek otevřete detail, kde můžete upravit metadata, nahradit cover nebo spustit enrichment.

Import a export

Aplikace podporuje: CSV, XLSX (s obrázky), JSON, HTML galerie a AIO ZIP exporty. V exportních šablonách najdete nastavení sloupců a formátů v Nastavení → Export.

Enrichment metadat

Enrichment kombinuje výsledky z více providerů (TMDb, OMDb, ČSFD, FDb). Výběr providerů a priority naleznete v Nastavení → Enrichment. Funkce Enrich Smart automaticky sloučí nejlepší dostupná data.

Poznámka: Pro videoklipy a hudební videa můžete povolit specializovaný provider IMVDB v nastavení zdrojů (defaultně vypnutý). Pokud chcete přidat vlastní provider, přidejte implementaci do APP_DATA a nastavte jej v konfiguračním souboru.

Watchdog (automatické sledování složek)

Watchdog sleduje přidané složky pro nové soubory. Při detekci nového souboru spustí parsing názvu, vytvoří záznam a stáhne cover/thumbnail pokud je povoleno.

Správa coverů

SimpleCoverDownloader stahuje obrázky v několika velikostech. V detailu filmu můžete zkopírovat cover do schránky, stáhnout alternativní cover nebo použít offline fallback.

Pokročilé nastavení

• Temata – vytvořte a aplikujte vlastní téma v editoru témat.
• Klávesové zkratky – viz sekce Klávesové zkratky pro rychlé akce (přidání, vyhledání, export).
• Logy – logy jsou v adresáři `logs/` a obsahují podrobné informace o běhu aplikace.

Řešení častých problémů

Pokud aplikace nezobrazuje covery nebo metadata, zkontrolujte nastavení API klíčů, dostupnost `ffmpeg`/`ffprobe` v PATH a oprávnění ke složkám.