Bluetoosh 📡

"Offline Bluetooth Messenger"

A retro 8-bit styled, fully offline peer-to-peer messenger that works entirely over Bluetooth. No internet. No servers. No cloud. Just Bluetooth.

---

Screenshots

Splash	Nearby	Chat	Settings
(placeholder)	(placeholder)	(placeholder)	(placeholder)

---

Features

• Retro 8-bit UI — "Press Start 2P" font, pixel art avatars, scanline overlay
• BLE + Classic Bluetooth — via flutter_blue_plus
• Mesh discovery — via Google Nearby Connections (nearby_connections)
• One-to-one chat over Bluetooth
• Group chat with admin controls (add/remove members)
• Media sharing — images, videos, documents, voice notes (chunked transfer)
• Voice calls over Bluetooth (8kHz PCM streaming)
• Video calls — low-fps JPEG slideshow mode (~2fps, Bluetooth bandwidth trade-off)
• AES-256 encrypted storage (keys in flutter_secure_storage)
• Delete My Data — full wipe with pixel skull animation
• 100% offline — works with zero internet connectivity

---

Tech Stack

Layer	Technology
Framework	Flutter 3.x (Dart 3)
Bluetooth	flutter_blue_plus + nearby_connections
Database	hive + hive_flutter
Encryption	encrypt (AES-256-CBC) + flutter_secure_storage
State	provider
Fonts	google_fonts (Press Start 2P)
Media	file_picker, image_picker, record, audioplayers, camera

---

Project Structure

lib/
├── main.dart                     # App entry, init DB + encryption
├── app.dart                      # App widget + providers
├── core/
│   ├── constants/colors.dart     # Retro color palette
│   ├── theme/pixel_theme.dart    # 8-bit ThemeData
│   └── utils/pixel_avatar_generator.dart  # Procedural pixel avatars
├── features/
│   ├── bluetooth/
│   │   ├── services/bluetooth_service.dart  # BLE connection manager
│   │   ├── services/peer_discovery.dart     # Nearby Connections mesh
│   │   └── models/peer.dart
│   ├── chat/
│   │   ├── screens/splash_screen.dart
│   │   ├── screens/onboarding_screen.dart
│   │   ├── screens/chat_list_screen.dart
│   │   ├── screens/chat_screen.dart
│   │   ├── screens/nearby_users_screen.dart
│   │   ├── widgets/pixel_message_bubble.dart
│   │   └── models/message.dart
│   ├── groups/
│   │   ├── screens/group_screen.dart
│   │   ├── screens/create_group_screen.dart
│   │   ├── screens/add_members_screen.dart
│   │   └── models/group.dart
│   ├── calls/
│   │   ├── screens/voice_call_screen.dart
│   │   ├── screens/video_call_screen.dart
│   │   ├── services/audio_stream.dart
│   │   └── services/video_stream.dart
│   ├── media/
│   │   ├── services/media_transfer.dart    # Chunked BT file transfer
│   │   └── services/file_handler.dart
│   ├── home/
│   │   └── home_screen.dart
│   └── settings/
│       └── screens/
│           ├── settings_screen.dart
│           └── delete_data_screen.dart     # Pixel skull wipe
├── storage/
│   ├── local_db.dart             # Hive database wrapper
│   └── encryption_service.dart   # AES-256 encrypt/decrypt
└── shared/
    └── widgets/
        ├── pixel_button.dart       # Press-down pixel button
        ├── pixel_dialog.dart       # 8-bit dialog
        ├── pixel_text_field.dart   # Pixel input field
        ├── pixel_progress_bar.dart # Stepped progress bar + spinner
        └── scanline_overlay.dart   # CRT scanline + signal bars

---

Build & Setup

Prerequisites

• Flutter SDK ≥ 3.3.0
• Dart ≥ 3.3.0
• Android Studio / Xcode

Install dependencies

flutter pub get

Run code generation (Hive adapters)

dart run build_runner build --delete-conflicting-outputs

Run on device

# Android
flutter run --release

# iOS (requires Mac + Xcode)
flutter run --release -d ios

Build APK

flutter build apk --release --split-per-abi

Build iOS IPA

flutter build ios --release

---

Android Setup Notes

• Min SDK: 21 (Android 5.0)
• Target SDK: 34
• Compile SDK: 34
• Bluetooth permissions are declared in AndroidManifest.xml
• For Android 12+, BLUETOOTH_SCAN / BLUETOOTH_CONNECT / BLUETOOTH_ADVERTISE are required

android/app/build.gradle additions needed:

android {
    compileSdkVersion 34
    defaultConfig {
        applicationId "com.bluetoosh.messenger"
        minSdkVersion 21
        targetSdkVersion 34
    }
}

---

iOS Setup Notes

• Deployment target: iOS 13.0+
• Add NSBluetoothAlwaysUsageDescription (already in Info.plist)
• Background Bluetooth modes enabled in Info.plist
• Enable Background Modes capability in Xcode: ✅ Uses Bluetooth LE accessories ✅ Acts as a Bluetooth LE accessory ✅ Audio, AirPlay, and Picture in Picture

---

Video Call Trade-off

True real-time video over Bluetooth is impractical due to bandwidth constraints (~720 Kbps for BT Classic, even less for BLE). Bluetoosh implements a low-fps JPEG slideshow mode:

• Resolution: 240p (low camera preset)
• Frame rate: ~2fps (one frame every 500ms)
• Encoding: JPEG (camera's native output)
• Audio: separate 8kHz PCM stream

This allows functional "video" communication while staying within Bluetooth bandwidth limits.

---

Privacy & Security

• All messages encrypted with AES-256-CBC before being stored in Hive
• Encryption key stored in flutter_secure_storage (iOS Keychain / Android EncryptedSharedPreferences)
• Media files saved to app-private directory under /Bluetoosh/Media/
• Delete My Data button permanently erases:
  • All Hive database boxes
  • All media files
  • All encryption keys
  • User profile
• No analytics, no crash reporting, no network calls

---

Comments in Persian / English

Key files contain bilingual comments:

• lib/main.dart — Persian + English
• lib/storage/local_db.dart — Persian + English
• lib/features/bluetooth/services/bluetooth_service.dart — Persian + English

---

License

MIT © Bluetoosh Contributors