zentap/scripts

ZenTap Build Scripts

This directory contains shell scripts for automating common development tasks for the ZenTap project.

Scripts Overview

🎵 convert_audio.sh

Converts audio files to the proper format and specifications for the ZenTap game.

📱 build_app.sh

Builds APK and AAB files for Android in debug and release modes.

---

Audio Conversion Script

Prerequisites

• ffmpeg must be installed on your system
  • Ubuntu/Debian: sudo apt install ffmpeg
  • macOS: brew install ffmpeg
  • Windows: Download from ffmpeg.org

Usage

./scripts/convert_audio.sh

How it works

1. Looks for source audio files in assets/audio/source/
2. Converts them according to specifications in assets/audio/README.md:
   • Sound Effects: MP3 format, 44.1 kHz, 128 kbps, mono, 0.1-0.5 seconds
   • Background Music: MP3 format, 44.1 kHz, 192 kbps, stereo, 2-8 minutes
3. Outputs converted files to appropriate directories:
   • Sound effects: assets/audio/source/
   • Menu music: assets/audio/menu/
   • Ingame music: assets/audio/ingame/
   • Compressed versions: assets/audio/compressed/
4. Validates file durations and reports status

Required Files

Sound Effects (source/)

• bubble_pop.mp3 - Primary bubble pop sound effect
• bubble_pop_alt.mp3 - Alternative bubble pop sound effect
• ambient_background.mp3 - Legacy background music

Theme-Based Menu Music (menu/)

• menu_default.mp3 - Default theme menu music
• menu_spring.mp3 - Spring theme menu music
• menu_summer.mp3 - Summer theme menu music
• menu_autumn.mp3 - Autumn theme menu music
• menu_winter.mp3 - Winter theme menu music

Theme-Based Ingame Music (ingame/)

• ingame_default_001.mp3 - Default theme gameplay music
• ingame_spring_001.mp3 - Spring theme gameplay music
• ingame_summer_001.mp3 - Summer theme gameplay music
• ingame_autumn_001.mp3 - Autumn theme gameplay music
• ingame_winter_001.mp3 - Winter theme gameplay music (track 1)
• ingame_winter_002.mp3 - Winter theme gameplay music (track 2)

Supported Source Formats

WAV, MP3, OGG, FLAC, M4A

---

Build Script

Prerequisites

• Flutter SDK must be installed and configured
• Android SDK and build tools must be set up
• Run flutter doctor to ensure all dependencies are satisfied

Usage

Build all variants (default)

./scripts/build_app.sh

Build specific variants

# Debug only
./scripts/build_app.sh --debug

# Release only
./scripts/build_app.sh --release

# APK files only
./scripts/build_app.sh --apk-only

# AAB files only
./scripts/build_app.sh --aab-only

# Clean build before building
./scripts/build_app.sh --clean --all

Get help

./scripts/build_app.sh --help

Build Variants

Variant	Description	Use Case
Debug APK	Development build with debugging symbols	Testing on devices, debugging
Release APK	Optimized build for production	Side-loading, testing stores
Debug AAB	Development Android App Bundle	Play Console internal testing
Release AAB	Production Android App Bundle	Google Play Store release

Output Location

Built files are saved in build/outputs/ with timestamps:

• APK files: build/outputs/apk/
• AAB files: build/outputs/bundle/

File Naming Convention

• ZenTap_debug_YYYYMMDD_HHMMSS.apk
• ZenTap_release_YYYYMMDD_HHMMSS.aab

---

Installation Instructions

Installing APK files

# Install via ADB
adb install build/outputs/apk/ZenTap_release_*.apk

# Or transfer to device and install manually

Uploading AAB files

1. Upload the AAB file to Google Play Console
2. Use for app releases on Google Play Store

---

Troubleshooting

Audio Conversion Issues

• ffmpeg not found: Install ffmpeg using your system's package manager
• Missing source files: Place original audio files in assets/audio/source/
• Duration warnings: Check if your audio files meet the length requirements

Build Issues

• Flutter not found: Ensure Flutter is installed and added to PATH
• Android toolchain issues: Run flutter doctor and follow the suggestions
• Build failures: Run flutter clean and try building again

Common Commands

# Check Flutter installation
flutter doctor

# Clean Flutter project
flutter clean && flutter pub get

# Run app in debug mode
flutter run

# Check connected devices
flutter devices

---

Color Scheme Reference

Both scripts follow the fSociety.hu color scheme defined in ../SCHEME_COLORS.md:

• Black (#000000) - Primary background
• White (#FFFFFF) - Primary text
• Red (#FF0000) - Error messages
• Gray (#808080) - Secondary elements
• Navy Blue (#000080) - Information messages

---

Contributing

When modifying these scripts:

1. Test thoroughly on different platforms
2. Update this README if adding new features
3. Follow the existing code style and error handling patterns
4. Ensure cross-platform compatibility (Linux, macOS, Windows with WSL)