mirror of
https://github.com/TagStudioDev/TagStudio.git
synced 2026-01-28 22:01:24 +00:00
chore: bump version to v9.5.0 Pre-Release 1; update docs (#751)
* chore: change version branch to "Pre-Release 1" * docs: update docstring for JSON `open_library()` Update method docstring with exact starting and ending versions now that they exist. * docs: update README, CONTRIBUTING.md, & index.md * docs: update roadmap * docs: fix typo in README, change callout * docs: update docs site with v9.5 features * docs: remove warning from index.md
This commit is contained in:
Travis Abendshien
committed by
GitHub
GitHub
parent
1b3b32de22
commit
880c8ef45f
@@ -1,20 +1,15 @@
|
||||
# Contributing to TagStudio
|
||||
|
||||
_Last Updated: December 12th, 2024_
|
||||
_Last Updated: January 30th, 2025_
|
||||
|
||||
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.
|
||||
|
||||
> [!CAUTION]
|
||||
> **As of Pull Request [#332](https://github.com/TagStudioDev/TagStudio/pull/332) (SQLite Migration) the `main` branch will marked as experimental before full JSON to SQL parity is operational.** Existing TagStudio libraries are not yet compatible with this change, however they will **NOT be corrupted or deleted** if opened with these versions. Once parity is reached and a stable conversion tool in place, this notice will be removed. UPDATE: As of November 19th, 2024, full parity is rapidly approaching.
|
||||
>
|
||||
> For the most recent stable feature release branch, see the [`Alpha-v9.4`](https://github.com/TagStudioDev/TagStudio/tree/Alpha-v9.4) branch. These v9.4 specific features are currently being backported to the SQL-ized `main` branch. (Feel free to help!)
|
||||
|
||||
## Getting Started
|
||||
|
||||
- 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.
|
||||
- **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
|
||||
@@ -141,13 +136,14 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
|
||||
|
||||
### Modules & Implementations
|
||||
|
||||
- **Do not** modify legacy library code in the `src/core/library/json/` directory
|
||||
- Avoid direct calls to `os`
|
||||
- Use `Pathlib` library instead of `os.path`
|
||||
- Use `platform.system()` instead of `os.name` and `sys.platform`
|
||||
- Don't prepend local imports with `tagstudio`, stick to `src`
|
||||
- Use the `logger` system instead of `print` statements
|
||||
- Avoid nested f-strings
|
||||
- Use HTML-like tags inside Qt widgets over stylesheets where possible.
|
||||
- Use HTML-like tags inside Qt widgets over stylesheets where possible
|
||||
|
||||
### Commit and Pull Request Style
|
||||
|
||||
@@ -159,7 +155,7 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
|
||||
|
||||
> [!IMPORTANT]
|
||||
> Please do not force push if your PR is open for review!
|
||||
>
|
||||
>
|
||||
> Force pushing makes it impossible to discern which changes have already been reviewed and which haven't. This means a reviewer will then have to rereview all the already reviewed code, which is a lot of unnecessary work for reviewers.
|
||||
|
||||
> [!TIP]
|
||||
@@ -172,9 +168,9 @@ Most of the style guidelines can be checked, fixed, and enforced via Ruff. Older
|
||||
- macOS: 12.0+
|
||||
- Linux: _Varies_
|
||||
- Final code must **_NOT:_**
|
||||
- Contain superfluous or unnecessary logging statements.
|
||||
- Cause unreasonable slowdowns to the program outside of a progress-indicated task.
|
||||
- Cause undesirable visual glitches or artifacts on screen.
|
||||
- Contain superfluous or unnecessary logging statements
|
||||
- Cause unreasonable slowdowns to the program outside of a progress-indicated task
|
||||
- Cause undesirable visual glitches or artifacts on screen
|
||||
|
||||
## Documentation Guidelines
|
||||
|
||||
|
||||
138
README.md
138
README.md
@@ -12,44 +12,42 @@
|
||||
|
||||
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. **Read the documentation and more at [docs.tagstud.io](https://docs.tagstud.io)!**
|
||||
|
||||
> [!CAUTION]
|
||||
> As of Pull Request [#332](https://github.com/TagStudioDev/TagStudio/pull/332) (SQLite Migration) the `main` branch will be an open test bed to get full JSON to SQL parity operational. This notice will be removed once parity between v9.4 and v9.5 is reached.
|
||||
>
|
||||
> For the most recent stable feature release branch, see the [`Alpha-v9.4`](https://github.com/TagStudioDev/TagStudio/tree/Alpha-v9.4) branch. These v9.4 specific features are currently being backported to the SQL-ized `main` branch. [Feel free to help!](/CONTRIBUTING.md)
|
||||
|
||||
> [!NOTE]
|
||||
> Thank you for being patient as we've migrated our database backend from JSON to SQL! The previous warnings about the main branch being experimental and unsupported have now been removed, and any pre-existing library save files created with official TagStudio releases are able to be opened and migrated with the new v9.5+ releases!
|
||||
|
||||
> [!IMPORTANT]
|
||||
> This project is still in an early state. There are many missing optimizations and QoL features, as well as the presence of general quirks and occasional jankiness. Making frequent backups of your library save data is **always** important, regardless of what state the program is in.
|
||||
>
|
||||
> With this in mind, TagStudio will _NOT:_
|
||||
>
|
||||
> - Touch, move, or mess with your files in any way _(unless explicitly using the "Delete File(s)" feature, which is locked behind a confirmation dialog)_.
|
||||
> - Ask you to recreate your tags or libraries after new releases. It's our highest priority to ensure that your data safely and smoothly transfers over to newer versions.
|
||||
> - Cause you to suddenly be able to recall your 10 trillion downloaded images that you probably haven't even seen firsthand before. You're in control here, and even tools out there that use machine learning still needed to be verified by human eyes before being deemed accurate.
|
||||
> - Touch, move, or mess with your files in any way _(unless explicitly using the "Delete File(s)" feature, which is locked behind a confirmation dialog)_.
|
||||
> - Ask you to recreate your tags or libraries after new releases. It's our highest priority to ensure that your data safely and smoothly transfers over to newer versions.
|
||||
> - Cause you to suddenly be able to recall your 10 trillion downloaded images that you probably haven't even seen firsthand before. You're in control here, and even tools out there that use machine learning still needed to be verified by human eyes before being deemed accurate.
|
||||
|
||||
<p align="center">
|
||||
<img width="80%" src="docs/assets/screenshot.jpg" alt="TagStudio Screenshot">
|
||||
<img width="80%" src="docs/assets/screenshot.png" alt="TagStudio Screenshot">
|
||||
</p>
|
||||
<p align="center">
|
||||
<i>TagStudio Alpha v9.4.2 running on Windows 10.</i>
|
||||
<i>TagStudio Alpha v9.5.0 running on macOS Sequoia.</i>
|
||||
</p>
|
||||
|
||||
## Contents
|
||||
|
||||
- [Goals](#goals)
|
||||
- [Priorities](#priorities)
|
||||
- [Current Features](#current-features)
|
||||
- [Contributing](#contributing)
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [FAQ](#faq)
|
||||
- [Goals](#goals)
|
||||
- [Priorities](#priorities)
|
||||
- [Current Features](#current-features)
|
||||
- [Contributing](#contributing)
|
||||
- [Installation](#installation)
|
||||
- [Usage](#usage)
|
||||
- [FAQ](#faq)
|
||||
|
||||
## Goals
|
||||
|
||||
- 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 dang thing look nice, too. It’s 2025, not 1995.
|
||||
- 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 dang thing look nice, too. It’s 2025, not 1995.
|
||||
|
||||
## Priorities
|
||||
|
||||
@@ -68,37 +66,35 @@ Translation hosting generously provided by [Weblate](https://weblate.org/en/). C
|
||||
|
||||
### 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.
|
||||
- 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.
|
||||
|
||||
### Tagging + Custom Metadata
|
||||
|
||||
- Add custom powerful tags to your library entries
|
||||
- Add metadata to your library entries, including:
|
||||
- Name, Author, Artist (Single-Line Text Fields)
|
||||
- Description, Notes (Multiline Text Fields)
|
||||
- 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)
|
||||
- Add custom powerful tags to your library entries
|
||||
- Add metadata to your library entries, including:
|
||||
- Name, Author, Artist (Single-Line Text Fields)
|
||||
- Description, Notes (Multiline Text Fields)
|
||||
- Create rich tags composed of a name, color, a list of aliases, and a list of “parent tags” - these being tags in which these tags inherit values from.
|
||||
- Copy and paste tags and fields across file entries
|
||||
- Automatically organize tags into groups based on parent tags marked as "categories"
|
||||
- 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`.
|
||||
- Search for file entries based on tags, file path (`path:`), file types (`filetype:`), and even media types! (`mediatype:`)
|
||||
- Use and combine boolean operators (`AND`, `OR`, `NOT`) along with parentheses groups, quotation escaping, and underscore substitution to create detailed search queries
|
||||
- Use special search conditions (`special:untagged` and `special:empty`) to find file entries without tags or fields, respectively
|
||||
|
||||
### 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_
|
||||
- Nearly 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.
|
||||
|
||||
> [!NOTE]
|
||||
> For more information on the project itself, please see the [FAQ](#faq) section as well as the [documentation](https://docs.tagstud.io/).
|
||||
> For more information on the project itself, please see the [FAQ](#faq) section as well as the [documentation](https://docs.tagstud.io/)!
|
||||
|
||||
## Installation
|
||||
|
||||
@@ -114,7 +110,7 @@ To download TagStudio, visit the [Releases](https://github.com/TagStudioDev/TagS
|
||||
|
||||
### Third-Party Dependencies
|
||||
|
||||
- For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system.
|
||||
- For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system. If you encounter any issues with this, please reference our [FFmpeg Help](/docs/help/ffmpeg.md) guide.
|
||||
|
||||
### Optional Arguments
|
||||
|
||||
@@ -134,14 +130,13 @@ With TagStudio opened, start by creating a new library or opening an existing on
|
||||
|
||||
### Refreshing the Library
|
||||
|
||||
In order to scan for new files or file changes, you’ll need to manually go to File -> Refresh Directories.
|
||||
|
||||
> [!NOTE]
|
||||
> In the future, library refreshing will also be automatically done in the background, or additionally on app startup.
|
||||
Libraries under 10,000 files automatically scan for new or modified files when opened. In order to refresh the library manually, select "Refresh Directories" under the File menu.
|
||||
|
||||
### Adding Tags to File Entries
|
||||
|
||||
Click the "Add Tag" button at the bottom of the preview panel with one or more tags selected. Search for existing inside the new dialog popup or create a new one from here. Click the “+” button next to whichever tags you want to add. Alternatively, after you search for a tag, press the Enter/Return key to add the first item in the list. Press Enter/Return once more to close the dialog box.
|
||||
Access the "Add Tag" search box by either clicking on the "Add Tag" button at the bottom of the right sidebar, accessing the "Add Tags to Selected" option from the File menu, or by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd>.
|
||||
|
||||
From here you can search for existing tags or create a new one if the one you're looking for doesn't exist. Click the “+” button next to any tags you want to to the currently selected file entries. To quickly add the top result, press the <kbd>Enter</kbd>/<kbd>Return</kbd> key to add the the topmost tag and reset the tag search. Press <kbd>Enter</kbd>/<kbd>Return</kbd> once more to close the dialog box. By using this method, you can quickly add various tags in quick succession just by using the keyboard!
|
||||
|
||||
To remove a tag from a file entry, hover over the tag in the preview panel and click on the "-" icon that appears.
|
||||
|
||||
@@ -160,33 +155,39 @@ Hover over the field and click the pencil icon. From there, add or edit text in
|
||||
|
||||
### Creating Tags
|
||||
|
||||
To create a new tag, click on Edit -> New Tag from the menu bar. From there, enter a tag name, shorthand name, any tag aliases separated by newlines, any subtags, and an optional color.
|
||||
Create a new tag by accessing the "New Tag" option from the Edit menu or by pressing <kbd>Ctrl</kbd>+<kbd>T</kbd>. In the tag creation panel, enter a tag name, optional shorthand name, optional tag aliases, optional parent tags, and an optional color.
|
||||
|
||||
- The tag **shorthand** is a type of alias that displays in situations when screen space is more valuable (ex. as a subtag for other tags).
|
||||
- **Aliases** are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
|
||||
- **Subtags** are tags in which this tag is a child tag of. In other words, tags under this section are parents of this tag. For example, if you had a tag for a character from a show, you would make the show a subtag of this character. This would display as “Character (Show)” in most areas of the app. The first tag in this list is used as the tag shown in parentheses for specification.
|
||||
- The **color** dropdown lets you select an optional color for this tag to display as.
|
||||
- The tag **name** is the base name of the tag. **_This does NOT have to be unique!_**
|
||||
- The tag **shorthand** is a special type of alias that displays in situations where screen space is more valuable, notably with name disambiguation.
|
||||
- **Aliases** are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
|
||||
- **Parent Tags** are tags in which this this tag can substitute for in searches. In other words, tags under this section are parents of this tag.
|
||||
- Parent tags with the disambiguation check next to them will be used to help disambiguate tag names that may not be unique.
|
||||
- For example: If you had a tag for "Freddy Fazbear", you might add "Five Nights at Freddy's" as one of the parent tags. If the disambiguation box is checked next to "Five Nights at Freddy's" parent tag, then the tag "Freddy Fazbear" will display as "Freddy Fazbear (Five Nights at Freddy's)". Furthermore, if the "Five Nights at Freddy's" tag has a shorthand like "FNAF", then the "Freddy Fazbear" tag will display as "Freddy Fazbear (FNAF)".
|
||||
- The **color** option lets you select an optional color palette to use for your tag.
|
||||
- The **"Is Cagegory"** property lets you treat this tag as a category under which itself and any child tags inheriting from it will be sorted by inside the preview panel.
|
||||
|
||||
### Editing Tags
|
||||
|
||||
To edit a tag, right-click the tag in the tag field of the preview pane and select “Edit Tag”
|
||||
To edit a tag, click on it inside the preview panel or right-click the tag and select “Edit Tag” from the context menu.
|
||||
|
||||
### Relinking Renamed/Moved Files
|
||||
### Relinking Moved Files
|
||||
|
||||
Inevitably, some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red tag with a cross through it _(this icon is also used for items with broken thumbnails)._ To relink moved files or delete these entries, go to Tools -> Manage Unlinked Entries. Click the “Refresh” button to scan your library for unlinked entries. Once complete, you can attempt to “Search & Relink” any unlinked entries to their respective files, or “Delete Unlinked Entries” in the event the original files have been deleted and you no longer wish to keep their metadata entries inside your library.
|
||||
Inevitably some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red broken chain link. To relink moved files or delete these entries, select the "Manage Unlinked Entries" option under the Tools menu. Click the "Refresh" button to scan your library for unlinked entries. Once complete, you can attempt to “Search & Relink” any unlinked file entries to their respective files, or “Delete Unlinked Entries” in the event the original files have been deleted and you no longer wish to keep their entries inside your library.
|
||||
|
||||
> [!WARNING]
|
||||
> There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a top priority for future releases.
|
||||
> There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a high priority for future releases.
|
||||
|
||||
> [!WARNING]
|
||||
> If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are top priorities for future versions.
|
||||
> If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are high priorities for future versions.
|
||||
|
||||
### Saving the Library
|
||||
|
||||
Libraries are saved upon exiting the program. To manually save, select File -> Save Library from the menu bar. To save a backup of your library, select File -> Save Library Backup from the menu bar. Automatic backups are created when loading a library, and are automatically loaded from in the event of a crash or unexpected system shutdown.
|
||||
As of version 9.5, libraries are saved automatically as you go. To save a backup of your library, select File -> Save Library Backup from the menu bar.
|
||||
|
||||
### Half-Implemented Features
|
||||
|
||||
These features were present in pre-public versions of TagStudio (9.0 and below) and have yet to be fully implemented.
|
||||
|
||||
#### Fix Duplicate Files
|
||||
|
||||
Load in a .dupeguru file generated by [dupeGuru](https://github.com/arsenetar/dupeguru/) and mirror metadata across entries marked as duplicates. After mirroring, return to dupeGuru to manage deletion of the duplicate files. After deletion, use the “Fix Unlinked Entries” feature in TagStudio to delete the duplicate set of entries for the now-deleted files
|
||||
@@ -194,13 +195,6 @@ Load in a .dupeguru file generated by [dupeGuru](https://github.com/arsenetar/du
|
||||
> [!CAUTION]
|
||||
> While this feature is functional, it’s a pretty roundabout process and can be streamlined in the future.
|
||||
|
||||
#### Image Collage
|
||||
|
||||
Create an image collage of your photos and videos.
|
||||
|
||||
> [!CAUTION]
|
||||
> Collage sizes and options are hardcoded, and there's no GUI indicating the process of the collage creation.
|
||||
|
||||
#### Macros
|
||||
|
||||
Apply tags and other metadata automatically depending on certain criteria. Set specific macros to run when the files are added to the library. Part of this includes applying tags automatically based on parent folders.
|
||||
@@ -223,7 +217,7 @@ See instructions in the "[Creating Development Environment](/CONTRIBUTING.md/#cr
|
||||
|
||||
### What State Is the Project Currently In?
|
||||
|
||||
As of writing (Alpha v9.4.2) the project is in a useable state, however includes several metadata field bugs and lacks several quality of life features. Focus has been on developing v9.5 with a new SQLite backend which will allow us to not only fix these bugs but also to give us a jumping off point for some [pretty cool](https://docs.tagstud.io/updates/roadmap/) features we've been wanting to add for quite a while now!
|
||||
As of writing (Alpha v9.5.0) the project is very usable, however there's some plenty of quirks and missing QoL features. Several additional features and changes are still planned (see: [Feature Roadmap](https://docs.tagstud.io/updates/roadmap/)) that add even more power and flexibility to the tagging and field systems while making it easier to tag in bulk and perform automated operations. Bugfixes and polish are constantly trickling in along with the larger feature releases.
|
||||
|
||||
### What Features Are You Planning on Adding?
|
||||
|
||||
@@ -231,11 +225,11 @@ See the [Feature Roadmap](https://docs.tagstud.io/updates/roadmap/) page for the
|
||||
|
||||
### Features That Will NOT Be Added
|
||||
|
||||
- Native Cloud Integration
|
||||
- There are plenty of services already (native or third-party) that allow you to mount your cloud drives as virtual drives on your system. Hosting a TagStudio library on one of these mounts should function similarly to what native integration would look like.
|
||||
- Supporting native cloud integrations such as these would be an unnecessary "reinventing the wheel" burden for us that is outside the scope of this project.
|
||||
- Native ChatGPT/Non-Local LLM Integration
|
||||
- This could mean different things depending on your intentions. Whether it's trying to use an LLM to replace the native search, or to trying to use a model for image recognition, I'm not interested in hooking people's TagStudio libraries into non-local LLMs such as ChatGPT and/or turn the program into a "chatbot" interface (see: [Goals/Privacy](#goals)). I wouldn't, however, mind using **locally** hosted models to provide the _optional_ ability for additional searching and tagging methods (especially when it comes to facial recognition) - but this would likely take the form of plugins external to the core program anyway.
|
||||
- Native Cloud Integration
|
||||
- There are plenty of services already (native or third-party) that allow you to mount your cloud drives as virtual drives on your system. Hosting a TagStudio library on one of these mounts should function similarly to what native integration would look like.
|
||||
- Supporting native cloud integrations such as these would be an unnecessary "reinventing the wheel" burden for us that is outside the scope of this project.
|
||||
- Native ChatGPT/Non-Local LLM Integration
|
||||
- This could mean different things depending on your intentions. Whether it's trying to use an LLM to replace the native search, or to trying to use a model for image recognition, I'm not interested in hooking people's TagStudio libraries into non-local LLMs such as ChatGPT and/or turn the program into a "chatbot" interface (see: [Goals/Privacy](#goals)). I wouldn't, however, mind using **locally** hosted models to provide the _optional_ ability for additional searching and tagging methods (especially when it comes to facial recognition) - but this would likely take the form of plugins external to the core program anyway.
|
||||
|
||||
### Why Is this Already Version 9?
|
||||
|
||||
|
||||
BIN
docs/assets/built_tag_shrek.png
Normal file
BIN
docs/assets/built_tag_shrek.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 98 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 859 KiB After Width: | Height: | Size: 158 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 851 KiB |
BIN
docs/assets/screenshot.png
Normal file
BIN
docs/assets/screenshot.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 1.2 MiB |
BIN
docs/assets/tag_categories_example.png
Normal file
BIN
docs/assets/tag_categories_example.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 23 KiB |
BIN
docs/assets/tag_color_selection.png
Normal file
BIN
docs/assets/tag_color_selection.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 103 KiB |
BIN
docs/assets/tag_disambiguation_example.png
Normal file
BIN
docs/assets/tag_disambiguation_example.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 26 KiB |
@@ -4,33 +4,15 @@ title: Home
|
||||
|
||||
# Welcome to the TagStudio Documentation!
|
||||
|
||||
!!! warning
|
||||
This documentation is still a work in progress, and is intended to aide with deconstructing and understanding of the core mechanics of TagStudio and how it operates.
|
||||
|
||||
|
||||
|
||||
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 width="60%" markdown="span">
|
||||
|
||||
<figcaption>TagStudio Alpha v9.4.2 running on Windows 10</figcaption>
|
||||
|
||||
<figcaption>TagStudio Alpha v9.5.0 running on macOS Sequoia.</figcaption>
|
||||
</figure>
|
||||
|
||||
## Goals
|
||||
|
||||
- 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 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...
|
||||
|
||||
## 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.
|
||||
@@ -39,31 +21,29 @@ The [Feature Roadmap](updates/roadmap.md) lists all of the planned core features
|
||||
|
||||
### 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.
|
||||
- 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
|
||||
### Tagging + Custom Metadata
|
||||
|
||||
- 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)
|
||||
- Add custom powerful tags to your library entries
|
||||
- Add metadata to your library entries, including:
|
||||
- Name, Author, Artist (Single-Line Text Fields)
|
||||
- Description, Notes (Multiline Text Fields)
|
||||
- Create rich tags composed of a name, color, a list of aliases, and a list of “parent tags” - these being tags in which these tags inherit values from.
|
||||
- Copy and paste tags and fields across file entries
|
||||
- Automatically organize tags into groups based on parent tags marked as "categories"
|
||||
- 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`.
|
||||
- Search for file entries based on tags, file path (`path:`), file types (`filetype:`), and even media types! (`mediatype:`)
|
||||
- Use and combine boolean operators (`AND`, `OR`, `NOT`) along with parentheses groups, quotation escaping, and underscore substitution to create detailed search queries
|
||||
- Use special search conditions (`special:untagged` and `special:empty`) to find file entries without tags or fields, respectively
|
||||
|
||||
### 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_
|
||||
- Nearly 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.
|
||||
|
||||
@@ -2,7 +2,8 @@
|
||||
|
||||
To download TagStudio, visit the [Releases](https://github.com/TagStudioDev/TagStudio/releases) section of the GitHub repository and download the latest release for your system under the "Assets" section. TagStudio is available for **Windows**, **macOS** _(Apple Silicon & Intel)_, and **Linux**. Windows and Linux builds are also available in portable versions if you want a more self-contained executable to move around.
|
||||
|
||||
For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system.
|
||||
**We do not currently publish TagStudio to any package managers. Any TagStudio distributions outside of the GitHub releases page are _unofficial_ and not maintained by us.** Installation support will not be given to users installing from unofficial sources. Use these versions at your own risk.
|
||||
|
||||
|
||||
!!! info "For macOS Users"
|
||||
On macOS, you may be met with a message saying _""TagStudio" can't be opened because Apple cannot check it for malicious software."_ If you encounter this, then you'll need to go to the "Settings" app, navigate to "Privacy & Security", and scroll down to a section that says _""TagStudio" was blocked from use because it is not from an identified developer."_ Click the "Open Anyway" button to allow TagStudio to run. You should only have to do this once after downloading the application.
|
||||
@@ -10,6 +11,10 @@ For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/
|
||||
!!! info "For Linux Users"
|
||||
On Linux with non-Qt based Desktop Environments you may be unable to open TagStudio. You need to make sure that "xcb-cursor0" or "libxcb-cursor0" packages are installed. For more info check [Missing linux dependencies](https://github.com/TagStudioDev/TagStudio/discussions/182#discussioncomment-9452896)
|
||||
|
||||
## Third-Party Dependencies
|
||||
|
||||
- For video thumbnails and playback, you'll also need [FFmpeg](https://ffmpeg.org/download.html) installed on your system. If you encounter any issues with this, please reference our [FFmpeg Help](/docs/help/ffmpeg.md) guide.
|
||||
|
||||
## Optional Arguments
|
||||
|
||||
Optional arguments to pass to the program:
|
||||
|
||||
@@ -1,26 +1,50 @@
|
||||
# Entry
|
||||
# File Entries
|
||||
|
||||
Entries are the units that fill a [library](index.md). Each one corresponds to a file, holding a reference to it along with the metadata associated with it.
|
||||
File entries are the individual representations of your files inside a TagStudio [library](index.md). Each one corresponds one-to-one to a file on disk, and tracks all of the additional [tags](tag.md) and metadata that you attach to it inside TagStudio.
|
||||
|
||||
### Entry Object Structure
|
||||
## Storage
|
||||
|
||||
1. `id`
|
||||
- Int, Unique, **Required**
|
||||
- The ID for the Entry.
|
||||
- Used for internal processing
|
||||
2. `filename`:
|
||||
- String, **Required**
|
||||
- The filename with extension of the referenced media file.
|
||||
3. `path`:
|
||||
- String, **Required**, OS Agnostic
|
||||
- The folder path in which the media file is located in.
|
||||
4. [`fields`](field.md):
|
||||
- List of dicts, Optional
|
||||
- A list of Field ID/Value dicts.
|
||||
File entry data is storied within the `ts_library.sqlite` file inside each library's `.TagStudio` folder. No modifications are made to your actual files on disk, and nothing like sidecar files are generated for your files.
|
||||
|
||||
!!! note
|
||||
Entries currently have several unused optional fields intended for later features.
|
||||
## Appearance
|
||||
|
||||
## Retrieving Entries based on [Tag](tag.md) Cluster
|
||||
File entries appear as file previews both inside the thumbnail grid. The preview panel shows a more detailed preview of the file, along with extra file stats and all attached TagStudio tags and fields.
|
||||
|
||||
By default when querying Entries, each Entry's `tags` list (stored in the form of Tag `id`s) is compared against the Tag `id`s in a given Tag cluster (list of Tag `id`s) or appended clusters in the case of multi-term queries. The type of comparison depends on the type of query and whether or not it is an inclusive or exclusive query, or a combination of both. This default searching behavior is done in _O(n)_ time, but can be sped up in the future by building indexes on certain search terms. These indexes can be stored on disk and loaded back into memory in future sessions. These indexes will also need to be updated as new Tags and Entries are added or edited.
|
||||
## Unlinked File Entries
|
||||
|
||||
If the file that an entry is referencing has been moved, renamed, or deleted on disk, then TagStudio will display a red chain-link icon for the thumbnail image. Certain uncached stats such as the file size and image dimensions will also be unavailable to see in the preview panel when a file becomes unlinked.
|
||||
|
||||
To fix file entries that have become unlinked, select the "Fix Unlinked Entries" option from the Tools menu. From there, refresh the unlinked entry count and choose whether to search and relink you files, and/or delete the file entires from your library. This will NOT delete or modify any files on disk.
|
||||
|
||||
## Internal Structure
|
||||
|
||||
- `id` (`INTEGER`/`int`, `UNIQUE`, `NOT NULL`, `PRIMARY KEY`)
|
||||
- The ID for the file entry.
|
||||
- Used for guaranteed unique references.
|
||||
- `folder` (`INTEGER`/`int`, `NOT NULL`, `FOREIGN KEY`)
|
||||
- _Not currently used, may be removed._
|
||||
- `path` (`VARCHAR`/`Path`, `UNIQUE`, `NOT NULL`)
|
||||
- The filename and filepath relative to the root of the library folder.
|
||||
- (E.g. for library "Folder", path = "any_subfolders/filename.txt")
|
||||
- `suffix` (`VARCHAR`/`str`, `NOT NULL`)
|
||||
- The filename suffix with no leading dot.
|
||||
- Used for quicker file extension checks.
|
||||
- `date_created` (`DATETIME`/`Datetime`)
|
||||
- _Not currently used, will be implemented in an upcoming update._
|
||||
- The creation date of the file (not the entry).
|
||||
- Generates from `st_birthtime` on Windows and Mac, and `st_ctime` on Linux.
|
||||
- `date_modified` (`DATETIME`/`Datetime`)
|
||||
- _Not currently used, will be implemented in an upcoming update._
|
||||
- The latest modification date of the file (not the entry).
|
||||
- Generates from `st_mtime`.
|
||||
- `date_added` (`DATETIME`/`Datetime`)
|
||||
- The date the file entry was added to the TagStudio library.
|
||||
|
||||
### Table Relationships
|
||||
|
||||
- `tag_entries`
|
||||
- A relationship between `entry_id` to `tag_id`s from the `tags` table.
|
||||
- `text_fields`
|
||||
- (TODO: determine the relationship for `entry_id`)
|
||||
- `datetime_fields`
|
||||
- (TODO: determine the relationship for `entry_id`)
|
||||
|
||||
@@ -1,68 +1,110 @@
|
||||
# Tag
|
||||
# Tags
|
||||
|
||||
Tags are user-defined attributes made up of one or more keywords, aliases, and relationships to other tags. A person, place, thing, concept, you name it! Tags allow for a more sophisticated way to organize and search [entries](entry.md) thanks to their aliases, parent tags, and more.
|
||||
Tags can be as simple or complex as wanted, so that any user can tune TagStudio to fit their needs.
|
||||
Tags are discrete objects that represent some attribute. This could be a person, place, object, concept, and more. Unlike most tagging systems, TagStudio tags are not solely represented by a line of text or a hashtag. Tags in TagStudio consist of several properties and relationships that give extra customization, searching power, and ease of tagging that cannot be achieved by string-based tags alone. TagStudio tags are designed to be as simple or as complex as you'd like, giving options to users of all skill levels and use cases.
|
||||
|
||||
Among the things that make tags so useful, aliases give the ability to contain alternate names and spellings, making searches intuitive and expansive. Furthermore, parent-tags/subtags offer relational organization capabilities for the structuring and connection of the [library's](index.md) contents.
|
||||
## Naming Tags
|
||||
|
||||
## Tag Object Structure
|
||||
TagStudio tags do not share the same naming limitations of many other tagging solutions. The key standouts of tag names in TagStudio are:
|
||||
|
||||
### `id`
|
||||
- Tag names do **NOT** have to be unique
|
||||
- Tag names are **NOT** limited to specific characters
|
||||
- Tags can have **aliases**, a.k.a. alternate names to go by
|
||||
|
||||
ID for the tag.
|
||||
### Name
|
||||
|
||||
- Int, Unique, Required
|
||||
- Used for internal processing
|
||||
This is the base name of a tag. It does not have to be unique, and can use any characters you wish. If your tag can go by multiple names, for example if it's the name of a person or something that's commonly shortened or abbreviated, then it's recommended that you put the full tag name here.
|
||||
|
||||
### `name`
|
||||
### Shorthand
|
||||
|
||||
The normal name of the tag, with no shortening or specification.
|
||||
This is a special type of alias that's used for shortening the tag name under special circumstances, mostly when screen space is limited. Tag shorthands can be searched for just like tag names and tag aliases.
|
||||
|
||||
- String, Required
|
||||
- Doesn't have to be unique
|
||||
- Used for display, searching, and storing
|
||||
### Aliases
|
||||
|
||||
### `shorthand`
|
||||
Aliases are alternate names that the tag can go by. This may include individual first names for people, alternate spellings, shortened names, and more. If there's a common abbreviation or shortened name for your tag, it's recommended to use the [shorthand](#shorthand) field for this instead.
|
||||
|
||||
The shorthand name for the tag. Works like an alias but is used for specific display purposes.
|
||||
When searching for a tag, aliases (including the shorthand) can also be used to find the tag. This not only includes searching for tags themselves, but for tagged [file entries](entry.md) as well!
|
||||
|
||||
- String, Optional
|
||||
- Doesn't have to be unique
|
||||
- Used for display and searching
|
||||
### Automatic Disambiguation
|
||||
|
||||
### `aliases`
|
||||
Just as in real life, sometimes there are different attributes that share the same name with one another. The process of adding specificity to something in order to not confuse it with something similar is known as [disambiguation](https://en.wikipedia.org/wiki/Word-sense_disambiguation). In TagStudio we give the option to automatically disambiguate tag names based on a specially marked [Parent Tag](#parent-tags). Parent tags are explained in further detail below, but for the purposes of tag names they can lend themselves to clarifying the name of a tag without the user needing to manually change the name or add complicated aliases.
|
||||
|
||||
Alternate names for the tag.
|
||||
Given a tag named "Freddy", we may confuse it with other "Freddy" tags in our library. There are lots of Freddys in the world, after all. If we're talking about Freddy from "Five Nights at Freddy's", then we may already (and likely should) have a separate "Five Nights at Freddy's" tag added as a parent tag. When the disambiguation box next to a parent tag is selected (see image below) then our tag name will automatically display its name with that parent tag's name (or shorthand if available) in parentheses.
|
||||
|
||||
- List of Strings, Optional
|
||||
- Recommended to be unique to this tag
|
||||
- Used for searching
|
||||
|
||||
|
||||
### `subtags`
|
||||
So if the "Five Night's at Fredddy's" tag is added as a parent tag on the "Freddy" tag, and the disambiguation box next to it is checked, then our tag name will automatically be displayed as "Freddy (Five Nights at Freddy's)". Better yet, if the "Five Night's at Fredddy's" tag has a shorthand such as "FNAF", then our "Freddy" tag will be displayed as "Freddy (FNAF)". This process preserves our base tag name ("Freddy") and provides an option to get a clean and consistent method to display disambiguating parent categories, rather than having to type this information in manually for each applicable tag.
|
||||
|
||||
Other Tags that make up properties of this tag. Also called "parent tags".
|
||||
## Tag Relationships
|
||||
|
||||
- List of Strings, Optional
|
||||
- Used for display (first parent tag only) and searching.
|
||||
One of the core properties of tags in TagStudio is their ability to form relationships with other tags, just as attributes have relationships with each other in real life. A rectangle is a square, but a square isn't a rectangle. A certain plumber with a red hat and blue overalls might be part of a well-known media franchise, developed by an equally well-known company. But how do representing these relationships help with tagging images and files? With tag relationships, we can leverage the following principles:
|
||||
|
||||
### `color`
|
||||
1. [Simplicity via Deduplication](#simplicity-via-deduplication)
|
||||
2. [Intuition via Substitution](#intuition-via-substitution)
|
||||
3. [Rediscovery via Linking](#rediscovery-via-linking)
|
||||
|
||||
A color name string for customizing the tag's display color
|
||||
### Parent Tags
|
||||
|
||||
- String, Optional
|
||||
- Used for display
|
||||
#### Simplicity via Deduplication
|
||||
|
||||
## Tag Search Examples:
|
||||
In a system where tags have no relationships, you're required to add as many tags as you possibly can to describe every last element of an image or file. If you want to tag an image of Shrek, you need to add a tag for `Shrek` himself, a `Character` tag since he's a character, a `Movie` and perhaps `Dreamworks` tag since he's a character from a movie, or perhaps a `Book` tag if we're talking about the original character, and then of course tags for every other attribute of Shrek shown or implied. By allowing tags to have inheritance relationships, we can have a single `Shrek` tag inherit from `Character` (Shrek IS a character) as well as from a separate `Shrek (Movie Franchise)` tag that itself inherits from `Movie Franchise` and `Dreamworks`. Now by simply adding the `Shrek` tag to an image, we've effectively also added the `Character`, `Shrek (Move Franchise)`, `Movie Franchise`, and `Dreamworks` attributes all in one go. On the image entry itself we only see `Shrek`, but the rest of the attributes are implied.
|
||||
|
||||
Using for example, a library of files including some tagged with the following tags:
|
||||
|
||||
|
||||
| Tag | `name` | `shorthand` | `aliases` | `parent tags` |
|
||||
| ------------------- | ------------------- | ----------- | ---------------------- | -------------------------------------------- |
|
||||
| _League of Legends_ | "League of Legends" | "LoL" | ["League"] | ["Game", "Fantasy"] |
|
||||
| _Arcane_ | "Arcane" | "" | [] | ["League of Legends", "Cartoon"] |
|
||||
| _Jinx (LoL)_ | "Jinx Piltover" | "Jinx" | ["Jinxy", "Jinxy Poo"] | ["League of Legends", "Arcane", "Character"] |
|
||||
| _Zander (Arcane)_ | "Zander Zanderson" | "Zander" | [] | ["Arcane", "Character"] |
|
||||
| _Mr. Legend (LoL)_ | "Mr. Legend" | "" | [] | ["League of Legends", "Character"] |
|
||||
#### Intuition via Substitution
|
||||
|
||||
Now when searching for for images that have `Dreamworks` and `Character`, any images or files originally just tagged with `Shrek` will appear as you would expect. A little bit of tag setup goes a long way not only saving so much time during tagging, but also to ensure an intuitive way to search your files!
|
||||
|
||||
#### Rediscovery via Linking
|
||||
|
||||
Lastly, when searching your files with broader categories such as `Character` or `Dreamworks` you may rediscover images and files that you had simply tagged with tags such as `Barbatus` or `Tulio`, since you didn't need to manually tag those files with `Character` or `Dreamworks`, but had forgotten that they are both in fact Dreamworks characters. While you focus on tagging your files with seemingly surface level attributes, your TagStudio library is building rich connections between tags and files that may not be fully apparent until being discovered through various search queries. While you were simply tagging images with `Shrek` and `Tulio`, you may have unlocked an easy way to search for "2D Dreamworks Characters" without having to explicitly tag for that!
|
||||
|
||||
### Component Tags
|
||||
|
||||
**_[Coming in version 9.6](../updates/roadmap.md#96-alpha)_**
|
||||
|
||||
Component tags will be built from a composition-based, or "HAS" type relationship between tags. This takes care of instances where an attribute may "have" another attribute, but doesn't inherit from it. Shrek may be an `Orge`, he may be a `Character`, but he is NOT a `Leather Vest` - even if he's commonly seen _with_ it. Component tags, along with the upcoming [Tag Override](tag_overrides.md) feature, are built to handle these cases in a way that still simplifies the tagging process without adding too much undue complexity for the user.
|
||||
|
||||
## Tag Appearance
|
||||
|
||||
### Color
|
||||
|
||||
Tags use a default uncolored appearance by default, however can take on a number of built-in and user-created\* colors and color palettes! Tag color palettes can be based on a single color value (see: TagStudio Standard, TagStudio Shades, TagStudio Pastels) or use an optional secondary color to override the border and text colors (see: TagStudio Neon).
|
||||
|
||||
|
||||
|
||||
\*_Coming in the full version 9.5.0 release_
|
||||
|
||||
### Icon
|
||||
|
||||
**_[Coming in version 9.6](../updates/roadmap.md#96-alpha)_**
|
||||
|
||||
## Tag Properties
|
||||
|
||||
Properties are special attributes of tags that change their behavior in some way.
|
||||
|
||||
#### Is Category
|
||||
|
||||
When the "Is Category" property is checked, this tag now acts as a category separator inside the preview panel. If this tag or any tags inheriting from this tag (i.e. tags that have this tag as a "[Parent Tag](#parent-tags)"), then these tags will appear under a separated group that's named after this tag. Tags inheriting from multiple "category tags" will still show up under any applicable category. _Read more under: [Tag Categories](../library/tag_categories.md)._
|
||||
|
||||
|
||||
|
||||
#### Is Hidden
|
||||
|
||||
**_[Coming in version 9.6](../updates/roadmap.md#96-alpha)_**
|
||||
|
||||
When the "Is Hidden" property is checked, any file entries tagged with this tag will not show up in searches by default. This property comes by default with the built-in "Archived" tag.
|
||||
|
||||
## Tag Search Examples
|
||||
|
||||
The following are examples of how a set of given tags will respond to various search queries.
|
||||
|
||||
| Tag | Name | Shorthand | Aliases | Parent Tags |
|
||||
| ------------------- | ------------------- | --------- | ---------------------- | -------------------------------------------- |
|
||||
| _League of Legends_ | "League of Legends" | "LoL" | ["League"] | ["Game", "Fantasy"] |
|
||||
| _Arcane_ | "Arcane" | "" | [] | ["League of Legends", "Cartoon"] |
|
||||
| _Jinx (LoL)_ | "Jinx Piltover" | "Jinx" | ["Jinxy", "Jinxy Poo"] | ["League of Legends", "Arcane", "Character"] |
|
||||
| _Zander (Arcane)_ | "Zander Zanderson" | "Zander" | [] | ["Arcane", "Character"] |
|
||||
| _Mr. Legend (LoL)_ | "Mr. Legend" | "" | [] | ["League of Legends", "Character"] |
|
||||
|
||||
**The query "Arcane" will display results tagged with:**
|
||||
|
||||
|
||||
@@ -2,10 +2,12 @@
|
||||
tags:
|
||||
---
|
||||
|
||||
# Tag Categories (v9.5)
|
||||
# Tag Categories
|
||||
|
||||
The "Is Category" property of tags determines if a tag should be treated as a category itself when being organized inside the preview panel. Tags marked as categories will show themselves and all tags inheriting from it (including recursively) underneath a field-like section with the tag's name. This means that duplicates of tags can appear on entries if the tag inherits from multiple parent categories, however this is by design and reflects the nature multiple inheritance. Any tags not inheriting from a category tag will simply show under a default "Tag" section.
|
||||
|
||||
|
||||
|
||||
### Built-In Tags and Categories
|
||||
|
||||
The built-in tags "Favorite" and "Archived" inherit from the built-in "Meta Tags" category which is marked as a category by default. This behavior of default tags can be fully customized by disabling the category option and/or by adding/removing the tags' Parent Tags.
|
||||
|
||||
@@ -19,27 +19,25 @@ Features are broken up into the following priority levels, with nested prioritie
|
||||
- [x] Tag shorthand (specific short alias for displaying) [HIGH]
|
||||
- [x] Parent/Inheritance subtags [HIGH]
|
||||
- [ ] Composition/HAS subtags [HIGH]
|
||||
- [x] Deleting Tags [HIGH] [#148]
|
||||
- [ ] Merging Tags [HIGH] [#12](https://github.com/TagStudioDev/TagStudio/issues/12)
|
||||
- [ ] Tag Icons [HIGH] [#195](https://github.com/TagStudioDev/TagStudio/issues/195)
|
||||
- [x] Deleting Tags [HIGH]
|
||||
- [ ] Merging Tags [HIGH]
|
||||
- [ ] Tag Icons [HIGH]
|
||||
- [ ] Small Icons [HIGH]
|
||||
- [ ] Large Icons for Profiles [MEDIUM]
|
||||
- [ ] Built-in Icon Packs (i.e. Boxicons) [HIGH]
|
||||
- [ ] User Defined Icons [HIGH]
|
||||
- [ ] Multiple Languages for Tag Strings [MEDIUM]
|
||||
- [ ] User-defined tag colors [HIGH] [#264](https://github.com/TagStudioDev/TagStudio/issues/264)
|
||||
- [ ] ID based, not string or hex [HIGH]
|
||||
- [ ] Color name [HIGH]
|
||||
- [ ] Color value (hex) [HIGH]
|
||||
- [ ] Existing colors are now a set of base colors [HIGH]
|
||||
- [ ] Editable [MEDIUM]
|
||||
- [ ] Non-removable [HIGH]
|
||||
- [ ] User-defined tag colors [HIGH]
|
||||
- [x] ID based, not string or hex [HIGH]
|
||||
- [x] Color name [HIGH]
|
||||
- [x] Color value (hex) [HIGH]
|
||||
- [x] Existing colors are now a set of base colors [HIGH]
|
||||
- [x] [Tag Categories](../library/tag_categories.md) [HIGH]
|
||||
- [x] 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]
|
||||
- [x] Title is tag name [HIGH]
|
||||
- [ ] [Tag Overrides](../library/tag_overrides.md) [MEDIUM]
|
||||
- [ ] Per-file overrides of subtags [HIGH]
|
||||
- [ ] Tag Packs [MEDIUM] [#3](https://github.com/TagStudioDev/TagStudio/issues/3)
|
||||
- [ ] Tag Packs [MEDIUM]
|
||||
- [ ] Human-readable (i.e. JSON) files containing tag data [HIGH]
|
||||
- [ ] Importable [HIGH]
|
||||
- [ ] Exportable [HIGH]
|
||||
@@ -48,7 +46,7 @@ Features are broken up into the following priority levels, with nested prioritie
|
||||
- [ ] Human-readable (i.e. JSON) files containing tag data [HIGH]
|
||||
- [ ] Importable [HIGH]
|
||||
- [ ] Exportable [HIGH]
|
||||
- [ ] Exportable Library Data [HIGH] [#47](https://github.com/TagStudioDev/TagStudio/issues/47)
|
||||
- [ ] Exportable Library Data [HIGH]
|
||||
- [ ] Standard notation format (i.e. JSON) contacting all library data [HIGH]
|
||||
- [ ] [Macros](../utilities/macro.md) [HIGH]
|
||||
- [ ] Sharable Macros [MEDIUM]
|
||||
@@ -69,7 +67,7 @@ Features are broken up into the following priority levels, with nested prioritie
|
||||
- [ ] Stored in system user folder/designated folder [HIGH]
|
||||
- [ ] Library Settings [HIGH]
|
||||
- [ ] Stored in `.TagStudio` folder [HIGH]
|
||||
- [ ] Multiple Root Directories per Library [HIGH] [#295](https://github.com/TagStudioDev/TagStudio/issues/295)
|
||||
- [ ] Multiple Root Directories per Library [HIGH]
|
||||
- [ ] [Entry groups](../library/entry_groups.md) [HIGH]
|
||||
- [ ] Groups for files/entries where the same entry can be in multiple groups [HIGH]
|
||||
- [ ] Ability to number entries within group [HIGH]
|
||||
@@ -80,21 +78,21 @@ Features are broken up into the following priority levels, with nested prioritie
|
||||
- [ ] Fields [HIGH]
|
||||
- [x] Text Boxes [HIGH]
|
||||
- [x] Text Lines [HIGH]
|
||||
- [ ] Dates [HIGH] [#213](https://github.com/TagStudioDev/TagStudio/issues/213)
|
||||
- [ ] Dates [HIGH]
|
||||
- [ ] Custom field names [HIGH]
|
||||
- [ ] Search engine [HIGH]
|
||||
- [x] Boolean operators [HIGH]
|
||||
- [ ] Tag objects + autocomplete [HIGH] [#476 (Autocomplete)](https://github.com/TagStudioDev/TagStudio/issues/476)
|
||||
- [ ] Tag objects + autocomplete [HIGH]
|
||||
- [x] Filename search [HIGH]
|
||||
- [x] Filetype search [HIGH]
|
||||
- [x] Search by extension (e.g. ".jpg", ".png") [HIGH]
|
||||
- [x] 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] [#272](https://github.com/TagStudioDev/TagStudio/issues/272)
|
||||
- [ ] Field content search [HIGH]
|
||||
- [ ] HAS operator for composition tags [HIGH]
|
||||
- [ ] OCR search [LOW]
|
||||
- [ ] Fuzzy Search [LOW] [#400](https://github.com/TagStudioDev/TagStudio/issues/400)
|
||||
- [ ] Sortable results [HIGH] [#68](https://github.com/TagStudioDev/TagStudio/issues/68)
|
||||
- [ ] Fuzzy Search [LOW]
|
||||
- [ ] Sortable results [HIGH]
|
||||
- [ ] Sort by relevance [HIGH]
|
||||
- [x] Sort by date added [HIGH]
|
||||
- [ ] Sort by date created [HIGH]
|
||||
@@ -136,22 +134,23 @@ Features are broken up into the following priority levels, with nested prioritie
|
||||
- [x] Toggle Mute [HIGH]
|
||||
- [ ] Timeline scrubber [HIGH]
|
||||
- [ ] Fullscreen [MEDIUM]
|
||||
- [ ] Audio Playback [HIGH] [#450](https://github.com/TagStudioDev/TagStudio/issues/450)
|
||||
- [x] Audio Playback [HIGH]
|
||||
- [x] Play/Pause [HIGH]
|
||||
- [ ] Loop [HIGH]
|
||||
- [ ] Toggle Autoplay [MEDIUM]
|
||||
- [x] Volume Control [HIGH]
|
||||
- [x] Toggle Mute [HIGH]
|
||||
- [x] Timeline scrubber [HIGH]
|
||||
- [ ] Fullscreen [MEDIUM]
|
||||
- [ ] Optimizations [HIGH]
|
||||
- [x] Thumbnail caching [HIGH]
|
||||
- [ ] File property indexes [HIGH]
|
||||
- [ ] File property caching/indexes [HIGH]
|
||||
|
||||
## Version Milestones
|
||||
|
||||
These version milestones are rough estimations for when the previous core features will be added. For a more definitive idea for when features are coming, please reference the current GitHub [milestones](https://github.com/TagStudioDev/TagStudio/milestones).
|
||||
|
||||
_(This list was created after the release of version 9.4)_
|
||||
|
||||
### 9.5 (Alpha)
|
||||
|
||||
- [x] SQL backend [HIGH]
|
||||
@@ -159,12 +158,10 @@ These version milestones are rough estimations for when the previous core featur
|
||||
- [ ] Tags [HIGH]
|
||||
- [x] Deleting Tags [HIGH]
|
||||
- [ ] User-defined tag colors [HIGH]
|
||||
- [ ] ID based, not string or hex [HIGH]
|
||||
- [ ] Color name [HIGH]
|
||||
- [ ] Color value (hex) [HIGH]
|
||||
- [ ] Existing colors are now a set of base colors [HIGH]
|
||||
- [ ] Editable [MEDIUM]
|
||||
- [ ] Non-removable [HIGH]
|
||||
- [x] ID based, not string or hex [HIGH]
|
||||
- [x] Color name [HIGH]
|
||||
- [x] Color value (hex) [HIGH]
|
||||
- [x] Existing colors are now a set of base colors [HIGH]
|
||||
- [x] [Tag Categories](../library/tag_categories.md) [HIGH]
|
||||
- [x] 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]
|
||||
@@ -177,13 +174,9 @@ These version milestones are rough estimations for when the previous core featur
|
||||
- [x] Search by media type (e.g. "image", "video", "document") [MEDIUM]
|
||||
- [ ] Field content search [HIGH]
|
||||
- [ ] Sortable results [HIGH]
|
||||
- [ ] Sort by relevance [HIGH]
|
||||
- [x] Sort by date added [HIGH]
|
||||
- [ ] Sort by date created [HIGH]
|
||||
- [ ] Sort by date modified [HIGH]
|
||||
- [ ] Sort by date taken (photos) [MEDIUM]
|
||||
- [ ] Sort by file size [HIGH]
|
||||
- [ ] Sort by file dimension (images/video) [LOW]
|
||||
- [ ] Settings Menu [HIGH]
|
||||
- [ ] Application Settings [HIGH]
|
||||
- [ ] Stored in system user folder/designated folder [HIGH]
|
||||
|
||||
@@ -6,19 +6,19 @@ With TagStudio opened, start by creating a new library or opening an existing on
|
||||
|
||||
## Refreshing the Library
|
||||
|
||||
In order to scan for new files or file changes, you’ll need to manually go to File -> Refresh Directories.
|
||||
|
||||
!!! note
|
||||
In the future, library refreshing will also be automatically done in the background, or additionally on app startup.
|
||||
Libraries under 10,000 files automatically scan for new or modified files when opened. In order to refresh the library manually, select "Refresh Directories" under the File menu.
|
||||
|
||||
## Adding Tags to File Entries
|
||||
Click the "Add Tag" button at the bottom of the preview panel with one or more tags selected. Search for existing inside the new dialog popup or create a new one from. Click the “+” button next to whichever tags you want to add. Alternatively, after you search for a tag, press the Enter/Return key to add the first item in the list. Press Enter/Return once more to close the dialog box.
|
||||
|
||||
Access the "Add Tag" search box by either clicking on the "Add Tag" button at the bottom of the right sidebar, accessing the "Add Tags to Selected" option from the File menu, or by pressing <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>T</kbd>.
|
||||
|
||||
From here you can search for existing tags or create a new one if the one you're looking for doesn't exist. Click the “+” button next to any tags you want to to the currently selected file entries. To quickly add the top result, press the <kbd>Enter</kbd>/<kbd>Return</kbd> key to add the the topmost tag and reset the tag search. Press <kbd>Enter</kbd>/<kbd>Return</kbd> once more to close the dialog box. By using this method, you can quickly add various tags in quick succession just by using the keyboard!
|
||||
|
||||
To remove a tag from a file entry, hover over the tag in the preview panel and click on the "-" icon that appears.
|
||||
|
||||
## Adding Metadata Fields to File Entries
|
||||
## Adding Metadata to File Entries
|
||||
|
||||
To add a metadata field to a file entry, start by clicking the “Add Field” button at the bottom of the preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry.
|
||||
To add a metadata field to a file entry, start by clicking the “Add Field” button at the bottom of the preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry
|
||||
|
||||
## Editing Metadata Fields
|
||||
|
||||
@@ -26,66 +26,33 @@ To add a metadata field to a file entry, start by clicking the “Add Field” b
|
||||
|
||||
Hover over the field and click the pencil icon. From there, add or edit text in the dialog box popup.
|
||||
|
||||
!!! warning
|
||||
Keyboard control and navigation is currently _very_ buggy, but will be improved in future versions.
|
||||
|
||||
## Creating Tags
|
||||
|
||||
To create a new tag, click on Edit -> New Tag from the menu bar. From there, enter a tag name, shorthand name, any tag aliases separated by newlines, any subtags, and an optional color.
|
||||
Create a new tag by accessing the "New Tag" option from the Edit menu or by pressing <kbd>Ctrl</kbd>+<kbd>T</kbd>. In the tag creation panel, enter a tag name, optional shorthand name, optional tag aliases, optional parent tags, and an optional color.
|
||||
|
||||
- The tag **shorthand** is a type of alias that displays in situations when screen space is more valuable (ex. as a subtag for other tags).
|
||||
- **Aliases** are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
|
||||
- **Subtags** are tags in which this tag is a child tag of. In other words, tags under this section are parents of this tag. For example, if you had a tag for a character from a show, you would make the show a subtag of this character. This would display as “Character (Show)” in most areas of the app. The first tag in this list is used as the tag shown in parentheses for specification.
|
||||
- The **color** dropdown lets you select an optional color for this tag to display as.
|
||||
- The tag **name** is the base name of the tag. **_This does NOT have to be unique!_**
|
||||
- The tag **shorthand** is a special type of alias that displays in situations where screen space is more valuable, notably with name disambiguation.
|
||||
- **Aliases** are alternate names for a tag. These let you search for terms other than the exact tag name in order to find the tag again.
|
||||
- **Parent Tags** are tags in which this this tag can substitute for in searches. In other words, tags under this section are parents of this tag.
|
||||
- Parent tags with the disambiguation check next to them will be used to help disambiguate tag names that may not be unique.
|
||||
- For example: If you had a tag for "Freddy Fazbear", you might add "Five Nights at Freddy's" as one of the parent tags. If the disambiguation box is checked next to "Five Nights at Freddy's" parent tag, then the tag "Freddy Fazbear" will display as "Freddy Fazbear (Five Nights at Freddy's)". Furthermore, if the "Five Nights at Freddy's" tag has a shorthand like "FNAF", then the "Freddy Fazbear" tag will display as "Freddy Fazbear (FNAF)".
|
||||
- The **color** option lets you select an optional color palette to use for your tag.
|
||||
- The **"Is Cagegory"** property lets you treat this tag as a category under which itself and any child tags inheriting from it will be sorted by inside the preview panel.
|
||||
|
||||
## Editing Tags
|
||||
|
||||
To edit a tag, right-click the tag in the tag field of the preview pane and select “Edit Tag”
|
||||
To edit a tag, click on it inside the preview panel or right-click the tag and select “Edit Tag” from the context menu.
|
||||
|
||||
## Relinking Renamed/Moved Files
|
||||
## Relinking Moved Files
|
||||
|
||||
Inevitably, some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red tag with a cross through it _(this icon is also used for items with broken thumbnails)._ To relink moved files or delete these entries, go to Tools -> Manage Unlinked Entries. Click the “Refresh” button to scan your library for unlinked entries. Once complete, you can attempt to “Search & Relink” any unlinked entries to their respective files, or “Delete Unlinked Entries” in the event the original files have been deleted and you no longer wish to keep their metadata entries inside your library.
|
||||
Inevitably some of the files inside your library will be renamed, moved, or deleted. If a file has been renamed or moved, TagStudio will display the thumbnail as a red broken chain link. To relink moved files or delete these entries, select the "Manage Unlinked Entries" option under the Tools menu. Click the "Refresh" button to scan your library for unlinked entries. Once complete, you can attempt to “Search & Relink” any unlinked file entries to their respective files, or “Delete Unlinked Entries” in the event the original files have been deleted and you no longer wish to keep their entries inside your library.
|
||||
|
||||
!!! warning
|
||||
There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a top priority for future releases.
|
||||
There is currently no method to relink entries to files that have been renamed - only moved or deleted. This is a high priority for future releases.
|
||||
|
||||
!!! warning
|
||||
If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are top priorities for future versions.
|
||||
If multiple matches for a moved file are found (matches are currently defined as files with a matching filename as the original), TagStudio will currently ignore the match groups. Adding a GUI for manual selection, as well as smarter automated relinking, are high priorities for future versions.
|
||||
|
||||
## Deleting Tags
|
||||
### Saving the Library
|
||||
|
||||
To delete a tag from your library, go to File -> Tag Manager, hover over the tag you wish to delete, and click the "-" icon that appears. You will be prompted to make sure you wish to delete this tag from your library and across all file entries.
|
||||
|
||||
## Saving the Library
|
||||
|
||||
Libraries are saved upon exiting the program. To manually save, select File -> Save Library from the menu bar. To save a backup of your library, select File -> Save Library Backup from the menu bar.
|
||||
|
||||
## Half-Implemented Features
|
||||
|
||||
### Fix Duplicate Files
|
||||
|
||||
Load in a .dupeguru file generated by [dupeGuru](https://github.com/arsenetar/dupeguru/) and mirror metadata across entries marked as duplicates. After mirroring, return to dupeGuru to manage deletion of the duplicate files. After deletion, use the “Fix Unlinked Entries” feature in TagStudio to delete the duplicate set of entries for the now-deleted files
|
||||
|
||||
!!! danger "Caution"
|
||||
While this feature is functional, it’s a pretty roundabout process and can be streamlined in the future.
|
||||
|
||||
### Image Collage
|
||||
|
||||
Create an image collage of your photos and videos.
|
||||
|
||||
!!! danger "Caution"
|
||||
Collage sizes and options are hardcoded, and there's no GUI indicating the process of the collage creation.
|
||||
|
||||
### Macros
|
||||
|
||||
Apply tags and other metadata automatically depending on certain criteria. Set specific macros to run when the files are added to the library. Part of this includes applying tags automatically based on parent folders.
|
||||
|
||||
!!! danger "Caution"
|
||||
Macro options are hardcoded, and there’s currently no way for the user to interface with this (still incomplete) system at all.
|
||||
|
||||
### Gallery-dl Sidecar Importing
|
||||
|
||||
Import JSON sidecar data generated by [gallery-dl](https://github.com/mikf/gallery-dl).
|
||||
|
||||
!!! danger "Caution"
|
||||
This feature is not supported or documented in any official capacity whatsoever. It will likely be rolled-in to a larger and more generalized sidecar importing feature in the future.
|
||||
As of version 9.5, libraries are saved automatically as you go. To save a backup of your library, select File -> Save Library Backup from the menu bar.
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
# Created for TagStudio: https://github.com/CyanVoxel/TagStudio
|
||||
|
||||
VERSION: str = "9.5.0" # Major.Minor.Patch
|
||||
VERSION_BRANCH: str = "EXPERIMENTAL" # Usually "" or "Pre-Release"
|
||||
VERSION_BRANCH: str = "Pre-Release 1" # Usually "" or "Pre-Release"
|
||||
|
||||
# The folder & file names where TagStudio keeps its data relative to a library.
|
||||
TS_FOLDER_NAME: str = ".TagStudio"
|
||||
|
||||
@@ -444,7 +444,7 @@ class Library:
|
||||
|
||||
def open_library(self, path: str | Path) -> OpenStatus:
|
||||
"""
|
||||
Open a TagStudio v9+ Library.
|
||||
Open a TagStudio v9.0 - v9.4.2 JSON Library.
|
||||
"""
|
||||
return_code = OpenStatus.CORRUPTED
|
||||
|
||||
|
||||
Reference in New Issue
Block a user