A premium, high-precision audio signal generator for Android, built with Flutter. Designed for audio engineering, acoustic testing, musical instrument tuning, neuroscience-inspired audio, and even practical pest deterrence.
The app offers six distinct operating modes, each with its own dedicated BLoC and audio engine:
| Tab | Mode | Description |
|---|---|---|
| 🎛️ | Single Oscillator | High-precision tone generation from 1 Hz to 22,000 Hz. Logarithmic slider, fine-tune ±0.1 Hz buttons, real-time waveform visualizer, volume & stereo balance. |
| 🎚️ | Multi Oscillator | Up to 3 independent oscillators active simultaneously, each with its own frequency, waveform, volume, and stereo position. |
| 📈 | Sweep Oscillator | Automated frequency sweeps between configurable start/end frequencies. Supports linear & logarithmic interpolation, adjustable duration, and loop/ping-pong mode. |
| 🎵 | Musical Notes | Browse the full chromatic scale (Octaves 0–8) as a searchable, filterable list. Supports custom A₄ tuning from 432 Hz to 446 Hz. |
| 🎧 | Binaural Beats | Dual-oscillator engine panned hard left/right. Presets for Alpha (Relaxation), Beta (Energy), Gamma (Concentration), Theta (Creativity), Delta (Sleep), and more. |
| 🐛 | Pest Control | A chaotic, randomized acoustic deterrent engine. Uses irregular duty cycles, randomized sweep speeds, and unpredictable frequency jumps to prevent animal habituation. Profiles for birds and pets. |
- Powered by flutter_soloud — a high-performance, low-latency binding to the SoLoud C++ audio engine.
- Initialized at 96,000 Hz sample rate.
- Four waveform types: Sine, Square, Triangle, and Sawtooth.
- Real-time PCM buffer polling (~60 Hz) feeds the live oscilloscope visualizer.
- All sweep engines use time-delta (dt) calculations — frame-rate-independent pitch updates.
| Category | Library | Version |
|---|---|---|
| Framework | Flutter | SDK ^3.11.1 |
| State Management | flutter_bloc | ^9.1.1 |
| Audio Engine | flutter_soloud | latest |
| Typography | Google Fonts (Inter) | ^8.0.2 |
| Icons | Lucide Icons Flutter | ^3.1.10 |
| Equality | equatable | ^2.0.8 |
| UUID | uuid | latest |
The project follows a strict BLoC (Business Logic Component) architecture. Each tab screen gets its own isolated BLoC instance, provisioned by MainScreen and disposed automatically when the app closes.
lib/
├── bloc/
│ ├── generator_bloc.dart # Single Oscillator: full-featured audio BLoC
│ ├── generator_event.dart
│ ├── generator_state.dart
│ ├── sweep_bloc.dart # Sweep Oscillator: time-delta sweep engine on SoLoud
│ ├── sweep_event.dart
│ ├── sweep_state.dart
│ ├── multi_frequency_bloc.dart # Multi Oscillator: manages up to 3 independent SoLoud sources
│ ├── multi_frequency_event.dart
│ ├── multi_frequency_state.dart
│ ├── binaural_bloc.dart # Binaural Beats: dual panned oscillators via SoLoud
│ ├── binaural_event.dart
│ ├── binaural_state.dart
│ ├── pest_bloc.dart # Pest Control: chaotic sweep engine with irregular duty cycles
│ ├── pest_event.dart
│ └── pest_state.dart
├── models/
│ ├── binaural_preset.dart # Carrier/beat frequency pairs for brain-state presets
│ ├── multi_oscillator_item.dart # Per-oscillator state for Multi mode
│ ├── pest_profile.dart # Acoustic deterrent profiles (e.g., Birds, Dogs & Cats)
│ └── waveform_type.dart # Shared waveform enum
├── screens/
│ ├── main_screen.dart # TabController + BLoC provisioning for all 6 tabs
│ ├── single_generator_screen.dart
│ ├── multi_generator_screen.dart
│ ├── sweep_generator_screen.dart
│ ├── tone_generator_screen.dart
│ ├── binaural_generation_screen.dart
│ └── pest_generation_screen.dart
├── utils/
│ ├── frequency_utils.dart # Logarithmic scaling, sweep interpolation, clamping
│ └── musical_notes_utils.dart # MIDI ↔ frequency math, chromatic scale generation
├── widgets/
│ ├── frequency_display.dart # Tappable, editable frequency readout
│ ├── frequency_slider.dart # Logarithmic-mapped frequency slider
│ ├── waveform_visualizer.dart # Custom-painted real-time oscilloscope
│ ├── waveform_selector.dart # Waveform type picker
│ ├── oscillator_card.dart # Reusable card for Multi Oscillator mode
│ ├── note_selector.dart # Note picker with octave navigation
│ ├── note_list_item.dart # Single note row for Musical Notes tab
│ ├── note_filter_bar.dart # Filter chips for note name filtering
│ ├── sweep_settings.dart # Sweep configuration bottom sheet
│ ├── configuration_dialogs.dart # Shared dialog widgets
│ ├── binaural_suggestions_dialog.dart # Binaural preset browser
│ ├── playback_button.dart # Play/Pause unified button
│ ├── volume_control.dart # Volume slider control
│ └── balance_control.dart # Stereo balance control
└── main.dart # App entry, SoLoud init, ThemeData
- SoLoud over sound_generator: The project migrated to
flutter_soloudfor lower latency, direct waveform manipulation, accurate PCM buffer access for the visualizer, and simultaneous multi-source audio (essential for Multi Oscillator and Binaural modes). - Isolated BLoCs per Tab: Each screen manages its own audio hardware lifecycle.
MainScreeninstantiates and disposes all BLoCs, preventing audio leaks between tabs. FrequencyUtils&MusicalNotesUtils: All domain math lives inlib/utils/as pure static methods. This guarantees a single source of truth and enables isolated unit testing without any BLoC or widget mocking.- Pest Engine Design: The
PestBlocdeliberately avoids habituation by using three randomization vectors: irregular ON/OFF duty cycles, chaotic sweep rates, and randomized step targeting — all driven by a 60HzTimer.periodicloop.
The app uses a dark-mode-first premium design with a Teal (#00FFCC) + Orange (#FF9800) accent palette.
| Token | Value | Usage |
|---|---|---|
primary |
#00FFCC (Teal) |
Main actions, active states, sliders |
secondary |
#FF9800 (Orange) |
Selections, accents, selected notes |
surface |
#1E1E1E |
Cards, containers, input fields |
scaffold |
#121212 |
App background |
All colors must be obtained via
Theme.of(context).colorScheme. Never use hardcoded color constants in widgets. See.agents/rules/design_system.md.
- Flutter SDK
>=3.11.1 - Android device or emulator (API 21+)
# Clone the repository
git clone <your-repo-url>
cd frequency_generator
# Get all dependencies
flutter pub get
# Run on a connected device
flutter runThe project has comprehensive unit, BLoC, and widget tests.
flutter test| Test File | Coverage |
|---|---|
generator_bloc_test.dart |
Single Oscillator BLoC state transitions |
sweep_bloc_test.dart |
Sweep BLoC engine & math |
binaural_bloc_test.dart |
Binaural dual-oscillator state |
multi_frequency_bloc_test.dart |
Multi Oscillator add/remove/playback |
pest_bloc_test.dart |
Pest Control profile selection & duty cycle |
musical_notes_utils_test.dart |
MIDI/frequency math correctness |
frequency_display_test.dart |
Widget rendering and text input handling |
tone_generator_screen_test.dart |
Musical Notes screen integration |
playback_button_test.dart, waveform_selector_test.dart |
Individual widget tests |
This project is optimized for AI-assisted development. See the .agents/ directory for rules and workflows:
- Design System Rules: How to use
Theme.of(context)and the project's color tokens. - Coding Practices: When and how to create utility classes; modern Flutter API requirements.
- Initialize Project Docs Workflow: Procedure for keeping README, AGENTS.md, LICENSE, and
.gitignoreup to date.
This project is licensed under the MIT License — see the LICENSE file for details.