Auto-Merge

Auto-Merge automatically finds and merges metadata from multiple providers to keep your library entries complete and duplicate-free. When you add a book, Tsumihon searches other connected providers for matching entries and intelligently combines the best metadata into a single, enriched record.

Overview

Books often appear on multiple metadata providers, each with slightly different information. One source might have better tags, another might have a higher-resolution cover, and a third might include more complete artist credits. Auto-Merge bridges these gaps by cross-referencing providers and combining their data according to your preferences.

The process is designed to be safe and conservative by default. Tsumihon uses a similarity scoring algorithm to find likely matches, then applies your auto-accept rules to merge non-conflicting data automatically. When genuine conflicts arise, you are prompted to resolve them.

Similarity Detection Algorithm

Auto-Merge uses a weighted scoring system to determine how likely two entries from different providers are the same book. The similarity score is calculated from the following factors:

• Title — 40% weight. Compares the primary title, accounting for minor formatting differences and alternate romanizations.
• Artist — 20% weight. Matches artist and circle names across providers.
• Page Count — 15% weight. Books with similar page counts are more likely to be the same work.
• Tags — 15% weight. Compares the overlap in tag sets between the two entries.
• Publication Date — 10% weight. Entries with close or matching dates score higher.

In addition, if both entries share a source ID (such as the same gallery ID on a provider), a +20% bonus is applied to the score. This makes source ID matches very reliable.

A candidate must meet or exceed the confidence threshold (default: 0.7, or 70%) to be considered a valid match.

Auto-Accept Settings

When a match is found, Auto-Merge can automatically accept certain types of metadata without prompting you. This keeps the process fast for non-controversial data. The following fields can be configured for auto-accept:

Enabled by default

• Tags — Merge tags from both sources into a combined set.
• Artists — Add any missing artist credits.
• Parodies — Merge parody/series associations.
• Characters — Merge character tags.
• URLs — Add source URLs from the new provider.
• Source IDs — Link the additional provider’s source ID to the existing entry.
• Circle / Publisher — Fill in circle or publisher if missing.
• Ratings — Accept ratings from the new source.

Opt-in (disabled by default)

• Covers — Replace the existing cover with the new provider’s cover. Disabled by default because cover preferences are subjective.
• Descriptions — Replace or append the description. Disabled by default to avoid overwriting curated summaries.
• Page Counts — Update the page count. Disabled by default because different providers may count pages differently (e.g., including or excluding covers).

Language Tag Filtering

Auto-Merge includes language-aware tag filtering to prevent irrelevant language tags from cluttering your entries. When merging tags, the system checks if the incoming tags include language identifiers and filters them according to the languages you have configured in your preferences. This avoids situations where a single book accumulates language tags from every provider that lists it.

Conflict Resolution Strategies

When Auto-Merge encounters a field where both the existing entry and the new source have different values, it needs a strategy to resolve the conflict. Tsumihon supports the following strategies:

• Keep Original — Always preserve the value already in your library. The incoming value is discarded.
• Use New — Always replace the existing value with the incoming one from the new provider.
• Merge Both — For fields that support multiple values (like tags or artists), combine both sets. For single-value fields, this behaves like Keep Original.
• Ask User — Present a merge dialog so you can manually choose which value to keep. This is the safest option for important fields like titles.
• Use Higher Quality — Automatically select the value that appears more complete or higher quality. For example, a longer description is preferred over a shorter one, and a higher-resolution cover is preferred over a lower-resolution one.

Setup

To configure Auto-Merge:

1. Open Settings from the navigation bar.
2. Tap Configure Auto-Merge.
3. Toggle Enable Auto-Merge to turn the feature on.
4. Set the Confidence Threshold — the minimum similarity score required for a match. The default is 0.7 (70%). Lower values find more matches but increase the risk of false positives.
5. Set Max Candidates — the maximum number of potential matches to evaluate per book. The default is 5. Higher values are more thorough but slower.
6. Configure which fields should be auto-accepted and which conflict resolution strategy to use for each field type.

How It Works When Adding a Book

When Auto-Merge is enabled and you add a new book to your library, the following happens automatically in the background:

1. Background Search — Tsumihon searches all connected providers for entries matching the book you just added.
2. Scoring — Each candidate is scored using the similarity detection algorithm. Candidates below the confidence threshold are discarded.
3. Merge Dialog — If matches are found and some fields have conflicts that require user input (based on your conflict resolution settings), a merge dialog is presented.
4. Preview — The dialog shows a side-by-side comparison of your existing entry and the candidate, highlighting differences and letting you choose which values to keep.
5. Execute — Once you confirm (or if all fields can be auto-accepted), the merge is executed and your library entry is updated with the combined metadata.

If no conflicts require user input, the merge happens silently in the background and you will see a brief notification confirming that metadata was enriched.

Manual Merge

You can also trigger a merge manually from any book’s detail screen:

1. Open the book you want to enrich.
2. Tap the menu button (three dots) in the top-right corner.
3. Select Search for Merge Candidates.
4. Tsumihon will search all connected providers and present any matches found.
5. Review the candidates, select one, and proceed through the merge dialog.

Configuration Best Practices

Getting the most out of Auto-Merge is a matter of finding the right balance between automation and control. Here are some recommendations:

• Start conservative. Begin with the default confidence threshold of 0.7 and the default auto-accept settings. This ensures you review most merges initially.
• Gradually relax. As you gain confidence that merges are working correctly for your library, you can lower the threshold slightly (e.g., to 0.6) and enable more auto-accept fields.
• Use “Ask User” for titles. Titles are the most visible field and often differ in formatting, romanization, or translation between providers. Keeping manual review for titles prevents unwanted changes.
• Enable cover auto-accept carefully. If you prefer a specific provider’s cover art, enable cover auto-accept and make sure that provider has the highest priority in your provider settings.
• Review merge history periodically. Check your recently merged books to verify that the results match your expectations. Adjust settings if you notice patterns you do not like.

Troubleshooting

No merge candidates are found

• Verify that you have multiple providers connected and configured. Auto-Merge needs at least one additional provider beyond the one the book was originally added from.
• Check that the providers are reachable (test by running a manual search in the Search tab).
• The book may genuinely not exist on other providers. This is common for rare or very new releases.
• Try lowering the confidence threshold temporarily to see if near-matches are being filtered out.

False positives (wrong books being matched)

• Increase the confidence threshold (e.g., from 0.7 to 0.8) to require stronger matches.
• Reduce the max candidates value to limit the pool of potential matches.
• Make sure the “Ask User” conflict strategy is set for title fields so you can catch incorrect matches before they are merged.
• If a specific merge was incorrect, you can undo it from the book’s edit screen by restoring the original values.

Wrong metadata being merged

• Review your auto-accept settings. Disable auto-accept for the field type that was merged incorrectly.
• Switch the conflict resolution strategy for that field to “Ask User” so you can review future merges manually.
• Check provider priority order in settings — when using “Use Higher Quality,” the system may prefer data from a provider you consider less reliable.