ITEM

📋 Application overview

MFilmDB is a desktop application for managing personal film collection, developed in Python using modern GUI framework tttbootstrap. The application is designed for users who want keep track of their films stored on local disks, NAS servers or external media.

TARGET

• Film enthusiasts with large collections of digital films
• Maintainer of home media servers (PLEX, Jellyfin, Kodi)
• Archivist who need to cataloguate media with metadata
• NAS Users with a large amount of video files

SECTION Technology

⚙️ Functions and options

• Management of the film database

The core of the application is a robust database system built on SQLite:

• 30 + data fields for each film (name, original name, year, genre, director, script, camera, music, cast, dubbing, subtitles, length, file size...)

• pdf List of columns in DB (technical overview)

  Technically, most fields are stored in SQLite as a text (varchar) or integer, with several indexes and a full text FTS5 index for quick search. Below is a selection of the most important columns and their purpose:

  • id (INTEGER PRIMARY KEY) - internal record identifier.
  • title, original _ title (TEXT) - standardized names for both display and search.
  • year (INTEGER) - year of issue (range 1900-2099).
  • directors, writers, cast (TEXT) - comma separated lists, or standardized items from 'KNOWN _ ACTORS'.
  • genes, tags (TEXT) - keywords for filtering and exports.
  • duration, resolution, width, height, aspect _ ratio - technical metrics used for filtering and displaying thumbnails.
  • file _ path, file _ name, extension, file _ size, file _ hash - source file and its finger print for detection duplicate.
  • source, quality, codecs, audio _ channels, language - information from filename parser and media- analyser (ffprobe / pymediainfo).
  • dubbing, subtitles, embedded _ subtitles - information on the presence and type of subtitles / dubbing.
  • cover _ path, cover _ hash - relative path to saved cover and hash for update control.
  • rating _ stars (INTEGER 1-10) - internal rating scale for user evaluation or conversion from external sources.
  • rating _ percentage (INTEGER 0-100) - percentage representation (for exports and statistics).
  • Vote - number of votes / source ratings.
  • Imdb _ id, tmdb _ id, csfd _ id, fdb _ id - external identifiers for quick queries on providers.
  • notes, added _ at, modified _ at, last _ scanned - administrative and audit metadata.

  In layman's terms: the database stores everything you want to know about the film - from the name and year to the quality and length to where the file is stored and whether it has subtitles. Thanks to indexes and FTS search you will find the film quickly even in large collections.

• Automatic folder scanning with three modes:
  • ⚡ Quick Scan - fast loading (path, size, format)
  • 🔍 Deep Scan - extraction of metadata from file names and paths
  • 🌐 Full Scan - complete online enrichment from API
• Hash Files for detection of duplicit
• Automatic recognition Year, quality (1080p, 720p, 4K), resources (BluRay, WEB- DL, HDTV)

▶ Name parsing and new content 'APP _ DATA'

In recent modifications the module was significantly expanded APP_DATA/logic.py - now contains a complex function parse_filename_metadata(filename)which extracts and normalizes the following information directly from the filename:

• Title - removing noise (codecs, quality, release tags) and shortened dash keeping readability.
• Year - including abbreviated formats (e.g. '78 → 1978) SHORT_YEAR_RE.
• Episode data - SxxExx, 1x01, EP1234, part / part etc., with support of three / four digits (EPISODE_PATTERNS).
• Actors - extraction from the name according to the extendable list KNOWN_ACTORS (added e.g. Al Pacino, Jean-Claude Van Damme).
• Uploader - recognition (e.g. romin, PeterXi) from the title or brackets (KNOWN_UPLOADERS, UPLOADER_RE).
• Source - BluRay, DVDRip, WEB- DL, DVBT etc. (SOURCE_PATTERNS).
• Dabing / language - detection of CZ / SK / EN and other abbreviations (DUBBING_PATTERNS).
• Subtitles in the image - hardcoded / in the detection panel (SUBTITLES_EMBEDDED_RE).
• Ordinals / serial numbers - prefixes of the type 01,Film Recognized by ORDINAL_PREFIX_RE.

This logic improves the accuracy of the automatic assignment of records to films and facilitates batch processing of large libraries.

Additional added and newly watched files / directories in APP_DATA:

• APP_DATA/GFX/w20-webp/ - set 20 × 20 webp icons (flags) suitable for UI badge; recommended to use a single source of icons for templates.
• APP_DATA/BBB_Browser/ - tools for viewing and generating BBB (backup / browser) outputs; part of DEV tools.
• APP_DATA/ISP_Generator_GUI.py - improved image template generator (poser / ISP).
• APP_DATA/localize_data.py - extended localization phase (new keys) for ~ 23 languages.

SECTION Localization (in detail)

Note to localizations: The full list of supported languages is defined in APP_DATA/localize_data.py. In the current version, these are: CZ, EN, SK, DE, PL, NL, FR, IT, FI, JA, ES, PT, RU, VI, NO, DA, ZH, HI, FA, TR, UK, HU, TA (23 languages in total).

How it works (layman): The user interface has translated texts for buttons, dialogues and progress phases - just select a language in the settings and applications will try to use the available translations.

Technically: Localization are saved as maps key → translation in APP_DATA/localize_data.py. The new phases of the process (phase _ 5,..., phase _ 100) are translated for 23 languages; adding another language is simple: add a dictionary with keys for new locale and update the registers in the file.

Overwriting and supplementing translations: For local modifications, create a file with renamed keys in the user profile folder or use tools in DEV_TOOLS/LocalizeAdder_QT.py.

Note for inventory: I also noticed more (previously untracked) files in the repository tree - for example flags in w20-webp/ and icons in the project root (icon_vav.ico). I recommend that you have these resources centralized and possibly add a manifesto with recommended icons for export templates.

Online enrichment metadata

The application supports automatic metadata download from many sources. Enrichment combines data from multiple providers with fallback logic and confidence scores - that is, if one provider does not have information, the application will try another and select the most reliable value.

Technical Note: For some providers (TMDb, OMDb), the API key is required; for others (CSDD, FDb) are obtained by scraping. Rate- limits and timeouts are respected and applications implement retry / backoff strategy.

The resources provided shall include:

Note: Online enrichment does not cover all public resources - for example specialized catalogues for video clips (IMVDB) may require a special provider. In this version, IMVDB is integrated for music videos, but is limited to files found in folders marked as Video clips (configuration: sources.imvdb). If you need other specialised resources (e.g. local or paid API), add provider to APP_DATA ('search _ *' or wrapper function) and register it in the source settings.

How to decide which provider to use: the application selects according to priority (settings), availability of API (keys), and according to content type - e.g. for video clips, the IMVDB shall be used primarily.

† Image Management (covers)

Covers are important for the application - they are displayed in tables, details and exports. The application uses a combination of local search and online download:

1. Locally covered search - first checks the directory of the film (files with names as cover. *, poser. *, folder. *) and then user-defined directory ('covers _ path' or specified in the settings).
2. SimpleCoverDownloader - if a local cover is not found or the user requests an update, it will download the covers from online providers (TMDb, OMDb, Google Images, etc.).
3. Storage - downloaded / selected covers are saved to folder covers/ (or in the way defined in 'config.json') with formatted names: {tmdb_id|imdb_id|normalized_title}_{year}.{ext}. Example: tt0111161_1994.jpg or Shawshank_Redemption_1994.webp. This ensures consistency and easy identification.
4. Hash & cache - each saved cover is supplemented by 'cover _ hash' in DB for detecting changes and for re-use without unnecessary download.
5. Formats and sizes - recommended formats are WebP or JPG; recommended minimum dimensions for detailed view: 600 × 900px (portrait) or 1280 × 720px (landscape). The application generates smaller thumbs for lists and thumbings.

User Tip: For large collections it is recommended to centralize covers in a separate directory and allow automatic processing (auto _ process _ covers) - this will speed up export and prevent duplicating files.

ITEM Export and Import

Flexible export and import options:

HTML Export Templates

There are 7 predefined templates for HTML export:

1. 01 _ default.html - Basic table appearance
2. 02 _ dark _ modern n.html - Dark modern theme
3. 03 _ netflix _ style.html - Netflix style catalog
4. 04 _ retro _ cinema.html - Retro film look
5. 05 _ minimalist _ light.html - Light minimalist design
6. 06 _ film _ cards.html - Grid of responsive cards with sorting and filtering
7. 07 _ accessible _ cards.html - Accessible cards for the weak-sighted (large text)

--Watchdog - automatic tracking

Integrated file system watcher for automatic detection of new films:

• Monitoring of multiple components simultaneously
• Recursive search sub-components
• Configurable file types (.mp4, .mkv, .avi, .mov, .wmv)
• Automatic import with optional enrichment
• Debound - protection against duplication of events

· Advanced search and sorting

• Full-text search across all fields
• Advanced filters by year, genre, quality
• Multi-level sorting (primary, secondary, tertiary)
• Paging for large databases (100 + movies per page)

‡ Configuration and settings

• JSON configuration file (config.json)
• Switching metadata sources individually
• API keys for TMDb and OMDb
• Watchdog Settings - folders, intervals, file types
• Export default directory
• Snapshots - automatic backup of X files / minutes

SECTION 1

Database is implemented using SQLite and file mfilmdb.sqlite3. The following are the main points and recommendations:

• Structure: more than 30 fields for one entry (metadata, technical data, notes).
• Transactions: larger batch operations should run in transactions to ensure consistency.
• Advances: create regular copies of SQLite file; before mass changes recommended make snapshot.
• Wal scheme: the repository contains WAL / SHM files - suitable for quick writing, but it must be managed correctly when backup is made.
• Indices: for large collections it is recommended to add indices to often filtered fields (year, genre, quality, hash).

SECTION Editing and mass modification

• Detailed editor allows manual modification of all fields; changes can be stored directly into DB.
• Batch edit: there are instruments in DEV_TOOLS for mass replacement of texts, repair of encoding and replenishment of missing keys.
• Rollback: is not built in complex rollback; the backup DB is the main mechanism of protection.

Non-cooperating exporting producers

Export functions cover most of the applications - details below:

• CSV - fast export for tables; recommended for simple data transfers.
• JSON - full serialization of records suitable for automatic processing and backup.
• XLSX - export with embedded thumbnails; useful for reports, but larger files can be slow.
• HTML - sabbatical export (APP _ DATA / templates); recommended to use the central set of templates and uniform paths to images.
• ZIP - package containing HTML + covers; suitable for sharing offline catalogue.

• Additional applications - evaluation and recommendations

1) BBB _ Browser (APP _ DATA / BBB _ Browser)

Purpose: tool for viewing generated outputs / backups (BBB = Browser / Backup Builder). Often used to check offline exports.

• Props: quick viewing of exported galleries, simple debuging of export templates.
• Negative: duplicity of functionality with the main application; it is not integrated into the UI as a plugin.
• Recommendation: convert the integrated module or plugin system so that users can view outputs directly in the MPillDB without launching a separate tool.

2) ThemeAdder (APP _ DATA / ThemeAdder _ GUI.py)

Purpose: graphic addition and modification of topics for tttbootstrap.

• Props: user friendly creation of color schemes, storage and reading of topics.
• Negative: need for validation of colour contrast and accessibility; no previews are available for different components.
• Recommendation: add component thumbnails (buttons, tables, forms) and export / import of JSON-sharing themes.

3) ISP Generator (APP _ DATA / ISP _ Generator _ GUI.py)

Purpose: Poster generator / thumbnails and templates for galleries.

• Props: permite (batch) generation of postures, source templates suitable for HTML exports.
• Negative: I / O intensive for a large number of files; batch processing is recommended outside the GUI.
• Recommendation: add a queue of tasks with the worker processes and the possibility to generate different sizes in one task; add fallback if source images are missing.

† Time stamps changes in the review

Shows when the individual parts of the review have been updated and how up to date this document is:

Review updated: 2026-01-02 12: 30 UTC

🎨 User interface

Total design

Application uses ttkbootstrap - modern wrapper above the Tkinter, which provides 20 + professional topics inspired by Bootstrap CSS framework. The user interface is consistent, responsive and visually welcoming.

SECTION 3

There are categories of topics:

• Dark topics: Darkly, Superhero, Cyborg, Warp, Solar
• Light topics: flatly, letter, mint, lumen, sandstone, yeti
• Own topics: possibility to create and save custom color scheme

• Application layout

Driving

• Drag & Drop - drag files / folders into the application window
• Context menu - right click on the movie
• Keyboard abbreviations - quick access to functions
• Double-click - opening of the film detail / editing

SECTION Localization

The application supports a multilingual interface. The full list of languages is defined in APP_DATA/localize_data.py:

• © Czech (CZ)
• United Kingdom (EN)
• IRELAND
• WRITTEN GERMAN (DE)
• SECTION II
• JUDGMENT Dutch (NL)
• © French (FR)
• IRELAND (IT)
• ITEM Finnish (FI)
• ITEM Japanese (JA)
• © Spanish (ES)
• United Kingdom (PT)
• ITEM Russian (RU)
• Vietnamese (VI)
• © Norwegian (NO)
• ITEM Danish (DA)
• ITEM Chinese (ZH)
• ITEM Hindi (HI)
• ITEM Farsi / Persian (FA)
• ITEM Turkish (TR)
• IRELAND (UK)
• ITEM Hungarian (HU)
• ITEM Tamil (TA)

⭐ Evaluation

Overall evaluation

Interpretation of evaluation: We internally store ratings as' rating _ stars' (integer 1-10) and 'rating _ percentage' (0-100) for exports and comparison between providers. When importing evaluations from external sources (e.g. TMDb / CSDD) application will normalize to 1-10 scale; e.g. 4.5 / 5 → 9 / 10, or 82% → 8 / 10 rounded off.

Technically: 'rating _ stars' is an INTEGER column, 'rating _ percentage' is an INTEGER (0-100). For statistics and average scores, the weighted average is used by 'votes'.

(b) Assessment by category

💡 Enlargement recommendations

• Priority improvements

1. Integration with PLEX / Jellyfin - synchronization of libraries and metadata
2. Web interface - access to database via browser (Flash / FastAPI)
3. Mobile company app - basic viewing of the collection on your phone
4. Batch operations - mass editing of multiple films at once
5. Statistics and graphs - visualization of collection (genres, years, sizes)

• Other proposals

• Plugin system - easy addition of new metadata sources
• Monitoring of playback - integration with VLC / mpv for tracking
• Recommended engine - motion picture design
• Backup system - automatic cloud backup
• _ - extraction of titles from embedded subtitles
• AI Recognition - identification of films by content
• Multi-user support - database sharing between users

Technical recommendations

• Migration to async / await for network operations
• Addition unit of tests for critical functions
• Implementation CI / CD pipeline for automatic building
• Creation Docker image for easy deployment
• Improvements error handling a logging

Conclusion

The MFilmDB is a solid tool for managing the film collection with a rich set of functions. The application excels in the field of automatic metadata enrichment and flexibility of exports. For ordinary users with a smaller to medium film collection, it represents excellent choice without the need for complex solutions Plex or Emby type.

I recommend for: Home archivist, film enthusiasts and administrator of smaller media servers.