NotchTune

A native macOS music controller that lives in your MacBook's notch.

NotchTune is a lightweight, zero-bloat utility that displays a sleek music player overlay when you hover your mouse near the notch on your MacBook. It reads track info from Spotify running in Safari and gives you full playback control — all from a beautiful, notch-shaped widget.

• Notch-shaped overlay — UI that mirrors your MacBook's notch design
• Real-time track info — Title, artist, and album art from Spotify
• Animated waveform seek bar — Beautiful 60fps visualization with drag-to-seek
• Playback controls — Play/pause, next, previous track
• Smooth animations — 270ms expand/collapse with haptic feedback
• Smart activation — Only appears when you hover near the notch
• Always-on-top — Stays visible across all Spaces and fullscreen apps
• Zero dock icon — Runs as a background accessory app

• macOS 14.0 (Sonoma) or later
• A MacBook with a notch (MacBook Pro 2021+, MacBook Air M3+)
• Safari with open.spotify.com loaded

1. Clone the repository:

   git clone https://github.com/blessedlab/NotchTune
   cd NotchTune

2. Build the app:

   swift build -c release

3. Create the app bundle:

   mkdir -p NotchBox.app/Contents/MacOS
   mkdir -p NotchBox.app/Contents/Resources
   cp .build/release/NotchBox NotchBox.app/Contents/MacOS/
   cp Resources/Info.plist NotchBox.app/Contents/

4. Move to Applications:

   mv NotchBox.app /Applications/

5. Launch the app:

   open /Applications/NotchBox.app

If you have the NotchBox-Classic.app bundle:

1. Copy NotchBox-Classic.app to your /Applications/ folder
2. Double-click to launch
3. Follow the permission setup below

NotchTune needs two permissions to work correctly. You'll be prompted automatically when you first launch the app.

Why: NotchTune monitors your mouse position globally to detect when you hover near the notch.

How to enable:

1. When you first launch, a system dialog will appear asking for Accessibility access
2. Click Open System Settings
3. Navigate to Privacy & Security → Accessibility
4. Click the + button and add NotchBox (or find it in the list and toggle it on)
5. If prompted, enter your password

Manual setup (if dialog doesn't appear):

1. Open System Settings
2. Go to Privacy & Security → Accessibility
3. Click the + button
4. Navigate to /Applications/NotchBox.app and add it
5. Make sure the toggle is ON

Why: NotchTune communicates with Safari via AppleScript to read track info and control playback on Spotify's web player.

How to enable:

1. Open Safari
2. Go to Safari → Settings → Privacy
3. Make sure Allow JavaScript from Apple Events is enabled
4. If not, check the box to enable it

Important: Safari must be running with open.spotify.com loaded in a tab. NotchTune communicates directly with the Spotify web player through Safari.

1. Open Safari
2. Navigate to open.spotify.com
3. Log in to your Spotify account
4. Start playing music
5. Keep Safari open (you can minimize it — NotchTune reads from the background)

1. Launch NotchBox from your Applications folder
2. Move your mouse to the top-center of your screen (near the notch)
3. Wait ~500ms — the overlay will expand smoothly from the notch
4. Interact with the controls:
   • Click Play/Pause to control playback
   • Click Forward/Backward to skip tracks
   • Drag the waveform seek bar to jump to a position
   • Hover over the seek bar to see a time preview
5. Move your mouse away — the overlay collapses back into the notch

• Ensure Accessibility permission is granted (see above)
• Make sure Safari is running with Spotify loaded
• Try restarting the app

• Check that Spotify is playing in Safari (not the desktop app)
• Verify the Spotify tab is in Safari window 1
• Refresh the Spotify page

• Ensure JavaScript from Apple Events is enabled in Safari settings
• Try reloading the Spotify page in Safari

• Launch the app once to trigger the permission prompt
• If still missing, add it manually via the + button

NotchTune/
├── Sources/NotchBox/
│   ├── main.swift              # App entry point
│   ├── NotchBoxApp.swift       # AppDelegate, accessibility setup
│   ├── NotchOverlayWindow.swift # Window management, mouse tracking
│   ├── NotchBoxView.swift       # Main UI (track info, controls)
│   ├── WaveformSeekBar.swift    # Animated waveform seek bar
│   ├── TrackInfoFetcher.swift   # Safari/AppleScript communication
│   ├── TrackInfoViewModel.swift # Real-time progress interpolation
│   ├── TrackInfo.swift          # Track data model
│   └── MediaKeySimulator.swift  # Playback control via JS
├── Resources/
│   └── Info.plist               # App metadata
└── Package.swift                # Swift Package Manager config

GNU General Public License v3.0 — see LICENSE for details.

1. Fork the repo
2. Create a feature branch
3. Make your changes
4. Test on a MacBook with a notch
5. Submit a pull request

Made with ❤️ for MacBook owners who love Spotify