Implement Phase 1: Foundation and cache system
- Add Cargo project with TUI and async dependencies - Implement cache-only architecture for low bandwidth operation - Add file scanner with media type detection - Create two-panel TUI layout (file tree and status) - Add config file support for scan path management - Implement XDG-compliant cache and config directories - Add Gitea CI/CD workflow for automated releases
This commit is contained in:
147
CLAUDE.md
Normal file
147
CLAUDE.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user