YT Streamer Control - WordPress Plugin
=======================================

Control a YT Live Streamer instance from WordPress when both run on the
same VPS. Gives you an admin control panel (start/stop/skip/switch playlist/
downloads) and a public read-only status shortcode for visitors.


HOW IT WORKS (SECURITY MODEL)
-----------------------------
  Browser  ->  WordPress (PHP)  ->  Streamer API (127.0.0.1:5000)

  - All control actions are made server-side in PHP via wp_remote_post().
  - The API token lives in the WordPress database and in PHP only.
    It is NEVER sent to the browser or shown in page source.
  - Admin actions require the manage_options capability + a nonce, so only
    logged-in administrators can control the stream.
  - The public status shortcode exposes ONLY two safe fields
    (streaming yes/no, and now-playing title). No control, no token.
  - Because WordPress calls 127.0.0.1, port 5000 never needs to be exposed
    to the public internet. Keep it firewalled.


REQUIREMENTS
------------
  - WordPress and YT Live Streamer on the SAME machine (VPS).
  - The streamer's Remote Control API plugin (remote_api.py) loaded and started.
  - A token set in the streamer: Settings > System > Remote Control API.


INSTALL
-------
  1. Copy the folder "yt-streamer-control" into:
       wp-content/plugins/

     So you have:
       wp-content/plugins/yt-streamer-control/yt-streamer-control.php

  2. In WordPress admin: Plugins -> Activate "YT Streamer Control".

  3. Go to: Stream Control -> Settings
       API URL:   http://127.0.0.1:5000   (default, same machine)
       API Token: (paste the same token from the streamer)
     Save. The page runs a connection test and shows server info if connected.


USING THE CONTROL PANEL
-----------------------
  Admin menu: "Stream Control" -> "Control Panel"

    Status card     Live/offline, now playing, FPS, bitrate (auto-refresh 5s)
    Playback        Start, Stop, Previous, Skip
    Switch Playlist Dropdown of saved playlists + Switch Now
    Downloads       Add a YouTube URL to the queue, Start/Stop downloads

  Every button calls WordPress server-side, which forwards to the streamer
  with the token attached. Results show as a toast bottom-right.


PUBLIC STATUS SHORTCODE
-----------------------
  Place this in any post or page to show a live/offline badge to visitors:

    [yt_streamer_status]

  Options:
    [yt_streamer_status show_now_playing="no"]   Hide the now-playing title
    [yt_streamer_status poll="30"]               Poll every 30 seconds

  This is read-only and safe for public pages. It calls a custom WordPress
  REST route (/wp-json/ytsc/v1/status) which returns only the streaming flag
  and now-playing title - never the token or control endpoints.


ENDPOINTS USED
--------------
  GET  /api/status            status card + public badge
  GET  /api/now-playing       now playing
  GET  /api/playlists         playlist dropdown
  GET  /api/downloads         (available to extend)
  GET  /api/health            (available to extend)
  POST /api/start             Start Stream
  POST /api/stop              Stop Stream
  POST /api/skip              Skip Next
  POST /api/prev              Previous
  POST /api/switch-playlist   Switch Now           {name}
  POST /api/download-add      Add to Queue         {url}
  POST /api/download-start    Start Downloads
  POST /api/download-stop     Stop Downloads
  POST /api/set-input         (available to extend) {source}
  POST /api/schedule-enable   (available to extend) {enable}


TROUBLESHOOTING
---------------
  "Not connected" on the Settings page
    - Is the streamer running with the API started?
      Settings > System > Remote Control API > Start API
    - Does the API URL match? Same machine = http://127.0.0.1:5000
    - Run on the VPS:  curl http://127.0.0.1:5000/api/status

  Buttons do nothing / "Permission denied"
    - You must be logged in as an administrator (manage_options).

  "Failed" toast on actions
    - Token mismatch. Re-copy the token from the streamer into Settings.
    - Check the streamer terminal for the incoming request.

  Public badge shows "Unavailable"
    - The streamer API is down or the token is wrong. The badge degrades
      gracefully and shows Offline/Unavailable rather than erroring.


EXTENDING
---------
  The AJAX proxy in yt-streamer-control.php has a whitelist map of actions.
  To add a new control, add an entry to $map (action => [endpoint, method])
  and a button with data-ytsc="your-action" in the control panel HTML.

  Only whitelisted actions can be proxied - this is deliberate so the browser
  can never call arbitrary endpoints.
