feature/hls: Add HLS playback support, and refactors documentation for better usability and maintainability. (#1)HEADv0.5.0master

## Overview
This PR introduces HLS playback support, improves the player experience, and refactors documentation for better usability and maintainability.

## Key Features

### HLS Playback Support
- Add HLS integration via new JavaScript assets:
  - `hls.min.js`
  - `plyr.hls.start.js`
  - `watch.hls.js`
- Separate DASH and HLS logic:
  - `plyr-start.js` → `plyr.dash.start.js`
  - `watch.js` → `watch.dash.js`
- Update templates (`embed.html`, `watch.html`) for conditional player loading

### Native Storyboard Preview
- Add `native_player_storyboard` setting in `settings.py`
- Implement hover thumbnail preview for native player modes
- Add `storyboard-preview.js`

### UI and Player Adjustments
- Update templates and styles (`custom_plyr.css`)
- Modify backend modules to support new player modes:
  - `watch.py`, `channel.py`, `util.py`, and related components

### Internationalization
- Update translation files:
  - `messages.po`
  - `messages.pot`

### Testing and CI
- Add and update tests:
  - `test_shorts.py`
  - `test_util.py`
- Minor CI and release script improvements

## Documentation

### OpenRC Service Guide Rewrite
- Restructure `docs/basic-script-openrc/README.md` into:
  - Prerequisites
  - Installation
  - Service Management
  - Verification
  - Troubleshooting
- Add admonition blocks:
  - `[!NOTE]`, `[!TIP]`, `[!IMPORTANT]`, `[!WARNING]`, `[!CAUTION]`
- Fix log inspection command:
  ```bash
  doas tail -f /var/log/ytlocal.log
  ````

* Add path placeholders and clarify permission requirements
* Remove legacy and duplicate content

Reviewed-on: https://git.fridu.us/heckyel/yt-local/pulls/1
Co-authored-by: Astounds <kirito@disroot.org>
Co-committed-by: Astounds <kirito@disroot.org>

1 files changed, 19 insertions, 7 deletions

diff --git a/server.py b/server.py
index eadcffe..36ddae5 100644
--- a/server.py
+++ b/server.py
@@ -1,22 +1,28 @@
 #!/usr/bin/env python3
+# E402 is deliberately ignored in this file: `monkey.patch_all()` must run
+# before any stdlib networking or gevent-dependent modules are imported.
 from gevent import monkey
 monkey.patch_all()
-import gevent.socket
 
 from youtube import yt_app
 from youtube import util
 
 # these are just so the files get run - they import yt_app and add routes to it
-from youtube import watch, search, playlist, channel, local_playlist, comments, subscriptions
+from youtube import (
+    watch,
+    search,
+    playlist,
+    channel,
+    local_playlist,
+    comments,
+    subscriptions,
+)
 
 import settings
 
 from gevent.pywsgi import WSGIServer
 import urllib
 import urllib3
-import socket
-import socks, sockshandler
-import subprocess
 import re
 import sys
 import time
@@ -55,8 +61,6 @@ def proxy_site(env, start_response, video=False):
         'User-Agent': 'Mozilla/5.0 (Windows NT 6.1; Win64; x64)',
         'Accept': '*/*',
     }
-    current_range_start = 0
-    range_end = None
     if 'HTTP_RANGE' in env:
         send_headers['Range'] = env['HTTP_RANGE']
 
@@ -217,6 +221,12 @@ def site_dispatch(env, start_response):
             start_response('302 Found', [('Location', '/https://youtube.com')])
             return
 
+        # Handle local API endpoints directly (e.g., /ytl-api/...)
+        if path.startswith('/ytl-api/'):
+            env['SERVER_NAME'] = 'youtube.com'
+            yield from yt_app(env, start_response)
+            return
+
         try:
             env['SERVER_NAME'], env['PATH_INFO'] = split_url(path[1:])
         except ValueError:
@@ -268,6 +278,8 @@ class FilteredRequestLog:
 
 if __name__ == '__main__':
     if settings.allow_foreign_addresses:
+        # Binding to all interfaces is opt-in via the
+        # `allow_foreign_addresses` setting and documented as discouraged.
         server = WSGIServer(('0.0.0.0', settings.port_number), site_dispatch,
                             log=FilteredRequestLog())
         ip_server = '0.0.0.0'