mirror of
https://github.com/TagStudioDev/TagStudio.git
synced 2026-01-29 06:10:51 +00:00
Merge branch 'main' into test-support-2
This commit is contained in:
Vele George
GitHub
142
README.md
142
README.md
@@ -1,4 +1,4 @@
|
||||
# TagStudio (Preview/Alpha): A User-Focused Document Management System
|
||||
# TagStudio (Alpha): A User-Focused Document Management System
|
||||
|
||||
<p align="center">
|
||||
<img width="60%" src="github_header.png">
|
||||
@@ -15,6 +15,7 @@ TagStudio is a photo & file organization application with an underlying system t
|
||||
</p>
|
||||
|
||||
## Contents
|
||||
|
||||
- [Goals](#goals)
|
||||
- [Priorities](#priorities)
|
||||
- [Current Features](#current-features)
|
||||
@@ -45,72 +46,28 @@ TagStudio is a photo & file organization application with an underlying system t
|
||||
- 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>`)
|
||||
- Search for entries based on tags, ~~metadata~~ (TBA), or filenames/filetypes (using `filename: <query>`)
|
||||
- Special search conditions for entries that are: `untagged`/`no tags` and `empty`/`no fields`.
|
||||
|
||||
> [!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:
|
||||
|
||||
- required to run the app: `pip install -r requirements.txt`
|
||||
- required to develop: `pip install -r requirements-dev.txt`
|
||||
|
||||
|
||||
To run all the tests use `python -m pytest tests/` from the `tagstudio` folder.
|
||||
|
||||
_Learn more about setting up a virtual environment [here](https://docs.python.org/3/tutorial/venv.html)._
|
||||
|
||||
### Launching
|
||||
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. 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.
|
||||
|
||||
> [!NOTE]
|
||||
> Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python3`.
|
||||
> 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.
|
||||
|
||||
#### Optional Arguments
|
||||
|
||||
Optional arguments to pass to the program.
|
||||
|
||||
> `--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.
|
||||
> `--config-file <path>` / `-c <path>`
|
||||
> Path to a TagStudio Library folder to open on start.
|
||||
|
||||
## Usage
|
||||
|
||||
@@ -202,11 +159,61 @@ Import JSON sidecar data generated by [gallery-dl](https://github.com/mikf/galle
|
||||
> [!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.
|
||||
|
||||
## Creating a Development Environment
|
||||
|
||||
If you're interested in contributing to TagStudio or just wish to poke around the live codebase, here are instructions for setting up the Python project.
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Python 3.12
|
||||
|
||||
### Creating a Python Virtual Environment
|
||||
|
||||
> [!NOTE]
|
||||
> Depending on your system, Python may be called `python`, `py`, `python3`, or `py3`. These instructions use the alias `python3`. You can check to see which alias you system uses and if it's for the correct Python version by typing `python3 --version` (or whichever alias) into your terminal.
|
||||
|
||||
_Skip these steps if launching from the .sh script on Linux/macOS._
|
||||
|
||||
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:
|
||||
|
||||
- required to run the app: `pip install -r requirements.txt`
|
||||
- required to develop: `pip install -r requirements-dev.txt`
|
||||
|
||||
|
||||
To run all the tests use `python -m pytest tests/` from the `tagstudio` folder.
|
||||
|
||||
_Learn more about setting up a virtual environment [here](https://docs.python.org/3/tutorial/venv.html)._
|
||||
|
||||
### Launching Development Environment
|
||||
|
||||
- **Windows** (start_win.bat)
|
||||
|
||||
- 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.
|
||||
|
||||
- **Linux/macOS** (TagStudio.sh)
|
||||
|
||||
- Run the "TagStudio.sh" script, and the program should launch! (Make sure that the script is marked as executable if on Linux). 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 `./TagStudio.sh`.
|
||||
|
||||
- **NixOS** (TagStudio.sh)
|
||||
- Use the provided `flake.nix` file to create and enter a working environment by running `nix develop`. Then, run the `TagStudio.sh` script.
|
||||
|
||||
- **Any** (No Scripts)
|
||||
|
||||
- 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`.
|
||||
|
||||
## FAQ
|
||||
|
||||
### What State Is the Project Currently In?
|
||||
|
||||
As of writing (Alpha v9.1.0) the project is in a “useable” state, however it lacks proper testing and quality of life features. Currently the program has only been verified to work properly on Windows, and is unlikely to properly run on Linux or macOS in its current state, however this functionality is a priority going forward with testers.
|
||||
As of writing (Alpha v9.2.0) the project is in a useable state, however it lacks proper testing and quality of life features.
|
||||
|
||||
### What Features Are You Planning on Adding?
|
||||
|
||||
@@ -219,18 +226,16 @@ Of the several features I have planned for the project, these are broken up into
|
||||
- Boolean Search
|
||||
- Coexisting Text + Tag Search
|
||||
- Searchable File Metadata
|
||||
- Tag management view
|
||||
- Applying metadata via multi-selection
|
||||
- Comprehensive Tag management tab
|
||||
- Easier ways to apply tags in bulk
|
||||
- Tag Search Panel
|
||||
- Recent Tags Panel
|
||||
- Top Tags Panel
|
||||
- Pinned Tags Panel
|
||||
- Apply tags based on system folders
|
||||
- Better (stable, performant) library grid view
|
||||
- Improved entry relinking
|
||||
- Cached thumbnails
|
||||
- Collations
|
||||
- Tag-like Groups
|
||||
- Resizable thumbnail grid
|
||||
- User-defined metadata fields
|
||||
- Multiple directory support
|
||||
@@ -240,13 +245,13 @@ Of the several features I have planned for the project, these are broken up into
|
||||
- Better internal API for accessing Entries, Tags, Fields, etc. from the library.
|
||||
- Proper testing workflow
|
||||
- Continued code cleanup and modularization
|
||||
- Reassessment of save file structure in order to prioritize portability (leading to exportable tags, presets, etc)
|
||||
- Exportable/importable library data including "Tag Packs"
|
||||
|
||||
#### Future Features
|
||||
|
||||
- Support for multiple simultaneous users/clients
|
||||
- Draggable files outside the program
|
||||
- Ability to ignore specific files
|
||||
- Comprehensive filetype whitelist
|
||||
- A finished “macro system” for automatic tagging based on predetermined criteria.
|
||||
- Different library views
|
||||
- Date and time fields
|
||||
@@ -254,20 +259,20 @@ Of the several features I have planned for the project, these are broken up into
|
||||
- Audio waveform previews
|
||||
- 3D object previews
|
||||
- Additional previews for miscellaneous file types
|
||||
- Exportable/sharable tags and settings
|
||||
- Optional global tags and settings, spanning across libraries
|
||||
- Importing & exporting libraries to/from other programs
|
||||
- Port to a more performant language and modern frontend (Rust?, Tauri?, etc.)
|
||||
- Plugin system
|
||||
- Local OCR search
|
||||
- Support for local machine learning-based tag suggestions for images
|
||||
- Mobile version
|
||||
- Mobile version _(FAR future)_
|
||||
|
||||
#### Features I Likely Won’t Add/Pull
|
||||
- Native Cloud Integration
|
||||
|
||||
- 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. Pointing TagStudio to one of these mounts should function similarly to what native integration would look like.
|
||||
- Native ChatGPT/Non-Local LLM Integration
|
||||
- This could mean different things depending on what you're intending. 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).
|
||||
- This could mean different things depending on what you're intending. 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).
|
||||
|
||||
### Why Is the Version Already v9?
|
||||
|
||||
@@ -275,14 +280,19 @@ I’ve been developing this project over several years in private, and have gone
|
||||
|
||||
### Wait, Is There a CLI Version?
|
||||
|
||||
As of right now, no. However, I _did_ have a CLI version in the recent past before dedicating my efforts to the Qt GUI version. I’ve left in the currently-inoperable CLI code just in case anyone was curious about it. Also yes, it’s just a bunch of glorified print statements (_the outlook for some form of curses on Windows didn’t look great at the time, and I just needed a driver for the newly refactored code...)._
|
||||
As of right now, **no**. However, I _did_ have a CLI version in the recent past before dedicating my efforts to the Qt GUI version. I’ve left in the currently-inoperable CLI code just in case anyone was curious about it. Also yes, it’s just a bunch of glorified print statements (_the outlook for some form of curses on Windows didn’t look great at the time, and I just needed a driver for the newly refactored code...)._
|
||||
|
||||
### Can I Contribute?
|
||||
|
||||
**Yes!!** I recommend taking a look at the [Priority Features](#priority-features), [Future Features](#future-features), and [Features I Won't Pull](#features-i-likely-wont-addpull) lists, as well as the project issues to see what’s currently being worked on. Please do not submit pull requests with new feature additions without opening up an issue with a feature request first.
|
||||
|
||||
Code formatting is automatically checked via [ruff](https://docs.astral.sh/ruff/).
|
||||
Code formatting is automatically checked via [Ruff](https://docs.astral.sh/ruff/).
|
||||
|
||||
To format the code manually, install ruff via `pip install -r requirements-dev.txt` and then run `ruff format`
|
||||
To format the code manually, install ruff via `pip install -r requirements-dev.txt` and then run `ruff format`
|
||||
|
||||
To format the code automatically before each commit, there's a configured action available for `pre-commit` hook. Install it by running `pre-commit install`. The hook will be executed each time on running `git commit`.
|
||||
|
||||
More structured documentation on contribution requirements is on its way, but for now:
|
||||
|
||||
- Use `pathlib` in favor of `os.path`
|
||||
- Try to make new UI additions match the existing style of the application
|
||||
|
||||
Reference in New Issue
Block a user