🎬 MFilmDB

📋 Přehled aplikace

MFilmDB je desktopová aplikace pro správu osobní filmové sbírky, vyvinutá v Pythonu s využitím moderního GUI frameworku ttkbootstrap. Aplikace je navržena pro uživatele, kteří chtějí mít přehled o svých filmech uložených na lokálních discích, NAS serverech nebo externích médiích.

🎯 Cílová skupina

• Filmové nadšence s rozsáhlými sbírkami digitálních filmů
• Správce domácích mediálních serverů (PLEX, Jellyfin, Kodi)
• Archiváře kteří potřebují katalogizovat média s metadaty
• Uživatele NAS s velkým množstvím video souborů

🏗️ Technologie

⚙️ Funkce a možnosti

📁 Správa filmové databáze

Jádrem aplikace je robustní databázový systém postavený na SQLite:

• 30+ datových polí pro každý film (název, originální název, rok, žánr, režisér, scénář, kamera, hudba, obsazení, dabing, titulky, délka, velikost souboru...)

• 🗄️ Seznam sloupců v DB (technický přehled)

  Technicky jsou většina polí uložena v SQLite jako text (varchar) nebo integer, s několika indexy a plnotextovým FTS5 indexem pro rychlé vyhledávání. Níže je výběr nejdůležitějších sloupců a jejich účel:

  • id (INTEGER PRIMARY KEY) — interní identifikátor záznamu.
  • title, original_title (TEXT) — normalizované názvy pro zobrazení i vyhledávání.
  • year (INTEGER) — rok vydání (rozsah 1900–2099).
  • directors, writers, cast (TEXT) — čárkou oddělené seznamy, případně normalizované položky z `KNOWN_ACTORS`.
  • genres, tags (TEXT) — klíčová slova pro filtrování a exporty.
  • duration, resolution, width, height, aspect_ratio — technické metriky používané pro filtrování a zobrazení náhledů.
  • file_path, file_name, extension, file_size, file_hash — zdrojový soubor a jeho fingerprint pro detekci duplicit.
  • source, quality, codecs, audio_channels, language — informace z filename parseru a media-analyzátoru (ffprobe/pymediainfo).
  • dubbing, subtitles, embedded_subtitles — informace o přítomnosti a typu titulků/dabingu.
  • cover_path, cover_hash — relativní cesta k uloženému coveru a hash pro kontrolu aktualizací.
  • rating_stars (INTEGER 1–10) — interní oceňovací škála pro uživatelské hodnocení nebo konverzi z externích zdrojů.
  • rating_percent (INTEGER 0–100) — procentuální reprezentace (pro exporty a statistiky).
  • votes — počet hlasů / zdrojových ratingů.
  • imdb_id, tmdb_id, csfd_id, fdb_id — externí identifikátory pro rychlé dotazy na providery.
  • notes, added_at, modified_at, last_scanned — administrativní a auditní metadata.

  Laicky: databáze ukládá vše, co chcete vědět o filmu — od názvu a roku přes kvalitu a délku až po to, kde je soubor uložen a zda má titulky. Díky indexům a FTS vyhledávání najdete film rychle i ve velkých kolekcích.

• Automatické skenování složek s třemi režimy:
  • ⚡ Quick Scan - rychlé načtení (cesta, velikost, formát)
  • 🔍 Deep Scan - extrakce metadat z názvů souborů a cest
  • 🌐 Full Scan - kompletní online enrichment z API
• Hash souborů pro detekci duplicit
• Automatické rozpoznávání roku, kvality (1080p, 720p, 4K), zdroje (BluRay, WEB-DL, HDTV)

🧭 Parsování názvů a nový obsah `APP_DATA`

V posledních úpravách byl významně rozšířen modul APP_DATA/logic.py — nyní obsahuje komplexní funkci parse_filename_metadata(filename), která extrahuje a normalizuje následující informace přímo z názvu souboru:

• Titul — odstranění šumu (kodeky, kvalita, release tagy) a zkrácených pomlček zachovávajících čitelnost.
• Rok — včetně zkrácených formátů (např. '78 → 1978) pomocí SHORT_YEAR_RE.
• Epizodická data — SxxExx, 1x01, EP1234, díl/část apod., s podporou tří/čtyřciferných čísel (EPISODE_PATTERNS).
• Herci — extrakce z názvu podle rozšiřitelného seznamu KNOWN_ACTORS (přidáni např. Al Pacino, Jean-Claude Van Damme).
• Uploader — rozpoznání (např. romin, PeterXi) z názvu nebo závorek (KNOWN_UPLOADERS, UPLOADER_RE).
• Zdroj — BluRay, DVDRip, WEB-DL, DVBT apod. (SOURCE_PATTERNS).
• Dabing / jazyk — detekce CZ/SK/EN a dalších zkratek (DUBBING_PATTERNS).
• Titulky v obraze — hardcoded / v obraze detekce (SUBTITLES_EMBEDDED_RE).
• Ordinály / pořadová čísla — prefixy typu 01,Film rozpoznány pomocí ORDINAL_PREFIX_RE.

Tato logika zlepšuje přesnost automatického přiřazování záznamů k filmům a usnadňuje dávkové zpracování velkých knihoven.

Další doplněné a nově sledované soubory/adresáře v APP_DATA:

• APP_DATA/GFX/w20-webp/ — sada 20×20 webp ikon (vlaječky) vhodná pro UI badge; doporučeno používat jednotný zdroj ikon pro šablony.
• APP_DATA/BBB_Browser/ — nástroje pro prohlížení a generování BBB (backup/browser) výstupů; součást DEV nástrojů.
• APP_DATA/ISP_Generator_GUI.py — vylepšený generátor obrazových šablon (poster/ISP).
• APP_DATA/localize_data.py — rozšířené fáze lokalizace (nové klíče) pro ~23 jazyků.

🌍 Lokalizace (podrobně)

Poznámka k lokalizacím: Plný seznam podporovaných jazyků je definován v APP_DATA/localize_data.py. V aktuální verzi jsou to: CZ, EN, SK, DE, PL, NL, FR, IT, FI, JA, ES, PT, RU, VI, NO, DA, ZH, HI, FA, TR, UK, HU, TA (celkem 23 jazyků).

Jak to funguje (laicky): Uživatelské rozhraní má přeložené texty pro tlačítka, dialogy a progress fáze — stačí v nastavení zvolit jazyk a aplikace se pokusí použít dostupné překlady.

Technicky: Lokalizace jsou uloženy jako mapy klíč→překlad v APP_DATA/localize_data.py. Nové fáze procesu (phase_5,...,phase_100) jsou přeloženy pro 23 jazyků; přidání dalšího jazyka je jednoduché: přidejte slovník s klíči pro nové locale a aktualizujte registry v souboru.

Přepsání a doplnění překladů: Pro lokální úpravy vytvořte soubor s přejmenovanými klíči ve složce uživatelského profilu nebo použijte nástroje v DEV_TOOLS/LocalizeAdder_QT.py.

Poznámka k inventarizaci: V rámci úprav jsem také zaznamenal více nových (dříve untracked) souborů ve stromu repozitáře — například vlaječky v w20-webp/ a ikony v kořeni projektu (icon_vav.ico). Doporučuji mít tyto zdroje centralizované a případně přidat manifest s doporučenými ikonami pro exportní šablony.

🌐 Online enrichment metadat

Aplikace podporuje automatické stahování metadat z mnoha zdrojů. Enrichment kombinuje data z více providerů s fallback logikou a confidence skóre — to znamená, že pokud jeden provider nemá informaci, aplikace zkusí další a vybere nejspolehlivější hodnotu.

Technická poznámka: Pro některé providery (TMDb, OMDb) je nutný API klíč; jiné (ČSFD, FDb) jsou získávány scrapováním. Rate-limity a timeouty jsou respektovány a aplikace implementuje retry/backoff strategii.

Součástí poskytovaných zdrojů jsou:

Poznámka: Online enrichment nepokrývá všechny veřejné zdroje — například specializované katalogy pro videoklipy (IMVDB) mohou vyžadovat speciální provider. V této verzi je IMVDB integrován pro hudební videoklipy, ale je omezen na soubory nacházející se ve složkách označených jako Videoklipy (konfigurace: sources.imvdb). Pokud potřebujete další specializované zdroje (např. lokální nebo placené API), přidejte provider do APP_DATA (funkce `search_*` nebo wrapper) a zaregistrujte jej v nastavení zdrojů.

Jak se rozhoduje, který provider použít: aplikace volí podle priority (nastavení), dostupnosti API (klíče), a podle typu obsahu — např. pro videoklipy se primárně použije IMVDB.

🖼️ Správa obrázků (covers)

Covery jsou pro aplikaci důležité — zobrazují se v tabulkách, detailech a exportech. Aplikace používá kombinaci lokálního vyhledávání a online downloaderu:

1. Vyhledávání lokálních coverů — nejprve zkontroluje adresář filmu (soubory s názvy jako cover.*, poster.*, folder.*) a poté uživatelem definovaný adresář (`covers_path` nebo zadaný v nastavení).
2. SimpleCoverDownloader — pokud lokální cover není nalezen nebo uživatel požádá o update, stáhne aplikace covery z online providerů (TMDb, OMDb, Google Images apod.).
3. Ukládání — stažené/vybrané covery se ukládají do složky covers/ (nebo do cesty definované v `config.json`) s formátovanými názvy: {tmdb_id|imdb_id|normalized_title}_{year}.{ext}. Příklad: tt0111161_1994.jpg nebo Shawshank_Redemption_1994.webp. Tím je zajištěna konzistence a snadná identifikace.
4. Hash & cache — každý uložený cover je doplněn o `cover_hash` v DB pro detekci změn a pro re-use bez zbytečného stahování.
5. Formáty a velikosti — doporučené formáty jsou WebP nebo JPG; doporučené minimální rozměry pro detailní zobrazení: 600×900px (portrait) nebo 1280×720px (landscape). Aplikace generuje menší thumbs pro seznamy a náhledy.

Tip pro uživatele: Pro velké sbírky je doporučeno centralizovat covery v samostatném adresáři a povolit automatické zpracování (auto_process_covers) — to urychlí export a zabrání duplikaci souborů.

📤 Export a import

Flexibilní možnosti exportu a importu dat:

🎨 HTML šablony exportu

K dispozici je 7 předdefinovaných šablon pro HTML export:

1. 01_default.html - Základní tabulkový vzhled
2. 02_dark_modern.html - Tmavé moderní téma
3. 03_netflix_style.html - Styl Netflix katalogu
4. 04_retro_cinema.html - Retro filmový vzhled
5. 05_minimalist_light.html - Světlý minimalistický design
6. 06_film_cards.html - Grid responzivních karet s řazením a filtrováním
7. 07_accessible_cards.html - Přístupné karty pro slabozraké (velký text)

👁️ Watchdog - automatické sledování

Integrovaný file system watcher pro automatickou detekci nových filmů:

• Sledování více složek současně
• Rekurzivní prohledávání podsložek
• Konfigurovatelné typy souborů (.mp4, .mkv, .avi, .mov, .wmv)
• Automatický import s volitelným enrichmentem
• Debouncing - ochrana proti duplicitním událostem

🔍 Pokročilé vyhledávání a třídění

• Full-text vyhledávání napříč všemi poli
• Pokročilé filtry podle roku, žánru, kvality
• Víceúrovňové třídění (primární, sekundární, terciární)
• Stránkování pro velké databáze (100+ filmů na stránku)

🔧 Konfigurace a nastavení

• JSON konfigurační soubor (config.json)
• Přepínání zdrojů metadat individuálně
• API klíče pro TMDb a OMDb
• Nastavení watchdog - složky, intervaly, typy souborů
• Export výchozí adresář
• Snapshoty - automatické zálohování po X souborech/minutách

🗄️ Databáze a editace záznamů (detail)

Databáze je implementovaná pomocí SQLite a souboru mfilmdb.sqlite3. Níže jsou hlavní body a doporučení:

• Struktura: více než 30 polí pro jeden záznam (metadata, technické údaje, poznámky).
• Transakce: větší dávkové operace by měly běžet v transakcích, aby byla zajištěna konzistence.
• Zálohy: vytvářejte pravidelné kopie SQLite souboru; před hromadnými změnami doporučeno provést snapshot.
• Wal režim: repository obsahuje WAL/SHM soubory — vhodné pro rychlé zápisy, ale je třeba jej správně spravovat při zálohách.
• Indexy: pro velké sbírky se doporučuje přidat indexy na často filtrovaná pole (rok, žánr, kvalita, hash).

✏️ Editace a hromadné úpravy

• Detailní editor umožňuje ruční úpravy všech polí; změny lze uložit přímo do DB.
• Batch edit: existují nástroje v DEV_TOOLS pro hromadné nahrazení textů, opravy kódování a doplnění chybějících klíčů.
• Rollback: není vestavěný komplexní rollback; zálohování DB je hlavní mechanismus ochrany.

📤 Exporty (detail)

Exportní funkce pokrývají většinu případů použití — níže podrobně:

• CSV — rychlý export pro tabulky; doporučeno pro jednoduché přenosy dat.
• JSON — plná serializace záznamů vhodná pro automatické zpracování a zálohy.
• XLSX — export s vloženými náhledy; užitečné pro reporty, ale větší soubory mohou být pomalé.
• HTML — šablonovatelný export (APP_DATA/templates); doporučeno používat centrální sadu šablon a jednotné cesty k obrázkům.
• ZIP — balíček obsahující HTML + covery; vhodné pro sdílení offline katalogu.

🧰 Doplnkové aplikace — hodnocení a doporučení

1) BBB_Browser (APP_DATA/BBB_Browser)

Účel: nástroj pro prohlížení generovaných výstupů / záloh (BBB = Browser/Backup Builder). Často používaný pro kontrolu offline exportů.

• Klady: rychlé prohlížení exportovaných galerií, jednoduché debugování exportních šablon.
• Zápory: duplicita funkcionality s hlavní aplikací; není integrován do UI jako plugin.
• Doporučení: převést na integrovaný modul nebo plugin systém, aby uživatelé mohli prohlížet výstupy přímo v MFilmDB bez spouštění samostatného nástroje.

2) ThemeAdder (APP_DATA/ThemeAdder_GUI.py)

Účel: grafické přidávání a úprava témat pro ttkbootstrap.

• Klady: uživatelsky přívětivé vytváření barevných schémat, ukládání a načítání témat.
• Zápory: potřeba validace barevných kontrastů a přístupnosti; chybí preview pro různé komponenty.
• Doporučení: přidat náhledy komponent (tlačítka, tabulky, formuláře) a export/import témat ve formátu JSON pro sdílení.

3) ISP Generator (APP_DATA/ISP_Generator_GUI.py)

Účel: generátor posterů/thumbnailů a šablon pro galerie.

• Klady: permite(batch) generování posterů, zdroje šablon vhodné pro HTML exporty.
• Zápory: náročné na I/O při velkém množství souborů; doporučuje se dávkové zpracování mimo GUI.
• Doporučení: přidat frontu úloh s worker procesy a možnost generovat různé velikosti v jedné úloze; přidat fallback pokud chybí zdrojové obrázky.

📝 Časová razítka změn v recenzi

Ukazuje, kdy byly jednotlivé části recenze aktualizovány a jak aktuální je tento dokument:

Recenze aktualizována: 2026-01-02 12:30 UTC

🎨 Uživatelské rozhraní

🖥️ Celkový design

Aplikace využívá ttkbootstrap - moderní wrapper nad Tkinter, který poskytuje 20+ profesionálních témat inspirovaných Bootstrap CSS frameworkem. Uživatelské rozhraní je konzistentní, responzivní a vizuálně přívětivé.

🎭 Témata a přizpůsobení

K dispozici jsou kategorie témat:

• Tmavá témata: darkly, superhero, cyborg, vapor, solar
• Světlá témata: flatly, litera, minty, lumen, sandstone, yeti
• Vlastní témata: možnost vytvořit a uložit vlastní barevné schéma

📐 Rozložení aplikace

⌨️ Ovládání

• Drag & Drop - přetažení souborů/složek do okna aplikace
• Kontextové menu - pravý klik na film
• Klávesové zkratky - rychlý přístup k funkcím
• Double-click - otevření detailu/editace filmu

🌍 Lokalizace

Aplikace podporuje vícejazyčné rozhraní. Plný seznam jazyků je definován v APP_DATA/localize_data.py:

• 🇨🇿 Čeština (CZ)
• 🇬🇧 Angličtina (EN)
• 🇸🇰 Slovenština (SK)
• 🇩🇪 Němčina (DE)
• 🇵🇱 Polština (PL)
• 🇳🇱 Nizozemština (NL)
• 🇫🇷 Francouzština (FR)
• 🇮🇹 Italština (IT)
• 🇫🇮 Finština (FI)
• 🇯🇵 Japonština (JA)
• 🇪🇸 Španělština (ES)
• 🇵🇹 Portugalština (PT)
• 🇷🇺 Ruština (RU)
• 🇻🇳 Vietnamština (VI)
• 🇳🇴 Norština (NO)
• 🇩🇰 Dánština (DA)
• 🇨🇳 Čínština (ZH)
• 🇮🇳 Hindština (HI)
• 🇮🇷 Fársí / Persky (FA)
• 🇹🇷 Turečtina (TR)
• 🇺🇦 Ukrajinština (UK)
• 🇭🇺 Maďarština (HU)
• 🇹🇳 Tamilština (TA)

⭐ Hodnocení

📊 Celkové hodnocení

Interpretace hodnocení: Interně ukládáme hodnocení jako `rating_stars` (celé číslo 1–10) a jako `rating_percent` (0–100) pro exporty a porovnání mezi providery. Při importu hodnocení z externích zdrojů (např. TMDb/ČSFD) aplikace provede normalizaci do 1–10 škály; např. 4.5/5 → 9/10, nebo 82% → 8/10 zaokrouhleně.

Technicky: `rating_stars` je INTEGER sloupec, `rating_percent` je INTEGER (0–100). Pro statistiky a průměrné skóre se používá vážený průměr podle `votes`.

📈 Hodnocení podle kategorií

💡 Doporučení pro rozšíření

🔮 Prioritní vylepšení

1. Integrace s PLEX/Jellyfin - synchronizace knihoven a metadat
2. Web rozhraní - přístup k databázi přes prohlížeč (Flask/FastAPI)
3. Mobilní companion app - základní prohlížení sbírky na telefonu
4. Batch operace - hromadná editace více filmů najednou
5. Statistiky a grafy - vizualizace sbírky (žánry, roky, velikosti)

🎯 Další návrhy

• Plugin systém - snadné přidávání nových zdrojů metadat
• Sledování přehrávání - integrace s VLC/mpv pro tracking
• Doporučovací engine - návrhy filmů podle preferencí
• Zálohovací systém - automatické zálohy do cloudu
• OCR titulky - extrakce názvů z embedded titulků
• AI rozpoznávání - identifikace filmů podle obsahu
• Multi-user podpora - sdílení databáze mezi uživateli

🛠️ Technická doporučení

• Migrace na async/await pro network operace
• Přidání unit testů pro kritické funkce
• Implementace CI/CD pipeline pro automatické buildy
• Vytvoření Docker image pro snadné nasazení
• Zlepšení error handling a logging

📝 Závěr

MFilmDB je solidní nástroj pro správu filmové sbírky s bohatou sadou funkcí. Aplikace vyniká v oblasti automatického enrichmentu metadat a flexibility exportů. Pro běžného uživatele s menší až střední sbírkou filmů představuje výbornou volbu bez nutnosti komplexních řešení typu Plex nebo Emby.

Doporučuji pro: domácí archiváře, filmové nadšence a správce menších mediálních serverů.