A simple Pomodoro timer with music playback for your work and break sessions. Keep your focus with customized work music and relax during breaks with soothing tunes.
- Customizable work and break durations
- Different music for work and break sessions
- Customizable collections
- Chime sound notifications between sessions
- Silent mode option (only chimes, no music)
- Graceful process handling and cleanup
- Unix-like system (macOS, Linux, BSD)
- Bash shell
- MP3 audio files for music (not included)
jqcommand-line JSON processor- One of the following audio players:
- macOS:
afplay(built-in) - Linux/Unix supported players:
ffplaympg123sox
- macOS:
# Install jq
brew install jq
# No audio player installation needed - uses built-in afplay# Install required packages
sudo apt-get install jq mpg123
# Or if using sox instead of mpg123
sudo apt-get install jq sox libsox-fmt-mp3
# Or if using ffplay instead
sudo apt-get install jq ffmpeg# Install required packages
sudo dnf install jq mpg123
# Or if using sox instead
sudo dnf install jq sox sox-plugins-mp3
# Or if using ffplay instead
sudo dnf install jq ffmpeg# Install required packages
sudo zypper install jq mpg123
# Or if using sox instead
sudo zypper install jq sox
# Or if using ffplay instead
sudo zypper install jq ffmpeg# Install required packages
sudo pacman -S jq mpg123
# Or if using sox instead
sudo pacman -S jq sox
# Or if using ffplay instead
sudo pacman -S jq ffmpeg# FreeBSD (using pkg)
pkg install jq mpg123
# Or if using sox instead
pkg install jq sox
# Or if using ffplay instead
pkg install jq ffmpeg# OpenBSD (using pkg_add)
pkg_add jq mpg123
# Or if using sox instead
pkg_add jq sox
# Or if using ffplay instead
pkg_add jq ffmpeg# NetBSD (using pkgin)
pkgin install jq mpg123
# Or if using sox instead
pkgin install jq sox
# Or if using ffplay instead
pkgin install jq ffmpeg- Clone this repository:
git clone https://github.com/yourusername/pomobeats.git
cd pomobeats- Make the script executable:
chmod +x script.shTo use pomobeats from anywhere in your system:
- Create a bin directory in your home folder if it doesn't exist:
mkdir -p ~/bin- Copy the script to your bin directory:
cp script.sh ~/bin/pomobeats- Make it executable:
chmod +x ~/bin/pomobeats- Add the following line to your
~/.zshrcor~/.bash_profile:
export PATH="$HOME/bin:$PATH"- Reload your shell configuration:
source ~/.zshrc # or source ~/.bash_profile- Create your music directories:
mkdir -p $HOME/pomobeats/music/work $HOME/pomobeats/music/break- Add your MP3 files:
- Work music goes in
music/work/ - Break music goes in
music/break/ - Check the placeholder.md files in each directory for music recommendations
- Work music goes in
You can also play collections by creating a collection folder (e.g. lofi) inside both work and break folders.
pomobeatsThis will start the timer with default durations (25min work, 5min break)
pomobeats -w 45m -b 15mThis starts a 45-minute work session followed by a 15-minute break
pomobeats -sRuns the timer with only chime sounds (no music)
pomobeats analyticsShows statistics about your Pomodoro sessions, including:
- Total work and break time
- Today's work and break time
- This week's work and break time
-w <duration>[s|m|h]: Set work duration (default: 25m)-b <duration>[s|m|h]: Set break duration (default: 5m)-s: Silent mode (no music, only chimes)-r: Shuffle mode-c <collection>: Set a collection-h: Show help message
analytics: Display session statistics
Ctrl+C: Gracefully stop the timer and cleanup- The timer will automatically transition between work and break sessions
$HOME/pomobeats/
├──-- music/
│ ├── work/ # Put your work music here
│ └── [collection]
│ └── break/ # Put your break music here
│ └── [collection]
├──-- sounds/
└── chime.mp3 # Session transition sound
If music continues playing after stopping the script:
pkill afplay # or pkill mpg123/sox/ffplay
Lorenzo Pieri 💻 Maintainer |
This project is licensed under the GPL 3.0 License - see the LICENSE file for details.