Implement vim-style navigation and visual mode

- Add vim-style h key: closes folders and jumps to parent - Implement stop() method in player for proper playback stopping - Add space key to restart playback when stopped - Add playlist color coding: green (playing), blue (paused), yellow (stopped) - Fix n/p keys to preserve player state when switching tracks - Implement vim-style visual mode with v key for multi-file selection - Visual mode exits automatically on play/add actions - Remove unused play_previous method - Bump version to 0.1.7
Add comprehensive technical README
2025-12-06 17:35:11 +01:00 · 2025-12-06 16:56:15 +01:00
6 changed files with 454 additions and 42 deletions
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "cm-player"
-version = "0.1.5"
+version = "0.1.7"
 edition = "2021"

 [dependencies]
--- a/README.md
+++ b/README.md
@@ -1,2 +1,278 @@
 # cm-player

+A high-performance terminal UI music and video player written in Rust, designed for low-bandwidth VPN environments with cache-only operation.
+
+## Features
+
+- **Cache-only architecture**: Scans media directories once and operates from cache, ideal for low-bandwidth VPN connections
+- **Vim-style navigation**: Familiar keybindings (j/k/h/l) for efficient navigation
+- **Incremental fuzzy search**: Real-time search with Tab completion, similar to vim's command-line search
+- **Directory tree browsing**: Collapsible folder structure with lazy scrolling
+- **Playlist management**: Mark multiple files (vim-style 'v' key) to create custom playlists
+- **MPV integration**: Video and audio playback via MPV subprocess with IPC control
+- **Dual-panel layout**: File browser on left, playlist on right
+- **Auto-advance**: Automatically plays next track when current track ends
+
+## Architecture
+
+### Core Components
+
+**State Management** (`src/state/mod.rs`)
+- Maintains flattened file tree from cache for efficient rendering
+- Handles directory expansion/collapse state
+- Manages playlist and playback position
+- Implements fuzzy search with folder priority boost
+
+**MPV IPC Integration** (`src/player/mod.rs`)
+- Spawns MPV as subprocess with Unix socket IPC
+- Automatic process respawn when MPV exits (user closes window)
+- Non-blocking socket communication with JSON protocol
+- Tracks playback state, position, duration via property observation
+
+**Cache System** (`src/cache/mod.rs`)
+- XDG-compliant cache storage: `~/.cache/cm-player/`
+- Serializes directory tree structure with serde_json
+- Supports manual refresh with 'r' key
+- Scans multiple configured paths
+
+**UI Rendering** (`src/ui/mod.rs`)
+- Three-section layout: title bar (1 line) | content | status bar (1 line)
+- Ratatui framework with crossterm backend
+- Theme matching cm-dashboard color scheme
+- Real-time playback progress in title bar
+
+### Technical Details
+
+**Fuzzy Search Algorithm**
+```rust
+// Scoring system:
+// - Characters must appear in order (not necessarily consecutive)
+// - Consecutive matches: +10 bonus per character
+// - Word boundary matches: +15 bonus
+// - Gap penalty: -1 per character between matches
+// - Folder priority: +50 score boost
+// - Length bonus: 100 - text_length
+```
+
+**MPV Communication**
+- IPC socket: `/tmp/cm-player-{pid}.sock`
+- Commands: `{ "command": ["loadfile", "path"] }`
+- Property observation: `time-pos`, `duration`, `pause`, `idle-active`
+- Process lifecycle: spawn -> connect -> command -> observe -> respawn on exit
+
+**Lazy Scrolling**
+- Selection stays in place until reaching viewport edge
+- Scroll offset only updates when necessary
+- Page navigation with Ctrl-D/U (half-page jumps)
+
+## Installation
+
+### Pre-built Binary (NixOS)
+
+```nix
+# hosts/common/cm-player.nix is automatically included
+# mpv is installed as dependency
+```
+
+### From Release
+
+```bash
+curl -L https://gitea.cmtec.se/cm/cm-player/releases/latest/download/cm-player-linux-x86_64 -o cm-player
+chmod +x cm-player
+sudo mv cm-player /usr/local/bin/
+```
+
+### Build from Source
+
+```bash
+git clone https://gitea.cmtec.se/cm/cm-player.git
+cd cm-player
+cargo build --release
+./target/release/cm-player
+```
+
+**Static linking** (for portability):
+```bash
+export RUSTFLAGS="-C target-feature=+crt-static"
+cargo build --release --target x86_64-unknown-linux-gnu
+```
+
+## Configuration
+
+### Config File
+
+Location: `~/.config/cm-player/config.toml`
+
+```toml
+[scan_paths]
+paths = [
+    "/mnt/music",
+    "/mnt/movie",
+    "/mnt/tv"
+]
+```
+
+### First Run
+
+1. Create config file with media paths
+2. Launch cm-player
+3. Press 'r' to scan directories and build cache
+4. Cache stored at `~/.cache/cm-player/cache.json`
+
+## Keybindings
+
+### Navigation
+- `j` / `k` / `↓` / `↑` - Move selection down/up
+- `h` - Collapse directory
+- `l` - Expand directory
+- `Ctrl-D` - Page down (half page)
+- `Ctrl-U` - Page up (half page)
+
+### Search
+- `/` - Enter search mode (fuzzy find)
+- `Tab` - Next search result
+- `Shift-Tab` - Previous search result
+- `Enter` - Execute search and enable n/N cycling
+- `n` - Next search match (after Enter) or next track
+- `N` - Previous search match
+- `Esc` - Clear search results
+
+### Playlist
+- `v` - Mark/unmark file or directory
+- `a` - Add marked files to playlist
+- `c` - Clear playlist
+
+### Playback
+- `Enter` - Play selected file/folder (uses marks if any)
+- `Space` - Pause/Resume
+- `s` - Stop playback
+- `p` - Previous track
+- `n` - Next track (when not in search results)
+- `←` / `→` - Seek backward/forward 10 seconds
+- `+` / `=` - Increase volume
+- `-` - Decrease volume
+
+### System
+- `r` - Rescan media directories and rebuild cache
+- `q` - Quit
+
+## Development
+
+### Project Structure
+
+```
+cm-player/
+├── src/
+│   ├── main.rs           # Event loop and key handling
+│   ├── state/mod.rs      # App state and search logic
+│   ├── player/mod.rs     # MPV IPC integration
+│   ├── ui/
+│   │   ├── mod.rs        # TUI rendering
+│   │   └── theme.rs      # Color scheme
+│   ├── cache/mod.rs      # Cache serialization
+│   ├── scanner/mod.rs    # Directory scanning
+│   └── config/mod.rs     # Config file handling
+├── .gitea/workflows/
+│   └── release.yml       # CI/CD pipeline
+└── Cargo.toml
+```
+
+### Dependencies
+
+- **ratatui** - Terminal UI framework
+- **crossterm** - Terminal backend
+- **tokio** - Async runtime for event loop
+- **serde/serde_json** - Cache serialization
+- **walkdir** - Directory traversal
+- **anyhow/thiserror** - Error handling
+
+### Logging
+
+Logs written to `/tmp/cm-player.log` to avoid interfering with TUI:
+
+```rust
+tracing::info!("Playing: {:?}", path);
+tail -f /tmp/cm-player.log
+```
+
+## Release Process
+
+### Automated CI/CD
+
+Releases are fully automated via Gitea Actions:
+
+```bash
+# Update version in Cargo.toml
+vim Cargo.toml
+
+# Commit and tag
+git add Cargo.toml
+git commit -m "Bump version to v0.1.X"
+git push
+git tag v0.1.X
+git push origin v0.1.X
+```
+
+**Workflow steps**:
+1. Build static binary with `RUSTFLAGS="-C target-feature=+crt-static"`
+2. Create GitHub-style release on Gitea
+3. Upload binary and tarball as release assets
+4. Calculate SHA256 hash from local tarball
+5. Clone nixosbox repository
+6. Update `hosts/common/cm-player.nix` with new version and hash
+7. Commit and push to nixosbox
+
+### Manual NixOS Update
+
+If workflow fails, update manually:
+
+```bash
+cd ~/projects/nixosbox
+
+# Download and hash the tarball
+curl -L https://gitea.cmtec.se/cm/cm-player/releases/download/v0.1.X/cm-player-linux-x86_64.tar.gz -o /tmp/cm-player.tar.gz
+sha256sum /tmp/cm-player.tar.gz | cut -d' ' -f1
+# Convert hex to base64: python3 -c "import base64, binascii; print(base64.b64encode(binascii.unhexlify('HEX_HASH')).decode())"
+
+# Edit hosts/common/cm-player.nix
+vim hosts/common/cm-player.nix
+# Update version and sha256
+
+git add hosts/common/cm-player.nix
+git commit -m "Update cm-player to v0.1.X"
+git push
+```
+
+## MPV Configuration
+
+Default MPV flags:
+- `--idle` - Keep MPV running between tracks
+- `--no-terminal` - Disable MPV's terminal output
+- `--profile=fast` - Use fast decoding profile
+- `--audio-display=no` - Disable cover art for audio files
+- `--input-ipc-server=/tmp/cm-player-{pid}.sock` - Enable IPC
+
+## Troubleshooting
+
+### MPV window closes immediately
+Check MPV installation: `mpv --version`
+
+### Scan shows no files
+- Verify paths in `~/.config/cm-player/config.toml`
+- Press 'r' to rescan
+- Check logs: `tail -f /tmp/cm-player.log`
+
+### Hash mismatch on NixOS rebuild
+- Wait for workflow to complete before rebuilding
+- Workflow calculates hash from local tarball, not downloaded
+- Check release assets are fully uploaded: https://gitea.cmtec.se/cm/cm-player/releases
+
+### Video playback issues
+MPV process respawns automatically if closed. If issues persist:
+1. Stop playback with 's'
+2. Restart cm-player
+3. Check `/tmp/cm-player.log` for errors
+
+## License
+
+Copyright (c) 2025 CM Tech
--- a/src/main.rs
+++ b/src/main.rs
@@ -161,24 +161,40 @@ async fn handle_key_event<B: ratatui::backend::Backend>(terminal: &mut Terminal<
        }
        (KeyCode::Esc, _) => {
            state.search_matches.clear();
+            if state.visual_mode {
+                state.visual_mode = false;
+                state.marked_files.clear();
+            }
        }
        (KeyCode::Char('n'), _) => {
            if !state.search_matches.is_empty() {
                state.next_search_match();
-            } else {
-                // If stopped, start from current index (0), otherwise go to next
-                if state.player_state == PlayerState::Stopped && !state.playlist.is_empty() {
+            } else if !state.playlist.is_empty() {
+                // Advance to next track
+                if state.playlist_index + 1 < state.playlist.len() {
+                    state.playlist_index += 1;
                    state.current_file = Some(state.playlist[state.playlist_index].clone());
-                    state.player_state = PlayerState::Playing;
-                    if let Some(ref path) = state.current_file {
-                        player.play(path)?;
-                        tracing::info!("Starting playlist: {:?}", path);
-                    }
-                } else {
-                    state.play_next();
-                    if let Some(ref path) = state.current_file {
-                        player.play(path)?;
-                        tracing::info!("Next track: {:?}", path);
+
+                    match state.player_state {
+                        PlayerState::Playing => {
+                            // Keep playing
+                            if let Some(ref path) = state.current_file {
+                                player.play(path)?;
+                                tracing::info!("Next track: {:?}", path);
+                            }
+                        }
+                        PlayerState::Paused => {
+                            // Load but stay paused
+                            if let Some(ref path) = state.current_file {
+                                player.play(path)?;
+                                player.pause()?;
+                                tracing::info!("Next track (paused): {:?}", path);
+                            }
+                        }
+                        PlayerState::Stopped => {
+                            // Just update current file, stay stopped
+                            tracing::info!("Next track selected (stopped): {:?}", state.current_file);
+                        }
                    }
                }
            }
@@ -209,15 +225,40 @@ async fn handle_key_event<B: ratatui::backend::Backend>(terminal: &mut Terminal<
        }
        (KeyCode::Char('a'), _) => {
            state.add_to_playlist();
+            if state.visual_mode {
+                state.visual_mode = false;
+                state.marked_files.clear();
+            }
        }
        (KeyCode::Char('c'), _) => {
            state.clear_playlist();
        }
        (KeyCode::Char('p'), _) => {
-            state.play_previous();
-            if let Some(ref path) = state.current_file {
-                player.play(path)?;
-                tracing::info!("Previous track: {:?}", path);
+            if !state.playlist.is_empty() && state.playlist_index > 0 {
+                state.playlist_index -= 1;
+                state.current_file = Some(state.playlist[state.playlist_index].clone());
+
+                match state.player_state {
+                    PlayerState::Playing => {
+                        // Keep playing
+                        if let Some(ref path) = state.current_file {
+                            player.play(path)?;
+                            tracing::info!("Previous track: {:?}", path);
+                        }
+                    }
+                    PlayerState::Paused => {
+                        // Load but stay paused
+                        if let Some(ref path) = state.current_file {
+                            player.play(path)?;
+                            player.pause()?;
+                            tracing::info!("Previous track (paused): {:?}", path);
+                        }
+                    }
+                    PlayerState::Stopped => {
+                        // Just update current file, stay stopped
+                        tracing::info!("Previous track selected (stopped): {:?}", state.current_file);
+                    }
+                }
            }
        }
        (KeyCode::Enter, _) => {
@@ -226,9 +267,14 @@ async fn handle_key_event<B: ratatui::backend::Backend>(terminal: &mut Terminal<
                player.play(path)?;
                tracing::info!("Playing: {:?} (playlist: {} tracks)", path, state.playlist.len());
            }
+            if state.visual_mode {
+                state.visual_mode = false;
+                state.marked_files.clear();
+            }
        }
        (KeyCode::Char('s'), _) => {
            // s: Stop playback
+            player.stop()?;
            state.player_state = PlayerState::Stopped;
            state.current_position = 0.0;
            state.current_duration = 0.0;
@@ -246,7 +292,17 @@ async fn handle_key_event<B: ratatui::backend::Backend>(terminal: &mut Terminal<
                    state.player_state = PlayerState::Playing;
                    tracing::info!("Resumed");
                }
-                PlayerState::Stopped => {}
+                PlayerState::Stopped => {
+                    // Restart playback from current playlist position
+                    if !state.playlist.is_empty() {
+                        state.current_file = Some(state.playlist[state.playlist_index].clone());
+                        state.player_state = PlayerState::Playing;
+                        if let Some(ref path) = state.current_file {
+                            player.play(path)?;
+                            tracing::info!("Restarting playback: {:?}", path);
+                        }
+                    }
+                }
            }
        }
        (KeyCode::Left, _) => {
--- a/src/player/mod.rs
+++ b/src/player/mod.rs
@@ -187,6 +187,13 @@ impl Player {
        Ok(())
    }

+    pub fn stop(&mut self) -> Result<()> {
+        self.send_command("stop", &[])?;
+        self.is_idle = true;
+        self.position = 0.0;
+        self.duration = 0.0;
+        Ok(())
+    }

    pub fn set_volume(&mut self, volume: i64) -> Result<()> {
        self.send_command("set_property", &[json!("volume"), json!(volume)])?;
--- a/src/state/mod.rs
+++ b/src/state/mod.rs
@@ -33,6 +33,8 @@ pub struct AppState {
    pub search_match_index: usize,
    pub tab_search_results: Vec<PathBuf>,
    pub tab_search_index: usize,
+    pub visual_mode: bool,
+    pub visual_anchor: usize,
 }

 #[derive(Debug, Clone)]
@@ -71,6 +73,8 @@ impl AppState {
            search_match_index: 0,
            tab_search_results: Vec::new(),
            tab_search_index: 0,
+            visual_mode: false,
+            visual_anchor: 0,
        }
    }

@@ -81,12 +85,20 @@ impl AppState {
            if self.selected_index < self.scroll_offset {
                self.scroll_offset = self.selected_index;
            }
+            // Update visual selection if in visual mode
+            if self.visual_mode {
+                self.update_visual_selection();
+            }
        }
    }

    pub fn move_selection_down(&mut self) {
        if self.selected_index < self.flattened_items.len().saturating_sub(1) {
            self.selected_index += 1;
+            // Update visual selection if in visual mode
+            if self.visual_mode {
+                self.update_visual_selection();
+            }
        }
    }

@@ -120,11 +132,39 @@ impl AppState {
    }

    pub fn collapse_selected(&mut self) {
-        if let Some(item) = self.get_selected_item() {
+        let item = self.get_selected_item().cloned();
+        if let Some(item) = item {
            if item.node.is_dir {
                let path = item.node.path.clone();
-                self.expanded_dirs.remove(&path);
-                self.rebuild_flattened_items();
+                let was_expanded = self.expanded_dirs.contains(&path);
+
+                if was_expanded {
+                    // Close the expanded folder
+                    self.expanded_dirs.remove(&path);
+                    self.rebuild_flattened_items();
+                } else {
+                    // Folder is collapsed, close parent instead and jump to it
+                    if let Some(parent) = path.parent() {
+                        let parent_buf = parent.to_path_buf();
+                        self.expanded_dirs.remove(&parent_buf);
+                        self.rebuild_flattened_items();
+                        // Jump to parent folder
+                        if let Some(parent_idx) = self.flattened_items.iter().position(|i| i.node.path == parent_buf) {
+                            self.selected_index = parent_idx;
+                        }
+                    }
+                }
+            } else {
+                // Close parent folder when on a file and jump to it
+                if let Some(parent) = item.node.path.parent() {
+                    let parent_buf = parent.to_path_buf();
+                    self.expanded_dirs.remove(&parent_buf);
+                    self.rebuild_flattened_items();
+                    // Jump to parent folder
+                    if let Some(parent_idx) = self.flattened_items.iter().position(|i| i.node.path == parent_buf) {
+                        self.selected_index = parent_idx;
+                    }
+                }
            }
        }
    }
@@ -140,13 +180,37 @@ impl AppState {
    }

    pub fn toggle_mark(&mut self) {
-        if let Some(item) = self.get_selected_item() {
-            if !item.node.is_dir {
-                let path = item.node.path.clone();
-                if self.marked_files.contains(&path) {
-                    self.marked_files.remove(&path);
-                } else {
-                    self.marked_files.insert(path);
+        if self.visual_mode {
+            // Exit visual mode and mark all files in range
+            self.update_visual_selection();
+            self.visual_mode = false;
+        } else {
+            // Enter visual mode
+            self.visual_mode = true;
+            self.visual_anchor = self.selected_index;
+            // Clear previous marks when entering visual mode
+            self.marked_files.clear();
+            // Mark current file
+            if let Some(item) = self.get_selected_item() {
+                if !item.node.is_dir {
+                    self.marked_files.insert(item.node.path.clone());
+                }
+            }
+        }
+    }
+
+    fn update_visual_selection(&mut self) {
+        // Clear marks
+        self.marked_files.clear();
+
+        // Mark all files between anchor and current position
+        let start = self.visual_anchor.min(self.selected_index);
+        let end = self.visual_anchor.max(self.selected_index);
+
+        for i in start..=end {
+            if let Some(item) = self.flattened_items.get(i) {
+                if !item.node.is_dir {
+                    self.marked_files.insert(item.node.path.clone());
                }
            }
        }
@@ -229,14 +293,6 @@ impl AppState {
        }
    }

-    pub fn play_previous(&mut self) {
-        if self.playlist_index > 0 {
-            self.playlist_index -= 1;
-            self.current_file = Some(self.playlist[self.playlist_index].clone());
-            self.player_state = PlayerState::Playing;
-        }
-    }
-
    pub fn refresh_flattened_items(&mut self) {
        // Keep current expanded state after rescan
        self.rebuild_flattened_items();
--- a/src/ui/mod.rs
+++ b/src/ui/mod.rs
@@ -95,8 +95,19 @@ fn render_right_panel(frame: &mut Frame, state: &AppState, area: Rect) {
                .map(|n| n.to_string_lossy().to_string())
                .unwrap_or_else(|| path.to_string_lossy().to_string());

-            let style = if idx == state.playlist_index && state.player_state != PlayerState::Stopped {
-                Theme::selected()
+            let style = if idx == state.playlist_index {
+                // Color based on player state
+                match state.player_state {
+                    PlayerState::Playing => Style::default()
+                        .fg(Theme::background())
+                        .bg(Theme::success()),  // Green
+                    PlayerState::Paused => Style::default()
+                        .fg(Theme::background())
+                        .bg(Theme::highlight()),  // Blue
+                    PlayerState::Stopped => Style::default()
+                        .fg(Theme::background())
+                        .bg(Theme::warning()),  // Yellow/orange
+                }
            } else {
                Theme::secondary()
            };
@@ -121,7 +132,7 @@ fn render_right_panel(frame: &mut Frame, state: &AppState, area: Rect) {
        );

    let mut playlist_state = ListState::default();
-    if state.player_state != PlayerState::Stopped && !state.playlist.is_empty() {
+    if !state.playlist.is_empty() {
        playlist_state.select(Some(state.playlist_index));
    }
    frame.render_stateful_widget(playlist_widget, area, &mut playlist_state);
@@ -249,9 +260,15 @@ fn render_status_bar(frame: &mut Frame, state: &AppState, area: Rect) {
        let status_bar = Paragraph::new(search_text)
            .style(Style::default().fg(Theme::foreground()).bg(Theme::background()));
        frame.render_widget(status_bar, area);
+    } else if state.visual_mode {
+        // Show visual mode indicator
+        let visual_text = format!("-- VISUAL -- {} files marked", state.marked_files.len());
+        let status_bar = Paragraph::new(visual_text)
+            .style(Style::default().fg(Theme::foreground()).bg(Theme::background()));
+        frame.render_widget(status_bar, area);
    } else {
-        // Normal mode shortcuts (always shown when not in search mode)
-        let shortcuts = "/: Search • v: Mark • a: Add • c: Clear • Enter: Play • Space: Pause • s: Stop • ←→: Seek • +/-: Vol • n/p: Next/Prev • r: Rescan • q: Quit";
+        // Normal mode shortcuts (always shown when not in search or visual mode)
+        let shortcuts = "/: Search • v: Visual • a: Add • c: Clear • Enter: Play • Space: Pause • s: Stop • ←→: Seek • +/-: Vol • n/p: Next/Prev • r: Rescan • q: Quit";
        let status_bar = Paragraph::new(shortcuts)
            .style(Style::default().fg(Theme::muted_text()).bg(Theme::background()))
            .alignment(Alignment::Center);