kfx_converter: EPUB to KFX with Word Wise, in pure Rust (no Kindle Previewer / Calibr

[hwanjongyu]

Hi all,

I built kfx_converter, a native EPUB to KFX converter in Rust, mainly to get Word Wise working on sideloaded books.

The problem: Word Wise works well on Amazon-purchased books, but not on personal EPUBs. MOBI is legacy, and AZW3/KF8 does not carry Word Wise data, so KFX was the only path. Until now, producing valid KFX usually meant relying on Kindle Previewer.

What this does:
- Converts DRM-free EPUB to KFX (Yellowjacket / Enhanced Typesetting)
- Generates a Word Wise sidecar (.kll) with a built-in CEFR B2-C2 lemma dictionary
- No Python, Calibre, or Kindle Previewer required
- CLI (kfx-conv) and GPUI desktop GUI (kfx-studio)
- Optional auto-sync to a connected Kindle

Word Wise data is stored in the local .kll sidecar, so it does not need to be fetched online after the book is on the device.

Build and use:
cargo build --release --bin kfx-conv
kfx-conv book.epub -o book.kfx -w
kfx-conv book.epub -w -s # convert with Word Wise and sync to Kindle

Source (MIT): https://github.com/hwanjongyu/kfx_converter

Current status: source build only, no prebuilt release yet. Tested on Kindle Scribe and Paperwhite.

Known limitations / feedback wanted:
- Which Kindle models and firmware versions show Word Wise correctly?
- Which EPUB structures break conversion or layout?
- Any books where the .kll glosses look wrong?

This is an independent project, not affiliated with Amazon. Feedback and bug reports are very welcome.

[DNSB]

Compiled the CLI and GUI versions for Windows (rustc 1.99.1). Both seemed to work though I've only tried a few ePubs.

[hwanjongyu]

Thanks so much for testing, DNSB — I really appreciate you building both the CLI and the GUI on Windows and giving it an early run.

Any suggestions are very welcome, whether it's about conversion quality, Word Wise display, or EPUB structures that don't convert cleanly. Feedback of any kind is a big help at this stage.

[hwanjongyu]

Duplicated post - please ignore.

[DNSB]

One oddity was that after the latest update to Windows Defender, the kfx-studio.exe file is now flagged as infected with the Trojan:Win32/Bearfoos.B!ml. This apparently a Microsoft special derived from machine learning ( !ml ) and according to multiple search hits is extremely likely to be a false positive. I ran the executable through several online scanners (VirusTotal, VirScan, etc.) and none of them reported any issues.

[hwanjongyu]

Originally Posted by DNSB

One oddity was that after the latest update to Windows Defender, the kfx-studio.exe file is now flagged as infected with the Trojan:Win32/Bearfoos.B!ml. This apparently a Microsoft special derived from machine learning ( !ml ) and according to multiple search hits is extremely likely to be a false positive. I ran the executable through several online scanners (VirusTotal, VirScan, etc.) and none of them reported any issues.

Thanks David, let me check if I can find reason why.

[DNSB]

I've complained to Microsoft and hopefully, they will remove that false positive. Oddly, after restarting Windows, it seems to happen the second time I run the kfx-studio executable.

[hwanjongyu]

Originally Posted by DNSB

I've complained to Microsoft and hopefully, they will remove that false positive. Oddly, after restarting Windows, it seems to happen the second time I run the kfx-studio executable.

Thanks a lot for submitting the false positive report to Microsoft!
As you noted, `Bearfoos.B!ml` is purely a machine-learning heuristic flag. The delayed trigger on the second run happens because Defender's cloud service analyzes newly executed unsigned binaries in the background after first launch, and the combination of Rust runtime + embedded assets (Word Wise dictionary) + Kindle USB queries trips their ML model.
On my end, I've just added proper Windows PE version metadata, a standard `asInvoker` UAC manifest via `winres`, and tuned the release LTO profile. This should significantly reduce these generic ML false positives.
I'll roll out an updated release with these fixes soon. Thanks again for your sharp eye and continuous support!

[DNSB]

I download the updated code from GitHUb and the CLI version compiled without error. The GUI version ( cargo build --release --bin kfx-studio --features gui ) errored out at the link stage. I've placed the error output in the spoiler below:

Spoiler:

warning: unused variable: `root`
   --> src\sync.rs:487:25
    |
487 |     pub fn eject_device(root: &Path) -> Result<(), SyncError> {
    |                         ^^^^ help: if this is intentional, prefix it with an underscore: `_root`
    |
    = note: `#[warn(unused_variables)]` (part of `#[warn(unused)]`) on by default

warning: associated function `is_kindle_name` is never used
   --> src\sync.rs:148:8
    |
 63 | impl KindleSync {
    | --------------- associated function in this implementation
...
148 |     fn is_kindle_name(name: &str) -> bool {
    |        ^^^^^^^^^^^^^^
    |
    = note: `#[warn(dead_code)]` (part of `#[warn(unused)]`) on by default

warning: `kfx-converter` (lib) generated 2 warnings (run `cargo fix --lib -p kfx-converter` to apply 1 suggestion)
error: linking with `link.exe` failed: exit code: 1123
  |
  = note: "C:\\Program Files\\Microsoft Visual Studio\\18\\Community\\VC\\Tools\\MSVC\\14.51.36231\\bin\\HostX64\\x64\\link.exe" "/NOLOGO" "<359 object files omitted>" "D:\\builder\\epubkfx\\target\\release\\deps\\rustcmXqCHn/{liblibsqlite3_sys-c0be5cbc6b1a9e81,libgetrandom-89e42ef145bfcc24,libwindows_registry-a17f0dccc016a41b,libwindows-ab2f2dc9856aa3a3,libwindows_future-79c6a810867e5810,libwindows_numerics-8d0f8a91efef756f,libwindows_core-e3ded34ffd1c1a89,libwindows_strings-04c41b8653662ca6,libstacker-253d2fcedeeb7044,libpsm-7f927a20eff055eb,libgetrandom-38adac1be841da9c,libwindows_strings-f8fe6725b16853f8,libwindows_result-cebce8030bb21f16,libring-1a0f87ea599c7489,libwindows_sys-f5e8fff48b7437d4,libparking_lot_core-a9dbb82ec08df968,libstd-3854312d46c17a37}.rlib" "<sysroot>\\lib\\rustlib\\x86_64-pc-windows-msvc\\lib/libcompiler_builtins-*.rlib" "D:\\builder\\epubkfx\\target\\release\\build\\kfx-converter-3121fc18f8aad7c3\\out\\resource.lib" "D:\\builder\\epubkfx\\target\\release\\build\\gpui-469c3ca86b3b8840\\out\\gpui.lib" "legacy_stdio_definitions.lib" "advapi32.lib" "kernel32.lib" "ktmw32.lib" "user32.lib" "advapi32.lib" "cfgmgr32.lib" "gdi32.lib" "kernel32.lib" "msimg32.lib" "ole32.lib" "opengl32.lib" "shell32.lib" "user32.lib" "winspool.lib" "C:\\Users\\dbowe\\.cargo\\registry\\src\\index.crates.io-1949cf8c6b5b557f\\windows_x86_64_msvc-0.53.1\\lib\\windows.0.53.0.lib" "bcrypt.lib" "advapi32.lib" "kernel32.lib" "kernel32.lib" "kernel32.lib" "ntdll.lib" "userenv.lib" "ws2_32.lib" "dbghelp.lib" "/defaultlib:msvcrt" "/NXCOMPAT" "/LIBPATH:D:\\builder\\epubkfx\\target\\release\\build\\kfx-converter-3121fc18f8aad7c3\\out" "/LIBPATH:D:\\builder\\epubkfx\\target\\release\\build\\gpui-469c3ca86b3b8840\\out" "/LIBPATH:D:\\builder\\epubkfx\\target\\release\\build\\ring-8d0cf9e51a1a2030\\out" "/LIBPATH:D:\\builder\\epubkfx\\target\\release\\build\\stacker-e8380614b70b7510\\out" "/LIBPATH:D:\\builder\\epubkfx\\target\\release\\build\\psm-9b70de6a8dd6abea\\out" "/LIBPATH:D:\\builder\\epubkfx\\target\\release\\build\\libsqlite3-sys-31f711c56cfe6404\\out" "/LIBPATH:C:\\Users\\dbowe\\.cargo\\registry\\src\\index.crates.io-1949cf8c6b5b557f\\windows_x86_64_msvc-0.53.1\\lib" "/OUT:D:\\builder\\epubkfx\\target\\release\\deps\\kfx_studio.exe" "/OPT:REF,ICF" "/DEBUG" "/PDBALTPATH:%_PDB%" "/NATVIS:<sysroot>\\lib\\rustlib\\etc\\intrinsic.natvis" "/NATVIS:<sysroot>\\lib\\rustlib\\etc\\liballoc.natvis" "/NATVIS:<sysroot>\\lib\\rustlib\\etc\\libcore.natvis" "/NATVIS:<sysroot>\\lib\\rustlib\\etc\\libstd.natvis" "/NATVIS:D:\\builder\\epubkfx\\target\\release\\deps\\rustcmXqCHn\\kfx_studio-0.natvis" "/NATVIS:D:\\builder\\epubkfx\\target\\release\\deps\\rustcmXqCHn\\kfx_studio-1.natvis" "/NATVIS:D:\\builder\\epubkfx\\target\\release\\deps\\rustcmXqCHn\\kfx_studio-2.natvis"
  = note: some arguments are omitted. use `--verbose` to show all linker arguments
  = note: CVTRES : fatal error CVT1100: duplicate resource.  type:MANIFEST, name:1, language:0x0409
          LINK : fatal error LNK1123: failure during conversion to COFF: file invalid or corrupt


error: could not compile `kfx-converter` (bin "kfx-studio") due to 1 previous error