mserajnik/quicktagr

A simple tool to quickly tag media files for booru-style media managers

1.6.1 2018-04-04 10:10 UTC

README

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

Install

For ease of use, quicktagr is available on Packagist and intended to be installed globally via Composer.

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 .bashrc, .zshrc or whatever configuration you are auto-loading on login:

export PATH=~/.composer/vendor/bin:$PATH

Dependencies

  • A terminal that supports stty (pretty much all Unix-based operating systems out of the box – Windows is not supported)
  • PHP 7.1.0 or higher
  • Composer

Updating

To update quicktagr, simply use Composer:

user@local:~$ composer global update mserajnik/quicktagr

Usage

CLI

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 file.

You can have as many working directories as you want and all of them can have different settings and tags in quicktagr.yaml.

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 quicktagr.yaml, quicktagr 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 quicktagr.yaml.

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 .txt extension.

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.

Configuration

quicktagr allows customization via the following settings:

version

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.

  • Type: Integer
  • Default: 1

supportedExtensions

Contains the supported file extensions. This should match the extension supported by your media manager.

  • Type: Array
  • Defaults:
    • gif
    • jpeg
    • jpg
    • mp4
    • png
    • swf
    • webm
  • Options: An array with string values, one per file extension.

tags

Contains the groups of tags (which by temselves contain the tags and tag templates you want to be using in that working directory).

  • Type: Object
  • Defaults:
    • simple tags
    • text placeholder templates
    • number placeholder templates
    • number placeholder templates with plural placeholders
    • implications
    • date placeholders
    • combinations
  • Options: One array per group, each one containing tags or tag templates as string values.

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:

  • location
  • objects
  • clothing
  • hair
  • events

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:

brand:bmw

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 <--T-->:

brand:<--T-->

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:

artists:<--T-->&<--T-->

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 text when the number placeholder at index x is replaced with 2 or more. The index starts with 1, so the first number placeholder has index 1, the second has 2 and 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 yyyymmdd

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 tag templates.

Donate

If you like quicktagr and want to buy me a coffee, feel free to donate via PayPal:

Donate via PayPal

Alternatively, you can also send me BTC:

Donate BTC
13jRyroNn8QF4mbGZxKS6mR3PsxjYTsGsu

Donations are unnecessary, but very much appreciated. :)

Maintainer

mserajnik

Contribute

You are welcome to help out!

Open an issue or submit a pull request.

License

MIT © Michael Serajnik