ButtonBox is a modern Android button-pack app rebuilt with Jetpack Compose. It started from AquaButton, but the new architecture is intentionally generic: voice buttons, meme soundboards, game clips, custom recordings, and video buttons can all live in the same pack system.
- Jetpack Compose and Material 3 UI.
- Android Studio Panda / AGP 9 / Gradle 9 toolchain.
- Launcher identity is now
ButtonBoxwith application idcom.znbsf.buttonbox. - Built-in AquaButton pack with 260 local voice assets.
- Built-in MeaButton pack with 237 local voice assets.
- Built-in MyInstants Meme Pack with 37 local meme audio assets.
- Room-backed local pack database foundation.
.buttonpack.zipimport/export for portable audio/video packs, with schema-version checks, duplicate-id checks, safe media-path validation, and clearer success/failure messages.- Import preview shows pack metadata, category/button counts, media counts, and same-id conflicts before writing anything.
- Same-id imports can either replace the existing pack or import as a copy.
- Custom pack creation plus guided single-audio import into any selected pack.
- Record new audio buttons with the microphone, preview/re-record before
saving, and export the recorded
.m4amedia inside.buttonpack.zippacks. - Import video buttons into packs and play them in an in-app Media3 immersive fullscreen player with auto-return on completion and a visible close button.
- Button trigger phrases can be edited on imported, recorded, and existing audio/video buttons, and are preserved in exported packs.
- Foreground voice trigger MVP: tap the microphone FAB, speak a saved trigger phrase, and ButtonBox plays the matching audio or opens the matching video. It checks multiple recognition candidates, shows matched phrase/candidate details, and falls back to bundled whisper.cpp offline short-phrase recognition if Android's system recognition service is unavailable.
- Video playback can be switched between fill-screen crop and complete-frame fit from the top-right pack actions menu.
- Rename packs/categories/buttons, move buttons between categories, and delete categories with confirmation.
- Move user-owned categories and buttons up/down; ordering is stored locally and survives restart.
- Button card actions are tucked into a per-button overflow menu so long titles have more room and destructive actions are less easy to hit by accident.
- Delete packs and buttons with confirmation, including bundled Aqua/Mea content as local hidden state.
- Add categories and imported audio to any selected pack, including bundled Aqua/Mea packs; imported media stays in app-private storage.
- Pack switching, category filtering, search, random play, stop, and local asset-first playback.
- Pack actions and category chips wrap across multiple rows on narrow screens.
- Fallback remote playback URL is retained for built-in packs.
Use the latest GitHub release:
https://github.com/znbsf/AquaButton-android/releases
Release assets are published with explicit names:
ButtonBox-*-bundled-debug.apk: app plus the three built-in packs (AquaButton, MeaButton, MyInstants Meme Pack).ButtonBox-*-empty-debug.apk: app shell without bundled audio packs; use this if you only want imported or self-made packs.myinstants-meme-pack.buttonpack.zip: standalone 37-button meme pack that can be imported into either APK.
To import a pack, install either APK, open ButtonBox, tap the top-right pack
actions menu, choose Import, then select the .buttonpack.zip file. ButtonBox
will preview the pack first; confirm Import, choose Replace for an existing
same-id pack, or choose Import Copy to keep both.
Recommended environment:
- Android Studio Panda 2025.3.4 or newer
- JDK bundled with Android Studio
- Android SDK Platform 36
- Android SDK Build Tools 36
Build from the repository root:
.\gradlew.bat assembleBundledDebug assembleEmptyDebugInstall on a connected emulator or device:
.\gradlew.bat installBundledDebugDevelopment is tracked in ROADMAP.md. The next major phases are:
- Richer pack import conflict previews and cleaner advanced-actions UI.
- Foreground voice-recognition triggers.
The current app already stores the built-in packs through a Room database. This keeps the UI path shared with future imported and user-created packs, including non-VTuber packs, while still refreshing bundled Aqua and Mea assets from read-only app assets.
ButtonBox uses a zip-based .buttonpack.zip format. The current foundation
supports audio and video files in the same manifest.
pack.json
assets/audio/*.mp3
assets/video/*.mp4
images/logo.png
The manifest stores pack metadata, categories, button titles, media type, media path, and trigger phrases. Imported media is copied into app-private storage so packs stay portable after import. Schema v2 adds validated audio/video media paths and persisted trigger phrases while remaining able to import older v1 packs.
Use New Pack to create a user-owned pack with an initial category. New Pack
uses the same chip style as regular pack tabs. Add Category appears at the
end of the category chips, and Add Media appears as the last card in the
shown button list. Choosing an audio or video file opens an edit dialog so the
title, target category, and trigger phrases can be checked before the button is
created.
The same Add Audio card can also record from the microphone. Tap Record,
stop when done, optionally preview or re-record, then save the recording into
the selected category. Recordings are stored as app-private .m4a files and
are included when the pack is exported.
Video buttons use the same pack/category flow. Tap Video in the Add Media
card, choose a video file, confirm the title/category/trigger phrases, then tap
the new button to play it in ButtonBox's fullscreen Media3 player. Playback
returns to the button list automatically when the clip ends, and the close
button can exit early. The pack actions menu includes Fill Screen: on crops
to fill the display, off keeps the complete video frame visible with letterbox
space when needed.
Voice triggers are foreground-only in this MVP. Add one or more trigger phrases
when creating or editing a button, then tap the microphone floating button and
speak the phrase. ButtonBox uses Android's system SpeechRecognizer; when the
recognized text contains a saved trigger phrase, audio buttons play immediately
and video buttons open in the fullscreen player. If nothing matches, the app
shows the recognized candidates so the phrase can be adjusted. If recognition
fails on a real device, the visible status includes the Android speech error
code, readable reason, and the last heard candidates.
On devices where Android reports that SpeechRecognizer is unavailable, the
same microphone button records up to 15 seconds and transcribes the short phrase
locally with whisper.cpp using the bundled multilingual tiny quantized model.
The result is matched against the same button trigger phrases.
Built-in Aqua and Mea packs keep their bundled assets read-only, but you can
add categories and imported audio to them. Imported audio files are copied into
app-private storage, can be deleted, and can be exported again as part of a
.buttonpack.zip. Pack rename, category rename/delete, Delete Pack,
Import, and Export live in the top app bar pack actions menu, grouped into
pack, category, and danger sections. Destructive actions ask for confirmation.
Buttons can be renamed, moved to another category, reordered inside a category,
or deleted from the per-button overflow menu. User-owned categories can also be
moved up/down from the pack actions menu. Deleting built-in content records a
local hidden-state preference so the app stops reseeding it on startup; it does
not rewrite APK assets.
This repository is a modernized continuation of:
Built-in voice data and assets are derived from:
- AquaButton web resources: zyzsdy/aqua-button
- MeaButton web resources: zyzsdy/meamea-button
- MyInstants user-uploaded meme clips collected locally for study/testing; verify rights before redistribution.
The original AquaButton Android program is GPLv3. This project keeps that license. Voice assets follow the relevant secondary-creation terms described by their upstream projects. This is a fan project and is not affiliated with Hololive, Minato Aqua, Kagura Mea, game publishers, or any official agency.