Christoffer Martinsson
e44c9e5bba
- Replace implementation plan with feature documentation - Document all keybindings - Add technical details about MPV IPC - List UI layout structure - Mark all phases as complete
148 lines
4.4 KiB
Markdown
148 lines
4.4 KiB
Markdown
# CM Player - Music and Video TUI
|
|
|
|
## Overview
|
|
|
|
A high-performance Rust-based TUI player for playing music and video files. Built to use mpv.
|
|
|
|
## Key features
|
|
|
|
- Scan and cache file structure
|
|
- Made for use on low bandwidh vpn connections
|
|
- Use same TUI layout/theme as cm-dashboard
|
|
- Left panel is file structure
|
|
- Right panel is media status
|
|
|
|
## Architecture
|
|
|
|
### Cache-Only Operation
|
|
|
|
**CRITICAL:** Left panel shows ONLY cached data. Never browse filesystem directly during operation.
|
|
|
|
**Configuration:** `~/.config/cm-player/config.toml`
|
|
```toml
|
|
[scan_paths]
|
|
paths = [
|
|
"/media/music",
|
|
"/media/videos"
|
|
]
|
|
```
|
|
|
|
**Cache Structure:** `~/.cache/cm-player/`
|
|
- `file_tree.json` - Full cached file structure
|
|
- `metadata.json` - File metadata (duration, codec, size)
|
|
|
|
**Workflow:**
|
|
1. User configures paths in config.toml
|
|
2. Scanner scans configured paths → builds cache
|
|
3. Left panel displays cached tree (instant, no filesystem access)
|
|
4. Playback uses cached file paths
|
|
5. Rescan command/keybinding to refresh cache
|
|
|
|
## Features
|
|
|
|
### Core Functionality
|
|
- **Cache-Only Operation** - Browse media from cached file structure, no direct filesystem access
|
|
- **MPV Integration** - Playback via MPV IPC (subprocess), no library linking required
|
|
- **Playlist Management** - Play single files, entire directories, or marked files
|
|
- **File Marking** - Mark multiple files to create custom playlists
|
|
- **Tree Navigation** - Vim-style keybindings for browsing collapsible directory structure
|
|
- **Manual Library Refresh** - User-controlled scanning with 'r' key
|
|
|
|
### UI Layout (cm-dashboard style)
|
|
- **Title Bar** - Shows player state (Playing/Paused/Stopped/Refreshing)
|
|
- **Left Panel** - Cached media file tree with vim navigation
|
|
- **Right Panel** - Player info (progress, volume) + Playlist view
|
|
- **Status Bar** - Centered help text with all keybindings
|
|
|
|
### Keybindings
|
|
- `j/k` or `↑↓` - Navigate files
|
|
- `h/l` - Collapse/expand directories
|
|
- `t` - Mark/unmark file
|
|
- `c` - Clear all marks
|
|
- `Enter` - Play (priority: marked files > directory > single file)
|
|
- `Space` - Pause/resume
|
|
- `← →` - Seek backward/forward 10 seconds
|
|
- `+ -` - Volume up/down by 5%
|
|
- `n/p` - Next/previous track in playlist
|
|
- `r` - Rescan library (manual refresh)
|
|
- `q` - Quit
|
|
|
|
### Technical Details
|
|
- **MPV IPC** - Communicates with mpv via Unix socket and JSON protocol
|
|
- **No Version Lock** - Uses mpv binary, not libmpv library (avoids version mismatch)
|
|
- **Logging** - Redirected to `/tmp/cm-player.log` to avoid TUI interference
|
|
- **Auto-advance** - Automatically plays next track when current ends
|
|
|
|
## Automated Binary Release System
|
|
|
|
CM Player uses automated binary releases instead of source builds.
|
|
|
|
### Creating New Releases
|
|
|
|
```bash
|
|
cd ~/projects/cm-player
|
|
git tag v0.1.X
|
|
git push origin v0.1.X
|
|
```
|
|
|
|
This automatically:
|
|
|
|
- Builds static binaries with `RUSTFLAGS="-C target-feature=+crt-static"`
|
|
- Creates GitHub-style release with tarball
|
|
- Uploads binaries via Gitea API
|
|
|
|
### NixOS Configuration Updates
|
|
|
|
Edit `~/projects/nixosbox/hosts/services/cm-player.nix`:
|
|
|
|
```nix
|
|
version = "v0.1.X";
|
|
src = pkgs.fetchurl {
|
|
url = "https://gitea.cmtec.se/cm/cm-player/releases/download/${version}/cm-player-linux-x86_64.tar.gz";
|
|
sha256 = "sha256-NEW_HASH_HERE";
|
|
};
|
|
```
|
|
|
|
## Important Communication Guidelines
|
|
|
|
Keep responses concise and focused. Avoid extensive implementation summaries unless requested.
|
|
|
|
## Commit Message Guidelines
|
|
|
|
**NEVER mention:**
|
|
|
|
- Claude or any AI assistant names
|
|
- Automation or AI-generated content
|
|
- Any reference to automated code generation
|
|
|
|
**ALWAYS:**
|
|
|
|
- Focus purely on technical changes and their purpose
|
|
- Use standard software development commit message format
|
|
- Describe what was changed and why, not how it was created
|
|
- Write from the perspective of a human developer
|
|
|
|
**Examples:**
|
|
|
|
- ❌ "Generated with Claude Code"
|
|
- ❌ "AI-assisted implementation"
|
|
- ❌ "Automated refactoring"
|
|
- ✅ "Implement maintenance mode for backup operations"
|
|
- ✅ "Restructure storage widget with improved layout"
|
|
- ✅ "Update CPU thresholds to production values"
|
|
|
|
## Implementation Rules
|
|
|
|
**NEVER:**
|
|
|
|
- Copy/paste ANY code from legacy implementations
|
|
- Create files unless absolutely necessary for achieving goals
|
|
- Create documentation files unless explicitly requested
|
|
|
|
**ALWAYS:**
|
|
|
|
- Prefer editing existing files to creating new ones
|
|
- Follow existing code conventions and patterns
|
|
- Use existing libraries and utilities
|
|
- Follow security best practices
|