A simple tool to quickly tag media files for booru-style media managers
quicktagr is a simple command-line tool to apply tags to media files that can be used by booru-style media managers like hydrus network or szurubooru. It is also intended as a companion tool for szuruporter and generates tags files in the needed format.
Table of contents
user@local:~$ composer global require mserajnik/quicktagr
If you know your way around Composer you can do it in other ways as well but the rest of this readme will assume you've installed it globally.
Note: You might need to add Composer's global
bin directory to your path.
To do so in Linux and macOS, simply add the following to your
.zshrc or whatever configuration you are auto-loading on login:
- A terminal that supports
stty(pretty much all Unix-based operating systems out of the box – Windows is not supported)
To update quicktagr, simply use Composer:
user@local:~$ composer global update mserajnik/quicktagr
To start off, you'll need to create a directory to put the files you want to tag in (the provided directory path can be relative or absolute):
user@local:~$ quicktagr create ./some/path/
This will create a new directory called
quicktagr (you can rename it
afterwards) in the provided directory path and put a file called
quicktagr.yaml there – this is the configuration file quicktagr needs to
work. Every time you run it, it will read the configuration and tags from this
You can have as many working directories as you want and all of them can have
different settings and tags in
Next, you'll need to adjust the settings and tags in
quicktagr.yaml – see
Configuration for detailed instructions on how to do so.
Note: Should a future update break an existing
will notify you and won't attempt to run using that working directory unless
you update the settings. In that case, depending on the amount of changes, it
might be faster to just create a new working directory and adjust the settings
in that up-to-date
After you've adjusted the settings, put the media files you wish to apply tags to into the working directory and run quicktagr (again, the path can be relative or absolute):
user@local:~$ quicktagr run ./some/path/quicktagr/
quicktagr will then go through all the supported media files and prompt you to
choose which tags or tag templates you want to apply to that file. After you've
gone through all the available tags and tag templates, it will create a tags
file that has the media file's name but with an added
Note: If a tags file with that name already exists alongside the media file quicktagr will assume that you want to merge any tags inside that file with the ones you've just set.
See Groups, tags and tag templates for details on how to define tags and tag templates.
quicktagr allows customization via the following settings:
Used to indicate if an outdated version of
quicktagr.yaml is being
used. Do not change this manually unless you know what you're doing.
Contains the supported file extensions. This should match the extension supported by your media manager.
- Options: An
stringvalues, one per file extension.
Contains the groups of tags (which by temselves contain the tags and tag templates you want to be using in that working directory).
text placeholder templates
number placeholder templates
number placeholder templates with plural placeholders
- Options: One
arrayper group, each one containing tags or tag templates as
Groups, tags and tag templates
Groups are meant to be used for grouping together tags in a way you can focus on specific aspects of an image when tagging. E.g., it might be useful to put all the tags that describe the actors in the media file together in one group. That way, you know you just have to focus on all the characters displayed and nothing else while going through the tags in that group. Some additional groups could be:
Use a schema for your groups that you're comfortable with! And if you don't feel the need to split your tags into different groups, simply use a single one called tags or something similar to circumvent this mechanic altogether.
Tags themselves can have two different forms. The first one is a simple word or phrase where you just have to choose if you want to apply it to the media file or not. Some examples could be:
car clouds scenery sky
But quicktagr doesn't stop there. For example, you might want to have prefixed tags in the following form where the text after the prefix will be different depending on the media file:
So, how do you tell quicktagr that the
bmw could actually be any other text
and that you'd like to set it when applying the tag? Simple, just add a text
placeholder in the form of
quicktagr will now ask you to input text when you come across this tag. This tag is now also what we call a tag template. A tag template is simply a tag that can't be applied to a media file without being transformed (automatically or by additional user input) first. Every tag template can have any number of placeholders, so you might also do something like this:
quicktagr would now prompt you twice, starting with the first text placeholder it finds reading from left to right.
Here is a list of all the available placeholders:
<--T-->: Text placeholder, will be replaced with any text you have to provide when asked.
<--N-->: Number placeholder, will be replaced with a positive whole number you have to provide when asked.
<--P(text|x)-->: Plural placeholder, will be replaced with
textwhen the number placeholder at index
xis replaced with 2 or more. The index starts with
1, so the first number placeholder has index
1, the second has
2and so on. Multiple plural placeholders can be assigned to the same number placeholder.
<--I(tag1|tag2|tag3)-->: Implication placeholders, will be removed from the tag and any text written between the parentheses will be added as a tag (you can define multiple tags at once by separating them with
|; alternatively you can also use multiple implication placeholders). You can add as many tags as you want in a single implication placeholder but you can't use tag templates there (their placeholders will be ignored and they will be added as tags just as they are). Any tags that are already set via an implication placeholder in another tag will be skipped in case they also exist as their own separate tags (meaning quicktagr won't ask you again if you want to add them).
<--D-->: Date placeholders, will be replaced with the current date in the form
The examples provided in the default
quicktagr.yaml that is generated when
adding a new working directory should also give you some ideas on how to use
If you like quicktagr and want to buy me a coffee, feel free to donate via PayPal:
Alternatively, you can also send me BTC:
Donations are unnecessary, but very much appreciated. :)
You are welcome to help out!
Open an issue or submit a pull request.
MIT © Michael Serajnik