Jellyfin-Comments/README.md

# 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.1.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 plugin DLL must sit directly inside it).
4. Restart Jellyfin.

### Option B — plugin repository

1. Host `dist/Jellyfin.Plugin.RedditComments_1.0.1.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.1.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 `Jellyfin.Plugin.RedditComments.dll` into your plugins folder and restart. The package is
intentionally a single DLL: the plugin uses the same `Microsoft.Data.Sqlite` build that Jellyfin
itself ships for `jellyfin.db`, so no extra assemblies or native libraries may be placed in the
plugin folder (Jellyfin tries to load every `*.dll` there as a managed assembly and disables the
plugin on failure).

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).