# 🧠 Neuro Timer **A productivity timer for Linux with focus protocols** _Optimize your work sessions with science-based timing techniques_ [](https://python.org) [](https://gtk.org) [](LICENSE) [](https://ubuntu.com)

🎯 Overview

Neuro Timer is a GTK3 desktop application for Linux that helps you optimize your work sessions using proven productivity protocols. Features include deep work timers, NSDR (Non-Sleep Deep Rest) with ambient audio, and brown noise for focus.

Key Features

• 🎯 90-Minute Deep Work — Optimal session length for sustained focus
• 🧘 NSDR Mode — 10-minute rest sessions with relaxation audio
• 🌊 Brown Noise — Background audio for enhanced concentration
• ☀️ Morning Protocol — Start your day with intention
• 🌙 Evening Wind-Down — Transition out of work mode
• 📊 Session Tracking — Monitor daily focus time
• 🔔 Desktop Notifications — Native Ubuntu/GNOME integration

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/metaphysicist1/neuro-timer.git
cd neuro-timer

# Run the installer
./install.sh

# Or run directly
python3 neuro_timer.py

Pin to Dock

1. Press Super key
2. Search "Neuro Timer"
3. Right-click → Add to Favorites

🎵 Audio Features

Requires: mpv audio player

sudo apt install mpv

⚠️ Audio files are NOT included in this repository due to licensing.
Add your own royalty-free audio to assets/. See Audio Setup below.

🔊 Audio Setup

Audio files must be added manually. Recommended free sources:

Setup:

# Add your audio files
cp your_relaxation.mp3 assets/nsdr.mp3
cp your_brown_noise.mp3 assets/brown.mp3

📋 Protocols

🛠️ Technical Stack

Project Structure

neuro-timer/
├── neuro_timer.py      # Main application
├── assets/
│   ├── icon.png        # App icon
│   ├── nsdr.mp3        # NSDR audio (add your own)
│   └── brown.mp3       # Brown noise (add your own)
├── install.sh          # Desktop integration
├── neuro-timer.desktop # Launcher file
├── .gitignore          # Excludes audio files
├── README.md
└── LICENSE

📋 Requirements

• Python 3.6+
• GTK3 (pre-installed on Ubuntu/GNOME)
• mpv (for audio playback)

# Install dependencies
sudo apt install python3-gi python3-gi-cairo gir1.2-gtk-3.0 mpv

🎨 Customization

Replace Audio Files

Simply replace the files in assets/:

• nsdr.mp3 — Your preferred relaxation audio
• brown.mp3 — Your preferred background noise

Modify Protocols

Edit the protocols list in neuro_timer.py:

protocols = [
    ("🎯 Deep Work", "deep_work", 90),
    ("🧘 NSDR", "nsdr", 10),
    # Add custom protocols:
    ("🍅 Pomodoro", "pomodoro", 25),
]

🤝 Contributing

Contributions welcome! Ideas:

• [ ] Binaural beat generation
• [ ] Session history export
• [ ] Custom protocol builder
• [ ] Keyboard shortcuts
• [ ] System tray integration

📄 License

MIT License — see LICENSE for details.

Note: Audio files in assets/ are excluded from the MIT license and are
for personal use only. See LICENSE file for full disclaimer.

👨‍💻 Author

[Your Name]

• GitHub: @Metaphysicist1
• LinkedIn: Edgar Abasov