hash-wallet/tools/demo/README.md

Hash Bags capture harness

Drives the real app through real wallet flows on an emulator while recording the screen, then cuts the recording into store screenshots and marketing video.

One recording produces both deliverables. Screenshots are pulled from the same footage as the video, at the timestamps the scenario reports, so a listing can't drift out of sync with its own trailer.

integration_test/demo/scenarios/*.dart   drive the app, emit timing marks
        │
        ▼
tools/demo/capture.sh record <scenario>  adb screenrecord + flutter drive
        │
        ├── marks.py cut    → trims lead-in, EXCISES seed frames
        ├── marks.py shots  → store screenshots at native 1080x1920
        └── reel.py         → branded master (social / apple-preview / play)

Quick start

cp tools/demo/demo.env.example tools/demo/demo.env   # fill in, gitignored
export BW_SESSION=$(bw unlock --raw)                 # Vaultwarden

tools/demo/build-apk.sh          # optional but recommended — see below
tools/demo/capture.sh boot       # 1080x1920 headless AVD
tools/demo/capture.sh all        # record every scenario + assemble a reel

build-apk.sh is not a strict prerequisite — capture.sh record runs flutter drive, which builds its own instrumented debug APK. Run it first anyway on a fresh checkout: it validates the entire toolchain in one shot, mints the local signing key, and warms the Gradle cache, so your first record doesn't spend twenty minutes compiling only to hit a config error. It also leaves you a sideloadable APK.

Individual steps:

tools/demo/capture.sh record core_store_set
tools/demo/capture.sh shots  core_store_set
tools/demo/capture.sh reel   social
tools/demo/capture.sh reel   apple-preview --overlays none

Output lands in ~/Build/hash-wallet/demo/ (never in the repo), split into raw/, cut/, screenshots/ and publish/.

Scenarios

Scenario	Shows	Notes
core_store_set	Dashboard, Receive, Send, Wallets, Security	The store screenshot set. Send is composed, never broadcast.
onboarding_create	Welcome → PIN → seed → dashboard	Creates a throwaway wallet. Never fund it.
restore_from_seed	Restore from mnemonic → syncing	Uses the demo wallet seed.
swap_and_buy	Trocador swap quote, Buy	Stops before creating a trade. Buy is skipped when no provider key is present.

Scenarios reuse the existing page robots in integration_test/robots/. They are not correctness tests — they add pacing (beat, hold, typeSlowly) so the footage is watchable, and timing marks so captions land on the right frame.

Seed safety

The demo wallet is a real wallet with a real balance — that is what makes the screenshots honest, and it is also why the harness is paranoid:

• The seed lives in Vaultwarden. It is fetched at capture time into one shell variable and passed as a --dart-define. It is never written to the repo, to .secrets.g.dart, or to demo.env.
• DemoSession.guardNoSeedOnScreen() fails the run if a mnemonic is rendered while recording. It checks for the known demo seed (whole and word-scattered) and for the generic shape of a mnemonic, so a freshly generated seed is caught too.
• Flows that must pass through a seed screen wrap it in blindfold(). Those spans are reported to the host and excised from the video, padded by 0.6s on each side. Screenshots use the same padding.
• marks.py manifest refuses to build a publishable master if any clip was cut without marks, since blindfold spans could not have been excised.

Do not lift those guards to get a nicer shot.

Overlays and the Apple App Preview

Touch indicators are the system-level ripple (settings put system show_touches 1), not a composited fake cursor — so they appear in the recording exactly as a user would see them.

They are on by default, and force-disabled for apple-preview. capture.sh reel apple-preview refuses to run against footage recorded with --overlays taps. The App Preview shows the app as-is: no touch indicators, no captions, no title/CTA cards, no music bed. reel.py also enforces Apple's 15–30s duration window and will fail rather than emit an out-of-spec preview.

The capture AVD (both details matter)

Create it as API 35, at exactly 1080×1920:

avdmanager create avd -n HashBags_Capture \
  -k "system-images;android-35;google_apis;x86_64" -d pixel_6
# then in ~/.android/avd/HashBags_Capture.avd/config.ini:
#   hw.lcd.width=1080  hw.lcd.height=1920  hw.lcd.density=420
#   hw.ramSize=6144    showDeviceFrame=no

Size: the stock "Medium Phone" AVD is 1080×2400 = 2.22:1, and Play rejects phone screenshots above 2:1. marks.py shots warns if extracted frames violate that ratio.

API level: use 35, not 36. On the API 36.1 image the guest MediaCodec AVC encoder is broken — screenrecord fails with Encoder failed (err=-38) at every resolution and writes a 0-byte file, and screencap aborts on a SwiftShader DMA assertion. Verified broken under swiftshader_indirect and under -gpu host on a real NVIDIA GPU. API 35 + -gpu software

• -feature -Vulkan (what capture.sh boot uses) works.

iOS App Store screenshots and the App Preview still have to come from a Mac — see store/SCREENSHOTS.md for the fastlane snapshot path.

Why a container for the build

The repo pins Flutter 3.32.0. A host Flutter 3.38+ cannot resolve the dependency set at all — hive_generator wants an analyzer that still ships the macros package, which newer Dart SDKs removed. build-apk.sh therefore builds inside the same image CI uses.

It also mints a throwaway signing key: android/app/build.gradle wires the debug build type to signingConfigs.release, so a local build cannot even configure without a keystore. A capture APK must never be signed with the Play upload key, and minting a separate one keeps that impossible by construction.

Reusing this elsewhere

reel.py imports such_graphics.video_transitions (tuned xfade presets) and such_graphics.video_qa (decode-level "did this render black" gate) from ~/src/such-graphics when that repo is checked out, and falls back to a local subset when it is not — this repo is public and must build without it. Point SUCH_GRAPHICS_HOME elsewhere if needed.

The music-bed handling (random offset per render, so repeat uploads of the same variant don't feel identical) is lifted from ~/src/medusa-multi-tenant-platform/tools/marketing-video/build.mjs.