Programe pantallas desde una hoja de cálculo

De la hoja a las pantallas

1. Parta de la plantilla. Guarde la plantilla como CSV o XLSX, o use su propia hoja con las mismas columnas.
2. Complete una fila por cada línea de programación. Indique la pantalla (o una carpeta o una etiqueta), el archivo, el inicio y el fin.
3. Impórtelo. Suelte el archivo en el diálogo Importar de la pestaña Programación del dashboard, o ejecute screenrig schedule import FILE.
4. Corrija las filas con errores. Cada error nombra la fila, la columna y un código. Edite la celda en el diálogo, o edite la hoja e impórtela de nuevo.
5. Revise la vista previa. Lista los niveles que crea la hoja, los que cambia o elimina y el calendario de las pantallas que toca.
6. Publique. Todas las filas se aplican juntas o ninguna.

Los pasos 1 a 5 no escriben nada. Una pantalla necesita una zona horaria (screen set-timezone) y una lista de reproducción predeterminada (screen assign) antes de que una fila pueda programarla, y un archivo debe ser una imagen o un video aprobado.

La hoja

La primera fila nombra las columnas. Cada fila siguiente es una línea de programación. Las filas en blanco se omiten. Una hoja es un archivo CSV (UTF-8, separado por comas o punto y coma) o un libro XLSX, y un libro XLSX se lee desde su primera hoja.

Los encabezados coinciden sin distinguir mayúsculas, espacios ni signos de puntuación. Una columna que nada lee se ignora, y la vista previa la lista. Una fila necesita un target, un content y al menos uno de start, end, days o una ventana diaria.

Screen,File,Start,End,Timezone,Days,Daily start,Daily end,Priority,Name
LOBBY-01,welcome-spring.jpg,2026-11-05 18:00,2026-11-08 02:00,America/Los_Angeles,,,,0,
folder:Casino Floor,happy-hour.mp4,2026-11-05,2026-11-30,,Mon-Fri,16:00,19:00,5,Happy hour
tag:elevators,playlist:Holiday loop,2026-12-01 09:00,2026-12-26,,,,,0,

• La fila 2 reproduce welcome-spring.jpg en la pantalla con el código LOBBY-01 desde las 6 PM del 5 de noviembre hasta las 2 AM del 8 de noviembre, hora del Pacífico.
• La fila 3 reproduce happy-hour.mp4 en todas las pantallas de la carpeta Casino Floor y en las carpetas que contiene, de 4 PM a 7 PM en días laborables, del 5 de noviembre hasta el final del 30 de noviembre.
• La fila 4 reproduce la lista de reproducción Holiday loop en todas las pantallas con la etiqueta elevators, desde las 9 AM del 1 de diciembre hasta el final del 25 de diciembre.

Destinos

Un destino es uno de estos:

• Una pantalla. Un id de pantalla, el valor de cualquier campo de la pantalla (un código de sala, un número de tienda) o el nombre de la pantalla. --code-field o code_field limita la coincidencia a un campo, como code o room_id.
• Una carpeta. folder:NAME o folder:Parent/Child. Alcanza la carpeta y todas las carpetas que contiene.
• Una etiqueta. tag:NAME alcanza todas las pantallas con la etiqueta.

Varios destinos en una celda se separan con ; o |, como en LOBBY-01;LOBBY-02|tag:elevators.

Contenido

• Un archivo. El nombre de un archivo multimedia del proyecto, o el nombre original de un archivo convertido cargado. El archivo se reproduce a pantalla completa. La primera confirmación que usa un archivo crea la lista de reproducción de un solo archivo Scheduled: FILE, y las importaciones posteriores la reutilizan.
• Una lista de reproducción. playlist:NAME o un id de lista de reproducción. La lista de reproducción tiene una versión aprobada y no es una plantilla.

Horas

• Fechas y horas. Se leen 2026-11-05 18:00, 2026-11-05T18:00, 11/5/2026 6:00 PM y las celdas de fecha de la hoja de cálculo. Una hora con desfase, como Z o +02:00, se rechaza.
• El reloj propio de cada pantalla. Las horas se leen en el reloj de las pantallas que alcanza la fila, de modo que 18:00 son las 6 PM donde esté la pantalla.
• Otra zona. Una celda timezone (o el timezone de la solicitud) indica que la fila está escrita en esa zona. Las horas se convierten a la zona de las pantallas cuando todas las pantallas de la fila comparten una zona. Una fila que alcanza pantallas de varias zonas deja timezone vacío y lee el reloj propio de cada pantalla.
• Una fecha sola como fin cierra ese día: 2026-11-30 termina al final del 30 de noviembre. Una fecha sola como inicio comienza a la medianoche.
• Sin fin mantiene la fila en reproducción hasta que una importación posterior la elimine. La vista previa avisa con open_end.
• Días. Mon-Fri, Mon,Wed,Fri, Sat,Sun, weekdays, weekends o daily. Una fila con days y sin ventana diaria se reproduce todo el día en esos días.
• Una ventana diaria. daily start y daily end dan las horas de cada día, como 16:00 y 19:00 o 4:00 PM y 7:00 PM. Indique ambas. Un fin igual o anterior al inicio cruza la medianoche y pertenece al día en que empieza. Sin days, la ventana se aplica todos los días.

Vista previa y errores

La vista previa verifica cada fila y cada celda antes de escribir nada. Una fila con un error se muestra con sus celdas, y cada error nombra la columna, un código y qué cambiar.

Dos advertencias no detienen una importación. open_end marca una fila sin fin. outranked marca una fila que un nivel compartido (una fila para varias pantallas, una carpeta o una etiqueta) reproduce por encima en una pantalla.

Una hoja sin filas, un archivo que no es UTF-8, más de 5,000 filas, un archivo de más de 8 MiB, o una confirmación que escribiría más de 400 programaciones propias de pantallas se rechaza con el motivo.

Niveles

Las filas que coinciden en contenido, horas, prioridad, nombre y pantalla forman un nivel. El destino no forma parte de la comparación, así que diez filas que reproducen el mismo archivo a las mismas horas en diez pantallas forman un solo nivel.

• Una pantalla crea una entrada en la programación propia de esa pantalla.
• Varias pantallas, una carpeta o una etiqueta crean un nivel compartido, una campaña sobre esa audiencia. Un nivel compartido prevalece sobre los niveles propios de una pantalla.

Agrupar convierte las 200 pantallas de un local en una sola campaña y no en 200 entradas, y una corrección en la hoja cambia un solo nivel. La columna name nombra un nivel compartido. Sin ella, se llama como la importación, el contenido y el destino, como en Spring promos: happy-hour.mp4 on Casino Floor.

Importar de nuevo

El name de una importación la identifica, y el valor predeterminado es import. Al importar de nuevo con el mismo nombre:

• actualiza los niveles que creó, incluso cuando cambiaron las fechas de una fila;
• agrega los niveles de las filas nuevas;
• elimina los niveles cuyas filas ya no están en la hoja;
• no cambia nada cuando la hoja es la misma.

Los niveles creados por una importación la llevan en su id (las entradas de una pantalla empiezan con imp_) y las campañas llevan una marca import. Los niveles creados a mano nunca se tocan. Use un nombre para cada hoja, y uno distinto para otra.

Ejecutar una importación

Panel

Abra la pestaña Programación de un proyecto y elija Importar. Suelte un archivo CSV o XLSX. El diálogo muestra una tabla de las filas con cada error junto a su celda, y usted edita la celda en el lugar. Luego muestra el calendario compuesto de las pantallas que cambia la importación. Publicar la confirma.

Línea de comandos

screenrig schedule template --output schedule.csv
screenrig schedule import schedule.csv --name "Spring promos" --timezone America/Los_Angeles
screenrig schedule import schedule.csv --name "Spring promos" --timezone America/Los_Angeles --commit

schedule import muestra una vista previa y no escribe nada. --commit aplica la hoja cuando todas las filas son válidas.

El comando termina con 0 para una hoja válida, 8 cuando hay filas con errores (no se escribe nada) y 5 cuando el proyecto cambió desde la vista previa (ejecútelo de nuevo). FILE es un archivo .csv, .xlsx o .json, o - para la entrada estándar. Un archivo JSON contiene un arreglo de objetos de fila, o {"rows": [...]}, con los nombres de columna como claves.

API

Envíe la hoja como filas JSON, o como cuerpo CSV o XLSX con los ajustes como parámetros de consulta. La vista previa requiere acceso de lectura. La confirmación requiere una credencial con acceso de escritura, que otorga una persona que pueda aprobar en el dashboard.

curl -s https://api.screenrig.ai/api/schedule/imports/preview \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Spring promos",
    "timezone": "America/Los_Angeles",
    "rows": [
      {"target": "LOBBY-01", "content": "welcome-spring.jpg", "start": "2026-11-05 18:00", "end": "2026-11-08 02:00"},
      {"target": "folder:Casino Floor", "content": "happy-hour.mp4", "start": "2026-11-05", "end": "2026-11-30",
       "days": "Mon-Fri", "daily_start": "16:00", "daily_end": "19:00", "priority": 5, "name": "Happy hour"}
    ]
  }'

La misma hoja como archivo:

curl -s "https://api.screenrig.ai/api/schedule/imports/preview?name=Spring%20promos&timezone=America/Los_Angeles" \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Content-Type: text/csv" \
  --data-binary @schedule.csv

La respuesta, abreviada:

{
  "name": "Spring promos",
  "valid": false,
  "fingerprint": "FINGERPRINT",
  "columns": ["target", "content", "start", "end", "days", "daily_start", "daily_end", "priority", "name"],
  "summary": {"rows": 2, "rows_with_errors": 1, "levels": 1, "creates": 1, "updates": 0,
              "unchanged": 0, "removes": 0, "screens": 1, "playlists": 1},
  "rows": [
    {"row": 2, "status": "ok", "level": "LEVEL_KEY"},
    {"row": 3, "status": "error",
     "errors": [{"column": "content", "code": "unknown_file",
                 "message": "No file or playlist is named \"happy-hour.mp4\"."}]}
  ],
  "levels": [{"key": "LEVEL_KEY", "action": "create", "home": "screen", "screen_id": "scr_LOBBY",
              "content": {"kind": "file", "id": "med_WELCOME", "name": "welcome-spring.jpg"},
              "screens": 1, "priority": 0, "from": "2026-11-05T18:00", "until": "2026-11-08T02:00", "rows": [2]}],
  "removals": []
}

rows[].cells devuelve las celdas de cada fila tal como las dio la hoja, de modo que un cliente las corrige y envía las filas de nuevo. valid es true cuando ninguna fila tiene un error. calendar tiene la forma de GET /api/schedule/calendar y muestra las pantallas que la importación cambia, tal como quedarían después de una confirmación.

La confirmación envía la misma hoja y el fingerprint de su vista previa, como miembro del cuerpo JSON o como parámetro de consulta con un archivo. Envíe un Idempotency-Key para reintentar de forma segura.

curl -s https://api.screenrig.ai/api/schedule/imports \
  --header "Authorization: Bearer $SCREENRIG_TOKEN" \
  --header "Idempotency-Key: spring-promos-1" \
  --header "Content-Type: application/json" \
  --data @commit.json

La respuesta contiene el preview y el applied, los recuentos de lo creado, actualizado, sin cambios y eliminado, con las pantallas escritas y las listas de reproducción creadas. Una confirmación se rechaza, y no escribe nada, como:

GET /api/schedule/imports/template?format=csv y format=xlsx responden a la plantilla.

Límites

• 5,000 filas y 8 MiB por hoja.
• 32 niveles propios por pantalla. Una organización admite hasta 100 campañas en todos sus proyectos, y cada nivel compartido es una.
• 400 programaciones propias de pantallas escritas por confirmación. Una fila de carpeta o de etiqueta alcanza cualquier número de pantallas.
• El nombre de una importación tiene de 1 a 80 caracteres.

Relacionado

• CLI de señalización: programaciones, toma de control y campañas para una pantalla o una flota.
• Referencia de la API: las rutas /api/schedule/imports y sus problemas.
• Autenticación: acceso Solo lectura, Proponer y Administrar.