Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/AlonsoSam/vozi-android/llms.txt

Use this file to discover all available pages before exploring further.

This guide is for developers who want to build, run, or contribute to VOZI. By the end you will have the app installed on a physical Android device, connected to a Supabase backend (or running fully offline), and ready to walk through a complete phoneme practice session as both a child and an adult user.
1

Prerequisites

Before cloning the repository, confirm you have the following tools and accounts ready:
  • Flutter SDK — VOZI requires Dart SDK ^3.12.2. Install Flutter from flutter.dev if you haven’t already.
  • Android Studio or Android SDK command-line tools — needed to build and sign the APK. Android Studio is recommended for its built-in AVD manager and Gradle integration.
  • Physical Android device with USB debugging enabled — VOZI’s on-device speech recognizer behaves differently on emulators. A real device is strongly recommended for testing the Hablar (Speak) feature.
  • Supabase project (optional) — create a free project at supabase.com. The app works fully offline without it; Supabase is only needed for adult account auth and progress sync.
Verify your Flutter installation and connected toolchains:
flutter doctor
Resolve any issues flagged under Android toolchain before continuing.
2

Clone and Install Dependencies

Clone the repository and fetch all pub packages:
git clone <URL_DEL_REPOSITORIO>
cd vozi-android
flutter pub get resolves all dependencies declared in pubspec.yaml, including flutter_tts, speech_to_text, audioplayers, rive, supabase_flutter, and flutter_dotenv.
3

Configure Environment Variables

VOZI reads Supabase credentials from a .env file at runtime. Copy the provided template and fill in your project values:
cp .env.example .env
Open .env and add your Supabase project URL and anon key:
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
Find these values in your Supabase dashboard under Project Settings → API.
Leaving both values blank is valid. When SUPABASE_URL and SUPABASE_ANON_KEY are empty, SupabaseConfig.isConfigured returns false and the app skips all backend initialization. Every feature — profiles, practice sessions, rewards, and the adult dashboard — works fully on-device without Supabase.
4

Run Supabase SQL Scripts

If you are connecting a Supabase backend, run the migration scripts in order from the supabase/final_reset/ directory using the Supabase SQL Editor (dashboard → SQL Editor → New query):
OrderFilePurpose
102_create_simple_schema.sqlCreates the 5 application tables: adults, children, sound_progress, practice_attempts, premium
203_rls_simple.sqlApplies Row Level Security policies so each adult can only read their own children’s data
304_verify_tables.sqlQueries every table to confirm the schema was created correctly
Run each script in the numbered order shown. Skipping 03_rls_simple.sql will leave your tables accessible to any authenticated user in the project.
5

Run on Device

Connect your Android device via USB and confirm Flutter can see it:
flutter devices
You will see output similar to:
1 connected device:

Pixel 7 (mobile) • 1ae8390b • android-arm64 • Android 14 (API 34)
Run VOZI on the detected device:
flutter run
Flutter will compile the app, install it on the device, and attach the debug console. The first build takes longer as Gradle downloads dependencies.
6

Explore the App

Once the app is running, walk through the full user flow:
  1. Create a child profile — on the Profiles screen, tap the add button and enter a name. The profile is saved locally to shared_preferences.
  2. Enter the practice path — select the profile to reach the child home screen, then start the learning path. The first phoneme available is R.
  3. Try Escuchar (Listen) — tap the Listen button on any word card. The app plays the MP3 from assets/audio/words/ or falls back to TTS if the file is not present.
  4. Try Hablar (Speak) — tap the Speak button. The microphone activates and the on-device recognizer transcribes your utterance. A word is marked correct when the exact token appears in the transcription, the target phoneme sound is preserved, and the edit-distance similarity score is ≥ 80%.
  5. Access the adult panel — look for the parent/settings entry point and enter PIN 1234 to reach the adult dashboard, where you can review progress and access the Premium demo.

​
Troubleshooting

GeneratedPluginRegistrant is defined multiple timesThis Gradle error appears when a previous build left stale generated files on the device or in the build cache. It most commonly happens after switching Flutter channels or updating plugin versions. To fix it:
  1. Manually uninstall VOZI from the Android device.
  2. Run the following commands:
rm -rf build
rm -rf android/.gradle
flutter pub get
flutter run
Or, if you need to target a specific device:
rm -rf build
rm -rf android/.gradle
flutter pub get
flutter run -d <DEVICE_ID>
These steps clear all cached build artifacts and force a clean Gradle build.
If flutter run hangs at “Installing build/app/outputs/flutter-apk/app-debug.apk…”, the app may still be installed from a previous build. Uninstall it from the device’s app settings and retry.

Build docs developers (and LLMs) love

Get started for freeTalk to us