Goldie Android

Google Play screenshot and listing-asset automation for coding agents and humans. Goldie Android drives a real Android app through Argent, captures deterministic screens, frames them with an Android-native bezel, generates localized marketing artwork, validates the result, and exports an upload-ready package.

Important

Goldie Android is an independent, unofficial Android-focused fork of Kacper Kapuściak's Goldie. For iOS and App Store assets, use the original Goldie project.

What it produces

For every configured locale:

out/google-play/<locale>/
├── phone/                  1080x1920 RGB PNG screenshots
├── feature-graphic.png     1024x500 RGB PNG
├── alt-text.json           accessibility copy by filename
└── listing-manifest.json   package metadata and compliance findings

An optional preview scene is rendered to out/previews/android-phone/<locale>/ for use as a self-hosted YouTube promo.

The verifier enforces the Google Play requirements it can determine mechanically:

• 2–8 phone screenshots;
• PNG/JPEG-compatible, opaque output;
• dimensions between 320 and 3840 pixels;
• no more than a 2:1 long-to-short aspect ratio;
• exactly one opaque 1024x500 feature graphic;
• expected render count, alt text, and listing metadata.

It recommends 1080x1920 screenshots and warns below four screenshots, for repeated early scenes, and for common calls-to-action or risky promotional claims. A human must still review visual quality and misleading-content risk.

Requirements

• macOS, Linux, or Windows;
• Node.js 20.12 or newer;
• Android SDK tools (adb, the emulator, and at least one installed AVD);
• ffmpeg and ffprobe;
• a release APK;
• Argent 0.22 or newer.

Capture reuses a running Android emulator or boots the first installed AVD. Connected physical devices are always ignored. List or start AVDs manually with:

emulator -list-avds
emulator -avd <name>

On Linux, Argent also needs its Android emulator host prerequisites.

Install

Install the prebuilt release with one command. No repository clone or local build is required:

npm install -g https://github.com/durmusun/goldie-android/releases/latest/download/goldie-android.tgz

Then verify the CLI:

goldie-android version
goldie-android help

The project is prepared under the npm package name goldie-android, but the registry package has not been published yet. The release asset above contains the same prebuilt package and is the supported installation path.

To install the included agent skill directly from GitHub:

npx skills add durmusun/goldie-android

Configure

Copy goldie.config.example.ts to a project-external working directory and set GOLDIE_CONFIG to its absolute path. Keeping configs, Argent flows, raw captures, and store output outside the target app repository prevents marketing automation from polluting the app's source tree.

The essential Android fields are:

android: {
  appPath: "/absolute/path/to/app-release.apk",
  applicationId: "com.example.app",
},
devices: ["android-phone"],
locales: ["en-US"],

Scenes point to replayable Argent YAML flows. See goldie.config.example.ts and the skills/goldie/references documentation for the full schema and flow conventions.

Typography and feature artwork

Long localized copy can be tuned without changing the built-in layouts:

theme: {
  // ...colors and fontFamily
  headlineScale: 0.8,
  subheadScale: 0.9,
},

Both scales default to 1 and are applied identically by the CLI renderer and Studio preview.

When the config includes a preview scene, preview and all record it on the Android emulator and render a portrait video for a self-hosted YouTube promo. Google Play links to that video rather than accepting a direct upload, so the App Store's 15–30 second limit does not apply.

Google Play feature graphics can use left- or center-aligned copy plus transparent artwork layers:

googlePlay: {
  featureGraphic: {
    title: { "en-US": "AppName" },
    subtitle: { "en-US": "A concise product promise" },
    textAlign: "left",
    artwork: [
      { src: "art/halo.png", x: 0.52, y: -0.2, width: 0.62, opacity: 0.6 },
      { src: "art/mark.png", x: 0.7, y: 0.14, width: 0.22 },
    ],
  },
},

Artwork paths resolve relative to goldie.config.ts. Layers render in array order above the background and below the feature-graphic copy.

Noto Sans SC is bundled as an automatic glyph fallback, so CJK copy renders consistently in both Studio previews and exported images.

Run

Always run the complete validation sequence before treating an export as finished:

GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android doctor
GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android capture
GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android frame
GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android preview
GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android manifest
GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android verify

Or run the whole pipeline:

GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android all

Open the visual editor with:

GOLDIE_CONFIG=/absolute/path/goldie.config.ts goldie-android studio

Studio runs at http://localhost:4321. Its export action renders the selected design, generates the Google Play package, runs verification, and creates a ZIP only when the required checks pass.

Android rendering

The default Android frame is code-native and uses Pixel-class geometry with a punch-hole camera. Silver, Deep Blue, and Cosmic Orange bezel tints are available in both the CLI and Studio. Custom Android frame art and screen cutout geometry can be supplied through android.frame; external device art is never bundled automatically.

Google Play accepts a YouTube URL rather than an uploaded app-preview video, so an optional preview scene renders a 1080x2400 portrait video for the user to publish there. Google Play does not impose the App Store's 15–30 second preview window.

Development

Source development additionally requires Bun.

bun install --frozen-lockfile
bun test
bun run check:ci
bunx tsc --noEmit
(cd studio && bunx tsc --noEmit)
bun run build

Please read CONTRIBUTING.md before opening a pull request.

Project lineage

• Original Goldie: Kacper Kapuściak and upstream contributors.
• Initial Android capture support: Craig de Gouveia (HughZurname).
• Goldie Android Play packaging, compliance, Android framing, and Studio integration: durmusun.

Source attribution and upstream integration references are retained so every contribution remains traceable. This fork is not endorsed by Kacper Kapuściak, Craig de Gouveia, Software Mansion, or the upstream Goldie project.

License and third-party notices

The software is distributed under the MIT License; retain the copyright and permission notice in LICENSE.

Bundled iPhone bezel images inherited from upstream are not MIT-licensed. They are derived from Kelly Hu's device frames under CC BY 4.0; see assets/ATTRIBUTION.md. Bundled fonts are licensed under the SIL Open Font License 1.1; see assets/fonts/OFL.txt.