How tagstudiodev/tagstudio works
Project type and purpose
• TagStudio is a cross-platform desktop application written in Python, with a Qt-based GUI front end and a core library back end responsible for file tagging, querying, and storage.
• It manages user libraries on disk, stores metadata in a .TagStudio folder per library (SQLite or JSON back ends), and invokes external tools (e.g., FFmpeg) for media previews.
File structure
• Top-level “src/tagstudio/core”: contains the core engine—database drivers, query language, library abstractions, utility functions.
• “src/tagstudio/qt”: contains the GUI layer—controllers, views, helpers, platform strings, resource loading, preview renderers.
• “pyproject.toml”, “flake.nix” / “nix/”: build, dependency, and packaging configurations.
• Tests live under “tests/”; docs under “docs/” / “mkdocs.yml”.
README insights
• Core features: library scanning, file tagging, custom metadata fields, search engine with AST-based parser.
• External dependencies: SQLite (via SQLAlchemy), optional JSON back end, Qt (PySide/PyQt), FFmpeg for media, ripgrep recommended for faster scans.
Main components & their interactions
a. Frontend (Qt GUI)
• Views: Qt widgets (main window, panels, dialogs).
• Controllers: respond to user events, call core driver.
• Preview Renderer: calls FFmpeg or bundled renderers (pydub, blender) to generate thumbnails/previews.
b. Backend/Core
• Driver/API (core/driver.py): single entry point for GUI & CLI to execute operations (scan, search, tag, field CRUD).
• Library Abstraction: two back ends—SQLAlchemy (SQLite) and JSON—implementing same interface.
• Query Language: tokenizer, parser, AST evaluator.
• Utilities: file‐system scanning, singleton management, subprocess wrappers, encoding helpers.
c. Storage
• .TagStudio/ts_library.sqlite or ts_library.json in user’s library folder.
• SQLAlchemy ORM models map to tables (tags, entries, fields, joins).
d. External Services
• FFmpeg CLI invoked for video/audio thumbnails.
• ripgrep (optional) for faster directory scans.
• Blender renderer (vendored) for specialized previews.
e. Build / Packaging
• pyproject.toml for dependencies.
• Nix flake + shell for reproducible dev environments.
• PyInstaller spec (tagstudio.spec) for creating executables.
Architectural patterns & design principles
• Layered Architecture (GUI → Core → Storage).
• Strategy Pattern for swappable back ends (SQL vs JSON).
• MVC/MVP-style separation: controllers mediate between Qt views and core driver.
• Plugin‐like modules for previews under qt/previews/vendored.