omaTUNES

A native Wayland music player written in Rust, built for Omarchy / Hyprland rices. Follows the active Omarchy theme automatically — colors update live when you switch themes.

omatunes is a customized fork of sheep-farm/lavanda by Balthazzahr.

---

Key Features

• Wide Audio Format Support: Plays MP3, FLAC, OGG, Opus, WAV, AAC, M4A, AIFF, and more natively via the high-performance Symphonia library.
• 100% Offline & Privacy-First: Zero tracking, zero background telemetry, and no network requirements. Logs and saves play counts, stats, and custom user playlists locally.
• JSON Database: Stores favorites, play counts, recently played tracks, hidden artists/albums, column settings, user playlists, and smart playlists in a single portable JSON file (~/.config/omatunes/db.json).
• Smart Playlists (New in v0.7.0): Create iTunes-style smart playlists using an interactive multi-criteria Rule Builder. Supports AND logic across criteria fields like Title, Artist, Album, Genre, Year, Play Count, Duration, Disc Number, Liked, Has Lyrics, and Last Played. Includes customization options for sorting (Random, Most Played, Recently Played, Year, Title), limit constraints, and live-updating toggles. Managed via a dedicated sidebar wand tab with right-click Edit/Delete context menu actions, automatically truncating long playlist names with an ellipsis (...) to prevent visual overflow.
• Now Playing Suffix & Equalizer Animation (New in v0.7.0): Displays the active playback context (e.g. Now Playing · Abbey Road) using the theme's secondary text color (theme::subtext()), supporting clean ellipsis (...) truncation on narrow screens. Shows an active 3-bar equalizer animation on the left of the tab label when playing, which freezes flat when paused and hides when stopped. Features contrast-compliant text styling that dynamically adapts to active accent backgrounds using WCAG contrast ratios.
• Icon-Based Sidebar Playlist Tabs (New in v0.7.0): Redesigned the playlist navigation area into three icon-based tabs (User Playlists, Auto Playlists, Smart Playlists) with hover tooltips for compact layout formatting.
• Synchronized LRC Lyrics & Interactivity: Parses LRC metadata to highlight and auto-scroll the active lyric line, supporting interactive seek-on-click to any lyric's timestamp.
• Logarithmic Audio Spectrum Visualizer: Computes real-time 2048-point Hann-windowed FFT to render 64 logarithmic bands colored with an amplitude gradient.
• Lyrics/Visualizer Drawer: Slide out a Lyrics or Spectrum visualizer panel from the right, with state persistence. The panel has a minimum width of 600px to fit full lines of lyrics without wrapping, and automatically collapses if the window gets too small (under 1499px).
• Unified Header Panel: Stacks player controls (270px height) and tab row/search bar controls seamlessly with a 1px stack overlap to hide borders and visually merge the sections.
• Enlarged Album Artwork: Displays cover art at 238x238 pixels with expanded player height to ensure high resolution on large screens without cropping.
• Aligned Settings Button: Sits at the far-right of the library tab row, custom styled to 56px width (matching the tab strip above) with top and side dividers, aligned perfectly on integer pixels to avoid subpixel blur.
• Flexible Theming System:
• System Theme: Automatically maps your active system theme (e.g. Omarchy colors) live to the UI palette.
• Built-in Presets: Quickly switch between standard presets: Nord, Catppuccin Mocha/Latte, Dracula, Gruvbox (Dark), Everforest (Dark), and Monokai.
• Custom Theme Builder: Build a personal palette by defining 7 base colors (Background, Primary Text, Accent, Green, Red, Yellow, Blue). The system dynamically derives the remaining 4 tokens (Background (Deep), Panel Background, Secondary Text, Muted Text/Icons) using target WCAG contrast ratios to ensure readability.
• Now Playing / Up Next Queue: A dedicated queue manager view with drag-and-drop handles for quick song re-ordering, active search filtering, and clear queue actions.
• Liked Column: Heart icon column integrated directly into the track list table. Clicking the heart toggles the track's liked status. Redundant per-row metadata and addition buttons have been removed and consolidated into the right-click track context menu.
• Responsive Columns: Automatically collapses columns as the window width narrows to prevent text wrapping. Prioritizes hiding Disc # first, followed by Plays, DatePlayed, Genre, Liked, Year, Album, and Artist, maintaining #, Title, and Duration as core elements.
• Native Wayland/X11 & Lightweight: Built in native Rust using the Iced GUI toolkit. Runs on any Wayland compositor (Hyprland, GNOME, KDE) or traditional X11 window managers. Features extremely fast startup and low resource consumption.
• Rich Waybar Integration: Pre-packaged with local Waybar status scripts (scripts/omatunes_text.py) and a control group mapping play, next, and like controls. Provides styled progress bars, listening history milestones, and interactive tooltip stats.
• Folder-Based Music Library: No forced file re-organization. Respects and reads your existing music library subdirectories exactly as they are.
• Advanced Bulk Metadata (ID3) Editing: Select multiple tracks, edit fields selectively using checkboxes, utilize predictive library-based autocomplete suggestions (shared component now used in the rule builder), and apply tag updates across entire albums.
• Customizable Columns: Toggle visibilities or re-order columns via a right-click header menu, saving preferences to your local database.
• Playlists & Smart Autoplaylists: Build custom playlists on the fly, or use automatic smart lists (Liked Songs, Recently Played, Most Played) that update live as you listen.
• MPRIS2 Server Support: Integrates natively with playerctl and other system D-Bus audio widgets.

---

📖 User Manual

For an in-depth reference covering all application features, including playback controls, keybindings, live lyrics scroll-seeking, database details, bulk ID3 metadata editing, and advanced Waybar integration styling, please see the USER_MANUAL.md.

---

Requirements

Requirement	Notes
Rust ≥ 1.75	rustup recommended
A Nerd Font	JetBrainsMono Nerd Font Mono by default; any Nerd Font works
PipeWire or PulseAudio	Audio output via cpal
D-Bus session bus	For MPRIS2 (DBUS_SESSION_BUS_ADDRESS must be set)
Wayland or X11	Tested on Hyprland; works on GNOME, KDE, and any standard Wayland/X11 window manager

---

Installation & Setup

1. Install the Player Binary

Option A: Download Pre-compiled Release (Recommended)

Download the pre-compiled binary directly from the latest GitHub release:

mkdir -p ~/.local/bin
curl -L -o ~/.local/bin/omatunes https://github.com/Balthazzahr/omatunes/releases/latest/download/omatunes
chmod +x ~/.local/bin/omatunes

Option B: Compile from Source

If you prefer to compile manually:

git clone https://github.com/Balthazzahr/omatunes
cd omatunes
cargo build --release
mkdir -p ~/.local/bin
cp target/release/omatunes ~/.local/bin/omatunes

2. Install Waybar Integration Scripts

To set up the Waybar module and stats dashboard, copy the scripts to your scripts folder and make them executable:

mkdir -p ~/.local/bin/omatunes_scripts
cp scripts/omatunes_text.py ~/.local/bin/omatunes_scripts/omatunes_text.py
cp scripts/omatunes_volume.sh ~/.local/bin/omatunes_scripts/omatunes_volume.sh
chmod +x ~/.local/bin/omatunes_scripts/omatunes_text.py
chmod +x ~/.local/bin/omatunes_scripts/omatunes_volume.sh

3. (Optional) Setup Auto-Sync Service

If you want to push local code edits automatically to your GitHub fork:

mkdir -p ~/.local/bin/omatunes_scripts
cp scripts/git_sync.sh ~/.local/bin/omatunes_scripts/git_sync.sh
chmod +x ~/.local/bin/omatunes_scripts/git_sync.sh

mkdir -p ~/.config/systemd/user
cp scripts/omatunes-sync.service ~/.config/systemd/user/omatunes-sync.service
systemctl --user daemon-reload
systemctl --user enable --now omatunes-sync.service

---

Configuration

omatunes generates ~/.config/omatunes/config.toml on first run. Edit it to configure paths and behaviors:

# ~/.config/omatunes/config.toml

# Path to your music library
music_dir = "~/Music"

# Initial volume (0.0 = mute, 1.0 = 100%)
volume = 0.8

# Start session with shuffle/repeat
shuffle = false
repeat = false

# Language ("auto", "en", "pt_BR", "es")
language = "auto"

# Seek / Volume steps
seek_step = 5
volume_step = 0.05

# Scale factor for UI text sizes (float)
font_scale = 1.0

# Theming source: "System", "Preset", or "Custom"
theme_source = "Preset"

# Selected built-in preset theme name
theme_preset = "Nord"

# Custom theme colors (used when theme_source = "Custom")
[custom_theme]
base = "#1e1e2e"       # Background
text = "#cdd6f4"       # Primary Text
accent = "#cba6f7"     # Accent
green = "#a6e3a1"      # Green highlight
red = "#f38ba8"        # Red highlight
yellow = "#f9e2af"     # Yellow highlight
blue = "#89b4fa"       # Blue highlight
# Note: mantle, surface0, overlay0, and subtext colors are automatically
# derived using WCAG contrast ratios and synced to this file upon saving.

---

Waybar Integration

The Waybar integration uses four discrete modules grouped together in config.jsonc. This provides specific button components for controlling playback while displaying active track details and listening history statistics.

Add the following to your ~/.config/waybar/config.jsonc file:

  "modules-left": [
    ...
    "group/omatunes-group"
  ],

  "group/omatunes-group": {
    "orientation": "horizontal",
    "modules": [
      "custom/omatunes-play",
      "custom/omatunes-next",
      "custom/omatunes-text",
      "custom/omatunes-like"
    ]
  },

  "custom/omatunes-play": {
    "exec": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py --button play",
    "interval": 1,
    "return-type": "json",
    "format": "{}",
    "on-click": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py --click play"
  },
  "custom/omatunes-next": {
    "exec": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py --button next",
    "interval": 1,
    "return-type": "json",
    "format": "{}",
    "on-click": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py --click next"
  },
  "custom/omatunes-like": {
    "exec": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py --button like",
    "interval": 1,
    "return-type": "json",
    "format": "{}",
    "on-click": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py --click like"
  },
  "custom/omatunes-text": {
    "exec": "/home/davepople/.local/bin/omatunes_scripts/omatunes_text.py",
    "interval": 1,
    "return-type": "json",
    "format": "{}",
    "markup": "pango",
    "on-click": "hyprctl dispatch focuswindow class:^omatunes$ || hyprctl dispatch focuswindow title:^omatunes$",
    "on-scroll-up": "/home/davepople/.local/bin/omatunes_scripts/omatunes_volume.sh up",
    "on-scroll-down": "/home/davepople/.local/bin/omatunes_scripts/omatunes_volume.sh down",
    "tooltip": true
  }

For the CSS styling details to combine these modules into a single pill layout that collapses cleanly when OmaTunes is closed, refer to the Waybar Integration section in the USER_MANUAL.md.

---

Keybindings

These work when the omatunes window is focused:

Key	Action
Space	Play / Pause
→ / ←	Seek +5s / −5s
n / p	Next / Previous track
s	Toggle Shuffle
r	Toggle Repeat
+ or =	Volume +5%
-	Volume −5%
E	Edit metadata for selected tracks

For the complete list of keyboard shortcuts (including focus navigation), see the Full Keybinding Reference in the USER_MANUAL.md.

---

Auto-Sync local changes to GitHub

A script is provided at scripts/git_sync.sh which watches the local codebase and automatically pushes updates to your GitHub repository in the background.

To activate, ensure your SSH key is added to GitHub, then run:

systemctl --user daemon-reload
systemctl --user enable --now omatunes-sync.service

---

License

MIT