play/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Video Player with Remote Control - A desktop video player built with Nuxt 4 and Tauri 2 that supports WebSocket-based remote control. The application automatically searches for and plays video.mp4 files from multiple locations and provides a fullscreen video experience with remote control capabilities.

Architecture

Tech Stack

• Frontend: Nuxt 4 (Vue 3) with TypeScript
• Backend: Rust with Tauri 2 framework
• UI Framework: NuxtUI v3 with TailwindCSS v4
• Communication: WebSocket server (port 6666) for remote control
• Package Manager: pnpm (enforced)

Key Components

Frontend (app/)

• Main Page: app/pages/index.vue - Fullscreen video player with connection status
• Tauri Module: app/modules/tauri.ts - Auto-imports Tauri APIs
• Assets: app/assets/ - CSS and icons
• Layouts: app/layouts/ - Application layouts
• Components: app/components/ - Reusable UI components

Backend (src-tauri/)

• Main Entry: src-tauri/src/main.rs - Application bootstrap
• Library: src-tauri/src/lib.rs - Tauri application setup and state management
• WebSocket Server: src-tauri/src/websocket_server.rs - Remote control server on port 6666
• Player State: src-tauri/src/player_state.rs - Video playback state management
• Commands: src-tauri/src/commands.rs - Tauri commands for frontend interaction
• Permissions: src-tauri/capabilities/main.json - Tauri v2 permission configuration

Communication Flow

1. Backend-to-Frontend: Tauri events (player-command, connection-status)
2. Frontend-to-Backend: Tauri commands (get_player_state, load_video, etc.)
3. Remote Control: WebSocket server accepts JSON commands for playback control
4. Auto-discovery: Backend searches for video.mp4 in multiple directories on startup

Development Commands

Setup & Installation

# Install dependencies (requires Node.js 23+)
pnpm install

# Verify Rust toolchain is installed for Tauri
rustc --version  # Should be >= 1.70
cargo --version

Development

# Start development server with Tauri
pnpm tauri:dev

# Frontend only (port 3000)
pnpm dev

# Lint and fix code
pnpm lint

Build & Distribution

# Build production application
pnpm tauri:build

# Build with debug symbols
pnpm tauri:build:debug

# Generate static site only
pnpm generate

# Version bump
pnpm bump

Testing WebSocket Control

# Test WebSocket connection (requires Node.js)
node test_websocket.js

Key Features

Video Playback

• Auto-loading: Searches for video.mp4 in current directory, public folder, and executable path
• Fullscreen: Auto-fullscreen mode configurable via app.config.ts
• Controls: Play/pause, seek, volume, loop, fullscreen toggle
• Format Support: MP4 with fallback handling

Remote Control

• WebSocket Server: Runs on port 6666
• JSON Protocol: Standardized message format for all commands
• Connection Status: Real-time connection indicator in UI
• Playlist Support: Load and play from video playlists

State Management

• PlayerState: Comprehensive video state including position, volume, loop status
• VideoInfo: Metadata tracking for loaded videos
• Real-time Sync: Frontend/backend state synchronization via Tauri events

Configuration Files

Application Config

• app.config.ts - Player settings (volume, fullscreen, etc.)
• player_config.json - Runtime configuration
• nuxt.config.ts - Nuxt and Tauri integration settings

Build Configuration

• src-tauri/tauri.conf.json - Tauri application settings
• src-tauri/Cargo.toml - Rust dependencies and features
• package.json - Node.js dependencies and scripts

Important Notes

Permissions

• Tauri v2 uses capabilities-based permissions in src-tauri/capabilities/main.json
• Required permissions: file system access, notifications, OS info, shell commands
• WebSocket server runs on port 6666 (configurable in src-tauri/src/lib.rs)

Development Gotchas

• SSR Disabled: ssr: false in nuxt.config.ts is required for Tauri
• Asset URLs: Uses asset://localhost/ protocol for local file access
• Auto-fullscreen: Configurable but may be disabled in some environments
• Video Discovery: Searches up to 6 directory levels up from executable

File Structure

video-player/
├── app/                    # Nuxt frontend
│   ├── pages/index.vue    # Main video player
│   ├── modules/tauri.ts   # Tauri API auto-imports
│   └── assets/            # Static assets
├── src-tauri/             # Rust backend
│   ├── src/
│   │   ├── lib.rs         # Main Tauri app
│   │   ├── websocket_server.rs  # Remote control
│   │   └── player_state.rs      # Video state
│   └── capabilities/      # Tauri permissions
├── public/                # Static files (video.mp4)
└── types/                 # TypeScript definitions

Environment Requirements

• Node.js: >= 23.0.0
• Rust: >= 1.70.0
• pnpm: >= 10.13.1 (enforced)
• Platform: Windows, macOS, or Linux with Tauri prerequisites

Common Development Tasks

Adding New Tauri Commands

1. Add command function in src-tauri/src/commands.rs
2. Register command in src-tauri/src/lib.rs invoke_handler
3. Add TypeScript bindings in frontend
4. Update capabilities if new permissions needed

WebSocket Protocol

• Connect: ws://localhost:6666
• Commands: JSON format {"type":"command","data":{"type":"play"}}
• Status: Real-time updates after each command
• Playlist: Support for multiple video files