Skip to content

add a packaged Windows release path - #49

Merged
laceyp99 merged 11 commits into
mainfrom
t3code/explain-repository-issue
Sep 14, 2026
Merged

laceyp99 merged 11 commits into
mainfrom
t3code/explain-repository-issue

Conversation

@laceyp99

@laceyp99 laceyp99 commented Sep 9, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add a reproducible PyInstaller onedir release path that produces dist\Murmur\murmur.exe without changing the Python development workflow.
  • Preserve Murmur branding, bundled asset lookup, and Windows autostart behavior in both source and packaged modes.
  • Validate bundled Whisper, Torch, WinRT, icon, and version resources during every release build.
  • Assign all repository paths to @laceyp99 through .github/CODEOWNERS.

Closes #48.

Validation

  • venv\Scripts\python.exe -m pip install -e ".[dev]"
  • venv\Scripts\ruff.exe format --check .
  • venv\Scripts\ruff.exe check .
  • venv\Scripts\pytest.exe (185 passed)
  • venv\Scripts\python.exe -m mkdocs build --strict
  • powershell -ExecutionPolicy Bypass -File .\build_windows.ps1
  • Packaged dependency self-check, Windows metadata, PE icon resource, and version resource checks

Notes

  • The generated onedir bundle is approximately 575 MiB and must be distributed as a complete folder.
  • The executable is unsigned. Installer creation, code signing, automatic updates, and release CI remain outside this change.
  • PyInstaller reports that Numba's optional TBB backend cannot resolve tbb12.dll; Murmur's packaged Whisper and Torch self-check passes without that backend.
  • Live tray, Settings, microphone dictation, clipboard, and registry autostart behavior still need human verification on Windows before marking the draft ready.

@laceyp99
laceyp99 marked this pull request as ready for review September 9, 2026 17:04
Comment thread run.py
Comment thread packaging/murmur.spec
Comment thread run_background.vbs Outdated
@laceyp99

laceyp99 commented Sep 9, 2026

Copy link
Copy Markdown
Owner Author

RC-002 (Medium): user_vocab.json is silently ignored in the packaged app

src/user_vocab.py:9 resolves DEFAULT_USER_VOCAB_PATH via Path(__file__).resolve().parents[1]. Inside the PyInstaller bundle this lands at dist\Murmur\_internal\user_vocab.json, so:

  • A user_vocab.json placed next to murmur.exe is silently ignored; load_user_vocab() (called per transcription in src/transcription.py:164) always returns {} and the vocabulary feature advertised in the README is silently unavailable in packaged mode.
  • save_user_vocab() would write into the read-only bundle directory, which fails (or succeeds only to be lost) on reinstall/upgrade.

This PR made src/assets.py bundle-aware (_get_resource_root() with _MEIPASS); user_vocab.py got no equivalent treatment. This is privacy-relevant: user vocabulary feeds transcript cleanup.

Suggestion: make the default path bundle-aware when sys.frozen ? e.g., resolve next to the executable (Path(sys.executable).parent) or in the canonical app-data dir (get_app_data_dir()), matching the assets approach ? or explicitly document in README and docs/settings-and-privacy.md that vocabulary overrides only work in source mode.

@laceyp99

laceyp99 commented Sep 9, 2026

Copy link
Copy Markdown
Owner Author

Update summary

  • Moved the desktop-runtime import behind command dispatch and included src.main in the captured packaged self-check, so native application import failures produce a traceback.
  • Moved packaged user_vocab.json persistence to %APPDATA%\murmur and documented the source and packaged locations.
  • Made run_background.vbs prefer the repository venv during development and repaired the source-launch test for Linux CI.
  • Added an exact PyInstaller 6.22.2 guard and documented why the private DLL-scan workaround is required.

Testing

  • venv\Scripts\ruff.exe format --check . passed
  • venv\Scripts\ruff.exe check . passed
  • venv\Scripts\pytest.exe passed, 187 tests
  • venv\Scripts\python.exe -m mkdocs build --strict passed
  • powershell -ExecutionPolicy Bypass -File .\build_windows.ps1 -SkipInstall passed, including the packaged dependency self-check

Notes

  • This update addresses RC-001 through RC-004 and the prior Ubuntu test failure.
  • Live tray, microphone, clipboard, Settings, and registry autostart checks remain manual before merge.

Whisper only shells out to FFmpeg for audio file paths; Murmur always
passes recorded audio arrays to the model and writes training audio with
the stdlib wave module, so FFmpeg is not a runtime dependency. Remove it
from the requirements table, install steps, and packaged-release notes.
@laceyp99

Copy link
Copy Markdown
Owner Author

Summary

Fix RC-006: a windowless packaged launch could exit before the tray appeared when Whisper needed to download its model. The download progress bar attempted to write to a missing terminal stream. Existing cached models bypassed this path, so the normal packaged self-check did not expose the failure.

Changes

Commit Change and reasoning
3e1c055 Supply discard-only output streams before application imports when stdout or stderr is absent. Preserve existing console streams and avoid persisting transcript output. Add regression coverage and an opt-in packaged download/loading check with an isolated cache. Document the maintainer procedure in Troubleshooting, with a short link from Getting Started.
1af6d12 Remove the inaccurate FFmpeg installation requirement. Murmur supplies recorded audio arrays to Whisper rather than audio file paths, so its current runtime path does not require a separate FFmpeg installation.
00b2e3c Ignore generated MkDocs site/ output to keep documentation build artifacts out of version control.

Validation

  • venv\Scripts\ruff.exe format --check .
  • venv\Scripts\ruff.exe check .
  • venv\Scripts\pytest.exe -q: 191 passed.
  • venv\Scripts\python.exe -m mkdocs build --strict
  • git diff --check
  • Regression test reproduced the original NoneType.write failure before the fix and passed afterward. It exercises Whisper's actual download/progress code with a mocked response and verifies output is discarded.
  • Rebuilt with build_windows.ps1 -SkipInstall; executable metadata validation and the normal packaged self-check passed.
  • The rebuilt windowless executable downloaded and loaded Whisper tiny on CPU into a verified empty isolated cache, exited 0, and produced a 75,572,083-byte model matching Whisper's expected SHA-256 checksum.

Notes

  • Normal user settings and the existing model cache were untouched during verification.
  • The default build self-check remains offline. The optional model-download check requires internet access.
  • Live tray, Settings, microphone dictation, clipboard, registry autostart, and CUDA behavior remain outside this validation.
  • GitHub checks for 3e1c055 are being monitored separately; the results above describe observed local validation.

@laceyp99

laceyp99 commented Sep 14, 2026

Copy link
Copy Markdown
Owner Author

Final validation update

Pushed commit e1c6eff with the packaged notification fix and lowercase murmur branding.

Validation

  • Packaged startup, tray identity, Settings UI, resizing, scrolling, and Alt+Tab passed.
  • Packaged startup, recording-started, and clipboard-complete Windows notifications passed.
  • Live packaged dictation and clipboard delivery passed.
  • Source-mode launch, notifications, dictation, and clipboard delivery passed.
  • Source autostart, packaged autostart, and disabled autostart registry states passed.
  • %APPDATA%\murmur persistence passed. A package-boundary scan found no config.json, user_vocab.json, or transcriptions.jsonl under dist\murmur.
  • CUDA/GPU transcription and optional Ollama cleanup passed in the user's environment.

Automated formatting, lint, tests, documentation, packaging, metadata, and packaged dependency self-checks passed during the gauntlet. The only remaining notes are the existing optional PyInstaller tbb12.dll analysis warning.

@laceyp99 laceyp99 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good but before I merge, I feel like we should see if there is a cleaner packaging without needing the internal directory structuring to be moved around with the murmur.exe file.

@laceyp99

Copy link
Copy Markdown
Owner Author

Packaging conclusion

Resolved for the current release path with commit 389ef17.

The confirmed workflow is to distribute the complete ZIP package, extract it to:

%LOCALAPPDATA%\Programs\murmur

The packaged files remain together, and users may create an optional Desktop shortcut to murmur.exe. Automatic launch is handled by murmur's existing Start with Windows setting, so a Start Menu shortcut is not required for autostart.

The user validated this workflow, including packaged startup, tray behavior, notifications, dictation, clipboard delivery, CUDA/GPU transcription, Ollama cleanup, and autostart persistence.

Future installer work is tracked in #50. The recommended first implementation is an Inno Setup installer around the existing onedir payload, with per-user installation, Start Menu and optional Desktop shortcuts, upgrade preservation of %APPDATA%\murmur, and a clean uninstall path. MSIX remains a later option after validating tray, notifications, autostart, CUDA, and local model-cache compatibility.

@laceyp99 laceyp99 left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Alright with everything finally addressed. This looks good to merge! We'll revisit the installer within it's own PR.

@laceyp99
laceyp99 merged commit f5bd5f4 into main Sep 14, 2026
6 checks passed
@laceyp99
laceyp99 deleted the t3code/explain-repository-issue branch September 14, 2026 05:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Package Murmur as a named Windows executable with the correct icon

1 participant