YT Live Streamer — Player Website v2
=====================================

WHAT IS THIS?
─────────────
A self-hosted live stream player you run alongside your YouTube stream.
Viewers on your own website get a full-featured dark-themed player with
live chat, reactions, now-playing info and stream stats — all running on
your own machine with no third-party services.


WHAT VIEWERS SEE
────────────────
  Video Player
    Full-screen capable HLS video player (Video.js)
    Theatre mode — hides header and info bar for a clean full-window view
    Picture-in-picture (browser PiP button built in)
    Auto-reconnects when stream resumes after a drop
    Animated offline screen with countdown to next retry check

  Header
    LIVE badge with pulse animation when stream is running
    Stream uptime counter — shows how long the stream has been live
    Viewer count updated in real time from chat server
    Copy Link button — one click copies the stream URL to clipboard
    Theatre Mode button — toggles header/info bar off for full-screen feel
    Hide / Show Chat toggle

  Info Bar (below video)
    Now Playing — current video title pulled from the streamer API
    Next Up — upcoming video title

  Stats Bar (below info bar)
    Stream status dot — green when live, red when offline
    Viewer count, uptime, bitrate, FPS — all pulled from streamer API

  Chat Panel
    Live WebSocket chat with coloured usernames
    Six reaction buttons — thumbs up, heart, fire, laugh, clap, party
    Reactions float up the screen as an animation when clicked
    Mention highlighting — your username lights up amber when mentioned
    Mention notification toast — pops up when someone says your name
    Sound notifications — subtle ping on new messages, two-tone on mention
    Sound toggle button to enable/disable sounds
    Auto-scroll with toggle to pause scrolling
    Rename button to change your display name
    Reconnects automatically if chat connection drops

  Mobile
    Floating chat toggle button
    Chat opens full-screen overlay on small screens
    Stats bar hidden on mobile to save space


FILES IN THIS FOLDER
────────────────────
  stream_player.html     The web player — copy to your web server root
  chat_server.py         Python WebSocket chat server
  setup_stream_server.sh Automated Ubuntu setup (nginx, rtmp, chat service)
  README.txt             This file
  INSTALL.txt            Full step-by-step setup guide
  ABOUT.txt              Overview and embedding options


REQUIREMENTS
────────────
  Ubuntu 20.04 or 22.04
  nginx with libnginx-mod-rtmp
  Python 3 + websockets package  (pip install websockets)
  ffmpeg (already installed if you use YT Live Streamer)
  Ports open: 80 (HTTP), 1935 (RTMP), 8765 (chat WebSocket)


QUICK SETUP
───────────
  1. Run the automated setup script on your Ubuntu machine:
       chmod +x setup_stream_server.sh
       ./setup_stream_server.sh

  2. Copy stream_player.html to your web server root:
       sudo cp stream_player.html /var/www/html/index.html

  3. Edit the CONFIG block at the top of the script section:
       streamTitle:  "My Stream Name"
       posterImage:  ""   (optional URL to offline poster image)
       apiUrl:       "http://YOUR_MACHINE_IP:5000"

  4. Enable the Multi-RTMP plugin in YT Live Streamer:
       Settings -> System -> Plugins -> Multi-RTMP
       Add your server as a destination:
         rtmp://YOUR_MACHINE_IP/live/stream

  5. Start streaming — your stream goes to YouTube AND your player at once.

  6. Viewers open:  http://YOUR_MACHINE_IP/


CONFIG OPTIONS
──────────────
  Open stream_player.html and find the CONFIG block near the top
  of the <script> section:

    const CONFIG = {
      hlsUrl:       window.location.origin + "/hls/stream/index.m3u8",
      chatWsUrl:    "ws://" + window.location.hostname + ":8765",
      apiUrl:       "http://" + window.location.hostname + ":5000",
      streamTitle:  "Live Stream",
      posterImage:  "",
      pollInterval: 5,
      apiInterval:  5,
    };

  hlsUrl        URL to the HLS manifest. Default uses same server as player.
  chatWsUrl     WebSocket URL for the chat server.
  apiUrl        URL of the YT Live Streamer remote API (port 5000).
                Set to your machine IP e.g. "http://192.168.1.100:5000"
                Leave blank to disable API features (now playing, stats).
  streamTitle   Stream name shown in the header.
  posterImage   Optional URL to an image shown behind the offline screen.
                e.g. "images/offline.jpg" — make a branded waiting screen.
  pollInterval  Seconds between checks when offline (default 5).
  apiInterval   Seconds between API stats polls (default 5).

  For HTTPS:
    Change ws:// to wss:// in chatWsUrl
    Change http:// to https:// in apiUrl
    Set up a reverse proxy with Let's Encrypt (see INSTALL.txt)


CHAT FEATURES
─────────────
  Viewer commands (type in the chat box):
    /name YourName       Set your display name
    /color #ff6b6b       Set your name colour (any CSS hex colour)
    /help                Show available commands

  Moderator commands (type /mod PASSWORD first to authenticate):
    /ban username        Ban a viewer by IP
    /clear               Clear chat for all viewers
    /mod PASSWORD        Authenticate as moderator

  Change the mod password:
    Edit /etc/systemd/system/stream-chat.service
    Add:   Environment="CHAT_MOD_PASSWORD=yourpassword"
    Then:  sudo systemctl daemon-reload
           sudo systemctl restart stream-chat

  Chat usernames and colours are saved in the browser (localStorage)
  so viewers keep their name automatically on return visits.


REACTIONS
─────────
  Six one-click emoji reaction buttons appear above the chat input.
  Clicking a button:
    1. Sends the emoji as a chat message so all viewers see it
    2. Floats the emoji upward on your own screen as a visual effect

  Reactions appear in chat like any other message — all viewers
  see them in real time via WebSocket.


SOUND NOTIFICATIONS
───────────────────
  The bell icon next to your username toggles notification sounds:
    Bell on  (default) — a soft ping plays on each new chat message
                         a two-tone chime plays when your name is mentioned
    Bell off           — silent

  Sounds are generated via the Web Audio API — no audio files needed.
  Your preference is saved in the browser.


NOW PLAYING AND STATS
─────────────────────
  The player pulls live data from the YT Live Streamer remote API:

    Now Playing title — current video filename or title
    Stream status     — live / offline indicator dot
    Viewer count      — from the chat server
    Uptime            — how long the stream has been running
    Bitrate           — current encode bitrate from ffmpeg
    FPS               — current frames per second

  Requirements:
    The remote_api.py plugin must be loaded and running in YT Live Streamer
    Settings -> System -> Remote Control API -> Start API

  If the API is unreachable, the player still works normally — only
  the now-playing and stats features are unavailable. The stats bar
  shows "API offline" in the bottom-right corner.


EMBEDDING ON AN EXISTING WEBSITE
──────────────────────────────────
  Full player in an iframe:
    <iframe src="http://YOUR_SERVER/" width="100%" height="700"
            frameborder="0" allowfullscreen></iframe>

  Video only (no chat) on any HTML page:
    <link href="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.6.1/video-js.min.css" rel="stylesheet">
    <script src="https://cdnjs.cloudflare.com/ajax/libs/video.js/8.6.1/video.min.js"></script>
    <video id="player" class="video-js" controls autoplay muted playsinline>
      <source src="http://YOUR_SERVER/hls/stream/index.m3u8"
              type="application/x-mpegURL">
    </video>
    <script>videojs("player");</script>


PUBLIC ACCESS OPTIONS
─────────────────────
  Option 1 — Port forward on your router
    Forward ports 80, 1935 and 8765 to your machine's local IP.
    Viewers connect using your public IP or a domain name.
    Free. Requires a router you control.

  Option 2 — Tailscale (recommended for private streams)
    Install Tailscale on your machine and viewers' devices.
    No port forwarding needed. Encrypted. Works from anywhere.
    Free for up to 100 devices.
    tailscale.com

  Option 3 — VPS (recommended for public streams)
    Run everything on a cheap Ubuntu VPS so you don't expose
    your home IP and get better upload bandwidth.

    Recommended VPS providers:
      Hetzner CX22    ~$5/mo   4GB RAM   Best value — EU + US
      Vultr           ~$6/mo   1GB RAM   Good reliability
      DigitalOcean    ~$6/mo   1GB RAM   Easy to use
      Linode          ~$5/mo   1GB RAM   Solid performance

    On a VPS, run the setup script and point your Multi-RTMP plugin
    at the VPS IP instead of your local machine.


TROUBLESHOOTING
───────────────
  Player shows "Stream Offline" even when streaming
    Check nginx is running:     sudo systemctl status nginx
    Check HLS files exist:      ls /var/www/html/hls/stream/
    Check RTMP port is open:    sudo ufw allow 1935
    Check ffmpeg is sending to: rtmp://YOUR_IP/live/stream

  Chat shows "Disconnected"
    Check chat server is running: sudo systemctl status stream-chat
    Check port 8765 is open:      sudo ufw allow 8765
    Check chatWsUrl in CONFIG matches your server IP

  Now Playing / Stats not showing
    Check remote_api.py is loaded and API is started in streamer
    Check apiUrl in CONFIG points to correct IP and port 5000
    Check port 5000 is open: sudo ufw allow 5000

  No sound notifications
    Click the bell icon to enable sounds
    Browsers require a user interaction before allowing audio
    Click anywhere on the page first, then sounds will work

  Stream quality is poor
    Check your upload speed — HLS needs at least 2x your stream bitrate
    Reduce stream bitrate in YT Live Streamer Settings -> Stream
    Or switch to a VPS with a better connection


CHANGELOG
─────────
  v2 (current)
    Theatre mode button
    Stream uptime counter in header
    Animated offline screen with retry countdown
    Optional poster/thumbnail behind offline screen
    Reaction buttons (thumbs up, heart, fire, laugh, clap, party)
    Floating emoji animation on reaction
    Mention highlighting and notification toast
    Sound notifications for messages and mentions with toggle
    Copy Link button
    Now Playing and Next Up bar from streamer API
    Live stats bar — viewer count, uptime, bitrate, FPS
    Show/Hide Chat button in header

  v1
    Initial release — HLS player, live chat, viewer count,
    auto-reconnect, offline screen, mobile support
