以用户为中心的文档管理系统

# TagStudio (Preview/Alpha): A User-Focused Document Management System <p align="center"> <img width="60%" src="github_header.png"> </p> > [!CAUTION] > This is still a **_very_** rough personal project of mine in its infancy. I’m open-sourcing it now in order to accept contributors sooner and to better facilitate the direction of the project from an earlier stage. > There **_are_** bugs, and there will **_very likely_** be breaking changes! 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. <p align="center"> <img width="80%" src="screenshot.jpg"> </p> ## Contents - [Goals](#goals) - [Priorities](#priorities) - [Current Features](#current-features) - [Installation](#installation) - [Usage](#usage) - [FAQ](#faq) ## 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. ## 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._ 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. ## 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, or filename (using `filename: <query>`) - Special search conditions for entries that are: `untagged`/`no tags` and `empty`/`no fields`. > [!NOTE] > For more information on the project itself, please see the [FAQ](#faq) section and other docs. ## Installation > [!CAUTION] > TagStudio is only currently verified to work on Windows. I've run into issues with the Qt code running on Linux, but I don't know how severe these issues are. There's also likely bugs regarding filenames and portability of the databases across different OSes. ### Prerequisites - Python 3.12 ### Creating the Virtual Environment *Skip this step if launching from the .sh script on Linux.* 1. In the root repository directory, create a python virtual environment: `python3 -m venv .venv` 2. Activate your environment: - Windows w/Powershell: `.venv\Scripts\Activate.ps1` - Windows w/Command Prompt: `.venv\Scripts\activate.bat` - Linux/macOS: `source .venv/bin/activate` 3. Install the required packages: `pip install -r requirements.txt` _Learn more about setting up a virtual environment [here](https://docs.python.org/3/tutorial/venv.html)._ ### Launching > [!NOTE] > Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python3`. #### Optional Arguments > `--open <path>` / `-o <path>` > Path to a TagStudio Library folder to open on start. #### Windows To launch TagStudio, launch the `start_win.bat` file. You can modify this .bat file or create a shortcut and add one or more additional arguments if desired. Alternatively, with the virtual environment loaded, run the python file at `tagstudio\tag_studio.py` from your terminal. If you're in the project's root directory, simply run `python3 tagstudio/tag_studio.py`. > [!CAUTION] > TagStudio on Linux & macOS likely won't function correctly at this time. If you're trying to run this in order to help test, debug, and improve compatibility, then charge on ahead! #### macOS With the virtual environment loaded, run the python file at "tagstudio/tag_studio.py" from your terminal. If you're in the project's root directory, simply run `python3 tagstudio/tag_studio.py`. When launching the program in the future, remember to activate the virtual environment each time before launching *(an easier method is currently being worked on).* #### Linux Run the "TagStudio.sh" script, and the program should launch! (Make sure that the script is marked as executable). Note that launching from the script from outside of a terminal will not launch a terminal window with any debug or crash information. If you wish to see this information, just launch the shell script directly from your terminal with `sh TagStudio.sh`. ##### NixOS Use the provided `flake.nix` file to create and enter a working environment by running `nix develop`. Then, run the above `TagStudio.sh` script. ## Usage ### Creating/Opening a Library With TagStudio opened, start by creating a new library or opening an existing one using File -> Open/Create Library from the menu bar. TagStudio will automatically create a new library from the chosen directory if one does not already exist. Upon creating a new library, TagStudio will automatically scan your folders for files and add those to your library (no files are moved during this process!). ### 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. ### Adding Metadata to Entries To add a metadata field to a file entry, start by clicking the “Add Field” button under the file preview in the right-hand preview panel. From the dropdown menu, select the type of metadata field you’d like to add to the entry. ### Editing Metadata Fields #### Text Line / Text Box Hover over the field and click the pencil icon. From there, add or edit text in the dialog box popup. #### Tag Box Click the “+” button at the end of the Tags list, and search for tags to add inside the new dialog popup. 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 add the first item in the list. Press Enter/Return once more to close the dialog box > [!WARNING] > Keyboard control and navigation is currently _very_ buggy, but will be improved in future versions. ### Creating Tags To create a n