From 63e7e645dd313b4521a47f1615be63ce3c1e525d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A9s=20Eduardo=20Garc=C3=ADa=20M=C3=A1rquez?=
 <andresgarcia0313@gmail.com>
Date: Sun, 11 Jan 2026 19:49:36 -0500
Subject: [PATCH] docs: Add project documentation

- README.md: Project overview, features, installation guide
- DEVELOPMENT.md: Lessons learned, common errors to avoid,
  VLC Skins2 reference, and development checklist
- CLAUDE.md: Project-specific Claude Code instructions

Key documented issues:
- Invalid XML attributes (action on Video, var on Playtree)
- Non-existent actions (dialogs.equalizer, vlc.setLoop)
- Shadow rendering problems in VLC Skins2
- Margin calculations for element positioning

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 CLAUDE.md      |  78 +++++++++++++++++++
 DEVELOPMENT.md | 205 +++++++++++++++++++++++++++++++++++++++++++++++++
 README.md      |  83 ++++++++++++++++++++
 3 files changed, 366 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 DEVELOPMENT.md
 create mode 100644 README.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..01211ef
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,78 @@
+# 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
diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
new file mode 100644
index 0000000..3cbb4d6
--- /dev/null
+++ b/DEVELOPMENT.md
@@ -0,0 +1,205 @@
+# Guía de Desarrollo - AppleVLC Skin
+
+## Lecciones Aprendidas y Errores a Evitar
+
+### 1. Validación XML Estricta
+
+VLC Skins2 usa un DTD estricto. **SIEMPRE** verificar que los atributos sean válidos.
+
+#### Atributos NO válidos encontrados:
+```xml
+<!-- INCORRECTO - "action" no existe en Video -->
+<Video id="videoArea" action="dialogs.popup()"/>
+
+<!-- INCORRECTO - "var" y "action" no existen en Playtree -->
+<Playtree id="playtree" var="playlist" action="dialogs.playlist()"/>
+```
+
+#### Corrección:
+```xml
+<!-- CORRECTO -->
+<Video id="videoArea" autoresize="false"/>
+<Playtree id="playtree" flat="false"/>
+```
+
+### 2. Acciones Válidas en VLC Skins2
+
+#### Acciones que SÍ funcionan:
+```
+vlc.play()          vlc.pause()         vlc.stop()
+vlc.quit()          vlc.minimize()      vlc.fullscreen()
+vlc.mute()          vlc.volumeUp()      vlc.volumeDown()
+
+playlist.next()     playlist.previous()
+playlist.setRandom(true/false)
+playlist.setLoop(true/false)
+playlist.setRepeat(true/false)
+
+dialogs.popup()     # Menú contextual
+windowName.show()   windowName.hide()
+```
+
+#### Acciones que NO funcionan:
+```
+dialogs.equalizer()    # NO EXISTE
+dialogs.extended()     # NO EXISTE
+dialogs.playlist()     # NO EXISTE
+vlc.setLoop()          # NO EXISTE (usar playlist.setLoop)
+```
+
+### 3. Márgenes y Posicionamiento
+
+#### Problema encontrado:
+Elementos aparecían cortados o fuera del fondo.
+
+#### Solución:
+- **Siempre** dejar mínimo 20px de margen en todos los bordes
+- Calcular posiciones desde el margen, no desde 0
+- Fórmula: `elemento_x = margen + offset_deseado`
+
+```xml
+<!-- Ventana 500x225 con márgenes de ~25px -->
+<Layout width="500" height="225">
+  <!-- Elementos empiezan en x=24-30, no en x=0 -->
+  <Button id="closeBtn" x="24" y="24"/>
+</Layout>
+```
+
+### 4. Sombras en VLC Skins
+
+#### Problema:
+Las sombras difusas NO funcionan correctamente en VLC Skins2. Aparecen como bordes negros sólidos en lugar de sombras suaves.
+
+#### Solución:
+- **NO usar sombras** en los assets PNG
+- Usar bordes sutiles con alpha bajo: `rgba(0,0,0,0.08)`
+- El fondo debe ser limpio sin efectos de sombra
+
+```python
+# INCORRECTO - sombra que no funciona
+shadow = img.filter(ImageFilter.GaussianBlur(10))
+
+# CORRECTO - borde sutil
+draw.rounded_rectangle([0,0,w-1,h-1], radius=20,
+                       outline=(0,0,0,20), width=1)
+```
+
+### 5. Checkbox vs Button para Estados
+
+#### Usar Checkbox cuando:
+- El control tiene dos estados persistentes (on/off)
+- Ejemplos: Shuffle, Repeat, Mute
+
+```xml
+<Checkbox id="shuffleBtn"
+  up1="shuffle_off_up" down1="shuffle_off_down" over1="shuffle_off_over"
+  up2="shuffle_on_up" down2="shuffle_on_down" over2="shuffle_on_over"
+  action1="playlist.setRandom(true)" action2="playlist.setRandom(false)"
+  state="playlist.isRandom"/>
+```
+
+#### Usar Button cuando:
+- Es una acción momentánea
+- Ejemplos: Play, Stop, Next, Previous
+
+### 6. Variables de Texto VLC
+
+```
+$N - Nombre del track (título)
+$T - Tiempo actual (0:00:00)
+$D - Duración total
+$B - Bitrate (kb/s)
+$S - Sample rate (kHz)
+$V - Volumen (%)
+$F - Nombre del archivo
+$P - Posición (%)
+```
+
+### 7. Visibilidad Condicional
+
+```xml
+<!-- Mostrar Play cuando NO está reproduciendo -->
+<Button id="playBtn" visible="not vlc.isPlaying"/>
+
+<!-- Mostrar Pause cuando SÍ está reproduciendo -->
+<Button id="pauseBtn" visible="vlc.isPlaying"/>
+
+<!-- Volumen normal vs Mute -->
+<Button id="volumeBtn" visible="not vlc.isMute"/>
+<Button id="muteBtn" visible="vlc.isMute"/>
+```
+
+### 8. Estructura de Slider
+
+```xml
+<!-- Track de fondo (imagen estática) -->
+<Image id="sliderBg" x="30" y="70" image="slider_track"/>
+
+<!-- Slider interactivo (encima del track) -->
+<Slider id="timeSlider" x="30" y="63"
+  up="slider_knob_up" down="slider_knob_down" over="slider_knob_over"
+  points="(0,10),(440,10)" thickness="20"
+  value="time"/>
+```
+
+- `points`: Define inicio y fin del recorrido del knob
+- `thickness`: Área clickeable vertical
+- El knob debe posicionarse ~7px arriba del track para centrado visual
+
+### 9. Generación de Assets PNG
+
+#### Requisitos:
+- Canal alpha real (RGBA)
+- `alphacolor="#FF00FF"` en theme.xml para compatibilidad
+- Tamaño exacto según uso (44x44 para botones, etc.)
+
+```python
+# Crear imagen con alpha
+img = Image.new('RGBA', (44, 44), (0, 0, 0, 0))
+
+# Guardar con alpha
+img.save('button.png', 'PNG')
+```
+
+### 10. Empaquetado del Skin
+
+```bash
+# El .vlt es simplemente un ZIP
+zip -r AppleVLC.vlt theme.xml images/ fonts/
+
+# Verificar contenido
+unzip -l AppleVLC.vlt
+```
+
+### 11. Testing y Debugging
+
+```bash
+# Ejecutar VLC con skin específica
+vlc -I skins2 --skins2-last /ruta/AppleVLC.vlt
+
+# Ver errores en terminal
+vlc -I skins2 --skins2-last /ruta/AppleVLC.vlt 2>&1 | grep -E "(error|warning)"
+
+# Forzar cierre si se cuelga
+pkill -9 vlc
+```
+
+### 12. Referencia DTD
+
+El DTD oficial está en:
+`http://www.videolan.org/vlc/skins2-0.dtd`
+
+Elementos principales válidos:
+- Theme, ThemeInfo, Bitmap, Font, Window, Layout
+- Button, Checkbox, Image, Text, Slider, Video, Playtree
+
+## Checklist Pre-Release
+
+- [ ] Verificar que theme.xml valida contra el DTD
+- [ ] Probar todos los botones y controles
+- [ ] Verificar que no hay elementos cortados
+- [ ] Probar con audio y video
+- [ ] Verificar estados hover/down en todos los botones
+- [ ] Probar shuffle, repeat, repeat one
+- [ ] Verificar slider de tiempo y volumen
+- [ ] Probar minimizar y cerrar ventana
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b74013d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,83 @@
+# AppleVLC - VLC Media Player Skin
+
+Skin moderna para VLC Media Player inspirada en Apple Human Interface Guidelines.
+
+## Características
+
+- **Diseño limpio**: Fondo con esquinas redondeadas (superelipse/squircle) estilo Apple
+- **Controles intuitivos**: Botones de 44px siguiendo las guías de Apple para touch targets
+- **Información completa**: Título, tiempo, bitrate y sample rate visibles
+- **Controles de ventana**: Solo cerrar y minimizar (sin maximizar, al estilo macOS)
+- **Estados visuales**: Hover con tinte azul Apple (#007AFF), estados disabled
+- **Iconos secundarios**: Color gris sistema (#8E8E93) para jerarquía visual
+
+## Controles Disponibles
+
+### Fila Principal
+- Stop, Playlist, Shuffle, Previous, Play/Pause, Next, Repeat All, Repeat One, Fullscreen
+
+### Fila Inferior
+- Volume (con slider), Equalizer, A-B Loop, Speed
+
+### Ventanas Adicionales
+- Video Window (640x480, redimensionable)
+- Playlist Window (320x400)
+- Fullscreen Controller
+
+## Instalación
+
+1. Copiar `AppleVLC.vlt` a `~/.local/share/vlc/skins2/`
+2. En VLC: Herramientas → Preferencias → Interfaz → Usar skin personalizado
+3. Seleccionar AppleVLC.vlt
+4. Reiniciar VLC
+
+O ejecutar directamente:
+```bash
+vlc -I skins2 --skins2-last /ruta/a/AppleVLC.vlt
+```
+
+## Estructura del Proyecto
+
+```
+PielVLC/
+├── AppleVLC.vlt          # Skin empaquetada (ZIP)
+├── theme.xml             # Definición de la interfaz
+├── generate_assets_v3.py # Script para generar PNGs
+├── images/               # Assets PNG generados
+├── fonts/                # Fuentes Liberation Sans
+└── DEVELOPMENT.md        # Guía de desarrollo
+```
+
+## Especificaciones Técnicas
+
+- **Dimensiones**: 500x225 px (ventana principal)
+- **Márgenes**: 20-30px en todos los bordes
+- **Track slider**: 8px de altura, 440px de ancho
+- **Volume slider**: 6px de altura, 80px de ancho
+- **Colores**:
+  - Fondo: #F5F5F7 (Apple Light Gray)
+  - Texto primario: #000000
+  - Texto secundario: #3C3C43
+  - Iconos secundarios: #8E8E93
+  - Acento: #007AFF (Apple Blue)
+  - Borde sutil: rgba(0,0,0,0.08)
+
+## Regenerar Assets
+
+```bash
+python3 generate_assets_v3.py
+zip -r AppleVLC.vlt theme.xml images/ fonts/
+```
+
+## Requisitos
+
+- VLC 3.0+ con soporte skins2
+- Python 3 + Pillow (solo para regenerar assets)
+
+## Autor
+
+Claude Code - Anthropic
+
+## Licencia
+
+MIT License