From 615978e5a60cb62095bfcd7cce96a2ae15ee93d0 Mon Sep 17 00:00:00 2001 From: Travis Abendshien <46939827+CyanVoxel@users.noreply.github.com> Date: Wed, 8 Oct 2025 01:39:06 -0700 Subject: [PATCH] docs: update README --- README.md | 286 +++++++++++++++++++------------------ docs/assets/screenshot.png | Bin 1137323 -> 1128624 bytes docs/index.md | 2 +- 3 files changed, 145 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 7a52f92b..852d91fe 100644 --- a/README.md +++ b/README.md @@ -1,120 +1,92 @@ -# TagStudio: A User-Focused Document Management System +# TagStudio: A User-Focused Photo & File Management System -[](https://hosted.weblate.org/projects/tagstudio/strings/) +[](https://github.com/TagStudioDev/TagStudio/releases) +[](https://hosted.weblate.org/projects/tagstudio/strings/) [](https://github.com/TagStudioDev/TagStudio/actions/workflows/pytest.yaml) [](https://github.com/TagStudioDev/TagStudio/actions/workflows/mypy.yaml) [](https://github.com/TagStudioDev/TagStudio/actions/workflows/ruff.yaml) -[](https://github.com/TagStudioDev/TagStudio/releases)
-
+
- TagStudio Alpha v9.5.0 running on macOS Sequoia. + TagStudio Alpha v9.5.5 running on macOS Sequoia.
## Contents -- [Goals](#goals) -- [Priorities](#priorities) -- [Current Features](#current-features) -- [Contributing](#contributing) +- [Feature Highlights](#feature-highlights) +- [Basic Usage](#basic-usage) - [Installation](#installation) -- [Usage](#usage) +- [Goals & Priorities](#goals--priorities) - [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. - -## 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... - -## Contributing - -If you're interested in contributing to TagStudio, please take a look at the [contribution guidelines](/CONTRIBUTING.md) for how to get started! - Translation hosting generously provided by [Weblate](https://weblate.org/en/). Check out our [project page](https://hosted.weblate.org/projects/tagstudio/) to help translate TagStudio! -## Current Features +## Feature Highlights ### 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. +A TagStudio library contains all of your tags, fields for a set of files based on one of your system directories. Similar to how Obsidian [vaults](https://help.obsidian.md/vault) function, TagStudio libraries act as a layer on top of your existing folders and file structure, and don't require your to move or duplicate files. -### Tagging + Custom Metadata +TagStudio places a `.TagStudio` folder in the folder you open as a library. Files included in your library are referred to as "entries", and are kept track of inside of a SQLite database inside the `.TagStudio` folder along with tags and other library data. -- 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) +### File Entries -### Search +All file types are supported in TagStudio libraries, just not all have dedicated preview support. For a full list of filetypes with supported previews, see the "[Supported Previews](https://docs.tagstud.io/preview-support)" page on the documentation site. There's also playback support for videos, audio files, and supported animated image formats. + +For a generalized list of what's currently supported: + +- **Images** + - Raster Images (JPEG, PNG, etc.) + - Vector (SVG) + - Animated (GIF, WEBP, APNG) + - RAW Formats +- **Videos** +- **Plaintext Files** +- **Documents** _(If supported)_ +- **eBooks** _(If supported)_ +- **Photoshop PSDs**, **Blender Projects**, **Krita Projects**, and more! + +### [Tags](https://docs.tagstud.io/tags) and [Fields](https://docs.tagstud.io/fields) + +Tags represent an object or 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. + +Tags currently consist of the following attributes: + +- **Name**: The full name for your tag. **_This does NOT have to be unique!_** +- **Shorthand Name**: The shortest alternate name for your tag, used for abbreviations. +- **Aliases**: Alternate names your tag goes by. +- **Color**: The display color of your tag. +- **Parent Tags**: Other tags in which this tag inherits from. In practice, this means that this tag can be substituted in searches for any listed parent tags. + - Parent tags checked with the "disambiguation" checkbox 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)". +- **Is Category**: A property that when checked, treats this tag as a category in the preview panel. + +Fields, like tags, are additional pieces of custom metadata that you can add to your file entries. Fields currently have several hardcoded names (e.g. "Title", "Author", "Series") but custom field names are planned for an upcoming update. + +Field types currently include: + +- **Text Lines**: Single lines of text. +- **Text Boxes**: Multi-line pieces of text. +- **Datetimes**: Dates and times. + +### [Search](https://docs.tagstud.io/search) - Search for file entries based on tags, file path (`path:`), file types (`filetype:`), and even media types! (`mediatype:`). Path searches currently use [glob](RrAi
zD|o^G>SYR9{!l+zl55<=>Q5iho4+wLq yW_anIUw+$7q>BDm)-
zOAy_7$Dj0)M+9N(`BwK g6@%Hl1J~0<{%?T!a#8J@8-@Z*NKn+)rqyv@Kiw&Qz&bt_xegu=XFS>@
zLGKW~{={v$5X>*fX6nvL*&=(KA`_6JyfEH)UMu^Dii$WuTc0*GNZkpd{vt!?(Qpso
z-Fx>4h(*^B{IP++ ?Ruz_@q|++PjUI;C4$ciF9|SBZHHw0PMCGR1hE!zF-d74aAEBn55NCD?!Mqxg`|@e}?gnb(!G`q4l?{>Cw2cXqO0QDRT(`Ts_z1(*4!@I*UIXMjT4Zut%Pk@s%l*kvSy(xX$ZF8OtB2
zay$Ja&Aa%N?fC~=)LVkCqLrsz`CR?BvgXhI?AmT#Y+fW=;OHC6^iny=#rjfHOFw*5
zH>X>-ycXa0z&-$VZ|>XP*0n8~E#)m*$@fVgF86Vc<*w{BJ0bJc~xZ6hmtiTFr@U(CUEzdrG@m*bYw%Bl;a7eBghV=lSV
zsdCNryZ9SU>p7!|R;TQ*I
BR=lnlm9--}^du
zH7j8Un1q<4Uw=IdN`UvNBd95es`=w9Qf5|G!?7xlCwALC0Tdz;ObPCxgE28!edd(7
z$})?Rt2F#k{<`>a*=yJCK`Ott^!Lt7xNr
z99cLj{#JqXk`h5i`KX$$snQQPj!XTu({f?aTn4yZ$@_LOcu)Om)+?5~xa7k^uE;!8
ze^48hYk=i7&UxN2J3ajhGxIB!?26FkpM>Mmbqu6uCK(ds`Gm
z406n9*N3
z+11Ccul@Zgcw7k)e!=#M`B`^9rfg>BS2aQvT(_Y7z=nj6kFVBBdTFRQxOZyI@JwH>
z!E)Y=vHVy|FA=JQ{MAvQD+m-kHk=Zz+|B!zkK7y>)u`!NTSm+GsUi1;
%5lWBD`t0e$h;jRTxfV-Gk_jLq>S#r@Lqt*z;
zzP~PBJl%Qm;>D2AP;S%R0i_6q9i6cG?(F#_5uO9#x`uJ$w;0)D|d@2-gHek!sYa;
K7N3a9pc}AHulm}Q|lFH
zhc;D%d1bZhNjbM8<@p}f7z<(@lm=VdfVy(KvHNy4R0>+L2|cMaR*xnPB&Dh^g`&=7
zO>T^Gjf8LKZbFHo50nixo4ys&vX``P8CzY2LDuaWp!VCXuG2yIM+D47PB-wM!^Xi8
z-NJ#dFcBXu#AR>7Twf>@KTYLiN8~H94Kh?1?8Q+&{nNlo_EY;$Sw7EA3r?=uP8kJ{
z$D@V!e{lig=mg~Zp6B>)+oK(K&Y`oPmkkDNuQqE7lgr1x%%N7kw7qw0Umk@mU$oQg
zyLaDi`CivV4%+2zYo`WkAZ7YkrDaB{2q4FBPE5+IcKFfmN!;0*@pILgBPrz`(-P*)
zx30B|>BF`^r(XN