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>
This commit is contained in:
Andrés Eduardo García Márquez
parent
ca28ec51f6
commit
63e7e645dd
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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
|
||||
Loading…
Reference in New Issue