mk-bkconv

A Go tool to convert backup files between the Mihon and Kotatsu Android apps.

Tip

Did you know?

mk-bkconv means:

1. mk → mihon-kotatsu
2. bk → backup
3. conv → converter

_{^{couldn't think of a better name. at least it's straightforward.}}

Important

Educational purpose only — this tool is provided under the MIT license. It is not intended to help circumvent paywalls, license restrictions, or facilitate piracy. Use at your own risk and only with data you own or have permission to process.

Table of contents

• Status
• Features
• Requirements
• Build
• Usage
• Design notes
• Limitations & next steps
• Contributing
• License

Status

• Scaffolding implemented.
• Mihon -> Kotatsu conversion implemented for core fields (manga, chapters, categories).
• Kotatsu -> Mihon conversion implemented for core fields (basic mapping). More fields can be added.

Features

• Convert Mihon backup (.tachibk — protobuf, optionally gzipped) to Kotatsu ZIP-of-JSON backup.
• Convert Kotatsu ZIP backup (JSON sections inside) to a minimal Mihon protobuf backup.
• Converted backups include the Keiyoushi extension repository with proper signing key fingerprint for automatic extension trust.
• Only includes sources available in both ecosystems to avoid "Source not found" errors.
• Provides step-by-step instructions for restoring the backup and installing required extensions.
• Modular code (separate packages for Mihon, Kotatsu, conversion) and a simple CLI.

Requirements

• Go 1.20+

Note

The following tools are optional and only required if you want to regenerate the Go protobuf bindings from the .proto files:

• protoc (Protocol Buffers compiler)
• protoc-gen-go (Go plugin for protoc)

Build

The following commands work on PowerShell, Command Prompt, Bash, and other POSIX-like shells (replace paths as needed).

1. Clone the repository and change into the project directory:

git clone https://github.com/galpt/mk-bkconv.git
cd mk-bkconv

2. Ensure module dependencies are tidy and cached:

go mod tidy

3. Build the CLI:

go build ./cmd/mk-bkconv

This produces an executable named mk-bkconv (or mk-bkconv.exe on Windows) in the current directory.

Tip

Windows: use the included compile.bat for a quick iterative build loop — it runs gofmt and go build and pauses so you can inspect any output.

Cross-compilation (optional): set GOOS/GOARCH environment variables before building, for example:

# Linux from Windows (example)
SET GOOS=linux
SET GOARCH=amd64
go build -o mk-bkconv-linux ./cmd/mk-bkconv

Or on Bash:

GOOS=linux GOARCH=amd64 go build -o mk-bkconv-linux ./cmd/mk-bkconv

Usage

Two subcommands are available:

• mihon-to-kotatsu — convert a Mihon .tachibk backup to a Kotatsu ZIP.
• kotatsu-to-mihon — convert a Kotatsu ZIP backup to a Mihon .tachibk (basic mapping).

Note

Protobuf generation:

• The repository already includes generated Go protobuf bindings for Mihon's backup message at proto/mihon/backup.pb.go. The CLI uses these generated types by default.
• You do NOT need protoc to build or run this tool unless you want to regenerate the Go bindings from proto/mihon/backup.proto.
• To regenerate bindings, run the scripts in proto/ (proto/generate.sh or proto/generate.bat). Those require protoc and protoc-gen-go to be installed.

Example (PowerShell):

# Mihon -> Kotatsu
.\mk-bkconv.exe mihon-to-kotatsu -in C:\path\to\app.mihon_2025-11-01.tachibk -out C:\tmp\kotatsu_backup.zip

# Kotatsu -> Mihon
.\mk-bkconv.exe kotatsu-to-mihon -in C:\path\to\kotatsu_backup.zip -out C:\tmp\app.mihon_new.tachibk

Tip

--allow-fallback — when running kotatsu-to-mihon, include this flag to allow falling back to deterministic hashing for source mapping when a mapping is missing. The flag may appear before or after the subcommand.

After converting to Mihon

The tool does a few things automatically when converting from Kotatsu:

• Adds the Keiyoushi extension repository with the correct signing key (so extensions auto-trust when installed)
• Filters out sources that don't exist in both ecosystems (avoids "Source not found" errors)
• Marks manga as initialized (readable immediately after you install extensions)
• Prints a summary showing which sources you need and how to get them working

To restore the backup in Mihon:

1. Open Mihon → Settings → Backup and restore → Restore backup
2. Pick the .tachibk file you generated
3. Mihon will restore your library and add the Keiyoushi repo automatically
4. Go to Browse → Extensions and search for the sources listed in the conversion output
5. Install the extensions you need — they'll auto-trust without prompts
6. Return to Library and verify your manga show up

Tip

1. The conversion output lists every source in your backup. Extension names usually match source names (e.g., "MangaDex" source → install "MangaDex" extension).

2. If you want deterministic outputs for testing, run the conversions on small sample backups first and inspect the resulting ZIP and JSON contents.

Design notes

• Mihon backups are produced using Kotlin kotlinx.serialization.protobuf annotations (@ProtoNumber) and are usually gzipped. The tool detects gzip magic bytes and decodes accordingly.
• Kotatsu backups are ZIP files containing JSON arrays under named sections (e.g., favourites, categories, history).
• For an MVP I implemented a minimal protobuf wire reader/writer in pkg/mihon that handles the fields needed for basic migrations (varint, length-delimited strings, 32-bit floats for chapter numbers). This avoids requiring protoc and generated code during early development.
• For full fidelity and long-term robustness, reconstructing the .proto definitions from Mihon's Kotlin models and generating Go bindings via protoc is recommended.

Data and privacy

Warning

Backup files contain private user data (reading history, bookmarks, possibly preferences). Do not share backups or processed outputs unless you have explicit permission.

Caution

Converting large backups may use significant memory. The current implementation decodes into memory for simplicity; for very large backups we should add streaming and per-entry processing.

Limitations & next steps

Known Limitations

1. Source ID Mapping: Kotatsu uses string-based source names (e.g., "MANGAFIRE_EN") while Mihon uses numeric source IDs based on extension package hashes. The converter generates deterministic source IDs from the source names using FNV-1a hashing, but these won't match real Mihon extension IDs. After importing to Mihon, you may need to manually reassign the correct sources for your manga.

2. Chapter Read Status: Currently not mapped from Kotatsu history. All chapters import as unread. Future versions could map Kotatsu history to Mihon chapter read status.

3. Incomplete Field Mapping: Only core fields (manga, chapters, categories) are converted. The following are not yet implemented:

   • Tracking data (MyAnimeList, AniList, etc.)
   • Reading history timestamps
   • Bookmarks
   • Preferences
   • Source preferences
   • Extension repositories

4. Proto Schema Difference: Mihon uses proto2 syntax with required/optional modifiers, while this implementation uses proto3. The conversion works correctly, but a future update could align the schemas exactly for perfect fidelity.

Next Steps

1. Map Kotatsu reading history to Mihon chapter read/bookmark status
2. Add source name hints in manga notes field to help with post-import source assignment
3. Consider migrating to proto2 schema matching Mihon exactly
4. Add comprehensive unit tests for round-trip conversions
5. Implement streaming for very large backups to reduce memory usage

Testing

The converter has been tested with real backup files containing 117+ manga and successfully generates files that Mihon accepts without corruption errors. The analysis tool (tools/analyze) can be used to validate converted backups before importing.

Contributing

Contributions welcome. Please open issues or PRs. If you want me to generate .proto files from the Kotlin sources and wire up protoc generation, tell me and I will implement that next.

License

MIT. See the LICENSE file.