docs(guide): troubleshooting for ffmpeg and wtsexporter, and the WhatsApp page without pipx (#1053)

[mbeisser1]

Title

docs(guide): troubleshooting for ffmpeg and wtsexporter, and the WhatsApp page without pipx (#1053)

Type of Change

• New feature
• Bug fix
• Documentation update
• Refactoring
• Security patch
• UI/UX improvement
• Performance improvement

Description

Step 5 of #1053's "Order of work", the user guide. Closes #1053.

• Troubleshooting (features/owner/troubleshooting.md) gets a section, "ffmpeg, ffprobe and wtsexporter". The two headings the app links, Import can't find wtsexporter and ffmpeg or ffprobe not found, keep their exact text and anchors. The section gives the apt, brew and winget commands for ffmpeg; the pinned release pages (ffmpeg-static b6.1.1, the fork's 0.13.0-mc.2) with the file for each computer, the rename, chmod +x, and the Tools Directory whose path Settings → System shows; a table of every failed download's reason with what it means and what fixes it; when a copy put in the Tools Directory by hand is kept (only the pinned file; anything else is replaced after a good download, and used until then); Linux on ARM, which has no wtsexporter download (a pipx install of the fork, linked in, which the app never replaces there); Windows on ARM, which gets the x64 ffmpeg; and macOS, where a Dock-opened app doesn't see Homebrew's PATH, and where a blocked program is allowed with Open Anyway or xattr -d com.apple.quarantine.
• WhatsApp (import-sources/whatsapp.md): the wtsexporter section says the app downloads the fork's pinned release, that an import can't start without it and waits for a download, and links Troubleshooting. No install, pipx, PATH or WTSEXPORTER is left. Both links to the original project now link the fork, as the 2026-10-02 comment asked.
• System (features/settings/system.md): had no ffmpeg directory field left after step 2 and already listed every state. Its failed-download line now links the program's own section instead of #import.
• Sweep: import-your-backup.md says ffmpeg is downloaded by the app; the developer pages formats/index.md (no more "pip or bundled binary") and contributing.md (the app replaces the hand-linked pipx copy with its pinned download, and the link serves until then or where there is no download).
• CHANGELOG: no new entry, because this is the guide. Three entries from steps 2 to 4 said something the final behaviour contradicts and are fixed in place: the Design entry no longer says the app doesn't download the programs yet, and the two Upgrading notes no longer ask for ffmpeg or wtsexporter to be installed or linked by hand.
• Code strings: the wtsexporter not-found error and the broken-shim hint (crates/exporters/whatsapp-exporter/src/wtsexporter.rs) told the person to pipx install and link the result, which the app's download replaces at the next start. Both now end with See "Import can't find wtsexporter" in Troubleshooting at messagecrate.app., the sentence tool_downloads::troubleshooting already uses. The pins.rs header now names the troubleshooting page as a place a newer pin must change, because it names the releases and files.

What done looks like, against main with this PR

• No ffmpeg, a WhatsApp import and Convert work with nothing installed and nothing clicked. Done by step 3 (feat(desktop): download ffmpeg, ffprobe and wtsexporter into the Tools Directory at start (#1053) #2001), the download at start, and step 4 (feat(desktop): the Import form says which program is missing, with Try again, and an import waits for a download (#1053) #2003), the import that waits for a download in progress. Checked on Linux by those PRs' tests; not run on macOS or Windows on ARM, which the issue lists as not checked.
• ffmpeg on PATH gets no ffmpeg download. Done by step 3 (feat(desktop): download ffmpeg, ffprobe and wtsexporter into the Tools Directory at start (#1053) #2001): the check skips both when both are on PATH.
• With no internet, the app starts and works; the Import form names the missing program and links the troubleshooting section, and a file put in the Tools Directory by hand is used. The form's notice and link: step 4 (feat(desktop): the Import form says which program is missing, with Try again, and an import waits for a download (#1053) #2003). The section it links: this PR. The hand-put file: step 2's lookup (feat: ffmpeg is looked for on PATH, then in the Tools Directory, and wtsexporter only there (#1053) #1996) and step 3's rule that keeps a file until a download passes (feat(desktop): download ffmpeg, ffprobe and wtsexporter into the Tools Directory at start (#1053) #2001).
• Not done: step 1, the Message Crate Directory (data/ and staging/ under ~/message-crate, the server on data/, the renamed button). Only ~/message-crate/tools exists. That work is #1053 step 1 is not built: the Message Crate Directory #1999, still open. The desktop app downloads ffmpeg and wtsexporter into the Tools Directory #1053 closes because the rest of its work is done and that leftover is tracked there.

Testing

• cd docs && npm run check (0 errors, 0 warnings) and npm run build; the built page carries the anchors import-cant-find-wtsexporter and ffmpeg-or-ffprobe-not-found that the app links.
• cargo test -p whatsapp-exporter --lib wtsexporter and clippy at -D warnings. wtsexporter_is_looked_for_nowhere_but_the_tools_directory now also asserts the not-found error ends with the troubleshooting sentence and names no pipx; it fails on main.
• ./scripts/check-pr.sh passes.
• The plain ffprobe-linux-x64 file of b6.1.1 was downloaded and its SHA-256 matched the program checksum in pins.rs, so the guide's plain file names (not the .gz) are adopted as the pinned file.

Impact

Guide text and two error strings. No behaviour change.

Additional Information

• The ffmpeg "doesn't run" reason says "Install it with your package manager instead; the app uses the copy on PATH." On macOS an app opened from the Dock doesn't see Homebrew's PATH, so that advice fails there. The guide gives the macOS route (allow the blocked file); the string is left as it is, since the macOS case is unchecked.
• A Gatekeeper-blocked wtsexporter shows as found, because its lookup only checks the executable bit; the import then fails when it runs the program. The guide says so, stated as unchecked, rather than claiming it shows as "doesn't run".

Checklist

• My code adheres to the coding and style guidelines of the project.
• I have performed a self-review of my own code.
• I have commented my code, particularly in hard-to-understand areas.
• I have made corresponding changes to the documentation.
• My changes generate no new warnings.

🤖 Generated with Claude Code

https://claude.ai/code/session_017gbWRfTT5AEWW1D6hTNDr1

[mbeisser1]

Review of 136d156 (up to date with main). Findings whose line is outside the diff follow; the rest are line comments.

• AGENTS.md:347 — Standards · judgement — contributing.md:85 now says the app replaces the pipx link at its next start with a connection; the developer-setup comment here ("the app runs it only from its Tools Directory") was not given the same note, so the two developer instructions no longer say the same thing.
• src-tauri/src/tool_downloads.rs:409 — Spec · spec — Spec: "The status line in Settings says what failed and why". The ffmpeg/ffprobe doesn't-run reason says "Install it with your package manager instead; the app uses the copy on PATH." The guide itself (troubleshooting.md:171, system.md:83) says a macOS app opened from the Dock never sees Homebrew's PATH, so this advice is known wrong there; the guide's table row works around it. The brief allowed fixing wrong strings: change the string to end with the troubleshooting sentence (where the guide gives the per-platform route) instead of the package-manager advice, and update its tests and the guide's row.

[mbeisser1]

Review of 71b849a (the PR with main merged in). Standards 4, Spec 3, Correctness 2; one Spec finding outside the diff (AGENTS.md:252) follows as a top-level comment.

[mbeisser1]

Spec · judgement (outside the diff: AGENTS.md:252)

The Helpers row still says "wtsexporter (Python) for WhatsApp, in the Tools Directory only". After this PR the app's wtsexporter is a standalone wtsexporter_<platform> file from the fork's release (src-tauri/src/tool_downloads/pins.rs:168-200), and Python is needed only on Linux on ARM, where the guide's pipx route applies. This PR closes #1053 and is the one that writes down where the program comes from; "(Python)" now misleads a developer. Fix: "wtsexporter for WhatsApp, downloaded by the app into the Tools Directory (a pipx install where the app has no download, such as Linux on ARM)".

[mbeisser1]

Re-review of the fix commits c76eb95 and 4ffa535: Standards 8, Correctness 3 (two overlap). Fixed in e60474c, except the duplicated-sentences finding, declined in its thread. The two merges of main (71b849a, 3b301ce) had merge reviews with no findings.

[mbeisser1]

Spec · judgement (outside the diff: AGENTS.md:252) The Helpers row still says "wtsexporter (Python) for WhatsApp, in the Tools Directory only."

Fixed in 4ffa535: the row says wtsexporter is downloaded by the app into the Tools Directory, with a pipx install linked there where the app has no download, such as Linux on ARM.

[mbeisser1]

Review summary

Reviewed head 71b849a (the PR with main merged in), fixes pushed on 3b301ce.

Findings per axis

Axis	Findings	Fixed	Declined	Deferred
Earlier review (2026-10-08): Standards 7, Spec 3, Correctness 2	12	12	0	0
Standards	4 (+1 outside the diff, AGENTS.md:252)	5	0	0
Spec	3	3	0	0
Correctness	2	2	0	0
Re-review of the fixes: Standards 8, Correctness 3	11	10	1	0

The one declined finding (the "When the download failed…" and keep-rule sentences in both program sections) stays because Settings → System links each section's anchor, so a reader lands below the intro; its thread has the evidence. No issues deferred.

Merges of the base

• 71b849a: resolved CHANGELOG.md, crates/exporters/whatsapp-exporter/src/wtsexporter.rs, docs/src/content/docs/docs/developer/formats/index.md, docs/src/content/docs/docs/user/import-sources/whatsapp.md (the PR's rewrites with main's fix(whatsapp): read sender ids, names and group members from the fork's JSON #2022, feat(whatsapp): each reaction is on the message under the reactor's WhatsApp id #2033 and The WhatsApp exporter reads sender ids, names and group members from the fork's JSON #1092 text). Merge review: no findings.
• 3b301ce: resolved docs/src/content/docs/docs/developer/formats/index.md (the PR's opening with feat(import): the server types every identity; the conversation file states none #2024's typing phrase). Merge review: no findings.

CI run 38022040153 on 3b301ce: success. No commits for CI failures. Spec was reviewed against #1053. No user threads.