cm-player/CLAUDE.md

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

[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

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:

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