-
Notifications
You must be signed in to change notification settings - Fork 93
UserGuide
When an archive is opened, and it has no tags, ComicTagger will attempt to parse the filename to glean some information. Generally, it expects a format similar to this:
SERIES_NAME vVOLNUM ISSUENUM (of COUNT) (PUBYEAR).ext
or
SERIES_NAME (SERIESYEAR) ISSUENUM (of COUNT) (PUBYEAR).ext
i.e.
Plastic Man v1 002 (1942).cbz
Blue Beetle 02.cbr
Monster Island vol. 2 #2.cbz
Crazy Weird Comics 2 (of 2) (1969).rar
Super Strange Yarns (1957) #92 (1969).cbz
Action Spy Tales v1965 #3.cbr
(In this scheme, the PUBYEAR refers to publication year of the issue, and SERIESYEAR as the start year of the volume/series)
Some other notes:
- ComicTagger is happiest when the issue number has a "#" in front of it:
Foobar-Man #121 (1974).cbz
- The volume name should come after the series name and before the issue number.
Foobar-Man Annual v2 #121 (1984).cbz
Foobar-Man Annual Vol. 2 121 (1984).cbz
- The first thing the filename parser tries to find is the issue number. If the '#' isn't used, the parser will try to find the most likely number. Generally, any parts of the filename that don't have parentheses around them are considered. The first example is will parse okay:
Foobar-Man Annual v2 121 (The Wrath of Foobar-Man, Part 1 of 2).cbz
This second example will not parse OK as the parser doesn't know which number is the issue number:
Foobar-Man Annual 121 - The Wrath of Foobar-Man, Part 1 of 2.cbz
You can also use a double dash ("--") or double underscore ("
__") to precede the part of the filename that won't be parsed. The following example will parse OK, since the text after the double dash will be ignored:
Foobar-Man Annual v2 121 -- The Wrath of Foobar-Man, Part 1 of 2.cbz
- As mentioned above, most text in parentheses will be ignored. This is also true for text after "--" or "
__":
Monster Island v1 1 (orginal cover) (c2c) .cbz
Monster_Island_v1_2__repaired__c2c.cbz
Monster Island v1 3 (1957) -- The Revenge Of King Klong (noads).cbz
Any text that is not explicitly parsed as series name, volume, issue number, or publication year, or issue count will be saved in the "scan info" field, if enabled.
- There should only be either a volume number or series year in the file name, since these are interpreted by the parser as the same thing. Whether to use start year or sequential volume numbers seems a matter of personal preference, but as even the publishers' use of sequential volume numbers is inconsistent, the start year is more unambiguous.
The following examples show variations on use of the series year. Any text in the parentheses after the "-" will be ignored by the parse:
Dusk Vampire (2010) #1.cbz
Dusk Vampire (2010-) #1.cbz
Dusk Vampire (2010-2012) #1.cbz
The cleaner the original filename is, the better ComicTagger is at matching online.
ComicTagger uses an image processing technique to compare the cover image of an archive with images found online to determine the correct metadata.
When an online search and auto-identification is attempted, ComicTagger will use the series name, issue number, and optionally the publication year to find the best match. Once the list of possibilities is narrowed, it will compare cover images to find the right choice.
(If the filename parsing failed to properly fill in the series name and number, you can manually enter those fields before you do the auto-identify.)
Obstacles to this process are alternate covers, duplicate covers ( such as multiple editions with the same numbering and virtually identical covers), improperly or poorly named files, and mis-sequenced cover images in the archive.
The settings allow the user to mitigate some of these problems by blacklisting certain publishers, and narrowing the name matching.
ComicTagger caches online search results and images from ComicVine in a temporary database to improve speed when doing similar searches repeatedly.
In order to read and write RAR and CBR archives, you will need to download tools from WinRAR. You may need to specify the tool locations via the settings/preferences dialog.
ComicTagger uses the command-line tools "rar" and "unrar", which, despite the warnings of the WinRAR GUI, don't seem to expire. So, no need to pay!
The template uses Python format strings, in the simplest use it replaces the field (e.g. {issue}) with the value for that particular comic (e.g. 1) for advanced formatting please reference the Python 3 documentation
Accepts the following variables:
| Tag name | Type |
|---|---|
| {is_empty} | boolean |
| {tag_origin} | string |
| {series} | string |
| {issue} | string |
| {title} | string |
| {publisher} | string |
| {month} | integer |
| {year} | integer |
| {day} | integer |
| {issue_count} | integer |
| {volume} | integer |
| {genre} | string |
| {language} | string |
| {comments} | string |
| {volume_count} | integer |
| {critical_rating} | string |
| {country} | string |
| {alternate_series} | string |
| {alternate_number} | string |
| {alternate_count} | integer |
| {imprint} | string |
| {notes} | string |
| {web_link} | string |
| {format} | string |
| {manga} | string |
| {black_and_white} | boolean |
| {page_count} | integer |
| {maturity_rating} | string |
| {story_arc} | string |
| {series_group} | string |
| {scan_info} | string |
| {characters} | string |
| {teams} | string |
| {locations} | string |
| {credits} | list of dict({'role': string, 'person': string, 'primary': boolean}) |
| {writer} | string |
| {penciller} | string |
| {inker} | string |
| {colorist} | string |
| {letterer} | string |
| {cover artist} | string |
| {editor} | string |
| {tags} | list of string |
| {pages} | dict({'Image': string(int), 'Type': string, 'Bookmark': string, 'DoublePage': string}) |
CoMet-only items:
| Tag name | Type |
|---|---|
| {price} | float |
| {is_version_of} | string |
| {rights} | string |
| {identifier} | string |
| {last_mark} | string |
| {cover_image} | string |
Examples:
{series} {issue} ({year})
Spider-Geddon 1 (2018)
{series} #{issue} - {title}
Spider-Geddon #1 - New Players; Check In
Renaming based on tag data is available, and a template can be set via the GUI settings dialog, or directly editing the settings file.
The template string accepts the following variables:
%series%
%issue%
%volume%
%issuecount%
%year%
%month%
%month_name%
%publisher%
%title%
%genre%
%language_code%
%criticalrating%
%alternateseries%
%alternatenumber%
%alternatecount%
%imprint%
%format%
%maturityrating%
%storyarc%
%seriesgroup%
%scaninfo%For example, the template:
%series% #%issue% (%year%)
might yield the name:
Plastic Man #002 (1944)
A "smart text cleanup" can optionally remove extra characters if some of the variables have empty values. For example, if there is no publication year available, the smart cleanup will remove the empty parentheses in the above example.
The ComicBookLover tag format (ComicBookInfo or CBI) has less dedicated fields than Comic Vine or the ComicRack format, but it does allow for a generic tag list that can be of any length. In addition, CBI has a unique way of managing credit information that has a concept of "Primary Writer" and "Primary Artist", which can often be guessed from the data at hand.
To try to cope with these idiosyncrasies, ComicTagger has a set of one-way optional "transforms" can be applied to when copying from other tag formats, when fetching data from Comic Vine, or manually via the GUI.
The transforms include:
- Assume the only writer or artist credit is the primary one
- Copying the list of characters to the generic tags
- Copying the list of teams to the generic tags
- Copying the list of locations to the generic tags
- Copying the weblink to the text comments
ComicTagger keeps the program settings (and caches) in a special folder. On Windows, you might find it in a folder like:
C:\Users\username\AppData\roaming\ComicTaggerThis might be a little different, depending on your version of Windows
On Unix systems, (including Mac) something like this:
/Users/username/.ComicTaggeror
/home/username/.ComicTaggerThe settings for the app affect both GUI and CLI mode. If you're using the GUI, everything in the settings folder can be changed via the app. If only using CLI mode, you might want to edit things such as RAR program location, and identifier settings.
The setting file itself is a standard "ini" format, and very human-readable.
[settings]
rar_exe_path = /Users/timmy/Downloads/rar/rar
check_for_new_version = False
send_usage_stats = False
unrar_lib_path =
[auto]
install_id = 17cc872250dd4293ae0d9185822c71fa
last_selected_load_data_style = 1
last_selected_save_data_style = 1
last_opened_folder = /Users/timmy/Downloads
last_main_window_width = 1096
last_main_window_height = 647
last_main_window_x = 501
last_main_window_y = 100
last_form_side_width = 839
last_list_side_width = 228
last_filelist_sorted_column = 0
last_filelist_sorted_order = 0
[identifier]
id_length_delta_thresh = 5
id_publisher_blacklist = Panini Comics, Abril, Planeta DeAgostini, Editorial Televisa, Dino Comics
id_publisher_filter = Panini Comics, Abril, Planeta DeAgostini, Editorial Televisa, Dino Comics
id_series_match_search_thresh = 90
id_series_match_identify_thresh = 91
[dialogflags]
ask_about_cbi_in_rar = True
ask_about_usage_stats = True
hide_rename_message = True
show_disclaimer = False
dont_notify_about_this_version =
settings_warning = 0
show_no_unrar_warning = True
[filenameparser]
parse_scan_info = True
complicated_parser = False
remove_c2c = False
remove_fcbd = False
remove_publisher = False
split_words = True
[comicvine]
sort_series_by_year = True
exact_series_matches_first = True
use_series_start_as_volume = False
clear_form_before_populating_from_cv = True
remove_html_tables = False
always_use_publisher_filter = False
cv_api_key = 63a92cc70ce2d0b371a73c1071cffc8921243d95
cv_url =
[cbl_transform]
assume_lone_credit_is_primary = False
copy_characters_to_tags = False
copy_teams_to_tags = False
copy_locations_to_tags = False
copy_storyarcs_to_tags = False
copy_notes_to_comments = False
copy_weblink_to_comments = False
apply_cbl_transform_on_cv_import = False
apply_cbl_transform_on_bulk_operation = False
[rename]
rename_issue_number_padding = 0
rename_extension_based_on_archive = True
rename_template = {series} ({volume}) #{issue} [{title}] [{story_arc}] [{month_name}, {year}] {language}
rename_new_renamer = True
rename_strict = True
rename_use_smart_string_cleanup = True
rename_dir =
rename_move_dir = False
[autotag]
save_on_low_confidence = False
dont_use_year_when_identifying = False
assume_1_if_no_issue_num = True
ignore_leading_numbers_in_filename = False
remove_archive_after_successful_match = False
wait_and_retry_on_rate_limit = False
auto_imprint = False
The GUI is for the most part pretty intuitive. You open files or folders via the menu, or by drag-and-drop, edit the tag fields, and save. But a some portions deserve a few words.
The right side of the main window is a list of all the comic files that have been opened by ComicTagger. As each file is read in, its existing metadata and other information are parsed and cached for quick browsing. Changing main selections in the list will cause the form to update, depending on which "Read Style" is selected. A right-click context menu is available for easy access to batch functions.
Multiple archives can be selected for batch operations.
The information source can be quickly changed via the "Metadata Source" drop-down if multiple are available.
The "Read Style" and "Modify Style" drop-down selections in the upper corner select which tags are shown in the form, and how the tags will be saved.
When the "Modify Style" is changed, certain entry fields will change color, and go inactive if those fields won't be saved for the selected style. For example, the ComicRack tag style doesn't support a field for "Country", so that entry control will be marked red, and made inactive. This block also affects the tag removal menu option, auto-tag, save, and the copy destination tag block.
The "Read Style" affects which tag block shown in the form when the user changes the list selection. This drop-down also affects which tags will be used in renaming, and the source tag block for a copy operation.
The ComicTagger GUI offers several different ways to acquire tags online:
The "Search" function uses only the text that has been entered in the "Series" field of the form. It offers an entirely interactive method for tagging a single file. It affects only the data in the form.
"Auto-Identify" uses the "Series", "Issue", and "Year" fields in the form. It will attempt to compare covers of comics online to determine the best match for a single file. Like the search function, it affects only the data in the form.
"Auto-Tag" does not use the form data at all. It is meant to be used with many files at once, and will use any metadata in the file and the file names as search keys. As it matches comics, it will write out the tag automatically.
Selecting the Page Browser menu option/toolbar button will bring up a very simple page broswer. It's meant to allow the user to to inspect pages of the archive to glean hints about metadata, and is in no way meant to be a comic reader.
In addition, double-clicking on cover or page images throughout the app will often bring up a full page view of the image.
The page list editor tab allows the user to change order that pages are display, and assign different page types. The page list order can be changed by using the up and down buttons, or by dragging and dropping.
ComicTagger supports a powerful command-line interface that can be used for batch processing of archives.
On the command-line just invoke the main executable with options.
On Windows the executable path should be something like this:
C:\Program Files\ComicTagger\comictagger.exeOn Mac something like this:
/Applications/ComicTagger.app/Contents/MacOS/ComicTaggerSince that is a little ungainly, you might want to consider running the following so you can just use "ComicTagger" from your shell prompt:
sudo mkdir -p /usr/local/bin
sudo ln -s /Applications/ComicTagger.app/Contents/MacOS/ComicTagger /usr/local/binIf running from python source, just run "comictagger.py"
Run comictagger with "--help" on the commandline to see all available options. Here is an example:
usage: comictagger [-h] [--version] [-p | -d | -c {CR,CBL,COMET} | -s | -r | -e | --only-set-cv-key] [-1] [--abort-on-conflict] [-a] [--config CONFIG_PATH] [--cv-api-key CV_API_KEY] [--cv-url CV_URL] [--delete-rar] [-f]
[--id ISSUE_ID] [-t {CR,CBL,COMET}] [-o] [-m METADATA] [-i] [--no-overwrite] [--noabort] [--nosummary] [--overwrite] [--raw] [-R] [-S SCRIPT] [--split-words] [--terse] [-v] [-w] [-n] [--darkmode] [-g]
[files ...]
A utility for reading and writing metadata to comic archives.
If no options are given, comictagger will run in windowed mode.
positional arguments:
files
optional arguments:
-h, --help show this help message and exit
--version Display version.
-p, --print Print out tag info from file. Specify type
(via -t) to get only info of that tag type.
-d, --delete Deletes the tag block of specified type (via -t).
-c {CR,CBL,COMET}, --copy {CR,CBL,COMET}
Copy the specified source tag block to
destination style specified via -t
(potentially lossy operation).
-s, --save Save out tags as specified type (via -t).
Must specify also at least -o, -f, or -m.
-r, --rename Rename the file based on specified tag style.
-e, --export-to-zip Export RAR archive to Zip format.
--only-set-cv-key Only set the Comic Vine API key and quit.
-1, --assume-issue-one
Assume issue number is 1 if not found (relevant for -s).
--abort-on-conflict Don't export to zip if intended new filename
exists (otherwise, creates a new unique filename).
-a, --auto-imprint Enables the auto imprint functionality.
e.g. if the publisher is set to 'vertigo' it
will be updated to 'DC Comics' and the imprint
property will be set to 'Vertigo'.
--config CONFIG_PATH Config directory defaults to ~/.ComicTagger
on Linux/Mac and %APPDATA% on Windows
--cv-api-key CV_API_KEY
Use the given Comic Vine API Key (persisted in settings).
--cv-url CV_URL Use the given Comic Vine URL (persisted in settings).
--delete-rar Delete original RAR archive after successful
export to Zip.
-f, --parse-filename, --parsefilename
Parse the filename to get some info,
specifically series name, issue number,
volume, and publication year.
--id ISSUE_ID Use the issue ID when searching online.
Overrides all other metadata.
-t {CR,CBL,COMET}, --type {CR,CBL,COMET}
Specify TYPE as either CR, CBL or COMET
(as either ComicRack, ComicBookLover,
or CoMet style tags, respectively).
Use commas for multiple types.
For searching the metadata will use the first listed:
eg '-t cbl,cr' with no CBL tags, CR will be used if they exist
-o, --online Search online and attempt to identify file
using existing metadata and images in archive.
May be used in conjunction with -f and -m.
-m METADATA, --metadata METADATA
Explicitly define, as a list, some tags to be used. e.g.:
"series=Plastic Man, publisher=Quality Comics"
"series=Kickers^, Inc., issue=1, year=1986"
Name-Value pairs are comma separated. Use a
"^" to escape an "=" or a ",", as shown in
the example above. Some names that can be
used: series, issue, issue_count, year,
publisher, title
-i, --interactive Interactively query the user when there are
multiple matches for an online search.
--no-overwrite, --nooverwrite
Don't modify tag block if it already exists (relevant for -s or -c).
--noabort Don't abort save operation when online match
is of low confidence.
--nosummary Suppress the default summary after a save operation.
--overwrite Overwrite all existing metadata.
May be used in conjunction with -o, -f and -m.
--raw With -p, will print out the raw tag block(s)
from the file.
-R, --recursive Recursively include files in sub-folders.
-S SCRIPT, --script SCRIPT
Run an "add-on" python script that uses the
ComicTagger library for custom processing.
Script arguments can follow the script name.
--split-words Splits words before parsing the filename.
e.g. 'judgedredd' to 'judge dredd'
--terse Don't say much (for print mode).
-v, --verbose Be noisy when doing what it does.
-w, --wait-on-cv-rate-limit
When encountering a Comic Vine rate limit
error, wait and retry query.
-n, --dryrun Don't actually modify file (only relevant for -d, -s, or -r).
--darkmode Windows only. Force a dark pallet
-g, --glob Windows only. Enable globbing
For more help visit the wiki at: https://github.com/comictagger/comictagger/wikiHere are some sample usages, that assume running from bash shell on a Mac or other UNIX system. If using Mac or Windows binary versions, substitute the correct ComicTagger command, as mentioned above.
Print out the tags for a single file
comictagger -p Plastic_Man_001_.zipPrint out the ComicRack tags for all CBZ files in the folder
comictagger -p -t cr *.cbzDelete the ComicBookLover tags for all CBR files in the folder
comictagger -d -t cbl *.cbrSet the ComicRack tags from online for a single file, using the filename to search
comictagger -s -t cr -f -o Plastic_Man_001_.cbrSearch online for for a single file, using the specified tags to search, be verbose, and save to ComicRack tags
comictagger -s -t cr -m "series=Plastic Man,issue=1" -o -v PlasMan001.cbrSet the ComicBookLover Publisher tag for a list of files
comictagger -s -t cbl -m "publisher=Quality Comics" Plastic\ Man*.*As above, but in "dry run" mode, where it just displays what would be saved
comictagger -n -s -t cbl -m "publisher=Quality Comics" Plastic\ Man*.*Search online for for a list of files, using the filename to search, interactively ask the user at the end (if needed) and save to ComicRack tags
comictagger -s -t cr -f -o -i *.cbrAs above, but un-sets any year found in the filenames
comictagger -s -t cr -f -o -i -m "year=" *.cbrRename a file based on ComicRack tags
comictagger -r -t cr PlasticManOne.cbzCopy the ComicBookLover tags in an archive to ComicRack tags
comictagger -c cbl -t cr PlasticManOne.cbzExport all CBR files in folder to Zip format
comictagger -e *.cbrRecursively tag all comics (without ComicRack tags already) under the current folder
comictagger -R -s -f -o -t cr --nooverwrite -i -v /path/to/comicsRun a custom python script using comictaggerlib:
comictagger -S /path/to/script.pyRecursively tag all comics (without ComicRack tags already) under the current folder
comictagger -s -f -o -t cr --nooverwrite -i --recursive .Recursively copy all ComicRack tags to CBL tags
comictagger -c cr -t cbl --recursive .