Whisper Mobile App

Flutter mobile application for audio transcription using the Whisper backend API.

Features

• 🎙️ Audio Recording - Record audio directly from the app
• 📁 File Upload - Upload audio files for transcription
• 📜 History - View all past transcriptions
• 🔐 API Key Management - Secure API authentication
• 🎨 Material Design 3 - Modern, beautiful UI
• 📱 Cross-platform - Works on iOS and Android

Prerequisites

• Flutter SDK 3.0.0 or higher
• Dart 3.0.0 or higher
• Running Whisper backend server (see ../py-whisper-be/)

Setup

1. Install Flutter

Follow the official Flutter installation guide: https://docs.flutter.dev/get-started/install

2. Install Dependencies

cd flutter-app-mobile
flutter pub get

3. Run the App

iOS Simulator

flutter run

Android Emulator

flutter run

Specific Device

# List available devices
flutter devices

# Run on specific device
flutter run -d <device_id>

Configuration

Backend Connection

1. Open the app
2. Go to Settings tab (bottom navigation)
3. Enter your backend URL (e.g., http://localhost:8000)
4. Enter your API Key (get from admin dashboard)
5. Tap Save Settings
6. Tap Test Connection to verify

Getting API Key

You need an API key from the Whisper backend:

# 1. Login as admin
curl -X POST http://localhost:8000/api/admin/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "your_password"}'

# 2. Create API key
curl -X POST http://localhost:8000/api/admin/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mobile App", "description": "Flutter mobile client"}'

Copy the returned API key and paste it into the app settings.

Project Structure

flutter-app-mobile/
├── lib/
│   ├── main.dart                    # App entry point
│   ├── config/
│   │   └── app_config.dart          # App configuration
│   ├── models/
│   │   ├── transcription_model.dart # Data models
│   │   └── api_exception.dart       # Exception handling
│   ├── services/
│   │   └── whisper_api_service.dart # API client
│   ├── providers/
│   │   └── transcription_providers.dart # State management
│   └── screens/
│       ├── home_screen.dart         # Home with navigation
│       ├── upload_screen.dart       # Upload/record audio
│       ├── history_screen.dart      # View transcriptions
│       └── settings_screen.dart     # App settings
├── pubspec.yaml                     # Dependencies
└── README.md

Usage

1. Upload Audio File

1. Tap the New Transcription button (floating action button)
2. Tap Choose Audio File
3. Select an audio file from your device
4. Tap Transcribe Audio
5. Wait for the transcription to complete
6. View the result and copy/share as needed

2. View History

1. Go to the History tab
2. See all past transcriptions
3. Tap any item to view full text
4. Pull down to refresh

3. Settings

1. Go to the Settings tab
2. Configure backend URL and API key
3. Test connection
4. View app info

Supported Audio Formats

• MP3
• MP4
• MPEG
• MPGA
• M4A
• WAV
• WebM
• OGG
• FLAC

Dependencies

• flutter_riverpod - State management
• dio - HTTP client
• file_picker - File selection
• record - Audio recording
• shared_preferences - Local storage
• intl - Date formatting

Troubleshooting

Cannot connect to backend

• Make sure the backend server is running
• Check the backend URL in settings
• If testing on a real device, use your computer's IP address instead of localhost
  • Example: http://192.168.1.100:8000

API Key not working

• Ensure you copied the full API key from creation response
• Check that the API key hasn't been revoked in admin dashboard
• Try creating a new API key

File upload fails

• Check file size (must be under configured limit)
• Ensure file format is supported
• Verify API key is set correctly

iOS Permissions

Add to ios/Runner/Info.plist:

<key>NSMicrophoneUsageDescription</key>
<string>We need access to your microphone to record audio for transcription</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>We need access to select audio files for transcription</string>

Android Permissions

Add to android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.RECORD_AUDIO"/>
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.INTERNET"/>

Build for Production

Android APK

flutter build apk --release

Output: build/app/outputs/flutter-apk/app-release.apk

iOS IPA

flutter build ios --release

Then archive in Xcode.

App Bundle (Android)

flutter build appbundle --release

Output: build/app/outputs/bundle/release/app-release.aab

Development

Run with Hot Reload

flutter run

Press r to hot reload, R to hot restart.

Run Tests

flutter test

Code Analysis

flutter analyze

Format Code

flutter format lib/

License

MIT

Related

• Backend API Documentation
• Backend Setup Guide