Elija la ruta de creación correcta

Ver cómo se construye

Película / Crear una aplicación de kiosco con el SDK

3:07

Use screenrig después de configurar la sesión en Inicio.

Elija la ruta del contenido

La generación compone el arte y la tipografía juntos, así que ponga todo el texto en el aviso. Las tarjetas dibujan su texto en el Player, por lo que una palabra o un número que cambia no necesita una nueva imagen fija. Los recursos terminados que se suministran no necesitan generación. La animación por sí sola no requiere ninguna de las dos.

Generar una imagen fija terminada

El agente envía un aviso más aspect_ratio y quality. screenRIG devuelve un objeto multimedia med_… en la tienda de medios de la cuenta. El llamante no vuelve a subir los bytes. Obtenga los bytes originales solo para inspeccionar; de lo contrario, mantenga la referencia med_… en una lista de reproducción.

Su propio media upload sigue siendo válido. No genere cuando ya tenga el archivo. Las páginas de video en vivo, transmisión, iframe y app web son primitivas de lista de reproducción, no imágenes fijas generadas.

La calidad es low, medium, o high (por defecto medium). La relación de aspecto es 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, o 2:3 (por defecto 16:9). --quality cambia el nivel de detalle de la imagen fija y por lo tanto cuántos tokens usa:

media generate --prompt TEXT [--aspect-ratio RATIO] [--quality QUALITY] [--tag TAG]

screenrig media generate --prompt "A 16:9 restaurant menu poster for North Lobby Cafe. Dark walnut, gold type. Title NORTH LOBBY CAFE. Items: Espresso $4, Cortado $4.50, House Blend $3. Footer Open 7am to 7pm. Typeset every line of copy in the image." --aspect-ratio 16:9 --quality high --tag LobbyMenu

El sobre informa un id med_…. Nunca imprime bytes de imagen.

{
  "ok": true,
  "data": {
    "id": "med_01EXAMPLEGENERATED0000000",
    "media_id": "med_01EXAMPLEGENERATED0000000"
  }
}

Agregar una banda sonora

Una lista de reproducción puede llevar una banda sonora: una lista ordenada de pistas MP3 que se reproduce continuamente mientras cambian las páginas. Las transiciones de página nunca detienen, reinician ni funden la música. La banda sonora es una configuración de lista de reproducción, no un séptimo primitivo, por lo que no tiene rectángulo ni capa en el lienzo.

Suba cada pista con media upload. Los archivos MP3 se suben tal cual; los archivos WAV, AAC, M4A, OGG y FLAC se transcodifican primero a MP3. Cada pista se convierte en un objeto multimedia audio con un id med_… y una duración.

screenrig media upload ./intro.mp3 --tag LobbyMusic
screenrig media upload ./bed.wav --tag LobbyMusic

Nombre las pistas en la lista de reproducción audio miembro; contiene de 1 a 128 pistas. Las pistas se reproducen en orden, una tras otra. loop (por defecto true) vuelve a empezar en la primera pista después de la última; volume (por defecto 1, de 0 a 1) escala el volumen propio del Player.

{
  "name": "Lobby",
  "audio": {
    "tracks": [
      { "id": "intro", "media_id": "med_01EXAMPLEINTRO000000000" },
      { "id": "bed", "media_id": "med_01EXAMPLEBED00000000000" }
    ],
    "loop": true,
    "volume": 0.8
  },
  "pages": [
    { "id": "welcome", "audio_cue": { "track": "intro", "restart": true } },
    { "id": "menu" }
  ]
}

Una página puede llevar un audio_cue opcional. Cuando esa página aparece, el Player cambia a la pista nombrada desde su inicio; si esa pista ya está reproduciéndose, solo se reinicia cuando restart es true. La secuencia continúa desde la pista señalada. Las señales son indicios: un Player las aplica con un fundido corto o las omite cuando la pista no está lista. Las páginas sin señal dejan la música intacta. Los campos de página distintos de id y audio_cue se omiten en el ejemplo anterior.

Reemplazar una lista de reproducción reemplaza también su banda sonora; omita audio para eliminarla. Los videos en el lienzo permanecen silenciados, por lo que la banda sonora es el único sonido que reproduce una pantalla.

Vincular una página a una pista

Para un álbum o libro con una página por pista, o cualquier página que dure exactamente tanto como una pista, vincule la página a su pista.

Establecer la página advance a { "mode": "audio_end" }. La página aplica su audio_cue cuando aparece, como cualquier señal, y termina cuando esa pista termina, de la misma manera que una página media_end termina con su video. La página debe llevar un audio_cue y la lista de reproducción una banda sonora audio. Los elementos de imagen y video siguen las reglas duration: sin dwell_ms, y one_at_a_time: true en cada selector dinámico (all, tag, folder o ids con más de un id), incluso cuando coincide con un objeto hoy. Un elemento stream aún necesita una página duration, y una aplicación en la página nunca es su controlador. max_ms es una pista de seguridad opcional; el servidor establece el plazo según la duración de la pista, así que omítalo. Si el reproductor no puede reproducir la pista, la página aún dura la duración de la pista.

Establezca cued a true en el miembro audio para detener la banda sonora después de cada pista. Una pista señalada se reproduce solo cuando una página audio_cue la inicia. Sigue reproduciéndose bajo cualquier página ordinaria que siga a su página hasta que termina, y luego la banda sonora queda en silencio hasta la siguiente señal, por lo que una página y su pista permanecen vinculadas, con cualquier número de páginas ordinarias entre páginas vinculadas. loop no afecta a una banda sonora señalada, y cued por defecto es false.

{
  "name": "Album",
  "audio": {
    "tracks": [
      { "id": "song1", "media_id": "med_01EXAMPLESONG1000000000" },
      { "id": "song2", "media_id": "med_01EXAMPLESONG2000000000" }
    ],
    "cued": true
  },
  "pages": [
    { "id": "song1-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song1", "restart": true } },
    { "id": "interlude", "advance": { "mode": "duration", "after_ms": 8000 } },
    { "id": "song2-cover", "advance": { "mode": "audio_end" }, "audio_cue": { "track": "song2", "restart": true } }
  ]
}

Los campos de página distintos de id, advance y audio_cue se omiten del ejemplo anterior.

Colocar una tarjeta para texto en vivo

Una tarjeta integrada dibuja texto, un menú, una tabla, un reloj o un medidor en el propio Player, de modo que el texto sigue siendo editable y un valor nuevo llega a cada pantalla sin una imagen fija nueva. cards list muestra los tipos, card create crea una instancia y la lista de reproducción la coloca como una primitiva card. card data put escribe sus valores en vivo. Tarjetas enumera cada tipo y diseño.

screenrig cards list
screenrig card create --type gauge --file gauge-params.json
screenrig card data put crd_EXAMPLE --file gauge-data.json

Mostrar un panel tras un inicio de sesión

Una conexión web inicia sesión en un sitio como lo haría una persona, con una cuenta de servicio, y una vista web muestra una página de ese sitio. Sirve para paneles de Salesforce, Looker Studio, Datadog, HubSpot y cualquier otro sitio que no tenga un enlace público. Un navegador en el borde de screenRIG abre la página con la sesión iniciada y el Player muestra una imagen de ella, redibujada cada refresh_s segundos (de 60 a 86 400, 300 por defecto). Todas las pantallas del mismo tamaño comparten una imagen, así que añadir pantallas no añade inicios de sesión, y la imagen solo se dibuja mientras la lista de reproducción de una pantalla muestra la vista. Las conexiones y vistas de Grafana, Power BI y Tableau funcionan igual y están en la referencia de la API.

1. Cree una cuenta de servicio en el sitio que pueda leer solo los paneles que muestran sus pantallas. Cada captura inicia sesión como ella.
2. Cree la conexión con kind web y los ajustes de abajo. La contraseña es secret.
3. Cree una vista de una página: su dirección https como url y, como wait_for, un selector CSS de un elemento que solo aparece cuando la página tiene la sesión iniciada y está lista, de modo que una página de inicio de sesión agota el tiempo en lugar de dibujarse. clip dibuja solo la parte de la página que nombra un selector, y wait_ms (hasta 10 000) espera a los gráficos tardíos.
4. Coloque el embed_url de la vista en una primitiva iframe con content_fit fill.

{
  "kind": "web",
  "name": "Sales dashboard",
  "config": {
    "login_mode": "auto",
    "login_url": "https://login.example.com/sign-in",
    "username": "screens@example.com"
  },
  "secret": "ACCOUNT_PASSWORD",
  "totp_secret": "AUTHENTICATOR_KEY"
}

{
  "connection_id": "bic_01EXAMPLECONNECTION0000",
  "name": "Sales this week",
  "url": "https://app.example.com/dashboards/sales",
  "refresh_s": 300,
  "wait_for": "#sales-total"
}

La contraseña, la clave TOTP y las cookies van junto a config, se almacenan selladas y nunca vuelven a mostrarse: una lectura indica si cada una está definida. Un secret o totp_secret vacío, o cookies: [], la elimina.

• Primero las cookies. La conexión conserva un único conjunto de cookies sellado: el que usted pegó y luego las cookies que devuelve cada captura. Una captura envía el conjunto de cookies y ninguna credencial, y solo inicia sesión cuando no hay conjunto o la última captura llegó a una página de inicio de sesión. Un sitio que guarda su sesión fuera de las cookies inicia sesión en cada captura, así que dé a su vista un refresh_s largo.
• La contraseña va solo a la página de inicio de sesión. Se escribe en login_url y en los pasos goto, nunca en la dirección de una vista. Añadir una dirección a cualquiera de los dos exige la contraseña en la misma solicitud, así que un miembro que no puede leer la contraseña no puede dirigirla a una página propia.
• La cuenta está protegida. Un inicio de sesión rechazado (bi_web_login_failed o bi_web_otp_required) espera 5 minutos, luego 15, 60 y 120, y el quinto seguido detiene la conexión hasta que cambie sus credenciales o sus ajustes de inicio de sesión, así que se ejecutan como máximo 3 intentos en la primera hora. Un inicio de sesión que termina de otro modo (tiempo agotado, bloqueo, una página que no abrió) espera 15 minutos. Use una cuenta de servicio de solo lectura.
• Algunos sitios no se pueden automatizar. Un sitio que aprueba inicios de sesión en un teléfono, comprueba dispositivos o muestra un CAPTCHA necesita un conjunto de cookies (login_mode none) o una cuenta de servicio que el sitio exima.

El Player conserva la última buena imagen mientras falla una captura, y el estado de la vista lleva uno de estos códigos:

screenrig bi connection test ID inicia sesión e informa del resultado. El session de una conexión indica en qué punto están sus cookies y su inicio de sesión: idle, active, login_needed, paused, stopped o expired.

Filtros de etiquetas y lotes de reproducción

Los medios llevan hasta 32 etiquetas únicas, cada una de 1 a 32 letras o dígitos. Reemplace todo el conjunto con screenrig media update med_ID --tags Summer,Drinks. --tag Summer lo reemplaza con una etiqueta; --clear-tag borra todas las etiquetas. media list --tag Summer coincide con la membresía en cualquier parte del conjunto. Las etiquetas distinguen mayúsculas y minúsculas y nunca son autorización.

Un selector dinámico puede usar un tag o un objeto filtro tags:

{
  "by": "tag",
  "tags": { "all": ["Summer", "Drinks"], "any": ["Lobby", "Patio"], "none": ["Expired"] },
  "order": "random",
  "one_at_a_time": false,
  "batch_size": 3
}

all requiere todas las etiquetas listadas, any requiere al menos una, y none excluye cualquier etiqueta listada. Los grupos presentes se combinan con AND; los grupos omitidos no imponen condición. Proporcione al menos un grupo no vacío. Cada grupo acepta hasta 32 etiquetas únicas. tag y tags son mutuamente excluyentes. Un filtro solo none selecciona todos los medios listos de ese primitivo excepto las etiquetas excluidas. Los selectores de imagen seleccionan imágenes y los de video seleccionan videos.

La piscina de candidatos contiene hasta 1,024 medios listos por selector, con 1,024 referencias de medios en toda la instantánea del ciclo completo. Un emparejamiento mayor devuelve un error; reduzca los filtros. batch_size es un límite separado de 1–1,024 elementos por visita de página. En una página media_end, one_at_a_time: false reproduce el siguiente lote en secuencia; omitir batch_size reproduce el resto del pase. one_at_a_time: true reproduce un elemento por aparición y solo permite un tamaño de lote omitido o batch_size: 1. La duración, la aplicación y las páginas audio_end requieren one_at_a_time: true. Las imágenes en media_end también requieren dwell_ms; los videos no pueden repetirse en esa página.

El reproductor resuelve cada primitiva multimedia dinámica en una solicitud al iniciar la lista de reproducción y en cada límite de ciclo. La membresía se congela durante el ciclo. Las cargas, eliminaciones, cambios de etiquetado y límites de disponibilidad no regeneran el manifiesto. En la siguiente actualización, los elementos eliminados o excluidos salen de la cola pendiente; las nuevas coincidencias se unen cuando termina el pase actual. Un lote final puede contener menos que el número solicitado; no se rellena con el siguiente pase. El orden de nombre de archivo ordena por nombre de archivo, luego ID de medio. El orden aleatorio mezcla una vez por pase completo, preservando el orden restante entre actualizaciones del ciclo. El orden ponderado sigue sus pesos, más abajo. El cursor es local a la pantalla, lista de reproducción, página y primitiva, persiste tras reinicio y se reinicia al cambiar filtro, orden o política de lote. La reproducción sin conexión usa la última instantánea exitosa. Las coincidencias vacías omiten la primitiva y cualquier página vacía resultante.

Guarde el objeto selector arriba como selector.json, luego inspeccione su catálogo de candidatos actual antes de publicar:

screenrig media selector-preview selector.json --primitive video

La vista previa devuelve matched_count, ordenado por nombre de archivo candidates con IDs de medios y etiquetas, y la política selector normalizada. Con orden aleatorio muestra el grupo y la política de mezcla; no elige la mezcla del reproductor, avanza un cursor, crea un permiso de reproducción ni cambia un manifiesto. Con orden ponderado devuelve, para cada candidato, weight y share_percent, además de cycle. --rect WxH (API rect: {width, height}) es el tamaño del espacio y es obligatorio con fit: "aspect"; las coincidencias que deja fuera se listan en excluded con el motivo aspect_mismatch. Los selectores de imágenes pasan --primitive image. La API es POST /api/selectors/preview con { "primitive": "video", "selector": ... }. Usa el proyecto autenticado y las mismas reglas de coincidencia que la reproducción. Los cambios en el catálogo después de la vista previa se resuelven en el siguiente ciclo de reproducción.

La exportación de paquete estático congela las coincidencias dinámicas como IDs exactos. Preserva la reproducción uno a la vez o de pase completo; una secuencia de tiempo de ejecución limitada usando batch_size con one_at_a_time: false requiere eliminar ese campo o elegir IDs explícitos antes de exportar. Esto evita perder silenciosamente un cursor de lote en tiempo de ejecución en un paquete estático.

Rotación ponderada y ajuste por aspecto

order: "weighted" rota las creatividades de un espacio según su peso, de modo que cada patrocinador conserva su parte de reproducciones. weights asigna un ID de medio (med_...) o tag:NAME a un entero de 1 a 1000, con un máximo de 64 claves. Funciona con by igual a all, tag o folder:

{
  "by": "all",
  "order": "weighted",
  "one_at_a_time": true,
  "weights": { "tag:Acme": 50, "tag:Globex": 30, "tag:Initech": 20 },
  "fit": "aspect"
}

Pesos de 50, 30 y 20 entregan exactamente 5, 3 y 2 de cada 10 reproducciones, en cada ciclo, y un reinicio continúa a mitad de ciclo. El peso de un elemento es su clave de ID de medio cuando existe; si no, la primera clave tag:NAME, en orden alfabético, entre las etiquetas que lleva, repartida por igual entre los elementos de la selección que la comparten, de modo que la parte de un patrocinador se mantiene sea cual sea el número de creatividades; si no, el elemento cuenta como su propio grupo con peso 1. Un ciclo tiene como máximo 4096 reproducciones; las partes se redondean a él solo cuando la proporción exacta exige un ciclo más largo.

El orden ponderado reproduce un elemento por visita, así que defina one_at_a_time: true o batch_size: 1. weights es obligatorio con el orden ponderado y solo se permite con él; de lo contrario, la escritura devuelve invalid_request. Los reproductores web, Android, Apple, Windows y Linux implementan el orden ponderado desde las versiones que declaran la capacidad de host selector.weighted. Un reproductor anterior reproduce el selector en orden aleatorio, y los diagnósticos del manifiesto incluyen selector_order_downgraded.

fit: "aspect" en un selector dinámico conserva solo los archivos cuya relación ancho/alto está dentro del 5 % de la del rectángulo del espacio, incluido un muro de video o marco de pantalla, leída cuando el selector se resuelve. Un espacio vertical nunca reproduce un archivo horizontal. No requiere ningún cambio en el reproductor.

screenrig media selector-preview imprime la proporción esperada de cada selector ponderado o ajustado por aspecto, y el editor de páginas del panel muestra la misma tabla en el inspector. La exportación de paquete estático congela un selector ponderado como IDs exactos en orden de nombre de archivo; los pesos no se conservan.

Tokens de pantalla en selectores de etiquetas

El tag de un selector de etiquetas, y cada entrada de su filtro tags, puede ser {screen.field.NAME} o {screen.id}, el identificador de la pantalla sin su prefijo scr_, que es una etiqueta. El servidor rellena el token para cada pantalla al construir el manifiesto y la instantánea de selectores de esa pantalla, así que una lista de reproducción reproduce los medios propios de cada pantalla. Etiquete los medios Lobby o Garage, defina el campo de cada pantalla con screenrig screen update scr_ID --field zone=Lobby y asigne al espacio este selector:

{ "by": "tag", "tag": "{screen.field.zone}", "one_at_a_time": true }

El valor rellenado sigue las reglas de las etiquetas: de 1 a 32 letras o dígitos. Una pantalla sin el campo, o cuyo valor no es una etiqueta, no selecciona nada: no reproduce ningún archivo de ese espacio, y los diagnósticos del manifiesto incluyen screen_fact_missing o screen_fact_invalid. Cambiar un campo regenera el manifiesto de esa pantalla. Un selector con token no se puede previsualizar (media selector-preview necesita una etiqueta concreta) ni congelar con playlist export.

Tokens de pantalla en direcciones de iframe y params de aplicación

El iframe y el src de un fallback_src pueden llevar tokens de pantalla en la ruta, la consulta o el fragmento de una dirección http o https, y también el params opcional de una primitiva application: hasta 16 nombres de 1 a 32 letras minúsculas, dígitos o guiones bajos (ticket y policy están reservados) con valores de hasta 512 caracteres. El servidor los rellena para cada pantalla:

{
  "primitive": "iframe",
  "src": "https://maps.example.com/directory?kiosk={screen.field.kiosk_id}&level={screen.field.level}",
  "title": "Directory"
}

La escritura guarda la plantilla tal como está escrita, con las llaves incluidas. El manifiesto de cada pantalla lleva su propia dirección, con cada valor codificado en porcentaje para su lugar en la URL: un kiosk_id de B 2&3 se convierte en B%202%263. Un token en el esquema, las credenciales, el host o el puerto, o en un enlace de YouTube, un enlace de documento de Google o Microsoft o una dirección de vista de BI, se invalid_request en src (o fallback_src). La publicación omite la comprobación de marcos para un src con plantilla, y las vistas previas muestran la plantilla tal como está escrita.

Una pantalla a la que le falta un valor (un campo sin definir, sin ubicación), o cuyos valores forman una dirección de más de 2048 caracteres o con un segmento de ruta de . o .., no recibe ese iframe ni aplicación, y los diagnósticos de su manifiesto llevan screen_fact_missing o screen_fact_invalid; una página que queda vacía se descarta. Toda escritura que llega a una pantalla así (una escritura de lista de reproducción, screen assign, screen update, una asignación de flota, una revisión aprobada) responde con una advertencia screen_fact_missing que nombra los tokens, los primeros 20 ids de pantalla y cuántas hay. Cambiar un campo o la ubicación vuelve a emitir el manifiesto de las pantallas a las que afecta.

Para una aplicación, cada param rellenado se añade a la dirección de lanzamiento después de ticket, codificado en porcentaje, con un máximo de 4096 caracteres en conjunto, de modo que la aplicación lo lee desde location.search (SDK). Los params de lanzamiento llegan al Player web y a los Players que lo ejecutan (Samsung Tizen, BrightSign, LG webOS y Vega); los Players Qt, Android, Apple y Windows cargan la aplicación desde su paquete local y no envían ninguno. El campo url de una plantilla puede ser un src de iframe completo, y su valor puede llevar a su vez tokens de pantalla, que se rellenan cuando se construye el manifiesto. Un selector de etiquetas usa {screen.id} y {screen.field.NAME} del mismo modo (arriba). Las tarjetas conservan sus propios tokens {screen.…}.

Disponibilidad de medios

screenrig media availability med_ID --file rule.json define cuándo los selectores dinámicos (all, tag y folder) pueden elegir un archivo. --clear elimina la regla y --expect-rev N protege la revisión del medio. La API es PATCH /api/media/{id}/availability con If-Match y { "availability": {...} | null }. Definir una regla requiere acceso Manage; una credencial Propose recibe insufficient_access.

La regla es la gramática horaria del calendario, leída en la zona horaria de cada pantalla, y contiene al menos un miembro: from y until (civil YYYY-MM-DDTHH:MM, until exclusivo), windows (semanal {days, start, end}), monthly ({day} o {nth, weekday}, cada uno con start y end opcionales), dates ({date, start, end}) y except (fechas que eliminan una ocurrencia, incluidas las colas después de medianoche). No tiene data ni interaction. La creatividad de un patrocinador para el fin de semana largo, disponible solo en las tardes entre semana dentro del periodo:

{
  "from": "2026-11-27T00:00",
  "until": "2026-11-30T23:59",
  "windows": [{ "days": ["mon", "tue", "wed", "thu", "fri"], "start": "17:00", "end": "22:00" }]
}

Solo los selectores leen la regla: un selector explícito con id o ids la ignora, igual que las referencias de medios de las tarjetas, el audio de la banda sonora y las creatividades publicitarias. Un archivo sale de la selección y vuelve en el siguiente ciclo de lista de reproducción de cada pantalla, en aproximadamente un minuto desde el límite. No cambia ninguna revisión de lista de reproducción ni de manifiesto, y un reproductor sin conexión conserva su última selección hasta que se reconecta. screenrig media selector-preview --timezone ZONE (UTC por defecto) lista en excluded los archivos fuera de su regla en ese momento, con el motivo outside_window.

Volver a la referencia CLI de screenRIG.