# Local Control Local Control is a small control page hosted by an individual player. It lets an authorized user operate the clients connected to that player when the main web application is unavailable or inconvenient to reach. Open Local Control at: ```text http://player-address:8081/local-control ``` Use the address and port exposed by the player in your deployment. Local Control controls only the player that served the page; it does not show or control every player in the installation. ## When To Use It The normal web application remains the main place to manage content, screens, playlists, users, and player assignments. Local Control is for immediate, player-specific operations such as: - Reloading a client that is stuck or displaying an old page. - Moving to the previous or next slide while checking playback. - Pausing or resuming a client. - Temporarily blacking out a client or restoring its display. - Checking which client is connected and what it is currently showing. Use the web application when you need to change a playlist, edit a slide, send commands to several screen groups, pair a player, or manage the signage setup. ## Signing In Local Control uses the central account information supplied by the web application. There are no separate player user accounts to create or manage. Enter the same username and password used for the central web application. Email addresses are not accepted in place of the username. The player checks the cached authorization data before creating a local session. The login session is stored in a player-specific, HTTP-only cookie. The cookie is limited to the Local Control path and uses `SameSite=Lax`, so it is not intended to be shared with another player or another part of the application. ### Failed Logins Repeated failed attempts are temporarily throttled to slow down guessing: - Five failed attempts are allowed within a fifteen-minute window. - Further attempts are rejected with a temporary lockout response. - The lockout lasts until the oldest failed attempt falls outside the window, so it can be less than fifteen minutes after the last failed attempt. - A successful login clears the failed-attempt record for that username and client address. - The limiter is held in memory on the player and resets if the player restarts. The login response does not reveal whether a username exists. This keeps invalid usernames and incorrect passwords on the same authentication path. ## What You See After signing in, Local Control shows the clients currently connected to the player. Each client row can include: - The client name. - The screen name. - The current slide title, when available. - The available action buttons. - Pause or blackout state when the client is in one of those states. If no clients are connected, the page remains available but there are no client actions to send. Connect or restart the player client, then reload the Local Control page to check again. ## Client Actions Actions apply to the selected client only. ### Reload Reloads the client page. Use this when the page is stale, an asset did not load, or a player-side display needs to restart without changing its content assignment. ### Previous and Next Moves the selected client to the previous or next slide in its current playlist. These actions are useful for checking a playlist or temporarily moving past a slide without editing the playlist. ### Pause and Resume Pauses the selected client on its current state. The same control resumes playback when the client is paused. ### Blackout and Restore Temporarily hides the selected client's display without changing its playlist. The same control restores the display. Use blackout for short operational interruptions; use screen or playlist changes when the content assignment itself needs to change. ## Live Updates Local Control opens an authenticated WebSocket after login. When the player reports a state change, the page can update the affected client row without a manual refresh. Live state can include: - Current slide title. - Pause state. - Blackout state. - Client connection and disconnection changes. If the live connection is interrupted, the page attempts to reconnect. The underlying player state and commands are still scoped to the local player. If a browser cannot use WebSockets, the page falls back to periodic state requests. ## Offline Authorization Cache The web application is the source of Local Control authorization. To support player-specific operation when the web application cannot be reached, each player stores a small local cache containing only the information needed to verify an eligible login: - A hashed username. - A password hash. - A password salt. Plain usernames, email addresses, display names, user IDs, and password iteration settings are not stored in this cache. Cached authorization is considered usable for up to 72 hours after the last successful synchronization. Once that period expires, Local Control rejects login attempts until the player receives a fresh synchronization. The cache is written with restricted file permissions and is not intended to be edited manually. Editing it does not provide a supported way to create local users. ## Authorization Updates Authorization is managed centrally by the web application and delivered to players through authenticated service connections. - Connected remote players receive a scheduled refresh every fifteen minutes. - A remote player receives the current authorization state immediately after it reconnects to the bridge. - The configured local player is not included in the remote-player fanout because it is refreshed through its local service path. - When the synchronized authorization changes, existing Local Control sessions on that player are closed. - A user removed from central access cannot continue using an existing Local Control session after the change reaches the player. A player that remains disconnected can continue using its last valid cache until the cache expires. Once it reconnects, it receives the current central state. ## Scope and Limitations Local Control is intentionally narrower than the web application: - It controls only clients connected to the current player. - It does not edit slides, templates, playlists, screens, or announcements. - It does not pair players or move clients between screen groups. - It does not provide local user administration. - It does not replace the web application as the source of content or authorization. ## Troubleshooting ### The login page says authorization is unavailable The cached authorization is missing or older than 72 hours. Restore the player's connection to the web service or bridge and wait for synchronization to complete. Restarting the player does not create a fresh authorization cache. ### A correct password is rejected Confirm that you are using the central username rather than an email address. If several failed attempts were made, wait for the temporary login throttle to expire. Also check whether the account's central access has changed. ### A client is not listed Confirm that the client is connected to the player serving Local Control. A client connected to another player will appear only in that player's Local Control page. Check the player connection and reload the page after the client reconnects. ### An action reports that the client is unavailable The client may have disconnected between the time the page loaded and the time the action was sent. Reload the page and check the current client list before trying again. ### Changes from the web application are not visible Check that the player can reach the web application or bridge and that its registration connection is healthy. A disconnected player can use its existing cache temporarily, but it cannot receive central authorization changes until it reconnects.