# Awesome Jellyfin Plugin Repository (Synq Core)

This directory contains a local, Jellyfin-compatible plugin catalog built from
[`awesome-jellyfin/awesome-jellyfin`](https://github.com/awesome-jellyfin/awesome-jellyfin).

## What was done

1. **Cloned** the awesome-jellyfin list.
2. **Parsed** all 69 community plugins into `plugin-catalog.json`.
3. **Downloaded** the latest release `.zip` for **53** of those plugins.
4. **Built** a Jellyfin plugin-repository manifest (`jellyfin-plugin-repo.json`).
5. **Serving** the manifest and plugin `.zip` files on
   `http://192.168.1.141:8097` (and `http://localhost:8097`).

## Current status

- ✅ **53 plugins** ready to install from the local repo
- ✅ Repository added to the running Jellyfin instance (`synq-jellyfin`)
- ✅ Persistent systemd service: `jellyfin-awesome-plugins.service`
- ⏳ **16 plugins** not yet fetched because the unauthenticated GitHub API rate
  limit was reached. They can be added later with a GitHub token or after the
  rate limit resets (≈ 1 hour).

## Plugin repo URLs

| Use case | URL |
|----------|-----|
| From this machine / Jellyfin container | `http://localhost:8097/jellyfin-plugin-repo.json` |
| From the local network | `http://192.168.1.141:8097/jellyfin-plugin-repo.json` |
| Public HTTPS | `https://plugins.teamspeed.team/jellyfin-plugin-repo.json` |

## Add the local repo to Jellyfin (already done)

The helper script was run as root and added the repo to Jellyfin's actual
config at `/opt/synq-deploy/synq-tv-kids/jellyfin/config/config/system.xml`.

If you ever need to re-run it:

```bash
cd /home/administrator/jellyfin-awesome-plugins
sudo python3 add_repo_to_jellyfin.py
docker restart synq-jellyfin
```

To use the local-network URL instead:

```bash
cd /home/administrator/jellyfin-awesome-plugins
REPO_URL="http://192.168.1.141:8097/jellyfin-plugin-repo.json" sudo -E python3 add_repo_to_jellyfin.py
docker restart synq-jellyfin
```

## Install plugins

After Jellyfin restarts:

1. Open **Dashboard → Plugins → Catalog**.
2. Select the **Awesome Jellyfin (local)** repository.
3. Choose any plugin and click **Install**.
4. Restart Jellyfin when prompted to load the plugin.

## Keep the local server running

A systemd service now keeps the server running across reboots:

```bash
sudo systemctl status jellyfin-awesome-plugins
sudo systemctl restart jellyfin-awesome-plugins
```

Configuration is in `/etc/systemd/system/jellyfin-awesome-plugins.service`.
Environment variables used by `serve_repo.py`:

| Variable | Default | Purpose |
|----------|---------|---------|
| `REPO_BIND_HOST` | `0.0.0.0` | Interface to bind to |
| `REPO_PUBLIC_HOST` | `192.168.1.141` | Hostname used in plugin download URLs |
| `REPO_PORT` | `8097` | TCP port |

Edit the service file and run `sudo systemctl daemon-reload && sudo systemctl restart jellyfin-awesome-plugins` to change them.

## Fetch the remaining 16 plugins

Set a GitHub token to avoid rate limits and re-run the fetch script:

```bash
cd /home/administrator/jellyfin-awesome-plugins
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
python3 fetch_releases.py
sudo systemctl restart jellyfin-awesome-plugins
```

The missing plugins are listed in `missing-plugins.txt`.

## Using `jellyfin.teamspeed.team`

The domain `jellyfin.teamspeed.team` currently resolves to `75.55.255.85` and is
served by an external reverse proxy (openresty), not by this machine directly.

To make the plugin repo available through that domain:

1. Point `jellyfin.teamspeed.team` (or a subdomain like `plugins.teamspeed.team`)
   at this machine's public IP (`146.70.224.53`) or forward a path from the
   existing reverse proxy to `http://192.168.1.141:8097`.
2. If using the local `synq-nginx` container, add an SSL server block in
   `/opt/synq-deploy/synq-tv-kids/nginx/` and put the matching certificate in
   `./ssl/`, then run `docker exec synq-nginx nginx -s reload`.
3. Update `REPO_PUBLIC_HOST` in the systemd service to the public hostname and
   restart the service so plugin download URLs use the public address.

## Files in this directory

| File | Purpose |
|------|---------|
| `plugin-catalog.json` | All 69 plugins parsed from awesome-jellyfin |
| `jellyfin-plugin-repo.json` | Jellyfin manifest with `file://` source URLs |
| `jellyfin-plugin-repo.served.json` | Manifest rewritten for the running server |
| `plugin-zips/` | Downloaded `.zip` releases |
| `.release-cache/` | Cached GitHub API responses |
| `parse_plugins.py` | Re-parse the awesome-jellyfin README |
| `fetch_releases.py` | Download releases and build the manifest |
| `serve_repo.py` | Local HTTP server for Jellyfin |
| `add_repo_to_jellyfin.py` | Inject the repo into Jellyfin's `system.xml` |

## Important notes

- These are **third-party/community plugins**. Install only the ones you need.
- Some plugins target specific Jellyfin versions. Check the plugin page before
  installing if Jellyfin is older than 10.8.
- The local server uses plain HTTP. If you expose it to the internet, run it
  behind a reverse proxy that provides HTTPS.

## Integration with Synq Core app

To expose this catalog through Synq Core:

1. Point Synq Core at the local manifest:
   `http://192.168.1.141:8097/jellyfin-plugin-repo.json`
2. Or consume `plugin-catalog.json` directly and drive Jellyfin plugin
   installation through the Jellyfin API.
3. For automated installs, extract the desired `.zip` from `plugin-zips/` into
   `/var/lib/jellyfin/plugins/{PluginName}/{version}/` and restart Jellyfin.