Merge remote-tracking branch 'upstream/main' into test

Author: DandyDev01

.github/workflows/pytest.yaml

@@ -5,7 +5,7 @@ on: [ push, pull_request ]
 jobs:
   pytest:
     name: Run tests
-    runs-on: ubuntu-22.04
+    runs-on: ubuntu-24.04
 
     steps:
       - name: Checkout repo
@@ -20,11 +20,12 @@ jobs:
       - name: Install system dependencies
         run: |
           # dont run update, it is slow
-          # sudo apt-get update
+          sudo apt-get update
           sudo apt-get install -y --no-install-recommends \
             libxkbcommon-x11-0 \
             x11-utils \
             libyaml-dev \
+            libgl1 \
             libegl1 \
             libxcb-icccm4 \
             libxcb-image0 \

CONTRIBUTING.md

@@ -1,6 +1,6 @@
 # Contributing to TagStudio
 
-_Last Updated: November 19th, 2024_
+_Last Updated: December 12th, 2024_
 
 Thank you so much for showing interest in contributing to TagStudio! Here are a set of instructions and guidelines for contributing code or documentation to the project. This document will change over time, so make sure that your contributions still line up with the requirements here before submitting a pull request.
 
@@ -14,6 +14,7 @@ Thank you so much for showing interest in contributing to TagStudio! Here are a
 -   Check the [Feature Roadmap](/docs/updates/roadmap.md) page to see what priority features there are, the [FAQ](/README.md/#faq), as well as the open [Issues](https://github.com/TagStudioDev/TagStudio/issues) and [Pull Requests](https://github.com/TagStudioDev/TagStudio/pulls).
 -   If you'd like to add a feature that isn't on the feature roadmap or doesn't have an open issue, **PLEASE create a feature request** issue for it discussing your intentions so any feedback or important information can be given by the team first.
     -   We don't want you wasting time developing a feature or making a change that can't/won't be added for any reason ranging from pre-existing refactors to design philosophy differences.
+- **Please don't** create pull requests that consist of large refactors, *especially* without discussing them with us first. These end up doing more harm than good for the project by continuously delaying progress and disrupting everyone else's work.
 -   If you wish to discuss TagStudio further, feel free to join the [Discord Server](https://discord.com/invite/hRNnVKhF2G)
 
 ### Contribution Checklist
@@ -150,9 +151,6 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
 
 ### Commit and Pull Request Style
 
-> [!CAUTION]
-> Please do not close and re-open pull requests. This makes it **much** more difficult to re-pull during reviews. If you would like to signal that your pull request is not ready, please mark is as a draft instead.
-
 -   Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0) as a guideline for commit messages. This allows us to easily generate changelogs for releases.
     -   See some [examples](https://www.conventionalcommits.org/en/v1.0.0/#examples) of what this looks like in practice.
 -   Use clear and concise commit messages. If your commit does too much, either consider breaking it up into smaller commits or providing extra detail in the commit description.

README.md

@@ -3,38 +3,51 @@
 FFmpeg is required for thumbnail previews and playback features on audio and video files. FFmpeg is a free Open Source project dedicated to the handling of multimedia (video, audio, etc) files. For more information, see their official website at [ffmpeg.org](https://www.ffmpeg.org/).
 
 ## Installation on Windows
+
 ### Prebuilt Binaries
-Pre-built binaries from trusted sources are available on the [FFmpeg website](https://www.ffmpeg.org/download.html#build-windows). To install:
+
+Pre-built binaries from trusted sources are available on the [FFmpeg website](https://www.ffmpeg.org/download.html). Under "More downloading options" click on the Windows section, then under "Windows EXE Files" select a source to download a build from. Follow any further download instructions from whichever build website you choose.
+
+![Windows Download Location](../assets/ffmpeg_windows_download.png)
+
+!!! note
+    Do NOT download the source code by mistake!
+
+To Install:
 
 1. Download 7z or zip file and extract it (right click > Extract All)
 2. Move extracted contents to a unique folder (i.e; `c:\ffmpeg` or `c:\Program Files\ffmpeg`)
-3. Add FFmpeg to your PATH 
+3. Add FFmpeg to your system PATH
 
-    1. Go to "Edit the system environment variables"
-    2. Under "User Variables", select "Path" then edit
-    3. Click new and add `<Your folder>\bin` (e.g; `c:\ffmpeg\bin` or `c:\Program Files\ffmpeg\bin`)
-    4. Click okay
+   1. In Windows, search for or go to "Edit the system environment variables" under the Control Panel
+   2. Under "User Variables", select "Path" then edit
+   3. Click new and add `<Your folder>\bin` (e.g; `c:\ffmpeg\bin` or `c:\Program Files\ffmpeg\bin`)
+   4. Click "Okay"
 
 ### Package Managers
+
 FFmpeg is also available from:
 
 1. WinGet (`winget install ffmpeg`)
 2. Scoop (`scoop install main/ffmpeg`)
 3. Chocolatey (`choco install ffmpeg-full`)
 
 ## Installation on Mac
+
 ### Homebrew
-FFmpeg is available via [Homebrew](https://brew.sh/) and can be installed via:
 
-`brew install ffmpeg`
+FFmpeg is available under the macOS section of the [FFmpeg website](https://www.ffmpeg.org/download.html) or can be installed via [Homebrew](https://brew.sh/) using `brew install ffmpeg`.
 
 ## Installation on Linux
+
 ### Package Managers
+
 FFmpeg may be installed by default on some Linux distributions, but if not, it is available via your distro's package manager of choice:
 
 1. Debian/Ubuntu (`sudo apt install ffmpeg`)
 2. Fedora (`sudo dnf install ffmpeg-free`)
 3. Arch (`sudo pacman -S ffmpeg`)
 
 # Help
+
 For additional help, please join the [Discord](https://discord.gg/hRNnVKhF2G) or create an Issue on the [GitHub repository](https://github.com/TagStudioDev/TagStudio)

docs/assets/db_schema.png

@@ -9,39 +9,61 @@ title: Home
 
 ![TagStudio Alpha](assets/github_header.png)
 
-TagStudio is a photo & file organization application with an underlying system that focuses on giving freedom and flexibility to the user. No proprietary programs or formats, no sea of sidecar files, and no complete upheaval of your filesystem structure.
+TagStudio is a photo & file organization application with an underlying tag-based system that focuses on giving freedom and flexibility to the user. No proprietary programs or formats, no sea of sidecar files, and no complete upheaval of your filesystem structure.
 
-<figure markdown="span">
+<figure width="60%" markdown="span">
   ![TagStudio screenshot](assets/screenshot.jpg)
-  <figcaption>TagStudio Alpha v9.1.0 running on Windows 10</figcaption>
+  <figcaption>TagStudio Alpha v9.4.2 running on Windows 10</figcaption>
 </figure>
 
 ## Goals
 
--   To achieve a portable, privacy-oriented, open, extensible, and feature-rich system of organizing and rediscovering files.
--   To provide powerful methods for organization, notably the concept of tag composition, or “taggable tags”.
--   To create an implementation of such a system that is resilient against a user’s actions outside the program (modifying, moving, or renaming files) while also not burdening the user with mandatory sidecar files or otherwise requiring them to change their existing file structures and workflows.
--   To support a wide range of users spanning across different platforms, multi-user setups, and those with large (several terabyte) libraries.
--   To make the darn thing look like nice, too. It’s 2024, not 1994.
+- To achieve a portable, private, extensible, open-format, and feature-rich system of organizing and rediscovering files.
+- To provide powerful methods for organization, notably the concept of tag inheritance, or “taggable tags” _(and in the near future, the combination of composition-based tags)._
+- To create an implementation of such a system that is resilient against a user’s actions outside the program (modifying, moving, or renaming files) while also not burdening the user with mandatory sidecar files or requiring them to change their existing file structures and workflows.
+- To support a wide range of users spanning across different platforms, multi-user setups, and those with large (several terabyte) libraries.
+- To make the darn thing look like nice, too. It’s 2024, not 1994.
 
 ## Priorities
 
-1. **The concept.** Even if TagStudio as a project or application fails, I’d hope that the idea lives on in a superior project. The [goals](#goals) outlined above don’t reference TagStudio once - _TagStudio_ is what references the _goals._
+1. **The concept.** Even if TagStudio as an application fails, I’d hope that the idea lives on in a superior project. The [goals](#goals) outlined above don’t reference TagStudio once - _TagStudio_ is what references the _goals._
 2. **The system.** Frontends and implementations can vary, as they should. The core underlying metadata management system is what should be interoperable between different frontends, programs, and operating systems. A standard implementation for this should settle as development continues. This opens up the doors for improved and varied clients, integration with third-party applications, and more.
 3. **The application.** If nothing else, TagStudio the application serves as the first (and so far only) implementation for this system of metadata management. This has the responsibility of doing the idea justice and showing just what’s possible when it comes to user file management.
-4. (The name.) I think it’s fine for an app or client, but it doesn’t really make sense for a system or standard. I suppose this will evolve with time.
+4. (The name.) I think it’s fine for an app or client, but it doesn’t really make sense for a system or standard. I suppose this will evolve with time...
 
 ## Feature Roadmap
 
 The [Feature Roadmap](updates/roadmap.md) lists all of the planned core features for TagStudio to be considered "feature complete" along with estimated release milestones. The development and testing of these features takes priority over all other requested or submitted features unless they are later added to this roadmap. This helps ensure that TagStudio eventually sees a full release and becomes more usable by more people more quickly.
 
 ## Current Features
 
--   Create libraries/vaults centered around a system directory. Libraries contain a series of entries: the representations of your files combined with metadata fields. Each entry represents a file in your library’s directory, and is linked to its location.
--   Add metadata to your library entries, including:
-    -   Name, Author, Artist (Single-Line Text Fields)
-    -   Description, Notes (Multiline Text Fields)
-    -   Tags, Meta Tags, Content Tags (Tag Boxes)
--   Create rich tags composed of a name, a list of aliases, and a list of “subtags” - being tags in which these tags inherit values from.
--   Search for entries based on tags, ~~metadata~~ (TBA), or filenames/filetypes (using `filename: <query>`)
--   Special search conditions for entries that are: `untagged`/`no tags` and `empty`/`no fields`.
+### Libraries
+
+- Create libraries/vaults centered around a system directory. Libraries contain a series of entries: the representations of your files combined with metadata fields. Each entry represents a file in your library’s directory, and is linked to its location.
+- Address moved, deleted, or otherwise "unlinked" files by using the "Fix Unlinked Entries" option in the Tools menu.
+
+### Metadata + Tagging
+
+- Add metadata to your library entries, including:
+  - Name, Author, Artist (Single-Line Text Fields)
+  - Description, Notes (Multiline Text Fields)
+  - Tags, Meta Tags, Content Tags (Tag Boxes)
+- Create rich tags composed of a name, a list of aliases, and a list of “parent tags” - being tags in which these tags inherit values from.
+- Copy and paste tags and fields across file entries
+- Generate tags from your existing folder structure with the "Folders to Tags" macro (NOTE: these tags do NOT sync with folders after they are created)
+
+### Search
+
+- Search for entries based on tags, ~~metadata~~ (TBA), or filenames/filetypes (using `filename: <query>`).
+- Special search conditions for entries that are: `untagged` and `empty`.
+
+### File Entries
+
+- All\* file types are supported in TagStudio libraries - just not all have dedicated thumbnail support.
+- Preview most image file types, animated GIFs, videos, plain text documents, audio files\*\*, Blender projects, and more!
+- Open files or file locations by right-clicking on thumbnails and previews and selecting the respective context menu options. You can also click on the preview panel image to open the file, and click the file path label to open its location.
+- Delete files from both your library and drive by right-clicking the thumbnail(s) and selecting the "Move to Trash"/"Move to Recycle Bin" option.
+
+> _\* Weird files with no extension or files such as ".\_DS_Store" currently have limited support._
+>
+> _\*\* Audio playback coming in v9.5_

docs/assets/ffmpeg_windows_download.png

@@ -156,7 +156,7 @@ These version milestones are rough estimations for when the previous core featur
 
 ### 9.5 (Alpha)
 
--   [ ] SQL backend [HIGH]
+-   [x] SQL backend [HIGH]
 -   [ ] Translations _(Any applicable)_ [MEDIUM]
 -   [ ] Multiple Root Directories per Library [HIGH]
 -   [ ] Tags [HIGH]
@@ -169,11 +169,16 @@ These version milestones are rough estimations for when the previous core featur
         -   [ ] Existing colors are now a set of base colors [HIGH]
             -   [ ] Editable [MEDIUM]
             -   [ ] Non-removable [HIGH]
+    -   [ ] [Tag Categories](../library/tag_categories.md) [HIGH]
+        -   [ ] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title [HIGH]
 -   [ ] Search engine [HIGH]
     -   [ ] Boolean operators [HIGH]
     -   [ ] Tag objects + autocomplete [HIGH]
-    -   [ ] Filename search [HIGH]
-    -   [ ] Filetype search [HIGH]
+    -   [x] Filename search [HIGH]
+    -   [x] Filetype search [HIGH]
+        -   [x] Search by extension (e.g. ".jpg", ".png") [HIGH]
+            -   [ ] Optional consolidation of extension synonyms (i.e. ".jpg" can equal ".jpeg") [LOW]
+        -   [x] Search by media type (e.g. "image", "video", "document") [MEDIUM]
     -   [ ] Field content search [HIGH]
     -   [ ] Sortable results [HIGH]
         -   [ ] Sort by relevance [HIGH]
@@ -200,8 +205,6 @@ These version milestones are rough estimations for when the previous core featur
         -   [ ] Built-in Icon Packs (i.e. Boxicons) [HIGH]
         -   [ ] User Defined Icons [HIGH]
     -   [ ] Multiple Languages for Tag Strings [MEDIUM]
-    -   [ ] [Tag Categories](../library/tag_categories.md) [HIGH]
-        -   [ ] Property available for tags that allow the tag and any inheriting from it to be displayed separately in the preview panel under a title [HIGH]
         -   [ ] Title is tag name [HIGH]
         -   [ ] Title has tag color [MEDIUM]
         -   [ ] Tag marked as category does not display as a tag itself [HIGH]

docs/assets/screenshot.jpg

@@ -1,4 +1,4 @@
-ruff==0.6.4
+ruff==0.8.1
 pre-commit==3.7.0
 pytest==8.2.0
 Pyinstaller==6.6.0