# CLAUDE.md

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

## Project Overview

AppleVLC is a VLC Media Player skin implementing Apple Human Interface Guidelines (HIG) design principles. It creates a macOS-style interface with superellipse corners, SF Symbols-inspired icons, and Apple color palette.

## Build Commands

```bash
# Generate all PNG assets (buttons, sliders, background)
python3 generate_assets_v3.py

# Package skin as .vlt file (zip archive)
zip -r AppleVLC.vlt theme.xml images/ fonts/

# Install skin to VLC
cp AppleVLC.vlt ~/.local/share/vlc/skins2/

# Test skin with VLC
vlc --intf skins2 --skins2-last ~/.local/share/vlc/skins2/AppleVLC.vlt
```

## Architecture

### File Structure
- `theme.xml` - VLC Skins2 XML definition (layout, controls, bitmaps, fonts)
- `generate_assets_v3.py` - Python/PIL script generating all PNG assets
- `images/` - Generated PNG files with alpha transparency
- `fonts/` - TTF fonts (LiberationSans)
- `AppleVLC.vlt` - Final packaged skin (zip format)

### VLC Skins2 Key Concepts

**Bitmap declarations require `alphacolor`:**
```xml
<Bitmap id="play_up" file="images/play_up.png" alphacolor="#FF00FF"/>
```

**Button states:** Each button needs 3 images: `_up`, `_down`, `_over`

**Checkbox states:** 6 images: `_off_up/down/over` and `_on_up/down/over`

**Window dragging:** Use `action="move"` on background Image

**Text variables:**
- `$N` - Track name
- `$T` / `$D` - Current time / Duration
- `$B` - Audio bitrate (kb/s)
- `$V` - Volume percentage

**VLC Actions:**
- `vlc.play()`, `vlc.pause()`, `vlc.stop()`
- `playlist.previous()`, `playlist.next()`
- `playlist.setRandom(true/false)`, `playlist.setLoop(true/false)`, `playlist.setRepeat(true/false)`

### Design Constants (Apple HIG)

```python
APPLE = {
    'blue': (0, 122, 255, 255),      # Primary action color
    'bg_primary': (242, 242, 247, 255),  # Window background
    'win_close': (255, 95, 87, 255),     # macOS red
    'win_min': (255, 189, 46, 255),      # macOS yellow
    'win_max': (39, 201, 63, 255),       # macOS green
}
```

**Touch targets:** Minimum 44px for all interactive controls

### Workflow

1. Edit `generate_assets_v3.py` to modify icons/colors
2. Run `python3 generate_assets_v3.py` to regenerate PNGs
3. Edit `theme.xml` to modify layout/controls
4. Package with `zip -r AppleVLC.vlt theme.xml images/ fonts/`
5. Test with VLC using skins2 interface