init

README.md

@@ -0,0 +1,121 @@
+# Jellyfin Reddit Comments
+
+A Jellyfin server plugin that adds a **comments button to the video player**. Clicking it opens a
+sidebar showing the Reddit discussion thread for the episode or movie you're watching — built
+primarily for anime, where almost every episode has a thread on r/anime.
+
+- **Lazy**: Reddit is only contacted when you click the button. No background searching.
+- **Cached**: threads and comments are stored in a local SQLite database, so re-watching an
+  episode (or everyone on your server watching the same one) costs zero extra API calls.
+- **Rate limited**: a sliding-window limiter caps Reddit API usage at 60 requests/minute
+  (configurable, hard-capped at Reddit's own 100/min limit). In practice a fresh episode lookup
+  costs ~2–4 requests.
+
+> **A note on Devvit:** this plugin does *not* use Devvit, Reddit's developer platform. Devvit apps
+> run sandboxed *on Reddit's own servers* and cannot be embedded in external software like a
+> Jellyfin plugin. Instead, the plugin talks to the **Reddit REST API** directly using OAuth2
+> app-only (client credentials) authentication.
+
+## Requirements
+
+- Jellyfin Server **10.11.x** (built against the 10.11.11 ABI, `net9.0`)
+- The Jellyfin **web client** (the button/sidebar is injected into jellyfin-web; the API works
+  from any client that can call the plugin endpoints)
+- A free Reddit "script" app (client id + secret)
+
+## 1. Create the Reddit app (one time)
+
+1. Go to <https://www.reddit.com/prefs/apps> and click **create app**.
+2. Pick any name, choose type **script**, set redirect uri to `http://localhost`.
+3. Note the **client id** (shown under the app name) and the **secret**.
+
+## 2. Install the plugin
+
+### Option A — manual install
+
+1. Download/copy `dist/Jellyfin.Plugin.RedditComments_1.0.0.0.zip`.
+2. Create a folder `RedditComments` inside your Jellyfin plugins directory:
+   - Linux (native): `/var/lib/jellyfin/plugins/RedditComments`
+   - Docker: `<your config volume>/plugins/RedditComments`
+   - Windows: `%ProgramData%\Jellyfin\Server\plugins\RedditComments`
+3. Extract the zip contents into that folder (the DLLs must sit directly inside it).
+4. Restart Jellyfin.
+
+### Option B — plugin repository
+
+1. Host `dist/Jellyfin.Plugin.RedditComments_1.0.0.0.zip` somewhere reachable by your server
+   (e.g. a GitHub release asset).
+2. Edit `manifest.json`: set `sourceUrl` to the zip URL and update `checksum` with the zip's MD5
+   (`md5sum Jellyfin.Plugin.RedditComments_1.0.0.0.zip`).
+3. Host `manifest.json` next to the zip.
+4. In Jellyfin: **Dashboard → Plugins → Repositories → +**, paste the manifest URL, then install
+   "Reddit Comments" from the catalog and restart.
+
+## 3. Configure
+
+**Dashboard → Plugins → Reddit Comments**:
+
+1. Enter your **Client ID** and **Client Secret**, and set a descriptive **User Agent**
+   (Reddit requires one, e.g. `linux:jellyfin-reddit-comments:v1.0 (by /u/yourname)`).
+2. Click **Test connection** to verify.
+3. Optionally adjust subreddits (default `anime`), cache durations, rate limit, and comment
+   filters, then **Save**.
+
+## Usage
+
+1. Play an episode in the Jellyfin web player.
+2. Click the new **chat bubble** button in the player controls (next to fullscreen).
+3. The sidebar opens with the matching Reddit thread: title (links to Reddit), subreddit/score/
+   comment-count chips, and the comment tree. Click a comment's meta line to collapse its replies.
+4. Use the **refresh** button in the sidebar header to bypass the cache and fetch fresh comments.
+
+Nothing is searched or fetched until the button is clicked.
+
+## How it works
+
+- **Finding the thread**: the plugin searches your configured subreddits for
+  `"<series name>" episode <N>` (plus season/original-title variants) and scores candidates by
+  episode-number match and title similarity. Results are cached per Jellyfin item.
+- **Caching**: SQLite at `<config>/plugins/RedditComments/reddit-comments.db`. Found threads are
+  cached for 30 days, "not found" results for 24 hours (both configurable).
+- **Rate limiting**: every Reddit request (including token refreshes) passes through a
+  sliding-window limiter — never more than the configured number per rolling 60 seconds.
+- **Web client injection**: at startup the plugin adds a `<script>` tag for its player script to
+  jellyfin-web's `index.html` (re-applied automatically after web client updates). If your web
+  directory is read-only (some Docker setups), the plugin logs a warning with the tag to add
+  manually; the API still works regardless.
+
+## Limitations
+
+- Episode matching assumes the Reddit thread uses the same episode number as your library
+  (r/anime uses the show's broadcast numbering). If your library uses absolute numbering but the
+  thread uses per-season numbering (or vice versa), the thread may not be found.
+- The button/sidebar only exists in the Jellyfin **web** player. Other clients (Android TV,
+  Swiftfin, etc.) are not supported.
+- Only episodes and movies are supported.
+
+## Building from source
+
+Requires the .NET 9 SDK:
+
+```bash
+dotnet publish Jellyfin.Plugin.RedditComments/Jellyfin.Plugin.RedditComments.csproj -c Release -o publish
+```
+
+Copy the plugin DLL plus `Microsoft.Data.Sqlite.dll`, the `SQLitePCLRaw.*.dll`s and the native
+`e_sqlite3` library for your platform (under `publish/runtimes/<rid>/native/`) into your plugins
+folder. The `dist/` zip in this repo is already assembled this way.
+
+Run the smoke tests (cache, Reddit response parsing, rate limiter):
+
+```bash
+dotnet run --project SmokeTests/SmokeTests.csproj -c Release
+```
+
+## Uninstalling
+
+1. Remove the `RedditComments` folder from the plugins directory and restart.
+2. Optionally delete the cache database `<config>/plugins/RedditComments/reddit-comments.db`.
+3. The injected `<script src=".../RedditComments/Static/reddit-comments.js">` tag in jellyfin-web's
+   `index.html` becomes a harmless 404 after uninstall; remove it manually if you want it gone
+   (it is also overwritten on every jellyfin-web update).