## English • [简体中文](./README_ZH.md) • [日本語](./README_JA.md)
## [中文文档](./README_ZH.md)
Booru style tag autocompletion for the AUTOMATIC1111 Stable Diffusion WebUI
This custom script serves as a drop-in extension for the popular [AUTOMATIC1111 web UI](https://github.com/AUTOMATIC1111/stable-diffusion-webui) for Stable Diffusion.
Tag Autocomplete is an extension for the popular [AUTOMATIC1111 web UI](https://github.com/AUTOMATIC1111/stable-diffusion-webui) for Stable Diffusion.
It displays autocompletion hints for recognized tags from "image booru" boards such as Danbooru, which are primarily used for browsing Anime-style illustrations.
Since some Stable Diffusion models were trained using this information, for example [Waifu Diffusion](https://github.com/harubaru/waifu-diffusion), using exact tags in prompts can often improve composition and help to achieve a wanted look.
Since some Stable Diffusion models were trained using this information, for example [Waifu Diffusion](https://github.com/harubaru/waifu-diffusion) and many of the NAI-descendant models or merges, using exact tags in prompts can often improve composition and consistency.
You can install it using the inbuilt available extensions list, clone the files manually as described [below](#installation), or use a pre-packaged version from [Releases](https://github.com/DominikDoom/a1111-sd-webui-tagcomplete/releases).
You can install it using the inbuilt available extensions list, clone the files manually as described [below](#-installation), or use a pre-packaged version from [Releases](https://github.com/DominikDoom/a1111-sd-webui-tagcomplete/releases).
## Common Problems & Known Issues:
- Depending on your browser settings, sometimes an old version of the script can get cached. Try `CTRL+F5` to force-reload the site without cache if e.g. a new feature doesn't appear for you after an update.
<br/>
## Screenshots & Demo videos
# ✨ Features
- 🚀 Instant completion hints while typing (under normal circumstances)
- ⌨️ Keyboard navigation
- 🌒 Dark & Light mode support
- 🛠️ Many [settings](#%EF%B8%8F-settings) and customizability
- 🌍 [Translation support](#translations) for tags, with optional live preview for the full prompt
- **Note:** Translation files are provided by the community, see [here](#list-of-translations) for a list of translations I know of.
Tag autocomplete supports built-in completion for:
- 🏷️ **Danbooru & e621 tags** (Top 100k by post count, as of November 2022)
- ✳️ [**Wildcards**](#wildcards)
-➕ [**Extra network**](#extra-networks-embeddings-hypernets-lora) filenames, including
- Textual Inversion embeddings [(jump to readme section)]
- Hypernetworks
- LoRA
- LyCORIS / LoHA
- 🪄 [**Chants**](#chants) (custom format for longer prompt presets)
- 🏷️ "[**Extra file**](#extra-file)", one set of customizable extra tags
Additionally, some support for other third party extensions exists:
(The second argument specifies the name of the folder, you can choose whatever you like).
## Additional completion support
### Wildcards
<br/>
# ❇️ Additional completion support
## Wildcards
Autocompletion also works with wildcard files used by https://github.com/AUTOMATIC1111/stable-diffusion-webui-wildcards or other similar scripts/extensions.
Completion is triggered by typing `__` (double underscore). It will first show a list of your wildcard files, and upon choosing one, the replacement options inside that file.
This enables you to either insert categories to be replaced by the script, or directly choose one and use wildcards as a sort of categorized custom tag system.
@@ -65,20 +116,21 @@ This enables you to either insert categories to be replaced by the script, or di
Wildcards are searched for in every extension folder, as well as the `scripts/wildcards` folder to support legacy versions. This means that you can combine wildcards from multiple extensions. Nested folders are also supported if you have grouped your wildcards in that way.
### Embeddings, Lora & Hypernets
Completion for these three types is triggered by typing `<`. By default it will show all three mixed together, but further filtering can be done in the following way:
## Extra networks (Embeddings, Hypernets, LoRA, ...)
Completion for these types is triggered by typing `<`. By default it will show them all mixed together, but further filtering can be done in the following way:
-`<e:` will only show embeddings
-`<l:` or `<lora:` will only show Lora
-`<l:` will only show LoRA and LyCORIS
- Or `<lora:` and `<lyco:` respectively for the long form
-`<h:` or `<hypernet:` will only show Hypernetworks
#### Embedding type filtering
### Embedding type filtering
Embeddings trained for Stable Diffusion 1.x or 2.x models respectively are incompatible with the other type. To make it easier to find valid embeds, they are categorized by "v1 Embedding" and "v2 Embedding", including a slight color difference. You can also filter your search to include only v1 or v2 embeddings by typing `<v1/2` or `<e:v1/2` followed by the actual search term.
For example:
### Chants
## Chants
Chants are longer prompt presets. The name is inspired by some early prompt collections from Chinese users, which often were called along the lines of "Spellbook", "Codex", etc. The prompt snippets from such documents were fittingly called spells or chants for this reason.
Similar to embeddings and loras, this feature is triggered by typing the `<`, `<c:` or `<chant:` commands. For instance, when you enter `<c:HighQuality` in the prompt box and select it, the following prompt text will be inserted:
@@ -88,6 +140,9 @@ Similar to embeddings and loras, this feature is triggered by typing the `<`, `<
Chants can be added in JSON files following this format:
<details>
<summary>Chant format (click to expand)</summary>
```json
[
{
@@ -110,6 +165,9 @@ Chants can be added in JSON files following this format:
}
]
```
</details>
<br/>
The file can then be selected using the "Chant file" settings dropdown if it is located inside the extension's `tags` folder.
A chant object has four fields:
@@ -118,7 +176,7 @@ A chant object has four fields:
-`content` - The actual prompt content
-`color` - Color, using the same category color system as normal tags
### Umi AI tags
## Umi AI tags
https://github.com/Klokinator/Umi-AI is a feature-rich wildcard extension similar to Unprompted or Dynamic Wildcards.
In recent releases, it uses YAML-based wildcard tags to enable a complex chaining system,for example `<[preset][--female][sfw][species]>` will choose the preset category, exclude female related tags, further narrow it down with the following categories, and then choose one random fill-in matching all these criteria at runtime. Completion is triggered by `<[` and then each following new unclosed bracket, e.g. `<[xyz][`, until closed by `>`.
@@ -127,77 +185,236 @@ It also shows how many fill-in tags are available to choose from for that combo
Most of the credit goes to [@ctwrs](https://github.com/ctwrs) here, they contributed a lot as one of the Umi developers.
## Settings
# 🛠️ Settings
The extension has a large amount of configuration & customizability built in:
The extension has a large amount of configuration & customizability built in. Most should be self-explanatory, but for a detailed description click on a section below.
The main tag file the script uses. Included by default are `danbooru.csv` and `e621.csv`. While you can add custom tags here, the vast majority of models are not trained on anything other than these two (mostly danbooru), so it will not have much benefit.
You can also set it to `None` if you want to use other functionality of the extension (e.g. Wildcard or LoRA completion), but aren't interested in the normal tags.
While the above options can turn off tag autocomplete globally, sometimes you might want to enable or disable it only for specific models. For example, if most of your models are Anime ones, you could add your photorealistic models, that weren't trained on booru tags and don't benefit from it, to the blacklist, which will automatically disable it after you switch to these models. You can use both the model name (including file extension) and their webui hashes (both short and long form).
`Blacklist` will exclude all specified models, while `Whitelist` will only activate it for these and stay off by default. One exception is an empty whitelist, which will be ignored (making it the same as an empty blacklist).
<summary>Move completion popup with cursor</summary>
This option enables or disables the floating popup to follow the position of your cursor, like it would do in an IDE. The script tries to reserve enough room for the popup to prevent squishing on the right side, but that doesn't always work for longer tags. If disabled, the popup will stay on the left.
Settings for the amount of results to show at once.
If `Show all results` is active, it will show a scrollable list instead of cutting it off after the number specified in `Maximum results`. For performance reasons, in that case not all are loaded at once, but instead in blocks. The block size is dictated by `How many results to load at once`. Once you reach the bottom, the next block will load (but that should rarely happen).
Notably, `Maximum results` will still have an influence if `Show all results` is used, since it dictates the height of the popup before scrolling begins.
Depending on the configuration, real time tag completion can get computationally expensive.
This option sets a "debounce" delay in milliseconds (1000ms = 1s), during which no second completion will get queried. This might especially be useful if you type very fast.
If this option is turned on, it will show a `?` link next to the tag. Clicking this will try to open the wiki page for that tag on danbooru or e621, depending on which tag file you use.
> ⚠️ Warning:
>
> Danbooru and e621 are external sites and include a lot of NSFW content, which might show in the list of examples for a tag on its wiki page. Because of this, the option is disabled by default.
These settings specify how the text will be inserted.
Booru sites mostly use underscores in tags instead of spaces, but during preprocessing most models replaced this back with spaces since the CLIP encoder used in Stable diffusion was trained on natural language. Thus, by default tag autocomplete will as well.
Parentheses are used as control characters in the webui to give more attention / weight to a specific part of the prompt, so tags including parentheses are escaped (`\( \)`) by default to not influence that.
Depending on the last setting, tag autocomplete will append a comma and space after inserting a tag, which may help for rapid completion of multiple tags in a row.
Tags often are referred to with multiple aliases. If `Search by alias` is turned on, those will be included in the search results, which might help if you are unsure of the correct tag. They will still get replaced by the actual tag they are linked to on insertion, since that is what the models were trained on.
`Only show alias` sets if you want to see only the alias or also the tag it maps to
Tag Autocomplete has support for tag translations specified in a separate file (`Translation filename`). You can search for tags using those translations, meaning that if you don't know the English tagword and have a translation file in your native language, you can use that instead.
It also has a legacy format option for some old files used in the community, as well as an experimental live translation preview for the whole prompt so you can easily find and edit tags afterwards.
For more details, see the [section on translations](#translations) below.
Specifies a set of extra tags that get appended either before or after the regular results, as specified here. Mostly useful for small custom tag sets such as the commonly used quality tags (masterpiece, best quality, etc.)
If you want completion for longer presets or even whole prompts, have a look at [Chants](#chants) instead.
Chants are longer presets or even whole prompts that can be selected & inserted at once, similar to the built in styles dropdown of the webui. They do offer some additional features though, and are faster to use.
For more info, see the section on [Chants](#chants) above.
Here, you can change the default colors used for different tag categories. They were chosen to be similar to the category colors of their source site.
The format is standard JSON
- The object names correspond to the tag filename they should be used for.
- The numbers are specifying the tag type, which is dependent on the tag source. For more info, see [CSV tag data](#csv-tag-data).
- The first value in the square brackets is for dark, the second for light mode. HTML color names and hex codes should both work.
| Setting | Description |
|---------|-------------|
| tagFile | Specifies the tag file to use. You can provide a custom tag database of your liking, but since the script was developed with Danbooru tags in mind, it might not work properly with other configurations.|
| activeIn | Allows to selectively (de)activate the script for txt2img, img2img, and the negative prompts for both. |
| maxResults | How many results to show max. For the default tag set, the results are ordered by occurence count. For embeddings and wildcards it will show all results in a scrollable list. |
| resultStepLength | Allows to load results in smaller batches of the specified size for better performance in long lists or if showAllResults is true. |
| delayTime | Specifies how much to wait in milliseconds before triggering autocomplete. Helps prevent too frequent updates while typing. |
| showAllResults | If true, will ignore maxResults and show all results in a scrollable list. **Warning:** can lag your browser for long lists. |
| replaceUnderscores | If true, undescores are replaced with spaces on clicking a tag. Might work better for some models. |
| escapeParentheses | If true, escapes tags containing () so they don't contribute to the web UI's prompt weighting functionality. |
| appendComma | Specifies the starting value of the "Append commas" UI switch. If UI options are disabled, this will always be used. |
| useWildcards | Used to toggle the wildcard completion functionality. |
| useEmbeddings | Used to toggle the embedding completion functionality. |
| alias | Options for aliases. More info in the section below. |
| translation | Options for translations. More info in the section below. |
| extras | Options for additional tag files / aliases / translations. More info below. |
| chantFile | The file to use for chants (longer prompt presets / shortcuts). |
| keymap | Customizable hotkeys. |
| colors | Customizable tag colors. More info below. |
### Colors
Tag type colors can be specified by changing the JSON code in the tag autocomplete settings.
The format is standard JSON, with the object names corresponding to the tag filenames (without the .csv) they should be used for.
The first value in the square brackets is for dark, the second for light mode. Color names and hex codes should both work.
```json
{
"danbooru":{
"-1":["red","maroon"],
"0":["lightblue","dodgerblue"],
"1":["indianred","firebrick"],
"3":["violet","darkorchid"],
"4":["lightgreen","darkgreen"],
"5":["orange","darkorange"]
},
"e621":{
"-1":["red","maroon"],
"0":["lightblue","dodgerblue"],
"1":["gold","goldenrod"],
"3":["violet","darkorchid"],
"4":["lightgreen","darkgreen"],
"5":["tomato","darksalmon"],
"6":["red","maroon"],
"7":["whitesmoke","black"],
"8":["seagreen","darkseagreen"]
}
}
```
This can also be used to add new color sets for custom tag files.
The numbers are specifying the tag type, which is dependent on the tag source. For an example, see [CSV tag data](#csv-tag-data).
Like on Booru sites, tags can have one or multiple aliases which redirect to the actual value on completion. These will be searchable / shown according to the settings in `config.json`:
-`searchByAlias` - Whether to also search for the alias or only the actual tag.
-`onlyShowAlias` - Shows only the alias instead of `alias -> actual`. Only for displaying, the inserted text at the end is still the actual tag.
This is a "fake" setting, meaning it doesn't actually configure anything. Rather, it is a small hack to abuse the refresh button developers can add to webui options. Clicking on the refresh button next to this setting will force tag autocomplete to recreate and reload some temporary internal files, which normally only happens on restarting the UI.
#### Translations
Tag autocomplete depends on these files for various functionality, especially related to extra networks and wildcard completion. This setting can be used to rebuild the lists if you have, for example, added a few new LoRAs into the folder and don't want to restart the UI to get tag autocomplete to list them.
You can also add this to your quicksettings bar to have the refresh button available at all times.
An additional file can be added in the translation section, which will be used to translate both tags and aliases and also enables searching by translation.
This file needs to be a CSV in the format `<English tag/alias>,<Translation>`, but for backwards compatibility with older files that used a three column format, you can turn on `oldFormat` to use that instead.
This file needs to be a CSV in the format `<English tag/alias>,<Translation>`, but for backwards compatibility with older files that used a three column format, you can turn on `Translation file uses old 3-column translation format instead of the new 2-column one` to support them. In that case, the second column will be unused and skipped during parsing.
- [🇨🇳 Chinese tags](https://github.com/DominikDoom/a1111-sd-webui-tagcomplete/discussions/23) by @HalfMAI, using machine translation and manual correction for the most common tags (uses legacy format)
- [🇨🇳 Chinese tags](https://github.com/sgmklp/tag-for-autocompletion-with-translation) by @sgmklp, smaller set of manual translations based on https://github.com/zcyzcy88/TagTable
> ### 🫵 I need your help!
> Translations are a community effort. If you have translated a tag file or want to create one, please open a Pull Request or Issue so your link can be added here.
> Please make sure the quality is alright though, machine translation gets a lot of stuff wrong even for the most common tags.
## Live preview
> ⚠️ Warning:
>
> This feature is still experimental, you might encounter some bugs when using it.
This will show a live preview of all detected tags in the prompt, both correctly separated by commas as well as in a longer sentence. It can detect up to three-word pairs in natural sentences, preferring perfect multi-word matches over single tags.
Above the detected tags will be their translation from the translation file, so if you aren't sure what the English tag means, you can easily find it there even after they have been inserted into the prompt (instead of just in the popup during completion).
The option defaults to off, but you can activate it by choosing a translation file and checking "Show live tag translation below prompt".
It will not affect the normal functionality if it is off.
The translation updates when the user types or pastes text, but not if the action happens programmatically (e.g. applying a style or loading from PNG Info / Image Browser). This can be worked around by typing something manually after the programmatic edit.
# Extra file
An extra file can be used to add new / custom tags not included in the main set.
The format is identical to the normal tag format shown in [CSV tag data](#csv-tag-data) below, with one exception:
Since custom tags likely have no count, column three (or two if counting from zero) is instead used for the gray meta text displayed next to the tag.
@@ -209,7 +426,7 @@ An example with the included (very basic) extra-quality-tags.csv file:
Whether the custom tags should be added before or after the normal tags can be chosen in the settings.
## CSV tag data
# CSV tag data
The script expects a CSV file with tags saved in the following way:
```csv
<name>,<type>,<postCount>,"<aliases>"
@@ -248,3 +465,34 @@ or similarly for e621:
|8 | Lore |
The tag type is used for coloring entries in the result list.
## ⚠️ Common Problems & Known Issues:
- Depending on your browser settings, sometimes an old version of the script can get cached. Try
<kbd>CTRL</kbd> + <kbd>F5</kbd>
to force-reload the site without cache if e.g. a new feature doesn't appear for you after an update.
- If the prompt popup has broken styling for you or doesn't appear at all (like [this](https://github.com/DominikDoom/a1111-sd-webui-tagcomplete/assets/34448969/7bbfdd54-fc23-4bfc-85af-24704b139b3a)), make sure to update your **openpose-editor** extension if you have it installed. It is known to cause issues with other extensions in older versions.
<!-- Variable declarations for shorter main text -->
web UIに内蔵されている利用可能な拡張機能リストを使用してインストールするか、[以下の説明](#インストール)に従ってファイルを手動でcloneするか、または[リリース](https://github.com/DominikDoom/a1111-sd-webui-tagcomplete/releases)からパッケージ化されたバージョンを使用することができます。
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
