The SpinetiX RPC API enables external systems to control player behaviour in real time. Unlike the REST API (designed for management), the RPC API is designed for action — switching playlists, triggering overlays, setting shared variables, and executing emergency overrides. An alarm system, IoT sensor, reception kiosk, or business application sends an HTTP POST, and the player responds instantly. This is the foundation of event-driven digital signage.
RPC Capabilities
Playlist Control
Switch the active playlist programmatically. A conference management system sends an RPC command 5 minutes before a session starts — the screen outside the conference room switches from generic lobby content to the session title, speaker name, and schedule. When the session ends, another RPC call restores the default lobby playlist.
Shared Variables
Shared variables are the simplest integration mechanism. Set a key-value pair via RPC
(e.g. POST /rpc with a JSON body specifying the variable name and value),
and the content template renders the current value. No data feed configuration needed — just
an HTTP POST and a template that reads the variable.
- Queue management:
queue_number=42→ "Now Serving: 42" - Welcome messages:
guest_name=Al Maktoum→ "Welcome, Al Maktoum" - Score updates:
home_score=3, away_score=1→ live scoreboard - Alert levels:
alert=warning→ yellow alert banner overlay
Emergency Override
The highest-priority RPC command. When a building management system or fire alarm sends an emergency trigger, all players immediately switch to the emergency playlist — evacuation routes, assembly points, and scrolling instructions. This override takes precedence over all scheduled content and cannot be overridden by normal content commands.
Trigger Events
Content projects can define named events that RPC commands trigger. A goal in a stadium sends a "goal_scored" event — the content plays a celebration animation. A VIP enters the building — "vip_arrival" triggers a personalized welcome on the lobby display. Events are defined in the content project, triggered externally.
Integration Examples
| Source System | RPC Command | Screen Response |
|---|---|---|
| Fire alarm | activatePlaylist("emergency") | Evacuation routes on all screens |
| Queue system | setVariable("now_serving", "42") | "Now Serving: 42" on counter display |
| Reception desk | setVariable("guest", "Ahmed") | "Welcome Ahmed" on lobby screen |
| Scoring system | triggerEvent("goal_home") | Goal celebration animation |
| IoT sensor | setVariable("temp", "23°C") | Room temperature display |
| Calendar system | activatePlaylist("meeting_in_progress") | Meeting room status → occupied |
Key Parameters
| Parameter | Value | Why It Matters |
|---|---|---|
| Protocol | HTTP POST | Standard web protocol, any language |
| Latency | Milliseconds | Real-time response for event-driven use |
| Authentication | Basic auth / player password | Prevent unauthorized control |
| Variable persistence | Until next set or reboot | Values survive playlist changes |
| Emergency priority | Highest — overrides all content | Life-safety compliance |
Common Mistakes
- No authentication on RPC endpoints. Without authentication, anyone on the network can trigger emergency overrides or change content. Always set a player password and require authentication for RPC calls.
- Not handling RPC failures. If the player is rebooting and the queue system sends "now_serving=43", the update is lost. Implement retry logic with a short delay — the player will be online again in under 30 seconds.
- Using RPC for data that should be a feed. If you're setting 50 variables every 5 seconds, you're using the wrong integration pattern. Use a data feed (REST API → JSON) for high-volume structured data. Use RPC for event triggers and individual variable updates.
- No emergency content testing. The RPC emergency trigger is useless if the emergency playlist hasn't been designed and tested. Create and verify emergency content during commissioning, not during actual emergencies.