Rhythm Lens

Draw a rhythm on a step-sequencer grid (8–32 steps per bar, 1–4 bars), point the app at your MIDI / BFD / EZdrummer library, and get every file ranked by how closely it matches your pattern — with a thumbnail, audio preview, and drag-to-DAW export.

A free, open-source take on the "tap to find" workflow for producers whose groove libraries span multiple plugins and formats. Runs on Windows and Linux — pre-built binaries are available on the Releases page, so no Python installation is required.

Features

• Step sequencer — click to draw hits per lane (Kick, Snare, Hi-Hat, Crash, Ride, Tom, etc.)
• Mute / Solo per lane — M mutes a lane (dimmed buttons), S solos it (only active solo lanes play)
• Results browser — filter by name, score (>80), or BPM range (120-140)
• BPM tooltip — hover a result to see name, match %, BPM, time signature, map
• Keyboard shortcuts — Space (play/pause grid), Ctrl+Z (undo), Delete (clear)
• Save-as-MIDI — export your grid as a .mid file from the transport bar
• Drag MIDI to your DAW — grab the ↗ handle to drag MIDI directly from the editor into your DAW
• Preview before loading — select a result and preview it (or hit Space / double-click); loops the matched bar or the whole groove
• Metronome — click-track toggle for keeping time while playing the grid
• Time-signature-aware — matching respects the grid's time signature (4/4, 3/4, 6/8, etc.), shown beside each match percentage
• Tom expand / collapse — toggle between 7 and 9 lanes
• Themes — Dark, Midnight Blue, Light, Nord, Orange

What it reads

Format	Extension	Notes
Standard MIDI	.mid, .midi	Drum note map is selectable (GM, BFD3, EZdrummer, AD, SSD5, Roland TD-17, or custom)
BFD Player / BFD3	.bfd3grv, .bfd2grv, .bfd3pal	Plain XML — carries its own instrument labels; palettes hold multiple grooves
Anything else	your choice	Identified by content, not extension; safe to enable unknown ones

Drum mapping

Select in Settings → Drum mapping:

• General MIDI — covers virtually every commercial MIDI groove pack
• BFD3 / BFD Player — note 24 = kick, not 36
• Auto-detect — picks between the two per file based on note positions
• EZdrummer, Addictive Drums, SSD5, Roland TD-17 — built-in presets
• Custom — add drum_maps.json next to main.py using drum_maps.example.json as a template

BFD groove files ignore note maps: they carry their own instrument labels.

Quick start (any OS)

pip install -r requirements.txt
python main.py

1. Draw a pattern on the grid. Clicking a step auditions that lane.
2. Pick bars (1–4), resolution (8th / 16th / 32nd notes), time signature, and tempo.
3. Select Folder → Find Matches.
4. Click a result to preview, or double-click / Space to load.
5. Drag the result or the ↗ handle to export MIDI to your DAW.

---

Linux guide

Option A — Pre-built binary (easiest)

Pre-built Linux and Windows binaries are built automatically by GitHub Actions whenever a new version tag is published. Each release on the Releases page therefore contains:

• RhythmLens-Linux.tar.gz — the Linux build
• RhythmLens-Windows.zip — the Windows build

Older releases (before the automated build was added) only carry RhythmLens.zip, the Windows build.

Download RhythmLens-Linux.tar.gz, extract it, and run the executable:

tar -xzf RhythmLens-Linux.tar.gz
cd 'MIDI Pattern Finder'
chmod +x 'MIDI Pattern Finder'
./'MIDI Pattern Finder'

Note: The first launch may take a few seconds. If you get a permission error, the chmod +x line above fixes it.

Option B — Run from source

Requires Python 3.10–3.12 (3.13+ may work but is less tested).

Ubuntu / Debian

sudo apt update
sudo apt install python3 python3-pip python3-venv libegl1 libgl1 libxcb-cursor0 libxcb-xinerama0 libxkbcommon-x11-0 libsdl2-2.0-0
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Fedora

sudo dnf install python3 python3-pip python3-devel libxcb-devel libxkbcommon-x11-devel mesa-libGL SDL2
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Arch Linux / Manjaro

sudo pacman -S python python-pip python-virtualenv sdl2
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python main.py

Audio on Linux

The app uses pygame-ce (SDL2) for audio. It works out of the box with PulseAudio and PipeWire (the default on most modern distros). If you hear no sound:

1. Check that your output device isn't muted in your system mixer.
2. Try running python main.py from a terminal — pygame-ce will print any audio device errors.
3. Install libsdl2-2.0-0 (Ubuntu/Debian) or SDL2 (Fedora/Arch) if you skipped it above.

Drag-and-drop into Linux DAWs

Drag-and-drop from the app into your DAW uses the standard text/uri-list MIME type. It works with:

• REAPER (native)
• Ardour (native)
• Bitwig Studio (native)
• Qt-based DAWs (native)
• FL Studio (via Wine — load the .mid from the exported file)

If your DAW doesn't accept the drag, use the 💾 Save MIDI button to save the file manually and import it.

Troubleshooting

Symptom	Likely fix
cannot import name 'QtCore' etc.	Make sure you're inside the .venv — run source .venv/bin/activate first
No module named 'PyQt6'	Run pip install -r requirements.txt
Window opens but grid is invisible	Install libxcb-cursor0 (Ubuntu) or the equivalent on your distro
libGL error: failed to create dri	Install libgl1 or mesa-libGL
Audio crackles or stutters	Lower the BPM or reduce the sample rate (not configurable yet — future feature)
App doesn't start, no error	Run from a terminal to see the actual error message

Custom sounds

Click the 🎵 button on any lane to load your own .wav. Choices persist in custom_samples.json. Without custom sounds the app uses synthesized tones — fine for rhythm, less inspiring for tone.

Project layout

main.py                   UI, transport, thumbnail rendering
core/drum_map.py          Note maps and presets
core/midi_parser.py       .mid → step grid (and grid → .mid)
core/bfd_groove_parser.py .bfd3grv → step grid
core/similarity.py        Vectorised cosine / Hamming matching
core/scanner.py           Folder walker, format sniffer
core/app_settings.py      settings.json persistence
core/time_sig.py          Time signature helpers
smoke_test.py             18 headless GUI checks
test_audio_features.py    71 audio engine tests

Known limitations

• BFD groove files say only "Cymbal", not which cymbal — that's in the separate .bfd3kit file. The first cymbal is treated as Crash, later ones as Ride (switchable in Settings).
• Percussion is parsed but has no lane to draw or match against yet.
• Velocity and swing / groove feel are ignored — matching is on hit positions only.

Downloads

Pre-built binaries for both platforms are on the Releases page — the latest release always includes RhythmLens-Windows.zip and RhythmLens-Linux.tar.gz, built automatically by GitHub Actions.