feat(ui): add beat-reactive animated animal DJ visualizers, improve UI preview docs, and bump to v0.0.3

Author: Kenth Fagerlund

Formula/halpradio.rb

@@ -4,26 +4,22 @@
 class Halpradio < Formula
   desc "LazyVim-inspired Terminal Internet Radio Streamer"
   homepage "https://github.com/halpworld/halpradio"
-  version "0.0.2"
+  version "0.0.3"
   license "MIT"
 
   on_macos do
     if Hardware::CPU.arm?
-      url "https://github.com/halpworld/halpradio/releases/download/v0.0.2/halpradio_0.0.2_darwin_arm64.tar.gz"
-      sha256 "e7d344645a807558f10125b9da2087acc14e09682b0837f197201d3e62682c0f"
+      url "https://github.com/halpworld/halpradio/releases/download/v0.0.3/halpradio_0.0.3_darwin_arm64.tar.gz"
     else
-      url "https://github.com/halpworld/halpradio/releases/download/v0.0.2/halpradio_0.0.2_darwin_amd64.tar.gz"
-      sha256 "70f89615278eec4105460cc1ea6a2adb80975050baf2a287c4b534af58271e88"
+      url "https://github.com/halpworld/halpradio/releases/download/v0.0.3/halpradio_0.0.3_darwin_amd64.tar.gz"
     end
   end
 
   on_linux do
     if Hardware::CPU.arm? && Hardware::CPU.is_64_bit?
-      url "https://github.com/halpworld/halpradio/releases/download/v0.0.2/halpradio_0.0.2_linux_arm64.tar.gz"
-      sha256 "022baff84f0e21a985690617938ec707f02938bd00a0505f46f000bdd2f96c49"
+      url "https://github.com/halpworld/halpradio/releases/download/v0.0.3/halpradio_0.0.3_linux_arm64.tar.gz"
     else
-      url "https://github.com/halpworld/halpradio/releases/download/v0.0.2/halpradio_0.0.2_linux_amd64.tar.gz"
-      sha256 "3c1aaae06b31394e5c4a2c538af0ee40981ee5b1047adc1ad015e323d4ad1a33"
+      url "https://github.com/halpworld/halpradio/releases/download/v0.0.3/halpradio_0.0.3_linux_amd64.tar.gz"
     end
   end
 

README.md

@@ -46,35 +46,66 @@ halpradio
 - **🐙 1-Key GitHub PR Export**: Press `p` on any station to copy a clean YAML snippet directly to your clipboard, ready for submitting a PR to [`stations.yaml`](./stations.yaml)!
 - **🔒 Private / Custom Stations**: Add private stream URLs locally via interactive `[ a ] Add Station` dialog (saved in `~/.config/halpradio/stations.yaml`).
 - **🎨 6 Vibrant Themes**: Tokyo Night, Catppuccin Mocha, Retro Synthwave '84, Nord, Gruvbox Dark, and Dracula.
-- **🔊 Live Audio Equalizer**: Dynamic animated TUI visualizers (Bars, Waveform, Spectrum, Minimal).
+- **🎧 Animated Animal DJ Visualizers**: Beat-reactive terminal DJs (Cat 🐱, Dog 🐶, Bear 🐻, Frog 🐸, Bunny 🐰) spinning vinyl, scratching decks, and pumping a smooth multi-frequency equalizer rack!
 - **📻 Real-time ICY Metadata**: Displays live song title and artist information for supported Icecast/Shoutcast HTTP streams.
 - **⭐ Favorites System**: Bookmark stations with `f` for 1-key instant access across restarts.
 
 ---
 
 ## 📺 Preview
 
+<p align="center">
+  <img src="./docs/images/preview.jpg" alt="halpradio TUI Preview" width="850" />
+</p>
+
 ```
-┌── 📻 HALPRADIO v0.0.2 ───────────────────────────────────────────────────────────── [ TOKYO NIGHT ] ┐
+┌── 📻 HALPRADIO v0.0.3 ───────────────────────────────────────────────────────────── [ TOKYO NIGHT ] ┐
 │                                                                                                    │
-│  [1] All Stations (128)   [2] Favorites (12)   [3] Categories   [4] Online Search (30,000+)       │
+│  [ 1: Catalog (128) ]   [ 2: Work Modes ]   [ 3: Genres ]   [ 4: Online Search ]   [ ▶ PLAY ]      │
 │ ────────────────────────────────────────────────────────────────────────────────────────────────── │
-│  ▶  ⭐  Lofi Girl Radio              [ Lofi / Chill ]             FR  •  128 kbps MP3            │
-│     ⭐  Nightwave Plaza              [ Vaporwave / Synth ]        US  •  320 kbps MP3            │
-│        Chillhop Music Radio          [ Lofi / HipHop ]            NL  •  192 kbps MP3            │
-│        SomaFM Groove Salad           [ Ambient / Downtempo ]      US  •  128 kbps MP3            │
-│        KEXP 90.3 FM                  [ Indie / Alternative ]      US  •  160 kbps AAC            │
-│        BBC Radio 6 Music             [ Eclectic / Rock ]          GB  •  128 kbps AAC            │
+│  ▶  ⭐  🇫🇷 Lofi Girl Radio            [ Lofi / Beats ]             FR  •  320 kbps MP3            │
+│     ⭐  🇺🇸 Nightwave Plaza            [ Vaporwave / Synth ]        US  •  192 kbps MP3            │
+│        🇳🇱 Chillhop Music Radio        [ Lofi / Jazz ]              NL  •  320 kbps MP3            │
+│        🇺🇸 SomaFM Groove Salad         [ Downtempo / Ambient ]      US  •  128 kbps MP3            │
+│        🇺🇸 KEXP 90.3 FM                [ Indie / Alt Rock ]         US  •  160 kbps AAC            │
+│        🇬🇧 BBC Radio 6 Music           [ Eclectic / Rock ]          GB  •  128 kbps AAC            │
 │ ────────────────────────────────────────────────────────────────────────────────────────────────── │
-│  NOW PLAYING: Lofi Girl Radio — Kupla & Philanthrope - Soft Wind                                   │
-│  VOLUME: [████████████████░░░░] 80%  •  BACKEND: mpv  •  VISUALIZER: ▃▅▇█▇▅▃ ▂▄▆█                      │
-│                                                                                                    │
-│  [?] WhichKey  [/] Search  [Space] Play/Pause  [f] Fav  [p] Export PR  [t] Theme  [q] Quit         │
+│  🇫🇷 Lofi Girl Radio (Lofi / Beats)                                    🔊 [████████░░] 80%          │
+│  ♪ Kupla & Philanthrope - Soft Wind           🎧 (=^･ω･^=)ﾉ [💿 ◓] ♫  ▂▃▄▅▆                        │
+│ ────────────────────────────────────────────────────────────────────────────────────────────────── │
+│  [?] WhichKey  [/] Search  [Space] Play/Pause  [v] Visualizer  [f] Fav  [t] Theme  [q] Quit        │
 └────────────────────────────────────────────────────────────────────────────────────────────────────┘
 ```
 
 ---
 
+## 🎧 Beat-Reactive Animal DJ Visualizers
+
+<p align="center">
+  <img src="./docs/images/visualizers.jpg" alt="halpradio Animated Animal DJ Visualizers" width="850" />
+</p>
+
+Press `v` anytime in **halpradio** to cycle through 5 animated animal DJs, classic bars, waveform, spectrum, or minimal meters:
+
+| Visualizer Mode | Animal Character | DJ Booth & Live Equalizer Preview |
+|---|---|---|
+| `dj-cat` *(default)* | 🐱 **DJ Cat** | `🎧 (=^･ω･^=)ﾉ [💿 ◓] ♫  ▂▃▄▅▆` |
+| `dj-dog` | 🐶 **DJ Dog** | `🎧  (∪･ω･∪) ﾉ [💿 ◑] ♫  ▂▃▄▅▆` |
+| `dj-bear` | 🐻 **DJ Bear** | `🎧  ʕ •ᴥ•ʔ  ﾉ [💿 ◒] ♫  ▂▃▄▅▆` |
+| `dj-frog` | 🐸 **DJ Frog** | `🎧  ( •⊖• ) ﾉ [💿 ◐] ♫  ▂▃▄▅▆` |
+| `dj-bunny` | 🐰 **DJ Bunny** | `🎧 ( •ㅅ• )  ﾉ [💿 ◓] ♫  ▂▃▄▅▆` |
+| `bars` | 📊 **Bars Equalizer** | `♫  ▂▃▄▅▆▇█▇▆▅▄▃▂  ♬` |
+| `wave` | ∿ **Waveform** | `∿ _⎽⎼─⎻⎺▔⎺⎻─⎼⎽_ ∿` |
+| `spectrum` | 🔊 **Spectrum** | `🔊 BASS ███ MID ███ TREB ███` |
+| `minimal` | 🎚️ **Minimal VU** | `L:████░░░░ R:██████░░` |
+
+- **Zero-Jitter Normalized Poses**: Every pose (head + arm + deck) has an exact, invariant width (24 visual columns) for smooth, stable rendering without horizontal shifting.
+- **Harmonic Multi-Frequency Equalizer Rack**: Solid 6-bar mini-EQ (` ▂▃▄▅▆`) driven by harmonic frequency physics (sub-bass kick, mid melody, treble shimmer) with smooth attack and exponential decay.
+- **Rhythmic Groove**: Head bobbing and turntable vinyl rotation (`◓`, `◑`, `◒`, `◐`) tempo-matched to audio playback.
+- **Sleep State**: When stopped/paused, the DJ rests peacefully on the turntable (`🎧 (= - ω - =)..zzZ [ 💿 ] ⏹ STOPPED`).
+
+---
+
 ## 📦 Installation Options
 
 ### Method 1: Homebrew (macOS & Linux) — Recommended
@@ -119,8 +150,8 @@ Download pre-compiled standalone tarballs from the [GitHub Releases](https://git
 **Manual Installation Steps:**
 ```bash
 # Example for macOS Apple Silicon:
-curl -LO https://github.com/halpworld/halpradio/releases/latest/download/halpradio_0.0.2_darwin_arm64.tar.gz
-tar -xzf halpradio_0.0.2_darwin_arm64.tar.gz
+curl -LO https://github.com/halpworld/halpradio/releases/latest/download/halpradio_0.0.3_darwin_arm64.tar.gz
+tar -xzf halpradio_0.0.3_darwin_arm64.tar.gz
 sudo mv halpradio /usr/local/bin/
 ```
 
@@ -194,7 +225,7 @@ Press `?` or `F1` anywhere in **halpradio** to open the floating **WhichKey Over
 | | `r` | Play random station |
 | | `+` / `-` | Volume up / down (5% step) |
 | | `m` | Mute / unmute |
-| | `v` | Cycle visualizer (`bars`, `waveform`, `spectrum`, `minimal`) |
+| | `v` | Cycle visualizer (`dj-cat`, `dj-dog`, `dj-bear`, `dj-frog`, `dj-bunny`, `bars`, `wave`, `spectrum`, `minimal`) |
 | **Catalog** | `f` | Toggle Favorite star ⭐ |
 | | `/` | Live fuzzy search / filter stations |
 | | `a` | Open **Add Custom Station** modal |

docs/CONFIGURATION.md

@@ -24,7 +24,7 @@ All user state and settings are stored in your platform's standard configuration
 volume: 80
 player_backend: "auto"     # auto, native, mpv, vlc, cvlc, ffplay, mplayer, mpg123
 theme: "tokyonight"        # tokyonight, catppuccin, synthwave, nord, gruvbox, dracula
-visualizer_mode: "bars"    # bars, waveform, spectrum, minimal
+visualizer_mode: "dj-cat"   # dj-cat, dj-dog, dj-bear, dj-frog, dj-bunny, bars, wave, spectrum, minimal, off
 last_station_id: ""        # Remembers last played station
 ```
 
@@ -33,31 +33,34 @@ last_station_id: ""        # Remembers last played station
 ## 🚩 Command-Line Flags
 
 ```bash
-# Force specific audio backend
-halpradio -backend mpv
+# Set audio player backend explicitly
+halpradio --backend=native
+halpradio --backend=mpv
+halpradio --backend=vlc
 
-# Force native Go audio engine (no mpv or vlc needed)
-halpradio -backend native
+# Choose initial color theme
+halpradio --theme=synthwave
+halpradio --theme=catppuccin
 
-# Launch with Synthwave '84 theme
-halpradio -theme synthwave
-
-# Display version information
-halpradio -version
+# Print version and system diagnostic report
+halpradio --version
 ```
 
 ---
 
-## ⌨️ Complete Keybindings Reference (LazyVim Style)
-
-Press `?` or `F1` anywhere in **halpradio** to toggle the floating **WhichKey Help Overlay**.
+## ⌨️ Global Keybindings Reference
 
-### 🧭 Navigation & Tab Controls
+### 🎧 Audio & Playback Controls
 
 | Keybinding | Action |
 |---|---|
-| `j` / `↓` | Move selection down |
-| `k` / `↑` | Move selection up |
+| `Space` / `Enter` | Toggle Play / Pause selected station |
+| `s` | Stop audio stream playback |
+| `r` | Play a random station |
+| `+` / `=` | Increase volume (+5%) |
+| `-` | Decrease volume (-5%) |
+| `m` | Mute / Unmute audio |
+| `v` | Cycle audio visualizer mode (`dj-cat` ➔ `dj-dog` ➔ `dj-bear` ➔ `dj-frog` ➔ `dj-bunny` ➔ `bars` ➔ `wave` ➔ `spectrum` ➔ `minimal` ➔ `off`) |
 | `h` / `←` | Focus left sidebar / Previous tab |
 | `l` / `→` | Focus main list / Next tab |
 | `1` - `4` | Direct jump to Tab (1: All, 2: Favorites, 3: Categories, 4: Online Search) |

docs/THEME_SYSTEM.md

@@ -58,19 +58,33 @@ type Theme struct {
 
 ## 🔊 Dynamic Audio Visualizers (`pkg/ui/components/visualizer.go`)
 
-When audio is playing, `halpradio` renders an animated visualizer in the Player Bar. Press `v` to cycle through 4 visualizer modes:
+<p align="center">
+  <img src="./images/visualizers.jpg" alt="halpradio Animated Animal DJ Visualizers" width="800" />
+</p>
+
+When audio is playing, `halpradio` renders a zero-jitter, beat-reactive animated visualizer in the Player Bar. Press `v` to cycle through visualizer modes:
 
 ```
-Bars Mode:     ▃▅▇█▇▅▃ ▂▄▆█▆▄▂
-Waveform Mode: ~≈∼-∼≈~-~≈∼-∼≈~
-Spectrum Mode: ░▒▓█▓▒░░▒▓█▓▒░
-Minimal Mode:  ● ∙ ○ ∙ ● ∙ ○ ∙
+DJ Cat Mode:    🎧 (=^･ω･^=)ﾉ [💿 ◓] ♫  ▂▃▄▅▆
+DJ Dog Mode:    🎧  (∪･ω･∪) ﾉ [💿 ◑] ♫  ▂▃▄▅▆
+DJ Bear Mode:   🎧  ʕ •ᴥ•ʔ  ﾉ [💿 ◒] ♫  ▂▃▄▅▆
+DJ Frog Mode:   🎧  ( •⊖• ) ﾉ [💿 ◐] ♫  ▂▃▄▅▆
+DJ Bunny Mode:  🎧 ( •ㅅ• )  ﾉ [💿 ◓] ♫  ▂▃▄▅▆
+Bars Mode:      ♫  ▂▃▄▅▆▇█▇▆▅▄▃▂  ♬
+Waveform Mode:  ∿ _⎽⎼─⎻⎺▔⎺⎻─⎼⎽_ ∿
+Spectrum Mode:  🔊 BASS ███ MID ███ TREB ███
+Minimal Mode:   L:████░░░░ R:██████░░
 ```
 
-1. **Bars Equalizer**: Dynamic vertical block bars (` ▂▃▄▅▆▇█`) responding to time ticks.
-2. **Waveform**: Smooth sine wave unicode characters depicting audio oscillation.
-3. **Spectrum**: Multi-level block density visualizer.
-4. **Minimal**: Compact pulsing dot indicators for minimalistic terminal layouts.
+1. **Animated Animal DJs** (`dj-cat`, `dj-dog`, `dj-bear`, `dj-frog`, `dj-bunny`):
+   - **Zero-Jitter Normalized Poses**: Every pose (head + arm + deck) has an exact, invariant width (24 visual columns) for smooth, stable rendering without horizontal shifting.
+   - **Harmonic Multi-Frequency Equalizer Rack**: Solid 6-bar mini-EQ (` ▂▃▄▅▆`) driven by harmonic frequency physics (sub-bass kick, mid melody, treble shimmer) with smooth attack and exponential decay.
+   - **Rhythmic Groove**: Head bobbing and turntable vinyl rotation (`◓`, `◑`, `◒`, `◐`) tempo-matched to audio playback.
+   - **Sleep State**: When stopped/paused, the DJ rests peacefully on the turntable (`🎧 (= - ω - =)..zzZ [ 💿 ] ⏹ STOPPED`).
+2. **Bars Equalizer**: Dynamic vertical block bars (` ▂▃▄▅▆▇█`) responding to time ticks.
+3. **Waveform**: Smooth sine wave unicode characters depicting audio oscillation.
+4. **Spectrum**: Multi-band frequency equalizer.
+5. **Minimal**: Compact stereo VU meters.
 
 ---
 

docs/images/preview.jpg

@@ -33,7 +33,7 @@ if [ -z "${VERSION}" ]; then
   echo "🔍 Fetching latest halpradio release..."
   VERSION=$(curl -s "https://api.github.com/repos/${REPO}/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
   if [ -z "${VERSION}" ]; then
-    VERSION="v0.0.2"
+    VERSION="v0.0.3"
   fi
 fi
 

docs/images/visualizers.jpg

@@ -12,7 +12,7 @@ import (
 	"github.com/halpworld/halpradio/pkg/util"
 )
 
-var Version = "0.0.2"
+var Version = "0.0.3"
 
 func Run(embeddedCatalog []byte) {
 	backendFlag := flag.String("backend", "auto", "Audio player backend: auto, native, mpv, vlc, ffplay, mplayer, mpg123")

install.sh

@@ -59,7 +59,8 @@ func RenderPlayerBar(
 		Foreground(th.Highlight)
 
 	isPlaying := (status == player.PlayStatus(player.StatusPlaying))
-	vizRendered := viz.Render(isPlaying, clamp(width/3, 15), th)
+	vizWidth := clamp(width*2/5, 20)
+	vizRendered := viz.Render(isPlaying, vizWidth, th)
 
 	line1Left := fmt.Sprintf("%s %s", currStation.CountryFlag(), titleStyle.Render(currStation.Name))
 	if currStation.Genre != "" {
@@ -77,7 +78,11 @@ func RenderPlayerBar(
 	if trackDisplay == "" {
 		trackDisplay = currStation.Name
 	}
-	line2Left := trackStyle.Render("♪ " + truncate(trackDisplay, clamp(width/2, 20)))
+	maxTrackWidth := width - lipgloss.Width(vizRendered) - 8
+	if maxTrackWidth < 15 {
+		maxTrackWidth = 15
+	}
+	line2Left := trackStyle.Render("♪ " + truncate(trackDisplay, maxTrackWidth))
 
 	space2 := width - lipgloss.Width(line2Left) - lipgloss.Width(vizRendered) - 6
 	if space2 < 1 {