# 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

### Implementation Plan

**Phase 1: Foundation + Cache System (CRITICAL)**
- Create Cargo.toml with dependencies (ratatui, crossterm, libmpv-rs, tokio, serde)
- Set up cache directory structure (XDG_CACHE_HOME/cm-player/)
- Implement cache serialization/deserialization
- File metadata cache schema (path, size, duration, codec, hash)
- Config file parsing (scan paths)
- Basic TUI two-panel layout
- State management with cache integration

**Phase 2: File Scanner with Caching**
- Directory traversal with media filtering (.mp3, .mp4, .mkv, .flac, etc.)
- Write all metadata to cache immediately
- Load from cache on startup (instant)
- Background refresh/validation
- Display cached structure in left panel with tree navigation

**Phase 3: MPV Integration**
- Initialize libmpv
- Playback from cached file paths
- Status display in right panel
- Event handling (position, duration, state)

**Phase 4: Player Controls**
- Keyboard shortcuts (space: pause, q: quit, arrows: navigate/seek, r: rescan)
- Volume control
- Progress bar
- Playlist/queue (cached)

**Phase 5: Polish**
- Error handling
- Bandwidth optimization validation
- CI integration with release workflow

## 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