DEV Community

Fernando Marcos Wittmann
Fernando Marcos Wittmann

Posted on

I built a terminal Pomodoro timer that plays lo-fi music - here's what I learned about the science behind it

I used to have the same tab open almost every day: YouTube search results for "lofi pomodoro".

Not even a specific playlist. Usually something like:

https://www.youtube.com/results?search_query=lofi+pomodoro

I'd pick a playlist, start working, and let the combination of lo-fi beats + Pomodoro timer do its thing.

That worked for a while. Then I hit the very predictable problem: I used those playlists so much that I got tired of them.

I wanted to customize the music, but I still wanted it synchronized with a Pomodoro timer. Work session starts? Music starts. Break starts? Music stops and ambient sound takes over. Work resumes? Music resumes.

So I built a CLI lo-fi music player that ties music playback to Pomodoro work and break sessions. Then I went down a rabbit hole researching whether lo-fi music and Pomodoro timers actually help you focus, or if the whole thing is just aesthetic productivity theater.

Here's what I found.


The tool first

Install it as a command-line tool from PyPI with uv:

uv tool install lofi-pomodoro
pomodoro
Enter fullscreen mode Exit fullscreen mode

You can also install it with pip (pip install lofi-pomodoro). The default lo-fi playlist is downloaded on the first local-music run and cached for later sessions. The timer starts with 25-minute work sessions, 5-minute short breaks, and 15-minute long breaks.

Spotify support is included in the standard install. With Spotify open on a device, this resumes or keeps the current playback and synchronizes it with work sessions:

pomodoro --spotify
Enter fullscreen mode Exit fullscreen mode

Or pass a built-in preset or playlist URI after --spotify:

pomodoro --spotify lofi
pomodoro --spotify spotify:playlist:37i9dQZF1DX0SM0LYsmbMT
Enter fullscreen mode Exit fullscreen mode

Built-in presets include lofi, lofi-beats, jazz, deep-focus, and chill. Spotify playback control requires Premium. On first use, the CLI asks for a Spotify Client ID and opens a browser for authorization; no separate Spotify extra needs to be installed.

Keyboard controls during the session:

  • s — skip track
  • p — pause/unpause timer and music
  • i — ignore this track forever (saved to .ignored_songs)
  • q — quit the session
  • a — add +5 minutes to the current work session

The terminal prompt looks like this:

Press 's' to skip, 'p' to pause/unpause, 'i' to ignore a local track, 'q' to quit
Enter fullscreen mode Exit fullscreen mode

You can also point it at your own folder:

pomodoro --music-folder ~/my-music --volume 0.7
Enter fullscreen mode Exit fullscreen mode

GitHub: WittmannF/lofi-pomodoro


A Quick Introduction to Pomodoro

If you're not familiar with the Pomodoro Technique, it's a time-management method developed by Francesco Cirillo in the late 1980s.

The basic idea is simple:

  1. Pick a task and focus on it for 25 minutes.
  2. Take a 5-minute break.
  3. Repeat, taking a longer break after four focus sessions.

That's the traditional 25/5 approach, although the full technique also includes planning, tracking interruptions, and reviewing your work.

Personally, I use it more as a starting point than a strict set of rules. The timer helps me begin working, but I don't necessarily stop when it rings.

Now, the science

I expected to find either:

  1. "Lo-fi makes you focus" is real science.
  2. "Lo-fi makes you focus" is pure placebo.

The actual answer is less satisfying and more useful: the evidence is mixed, but the mechanism makes sense if you separate two different problems.

Pomodoro is mostly about effort regulation: when do I work, when do I stop, and how do I avoid negotiating with myself every five minutes?

Lo-fi is mostly about environment regulation: what audio background keeps me calm, masks distractions, and doesn't compete too much with the task?

There isn't strong direct evidence that "Pomodoro + lo-fi" is the optimal combination. But there is evidence for both sides of the design: structured breaks can reduce the cost of self-regulation, and certain kinds of background music can support mood and attention without hijacking cognition.

That's the "best of both worlds" argument. Not magic. Just two small interventions solving different parts of the focus problem.

1. Pomodoro is not magic, but timers reduce self-negotiation

The most relevant paper I found was Biwer et al. (2023), Understanding effort regulation: Comparing 'Pomodoro' breaks and self-regulated breaks.

They studied 87 university students during authentic self-study sessions. One group chose their own breaks. Two groups used systematic breaks: 24 minutes study / 6 minutes break, or 12 minutes study / 3 minutes break.

The result was not "Pomodoro users completed way more work." Task completion was similar.

But the systematic-break groups reported:

  • lower fatigue and distractedness
  • higher concentration and motivation
  • similar task completion in less time

The authors' explanation is the part I care about as a developer: deciding when to stop is itself cognitive work. A timer externalizes that decision. Instead of constantly asking "should I take a break now?", you postpone that negotiation until the bell.

That matches how Pomodoro feels in practice. The timer does not make me smarter. It removes one class of decisions.

2. Fixed timers can also backfire

A newer study by Smits, Wenzel & de Bruin (2025) compared self-regulated breaks, Pomodoro breaks, and Flowtime breaks during a two-hour study session.

The results were more cautious: there were no overall differences in productivity, task completion, or flow. Pomodoro breaks led to a faster increase in fatigue, and Pomodoro/Flowtime led to a faster decrease in motivation compared with self-regulated breaks.

So no, the honest conclusion is not "always force 25/5."

The better conclusion is: timers are useful when you need structure, especially when you are procrastinating or task-switching too much. But if you are genuinely in flow, a rigid timer can be annoying.

That's why I added a to extend the current work session by five minutes. The timer gives structure, but it should not punish momentum.

3. The Mozart Effect is mostly fake

You've probably heard that listening to classical music makes you smarter. This comes from a 1993 paper by Rauscher, Shaw & Ky in Nature — 36 college students showed a temporary improvement in spatial reasoning after listening to Mozart K. 448.

The media distorted "temporary spatial reasoning boost in 36 adults" into "Mozart makes babies smarter." Georgia's governor proposed distributing Mozart CDs to newborns. Baby Einstein became a franchise.

The problem: the effect is entirely explained by arousal and mood. Thompson et al. (2001) showed that when you statistically control for how much participants enjoyed and were energized by the music, the Mozart Effect disappears. Any pleasant, energizing stimulus — including a Stephen King passage — produces the same effect.

It's not Mozart. It's not classical music. It's mood and arousal.

4. Lyrics consistently hurt reading and writing tasks

This one is well-established and important.

When you read or write, your brain uses the phonological loop — the inner voice that "speaks" words as you process them. Background speech and song lyrics compete directly with this system, even when you're not consciously listening to them.

Salamé & Baddeley (1989) demonstrated this with serial recall tasks — 769 citations later, the finding has been consistently replicated. A 2023 paper in Journal of Cognition confirmed: "music with lyrics interferes with cognitive tasks."

The language of the lyrics matters too: if the lyrics are in the same language as the text you're reading, interference is higher than if the song is in a foreign language (Sun et al., 2024).

Practical implication: for reading, writing, coding with complex logic — instrumental only. For mechanical or physical tasks, lyrics cause much less harm.

5. Lo-fi probably works because it's predictable and low-friction

The key mechanism is probably cognitive load.

Your auditory cortex constantly predicts what comes next in music. When predictions are confirmed, the brain stops allocating resources to musical analysis — the music recedes into the background.

Lo-fi achieves this through:

  • Simple, repetitive harmony — your brain builds the model fast
  • Consistent 70–90 BPM tempo — no surprises
  • Imperfections (vinyl crackle, tape hiss) — paradoxically signal that the music isn't competing for attention. It sounds "not produced to grab you."
  • No lyrics — no phonological loop competition
  • Masking — the consistent audio field masks sudden environmental sounds (notifications, conversations) that would otherwise trigger involuntary attentional orienting

There is some direct lo-fi evidence, but I would not oversell it.

Kirk et al. (2022) compared jazz, piano, lo-fi, and no-music groups and found that focus music groups showed better sustained-attention performance and increased heart-rate variability compared with no music. But this was a controlled study with specific tracks, not proof that every YouTube lo-fi playlist improves coding.

Orpella et al. (2025), in PLOS ONE, tested music advertised for "work flow" and "deep focus" during a flanker task. Only the "work flow" condition produced significant mood and performance benefits. The "deep focus" label alone was not enough.

That's an important warning: the playlist name is not the mechanism. The actual acoustic features matter.

6. Volume matters more than you think

Mehta, Zhu & Cheema (2012) tested three noise levels — 50 dB, 70 dB, 85 dB — and found 70 dB (roughly café volume) was the sweet spot for creative work. Below that: mild under-arousal. Above 85 dB: performance degraded.

For deep analytical work (reading, writing, learning new material), 45–60 dB is better — less stimulation, less interference with complex processing.

The Yerkes-Dodson curve applies: moderate arousal enhances performance; too much or too little hurts. Music is an arousal lever.

7. White noise is genuinely useful for ADHD

This was the most surprising finding.

Séderlund et al. (2010) proposed the stochastic resonance model: ADHD brains have lower baseline dopamine, which means lower internal neural "noise." Your brain needs a certain noise floor to detect weak signals. When that floor is too low (as in ADHD), weak signals don't get processed properly.

White noise adds external noise to bring subthreshold signals above the detection threshold — improving working memory and focus for ADHD individuals.

This explains the paradox: white noise helps ADHD individuals but slightly impairs neurotypical people. Neurotypical people already have adequate internal noise; adding more pushes them past the optimal point.

Multiple studies since have confirmed this (Helps et al., 2014; Baijot et al., 2016).

8. Why I like the combination

The strongest case for a lo-fi Pomodoro timer is not that it maximizes raw cognitive performance.

It's that it creates a repeatable work environment:

  • the timer reduces self-negotiation about breaks
  • the music reduces environmental randomness
  • instrumental tracks avoid lyric interference
  • breaks create a clean boundary between "focus" and "rest"
  • Spotify/custom folders prevent the playlist fatigue I hit with YouTube

That's why I wanted the music synchronized with the timer. If the timer says "work", the soundscape should support work. If the timer says "break", the soundscape should stop asking for focus.


Implementation notes (for the devs)

The timer loop and local audio player live in pomodoro/__main__.py. The first-run playlist download and cache are handled in pomodoro/playlist_cache.py; Spotify playback and PKCE authentication live in pomodoro/spotify_player.py.

The main thread runs the cycle state machine and renders the Rich progress bar. Background workers handle local or Spotify playback and read keyboard input without requiring Enter. Queues carry skip, pause, and ignore commands between the key listener and the music player. The terminal listener restores terminal settings on exit.

The project is published on PyPI and has GitHub Actions coverage for Python 3.12, 3.13, and 3.14. CI runs the unit tests and smoke-tests the CLI, including Spotify playlist arguments. pygame-ce replaced pygame to provide the audio mixer on Python 3.14.

Current scope

Spotify mode controls playback during work sessions; break sounds such as rain, fireplace, or wind are still played locally. In local mode, you can use the cached default playlist or point the timer at your own music folder. The timer is available from PyPI, and Spotify support ships with the standard installation.

The full research document on music and cognition is in the repo at docs/music-science-studying.md if you want to go deeper.

GitHub: WittmannF/lofi-pomodoro

Happy to answer questions about the implementation or the research.

Top comments (1)

Collapse
 
the_4th_life profile image
Diego •

the ignore-this-track-forever key is a nice touch. if a song pulls you out once it'll probably do it again next time it comes round, so dropping it with one keypress keeps the playlist boring in the good way. and having the music stop on break is a neat cue that the session's actually over