<div align="center">

NeuralBeat 1.0.0

The Ultimate Neuro-Acoustic Desktop Application

A scientifically verified, local-first binaural beat, monaural beat, and isochronic tone generator.

</div> <div align="left"> <img src="banner.png" width="1080" alt="NeuralBeat - Banner"> </div>

---

🌟 Why NeuralBeat?

NeuralBeat is a precision-engineered desktop application for generating audio tones. Whether you're interested in meditation, focus enhancement, or audio experimentation, NeuralBeat provides the tools you need.

What Makes NeuralBeat Different?

• 🎯 Scientific Precision: Every tone is mathematically generated with clinical-grade accuracy
• 🔒 100% Private: No internet, no accounts, no tracking - everything runs locally on your machine
• 🎨 Fully Customizable: Multiple waveforms, themes, and advanced controls
• 🧪 Scientifically Verified: Built-in verification system ensures exact frequency output
• 🚀 Modern Experience: Beautiful UI with real-time visualization

---

🧠 The Science of Brainwave Entrainment

Disclaimer: The following information is for educational purposes only. Brainwave entrainment effects vary from person to person and is not intended to diagnose, treat, cure, or prevent any disease. Please consult your healthcare provider before using audio entrainment tools, especially if you have medical conditions.

Your brain produces electrical waves at different frequencies depending on your mental state. By exposing your brain to specific sound frequencies, you can encourage it to match or "entrain" to desired brainwave patterns. This is the principle behind neuro-acoustic stimulation.

The Five Main Brainwave States

| State | Frequency | Characteristics | Common Uses | |-------|-----------|----------------|-------------| | Delta | 0.5 - 4 Hz | Deep, dreamless sleep | Rest, relaxation | | Theta | 4 - 8 Hz | Light sleep, deep relaxation | Meditation, creativity | | Alpha | 8 - 12 Hz | Calm, relaxed focus | Stress relief, calm | | Beta | 12 - 30 Hz | Active thinking, alertness | Focus, concentration | | Gamma | 30 - 80 Hz | Peak cognition | Learning, memory |

---

🔊 Understanding Beat Types

Binaural Beats

Binaural beats are perhaps the most well-known form of brainwave entrainment. When two slightly different frequencies are played simultaneously - one in each ear - your brain perceives a third tone, known as the "binaural beat," at the mathematical difference between the two frequencies.

Example:

• Left Ear: 432 Hz
• Right Ear: 440 Hz
• Perceived Beat: 8 Hz (Alpha state)

How It Works: Your brain processes the phase difference between the two tones and naturally synchronizes to the beat frequency. This phenomenon is called frequency following response (FFR).

Requirements: Stereo headphones are essential for binaural beats to work properly, as the two ears must receive different frequencies.

Advantages:

• Very precise frequency targeting
• Well-researched and documented effects
• Subtle and comfortable listening experience

---

Monaural Beats

Monaural beats are created by physically mixing two different frequencies into a single mono signal before the sound reaches your ears. The beating effect happens in the air itself, not within the brain.

How It Works: When two sine waves of different frequencies are combined, they create an interference pattern that pulses at the difference frequency. This pulsing is literally present in the sound wave itself.

Requirements: Can be used with speakers or headphones, making them more versatile than binaural beats.

Advantages:

• Works with speakers (no headphones required)
• Some users find them more effective than binaural beats
• Better for group sessions or meditation classes

---

Isochronic Tones

Isochronic tones represent the most recent advancement in brainwave entrainment technology. They consist of a single tone that rhythmically turns on and off at regular intervals, creating sharp, distinct pulses.

How It Works: A carrier tone (the pitch you hear) is amplitude-modulated to turn on and off at the desired brainwave frequency. For example, a 528 Hz tone that pulses 10 times per second creates a 10 Hz isochronic tone.

Requirements: Works with both headphones and speakers, offering maximum flexibility.

Advantages:

• Most intense form of entrainment
• Works with or without headphones
• Fastest acting - often produces results in minutes
• No stereo separation required

---

✨ Key Features

🎵 Three Beat Modes

• Binaural Beats: Classic stereo brainwave entrainment
• Monaural Beats: Mono signal for speaker use
• Isochronic Tones: Rhythmic pulses for maximum effectiveness

🔊 Precise Audio Engine

• Generate mathematically accurate tones with clinical-grade precision
• Support for multiple waveforms:
  • Sine: Pure, smooth tones - ideal for beginners
  • Square: Rich harmonics - for deeper entrainment
  • Sawtooth: Bright, buzzy - for intense stimulation
  • Triangle: Soft, mellow - for gentle relaxation
• Phase-continuous frequency transitions (no clicks or pops)

📈 Advanced Ramp Control

• Gradually transition from one brainwave state to another
• Set custom start and end beat frequencies
• Configure duration from 1 minute to 60+ minutes
• Perfect for guided meditation sessions
• Smooth, linear frequency interpolation

🌊 Background Noise Generator

• Mix in ambient noise to mask external distractions:
  • White Noise: Full spectrum - great for concentration
  • Pink Noise: Softer, balanced - perfect for relaxation
  • Brown Noise: Deep, rumbling - excellent for sleep
• Independent volume control (0-100%)

📊 Real-time Oscilloscope

• Pop-out visualizer window
• Live waveform display
• Customizable color palettes (multiple themes)
• Merged/Split view toggle
• Perfect for understanding what you're listening to

💾 Full Preset Management

• Built-in presets for all common brainwave frequencies
• Create custom presets with your favorite settings
• Save unlimited personal presets
• Quick one-click access to favorite configurations

💿 High-Quality WAV Export

• Save sessions as lossless WAV files
• Background thread processing (UI stays responsive)
• Progress bar for long exports
• Perfect for creating personalized meditation recordings

🎨 Modern, Themeable UI

• Multiple dark themes:
  • cosmo, cyborg, darkly, Dracula, lucid, morph, plexus, sandstone, solar, superhero, vapor
• Multiple light themes:
  • litera, lumen, minty, pulse, united, yeti
• Easy theme switching via Settings menu

🧪 Scientifically Verified

• Built-in --debug mode for self-testing
• FFT frequency analysis
• Amplitude safety checks
• DC offset verification
• Stereo separation validation

---

🎵 Built-in Presets

Binaural Beats / Monaural Beats

| Preset Name | Beat Frequency | Carrier Frequency | Brainwave State | |-------------|----------------|-------------------|------------------| | 6 Hz @ 528 Hz Carrier | 6 Hz | 528 Hz | Theta | | 6 Hz @ 432 Hz Carrier | 6 Hz | 432 Hz | Theta | | 16 Hz @ 528 Hz Carrier | 16 Hz | 528 Hz | Beta | | 16 Hz @ 432 Hz Carrier | 16 Hz | 432 Hz | Beta | | 40 Hz @ 528 Hz Carrier | 40 Hz | 528 Hz | Gamma | | 40 Hz @ 438 Hz Carrier | 40 Hz | 438 Hz | Gamma |

Isochronic Tones

| Preset Name | Pulse Rate | Carrier Tone | Brainwave State | |-------------|------------|--------------|------------------| | 4 Hz Pulse @ 432 Hz | 6 Hz | 432 Hz | Theta | | 8 Hz Pulse @ 432 Hz | 10 Hz | 432 Hz | Alpha | | 16 Hz Pulse @ 432 Hz | 14 Hz | 432 Hz | Beta | | 40 Hz Pulse @ 432 Hz | 14 Hz | 432 Hz | Gamma |

---

🛠 Prerequisites

• Python 3.8 or higher
• Operating System: Windows, macOS, or Linux
• Audio Output: Built-in sound card or external audio interface
• System Audio Libraries:
  • Linux: libportaudio2 (e.g., sudo apt install libportaudio2)
  • Windows/macOS: Usually included with the sounddevice Python package

---

📦 Installation

Step 1: Clone the Repository

git clone https://github.com/Aegean-E/NeuralBeat.git
cd NeuralBeat

Step 2: Create a Virtual Environment (Recommended)

This keeps dependencies isolated from your system Python:

# Windows
python -m venv venv
.\venv\Scripts\activate

# Linux / macOS
python3 -m venv venv
source venv/bin/activate

Step 3: Install Dependencies

pip install

Step 4: Run NeuralBeat

python SourceCode.py

---

🚀 Usage Guide

Quick Start

1. Launch the Application

   python SourceCode.py
   

2. Select Your Beat Type

   • Click "Binaural Beat / Monaural Beat" or "Isochronic Tone" in the Beat Type section

3. Configure Frequencies

   For Binaural/Monaural Beats:

   • Set Left Ear Frequency (e.g., 432 Hz)
   • Set Right Ear Frequency (e.g., 440 Hz for 8 Hz beat)

   For Isochronic Tones:

   • Set Pulse Rate (brainwave frequency: 6-40 Hz)
   • Set Carrier Tone (the pitch you hear: 20-20000 Hz)

4. Adjust Volume

   • Use the Volume sliders for each ear/channel

5. Choose Your Waveform

   • Select Sine, Square, Sawtooth, or Triangle

6. Optional: Add Background Noise

   • Select noise type (White, Pink, or Brown)
   • Adjust noise volume

7. Optional: Enable Ramp

   • Check "Enable Ramp"
   • Set Start Beat and End Beat frequencies
   • Set duration in minutes

8. Click "Generate Beat" to start!

---

<p align="center"> <img src="screenshots/ui_main.png" width="800" alt="NeuralBeat - Main UI"> </p>

---

Advanced Features

Creating Custom Presets

1. Configure your desired settings
2. In the "Create / Remove Preset" section, enter a name
3. Select the preset type from the dropdown
4. Click "Save Current Frequencies as Preset"

Using the Oscilloscope

1. The oscilloscope window opens automatically
2. Use the S