A Modern Metronome for Musicians

Tempo is a simple, reliable, and aesthetically pleasing metronome application built with GTK4 and Libadwaita. It provides precise timing, customizable settings, and a distraction-free user experience for musicians of all levels.

Main window with tempo controls	General preferences
Visual preferences with theme selection	About dialog

• Precise Timing: Sub-millisecond accuracy with drift-free timing engine
• Customizable Tempo: Set BPM from 40 to 240 using slider, stepper, or tap tempo
• Time Signature Control: Full support for time signatures with working denominators (4/4, 4/8, 4/2, 4/16, etc.)
• Visual Beat Indicator: Clear visual feedback synchronized with audio
• Accented Downbeats: Distinct sound for the first beat of each measure
• Low-Latency Audio: Optimized GStreamer pipeline for minimal audio delay
• Modern UI: Clean, adaptive interface following GNOME design principles
• Keyboard Shortcuts: Spacebar to start/stop, arrow keys for tempo adjustment
• Settings Persistence: Automatically saves your preferred settings

The easiest way to install Tempo is via Flatpak:

flatpak install flathub io.github.tobagin.tempo

• Python 3.8 or newer
• GTK4 development libraries
• Libadwaita development libraries
• GStreamer development libraries
• Meson build system
• Blueprint compiler

On Ubuntu/Debian:

sudo apt install python3-dev libgtk-4-dev libadwaita-1-dev \
    libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    meson blueprint-compiler

On Fedora:

sudo dnf install python3-devel gtk4-devel libadwaita-devel \
    gstreamer1-devel gstreamer1-plugins-base-devel \
    meson blueprint-compiler

1. Clone the repository:

git clone https://github.com/tobagin/tempo.git
cd tempo

2. Build with Meson:

meson setup builddir
meson compile -C builddir

3. Install (optional):

meson install -C builddir

For development, you can build and run locally:

./build.sh --dev --install
flatpak run io.github.tobagin.tempo

• Start/Stop: Click the play button or press Spacebar
• Adjust Tempo: Use the slider, spin button, or arrow keys (↑/↓)
• Tap Tempo: Click "Tap Tempo" or press T repeatedly to set tempo
• Time Signature: Set beats per measure and note value

• Spacebar: Start/stop metronome
• T: Tap tempo
• ↑: Increase tempo by 1 BPM
• ↓: Decrease tempo by 1 BPM
• Ctrl+Q: Quit application

The beat indicator shows:

• Blue circle: Regular beats
• Red circle: Downbeats (first beat of measure)
• Beat numbers: Current beat position in measure

Tempo is built with modern technologies:

• Frontend: GTK4 with Libadwaita for native Linux integration
• UI Definition: Blueprint markup language for clean, maintainable UI
• Audio Engine: GStreamer with optimized low-latency pipeline
• Timing Engine: High-precision threading with drift compensation
• Build System: Meson for cross-platform building
• Packaging: Flatpak for universal Linux distribution

The metronome engine uses several techniques to ensure accuracy:

• Absolute time references prevent cumulative drift
• High-resolution performance counter (time.perf_counter)
• Compensation for system delays and sleep interruptions
• Separate timing thread to avoid GUI blocking
• Buffer management for consistent audio latency

tempo/
├── data/           # UI files, icons, sounds, schemas
├── src/            # Python source code
├── tests/          # Unit tests
├── packaging/      # Flatpak manifests
├── po/             # Translations
├── meson.build     # Build configuration
└── build.sh        # Convenience build script

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ -v --cov=src --cov-report=html

# Run specific test file
pytest tests/test_metronome.py -v

The project uses:

• Ruff for linting and formatting
• MyPy for type checking
• Black for code formatting

# Check code style
ruff check src/ tests/
mypy src/ --strict

# Auto-fix issues
ruff check src/ tests/ --fix

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. Submit a pull request

If you experience audio problems:

1. Check audio permissions: Ensure Flatpak has audio access
2. Verify GStreamer: Make sure GStreamer plugins are installed
3. Audio system: Try switching between PulseAudio and PipeWire
4. Latency: Check audio settings in system preferences

For timing accuracy problems:

1. System load: Close unnecessary applications
2. Power management: Disable CPU scaling if possible
3. Audio buffer: Adjust buffer sizes in audio settings
4. Real-time priority: Some systems may require RT permissions

# Reinstall Flatpak version
flatpak uninstall io.github.tobagin.tempo
flatpak install flathub io.github.tobagin.tempo

# Reset settings
rm -rf ~/.config/tempo

# Check GStreamer plugins
gst-inspect-1.0 | grep audio

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

• Fixed Time Signature Denominators: Time signature denominators now properly affect beat timing
  • 4/4 = quarter notes get the beat (normal speed)
  • 4/8 = eighth notes get the beat (twice as fast)
  • 4/2 = half notes get the beat (half speed)
  • 4/16 = sixteenth notes get the beat (very fast)
• Enhanced Musical Accuracy: Improved beat duration calculation for practice sessions

• Bug Reports: GitHub Issues
• Feature Requests: GitHub Discussions
• Documentation: Project Wiki