Masamune

Local, verified Morphe APK builds configured and monitored from a terminal UI.

GitHub | Releases | Issues

Masamune is a Textual terminal interface for building Morphe APKs from user-supplied local APK and split-APK files.

It verifies local inputs, merges splits, resolves Morphe tooling, applies patches, signs outputs, and optionally packages modules. It does not download stock APKs from Google Play or fallback providers.

Preview

Requirements

Windows and Linux are supported. Morphe CLI, patch bundles, APKEditor, and uber-apk-signer are prepared in the user cache when a build starts.

Features

• Local-only APK input: native APK and folder pickers; no stock APK downloads.
• Input verification: package identity, version, version code, architecture, split coverage, hashes, and signing certificates are checked before use.
• Config-driven builds: apps, architectures, versions, patch sources, and build modes live in morphe.toml.
• Morphe patch workflow: discover patches, select exact patch sets, and edit configurable patch options.
• APK and module output: build patched APKs plus optional deterministic Magisk/KernelSU modules.
• Background execution: current stage, per-job status, redacted events, and build logs remain visible while tools run.
• Signing controls: bundled public template keystore for checkout testing, or a private user keystore for real signing.
• Build history: completed, failed, and cancelled builds remain available with output paths and summaries.
• Safe cache cleanup: inspect cache areas and remove only disposable data.
• Atomic publication: existing outputs are never overwritten; failed builds publish nothing.
• Terminal-native UI: keyboard navigation, command palette, themes, compact sidebar, and reduced-motion support.

Install

From PyPI

uv tool install masamune-tui
masamune

From source

git clone https://github.com/Villoh/masamune.git
cd masamune
uv sync
uv run masamune

Running masamune without arguments opens the TUI. The explicit masamune tui form accepts launch options.

Configure local APKs

Create morphe.toml:

[toolchain]
morphe-source = "MorpheApp/morphe-desktop"
morphe-version = "latest"
patches-source = "MorpheApp/morphe-patches"
patches-version = "latest"

[[apps]]
package = "com.google.android.youtube"
name = "YouTube"
source-dir = "C:/Users/me/Downloads/youtube-splits"
version = "auto"
arch = "arm64-v8a"
build-mode = "apk"
include-patches = ["GmsCore support", "SponsorBlock"]

source-dir is optional. If omitted, Start build asks for a source for each enabled app through the native picker:

• Select an APK to use its containing directory.
• Select a folder to use that folder directly.
• Use {arch}, {abi}, or {module} placeholders for architecture-specific directories.

The TUI writes validated configuration changes atomically. Unsupported TOML fields remain safe to edit manually.

Launch options

masamune tui \
  --config morphe.toml \
  --cache /path/to/cache \
  --output build \
  --keystore /path/outside/repository/masamune.p12 \
  --keystore-alias masamune

Private keystore passwords are read only from MORPHE_KEYSTORE_PASSWORD. They are never displayed or stored by TUI.

Interface

Build flow

1. Add or select an application.
2. Select a local APK or split directory.
3. Review version, architecture, patches, output, and signing key.
4. Confirm the build.
5. TUI verifies inputs, merges splits, applies Morphe patches, signs outputs, and publishes verified artifacts atomically.

Build view reports:

• pending, running, success, failed, and cancelled states;
• current stage and per-job state;
• redacted, scrollable subprocess events;
• output paths and artifact names;
• build.log and provenance files in each published build directory.

Only one build runs at a time. Stop build cancels the active downloader and cleans temporary staging; it does not interrupt arbitrary external tools.

Patch bundles and individual patches

Bundles provides discovery data for supported applications from public patch sources. Add an application to the dashboard or assign a patch source to an existing app without replacing unrelated configuration.

Patches resolves the configured source, lists compatible patches, and saves an exact selection. Configurable patches expose boolean, numeric, and free-text options with upstream defaults and suggestions.

Patch resolution may download Morphe metadata and toolchains into the external cache. It never downloads stock APKs.

Safety model

• No Google Play, APKMirror, Uptodown, or other stock APK downloads.
• Original local split APKs remain unchanged.
• APK metadata, hashes, architecture, and signer identity are verified.
• Existing output directories are never overwritten.
• Signing keys are protected from cache cleanup.
• Sensitive passwords and subprocess output are redacted.
• Failed builds publish no partial output.

The bundled template keystore is for local test builds only. It does not prove publisher identity. Use a private keystore for distributable builds.

Current limits

The TUI intentionally does not provide:

• credential storage or display;
• raw/free-form TOML editing;
• GitLab patch-source assignment;
• parallel builds;
• web mode;
• runtime PNG rendering;
• hard cancellation of every external subprocess.

Use the CLI or a text editor for automation and unsupported configuration fields.

Development

uv sync
uv run python -m unittest discover -s tests
uv lock --check
uv build

Detailed interface notes live in docs/tui.md.

License

MIT. See LICENSE.