USB de biblioteca — nombres de carpetas y archivos

Read in English

Cómo organizar el USB de biblioteca para que Library.resolve() (src/core/library.py) realmente encuentre lo que le pongas. Esto no lo valida ninguna herramienta — si te equivocas en un nombre, la pista se trata en silencio como un espacio vacío (sin error, no pasa nada al presionar el pedal). Lee esto antes de editar la biblioteca, no después de que un show salga mal.

Estructura

<raíz del USB>/
├── active_show.txt          -- texto plano, una línea: el nombre de la carpeta del show activo
├── standby.mp4               -- en loop cuando no hay nada reproduciéndose
└── <Nombre del Show>/         -- ej. "Live", una carpeta por show/colección de setlists
    ├── Set 1/
    │   ├── A - nombre de canción.mp3
    │   ├── B - otra canción.mp4
    │   └── C - una tercera.wav
    ├── Set 2/
    │   └── ...
    └── Set N/

active_show.txt: su contenido (sin espacios extra) debe coincidir exactamente con el nombre de una carpeta directamente bajo la raíz del USB. Si apunta a una carpeta que no existe, o está vacío/no se puede leer, se reproduce el standby de respaldo en vez de cualquier contenido real.
Set N/: N es el número de setlist, coincide con el grupo del controlador (ver MAVAVE_ANALYSIS.md para cómo un número de grupo se mapea a N específicamente para el M-VAVE PD41). Los nombres de carpeta se comparan exactamente como Set seguido de dígitos — Set 1, Set 12, no set 1, Set1, ni Set 01.
Archivos de pista: exactamente un archivo por letra, A/B/C (el footswitch D siempre es STOP — nunca necesita archivo). Un espacio vacío (sin archivo para una letra) es normal y esperado, no un error.

La única regla que realmente importa: el patrón del nombre de archivo

<Letra> - <lo que sea>.<extensión>

Exactamente un espacio antes del guion, uno después. La letra debe ir seguida inmediatamente por ` - ` (espacio, guion, espacio), luego cualquier nombre, luego una extensión soportada:

Solo audio (el standby sigue en loop debajo, el audio suena encima): .mp3, .wav
Video con audio embebido: .mp4, .mov, .mpeg, .mpg

Mayúsculas/minúsculas no importan ni en la letra ni en la extensión (a - x.MOV calza perfecto). Lo único que tiene que ser exacto es ese único espacio a cada lado del guion.

Este es el error más fácil de cometer, y falla completamente en silencio — ningún error en ningún lado, el footswitch simplemente no hace nada, porque un nombre de archivo que no calza se ve idéntico a un espacio vacío intencional.

A - mi canción.mp3        <- correcto
A  - mi canción.mp3       <- MAL (dos espacios antes del guion) -- ignorado en silencio
A- mi canción.mp3         <- MAL (sin espacio antes del guion) -- ignorado en silencio
A -mi canción.mp3         <- MAL (sin espacio después del guion) -- ignorado en silencio

La forma más segura de evitarlo: no escribas un nombre de archivo nuevo desde cero. Duplica un archivo de pista que ya funcione (en el mismo Set o en otro) y renombra solo la parte después de ` - , así el - ` en sí nunca se vuelve a teclear.

Si una pista no suena y todo lo demás se ve bien (el archivo sí está ahí, en el Set correcto, con el show correcto activo), renombra el archivo para descartar un problema de espacios antes de asumir que es un problema de códec o de hardware.

Codificación recomendada para video grabado con el celular

Los videos de las carpetas Set se decodifican por hardware (mpv --hwdec=v4l2m2m-copy en la Raspberry Pi 2), que solo soporta H.264. Las apps de cámara —especialmente la del iPhone— vienen configuradas por defecto con ajustes que este hardware no puede tocar en absoluto. Antes de copiar metraje del celular a la biblioteca, re-codifícalo a:

Ajuste	Recomendado	Por qué
Códec de video	H.264 (`libx264`)	El único códec que este hardware decodifica; fila “Video” de `MASTER_SPECIFICATION.md`
Formato de píxel	`yuv420p` (8-bit)	El metraje HEVC/HDR de celular suele ser 10-bit; el decodificador de hardware espera 4:2:0 de 8-bit plano
Resolución	1080p máximo (`scale=-2:1080`)	La resolución objetivo de este proyecto; 4K solo agrega trabajo de decodificación sin ganancia visible en un TV alimentado a 1080p
Bitrate de video	~8-12 Mbps para 1080p	Buena calidad de sobra para un clip corto. Esta no es la situación del video de standby (la salida de `scripts/generate_fallback_standby.sh` y el `standby.mp4` real están codificados mucho más ligero, alrededor de 1.8 Mbps) — el standby está en loop durante todo el show y su tamaño de archivo sí importa; una canción/video individual en el USB de biblioteca no tiene esa restricción, así que no hay razón para escatimarle bitrate también
Códec de audio	AAC, 44.1 u 48kHz, estéreo	`Player` fuerza 48kHz/estéreo en la salida sin importar el origen, así que la fuente solo necesita ser un stream AAC normal, no una tasa de muestreo específica
Contenedor	`.mp4`	Sin importar la extensión original del archivo — un origen `.mov` se codifica bien a salida `.mp4`

ffmpeg -i entrada.mov -c:v libx264 -pix_fmt yuv420p -vf scale=-2:1080 \
       -b:v 10M -c:a aac -b:a 192k -movflags +faststart "A - nombre de canción.mp4"

Si un video se ve bien en un teléfono/computador pero no a través del pedal, revisa su códec (ffmpeg -i <archivo> lo muestra en la línea Video:) antes de sospechar del nombre del archivo, y re-codifica con el comando de arriba — un nombre mal puesto y un códec incompatible pueden ser ambos ciertos en el mismo archivo a la vez, así que arreglar uno no garantiza que el otro no siga siendo un problema.