# 09-threadfin.md

kstack:
  book: Centerpoint Home Lab
  chapter: Media & Entertainment
  page: Threadfin
  tags: [threadfin, iptv, m3u, xmltv, plex, jellyfin]
---

## Overview

Threadfin is an M3U proxy and IPTV middleware that translates IPTV streams into a
format consumable by Plex DVR and Jellyfin Live TV. It manages M3U playlists, XMLTV
guide data, and presents a virtual tuner device to media servers via HDHR (HDHomeRun)
emulation.

## Access

| Type    | URL / Endpoint                  | Notes                                  |
|---------|---------------------------------|----------------------------------------|
| Web UI  | `http://192.168.1.85:34400`     | Direct LAN access — no Traefik route   |
| HDHR    | `http://192.168.1.85:34400`     | HDHomeRun device emulation endpoint    |

No Traefik route is configured for Threadfin — Plex and Jellyfin connect to it via
direct IP and port on the LAN.

## Configuration

**Image:** `fyb3roptik/threadfin:latest`
**Compose project:** Standalone (managed via Portainer)

### Ports

| Port    | Protocol | Purpose                               |
|---------|----------|---------------------------------------|
| `34400` | TCP      | Threadfin web UI and HDHR endpoint (host-bound) |

### Environment Variables

| Variable                   | Value             | Purpose                          |
|----------------------------|-------------------|----------------------------------|
| `TZ`                       | `America/Toronto` | Timezone                         |
| `THREADFIN_PORT`           | `34400`           | Listen port                      |
| `THREADFIN_BRANCH`         | `main`            | Update channel                   |
| `THREADFIN_BIND_IP_ADDRESS`| `0.0.0.0`         | Bind to all interfaces           |
| `THREADFIN_DEBUG`          | `0`               | Debug logging off                |

## Volumes / Bind Mounts

| Host Path                               | Container Path           | Purpose                            |
|-----------------------------------------|--------------------------|------------------------------------|
| `/home/jeeves/docker/threadfin/config`  | `/home/threadfin/conf`   | M3U playlists, XMLTV data, settings |

## Networks

| Network       | Purpose                                              |
|---------------|------------------------------------------------------|
| `traefik-net` | Present (container is on traefik-net but no labels)  |

Threadfin is on `traefik-net` for network reachability but has no Traefik labels —
it is accessed by direct IP.

## Plex / Jellyfin Integration

**Plex:**
1. In Plex Settings → Live TV & DVR → Set Up Plex Tuner
2. Enter the Threadfin HDHR URL: `http://192.168.1.85:34400/device.xml`
3. Plex discovers the virtual tuner and available channels

**Jellyfin:**
1. Admin Dashboard → Live TV → Add Tuner Device
2. Select HDHomeRun and enter `http://192.168.1.85:34400`

## Dependencies

- M3U source URL (IPTV provider) configured in Threadfin UI
- XMLTV guide source configured in Threadfin UI
- Plex or Jellyfin must be able to reach `192.168.1.85:34400` on the LAN

## Notes / Gotchas

- M3U playlists and XMLTV guide data are refreshed on a schedule configured in the
  Threadfin UI. If the IPTV provider URL changes, update it in Threadfin settings —
  Plex and Jellyfin do not need to be reconfigured.
- Threadfin does not store or proxy video streams itself; it redirects the media
  server directly to the IPTV stream URL. Buffering and quality are determined by
  the stream source.
- Port `34400` is non-standard. Ensure no firewall rules block LAN-to-LAN traffic
  on this port between Plex/Jellyfin and Centerpoint.

---
*Last Updated: 2026-06-16*