Guida Utente MediaVista — MVP

Accesso al Pannello Admin

Il pannello di amministrazione di MediaVista si trova all'indirizzo /admin. Per accedere, utilizza le credenziali fornite dall'amministratore del sistema. Il pannello utilizza Filament come framework di gestione e offre un'interfaccia intuitiva per tutte le operazioni.

Creazione Workspace

Il workspace rappresenta l'unità organizzativa principale di MediaVista. Ogni workspace raggruppa dispositivi, asset, playlist e utenti. Un super admin può creare nuovi workspace dal pannello navigando in Workspace → Crea Nuovo.

• Inserisci un nome descrittivo per il workspace (es. "Sede Milano Centro")
• Configura lo slug identificativo univoco
• Aggiungi i membri del team con i ruoli appropriati (owner, admin, editor, viewer)

Primo Accesso e Configurazione Utente

Al primo accesso, ogni utente deve completare la configurazione del proprio profilo. I ruoli determinano i permessi operativi all'interno di ciascun workspace. Un utente può appartenere a più workspace contemporaneamente con ruoli differenti.

Cosa sono gli Impianti

Un impianto rappresenta una locazione fisica dove sono installati uno o più dispositivi di digital signage. Può essere un negozio, un ufficio, un centro commerciale o qualsiasi altro punto di installazione. Gli impianti permettono di raggruppare logicamente i dispositivi per posizione geografica.

Come Creare un Impianto

Dal pannello admin, naviga nella sezione Impianti → Crea Nuovo e compila i seguenti campi:

• Nome — Identificativo dell'impianto (es. "Store Via Roma 15")
• Indirizzo — Posizione fisica dell'installazione
• Note — Informazioni aggiuntive per gli operatori

Assegnazione Dispositivi e Playlist

Una volta creato l'impianto, è possibile associare dispositivi esistenti tramite la relazione nella scheda dettaglio. Ogni dispositivo può appartenere a un solo impianto alla volta. Le playlist e i layout vengono gestiti a livello di singolo dispositivo, ma l'impianto fornisce un contesto organizzativo per le operazioni di gruppo.

I dispositivi sono gli schermi fisici che riproducono i contenuti. MediaVista supporta due flussi di pairing per collegare un nuovo dispositivo al sistema.

Upload Asset

Gli asset sono i contenuti multimediali che verranno riprodotti sui dispositivi. MediaVista supporta diversi formati:

• Immagini — JPEG, PNG, WebP, SVG
• Video — MP4 (H.264), WebM
• HTML/SPA — Pacchetti HTML5 compressi in ZIP per contenuti interattivi

Per caricare un asset, naviga in Asset → Carica Nuovo dal pannello admin e seleziona il file. Il sistema accetta upload fino alla dimensione configurata nel server.

Processing Automatico

Dopo il caricamento, il sistema esegue automaticamente:

• Generazione thumbnail — Per tutti i tipi di asset, viene creata una miniatura per l'anteprima nel pannello
• Transcoding video — I video vengono ottimizzati per la riproduzione su dispositivi di digital signage
• Calcolo checksum — Viene generato un hash SHA-256 per la verifica di integrità nella cache locale del player

Creazione Playlist

Una playlist è una sequenza ordinata di asset. Per creare una playlist:

• Naviga in Playlist → Crea Nuova
• Assegna un nome descrittivo alla playlist
• Aggiungi gli asset desiderati come item della playlist
• Riordina gli item tramite drag & drop per definire la sequenza di riproduzione

Configurazione Item

Ogni item della playlist può essere configurato con:

• Durata — Il tempo di visualizzazione in secondi (per immagini e HTML)
• Posizione — L'ordine di riproduzione all'interno della playlist
• Transizione — L'effetto di transizione verso l'item successivo (es. fade, slide, none)

Creazione Layout Multi-Zona

Un layout definisce come lo schermo viene suddiviso in zone, ognuna delle quali riproduce una playlist indipendente. Questo permette di mostrare contenuti diversi contemporaneamente su parti diverse dello schermo.

Per creare un layout, naviga in Layout → Crea Nuovo e definisci le zone desiderate.

Definizione delle Zone

Ogni zona è definita dai seguenti parametri, tutti espressi in percentuale rispetto alle dimensioni dello schermo:

• Nome — Identificativo della zona (es. "Main", "Ticker", "Sidebar")
• X — Posizione orizzontale dell'angolo superiore sinistro (0-100%)
• Y — Posizione verticale dell'angolo superiore sinistro (0-100%)
• Width — Larghezza della zona (0-100%)
• Height — Altezza della zona (0-100%)

Assegnazione Playlist e Dispositivi

Dopo aver definito le zone, assegna una playlist a ciascuna zona. Infine, assegna il layout completo a uno o più dispositivi. Ogni dispositivo può avere un solo layout attivo alla volta.

Il manifest è il documento JSON che il player scarica per conoscere quali contenuti riprodurre, come disporli e con quali impostazioni operare. La versione 2.0 introduce un catalogo asset deduplicato e il supporto per aggiornamenti delta tramite ETag.

Esempio Completo

{
  "version": "2.0",
  "generated_at": "2026-02-06T10:30:00Z",
  "device_id": "uuid-device",
  "workspace_id": "uuid-workspace",
  "asset_catalog": {
    "asset-uuid-1": {
      "url": "/api/v1/assets/asset-uuid-1/download",
      "mime_type": "video/mp4",
      "size": 15728640,
      "checksum": "sha256:abc123...",
      "thumbnail_url": "/api/v1/assets/asset-uuid-1/thumbnail"
    }
  },
  "layout": {
    "id": "layout-uuid",
    "name": "Layout Principale",
    "zones": [
      {
        "id": "zone-uuid-1",
        "name": "Main",
        "x": 0, "y": 0, "width": 100, "height": 70,
        "playlist": {
          "id": "playlist-uuid",
          "name": "Playlist Principale",
          "items": [
            {
              "asset_id": "asset-uuid-1",
              "duration": 15,
              "position": 1,
              "transition": "fade"
            }
          ]
        }
      },
      {
        "id": "zone-uuid-2",
        "name": "Ticker",
        "x": 0, "y": 70, "width": 100, "height": 30,
        "playlist": { "...": "..." }
      }
    ]
  },
  "schedule": {
    "default_playlist_id": "playlist-uuid",
    "entries": []
  },
  "emergency": null,
  "commands_pending": 0,
  "settings": {
    "heartbeat_interval": 30,
    "manifest_poll_interval": 300,
    "log_level": "info"
  }
}

Descrizione dei Campi

version

Versione dello schema del manifest. Attualmente "2.0".

generated_at

Timestamp ISO 8601 della generazione del manifest lato server.

device_id

UUID del dispositivo a cui è destinato il manifest.

workspace_id

UUID del workspace di appartenenza del dispositivo.

asset_catalog

Catalogo deduplicato di tutti gli asset referenziati. Ogni asset è indicizzato per UUID e contiene URL di download, tipo MIME, dimensione in byte, checksum SHA-256 e URL della thumbnail.

layout

Definizione del layout attivo, con l'elenco delle zone. Ogni zona specifica posizione e dimensioni in percentuale, oltre alla playlist assegnata con i relativi item ordinati.

layout.zones[].playlist.items[]

Ogni item contiene il riferimento all'asset (asset_id), la durata in secondi, la posizione nella sequenza e il tipo di transizione.

schedule

Programmazione temporale dei contenuti. Contiene la playlist predefinita e un array di entry per la pianificazione oraria.

emergency

Messaggio di emergenza attivo. Valore null se non c'è nessuna emergenza in corso.

commands_pending

Numero di comandi remoti in attesa di esecuzione da parte del player.

settings

Configurazione operativa del player: intervallo heartbeat (secondi), intervallo di polling del manifest (secondi) e livello di log.

MediaVista permette di inviare comandi remoti ai dispositivi per operazioni di gestione e manutenzione. I comandi possono essere inviati dal pannello admin o direttamente via API.

Invio Comandi dal Pannello Admin

Nel pannello Filament, apri la scheda dettaglio di un dispositivo e utilizza i pulsanti di azione rapida nella sezione "Comandi". Il comando viene accodato e il player lo riceve al prossimo heartbeat o immediatamente via WebSocket.

Invio Comandi via API

I comandi possono essere inviati programmaticamente tramite l'endpoint dedicato. Il player recupera i comandi in attesa tramite GET /api/v1/devices/commands/pending durante il ciclo di heartbeat.

Messaggi Broadcast di Emergenza

Il sistema di emergenza permette di sovrascrivere istantaneamente il contenuto di tutti i dispositivi di un workspace con un messaggio prioritario. Questo è utile per comunicazioni urgenti, avvisi di sicurezza o informazioni critiche.

Come Creare un'Emergenza

• Dal pannello admin, naviga in Emergenze → Crea Nuova
• Inserisci il testo del messaggio di emergenza
• Seleziona il workspace (o tutti i workspace) da coinvolgere
• Conferma l'invio — il messaggio viene distribuito immediatamente

Priorità e Comportamento

I messaggi di emergenza hanno la priorità massima e sovrascrivono qualsiasi contenuto in riproduzione. Il player interrompe la playlist corrente e mostra il messaggio a schermo intero fino alla cancellazione dell'emergenza.

Cancellazione

Per cancellare un'emergenza attiva, naviga nella sezione emergenze del pannello e utilizza l'azione "Termina". Tutti i dispositivi torneranno automaticamente alla riproduzione normale dei contenuti programmati.

MediaVista espone due famiglie di API REST, tutte sotto il prefisso /api/v1/.

Device API (Autenticazione JWT)

Utilizzate dai player per comunicare con il server. L'autenticazione avviene tramite token JWT ottenuto durante il pairing.

Admin / Workspace API (Autenticazione Sanctum)

Utilizzate dal pannello admin e da integrazioni esterne. L'autenticazione avviene tramite token Sanctum. Tutti gli endpoint sono prefissati con /api/v1/.

Il player MediaVista include strumenti di debug integrati per la diagnostica sul campo. Queste funzionalità sono accessibili tramite scorciatoie da tastiera.

Console del Browser

Il player scrive log dettagliati nella console del browser. Apri gli strumenti di sviluppo (F12) per visualizzare:

• Log di rete (richieste manifest, heartbeat, download asset)
• Eventi del Service Worker (cache hit/miss, aggiornamenti)
• Transizioni di stato della riproduzione
• Errori di rendering e codec non supportati

Di seguito i problemi più comuni e le relative soluzioni.