Add Claude Code project setup

- CLAUDE.md with architecture overview and development guide - .mcp.json with docker, ssh, gitea, csharp-lsp, and nuget MCP servers - Skills for ersatztv and jellyfin - .gitignore: exclude .mcp/ (built MCP tools) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-26 23:50:41 +01:00
parent 0d301df5e8
commit 5034941a79
5 changed files with 389 additions and 0 deletions
--- a/.claude/skills/ersatztv/SKILL.md
+++ b/.claude/skills/ersatztv/SKILL.md
@@ -0,0 +1,167 @@
+---
+name: ersatztv
+description: ErsatzTV custom IPTV channel management — REST API, SQLite DB, Jellyfin integration, FFmpeg profiles. Use when managing custom TV channels.
+---
+
+# ErsatzTV Channel Management
+
+Container: `ersatztv` | Port: `8409` | IP: `172.16.238.11` (may change on restart)
+Web UI: internal only (`http://localhost:8409` via SSH)
+SQLite DB: `~/downloadswarm/ersatztv/ersatztv.sqlite3` on jazz (owned by root — use `sudo sqlite3`)
+Image: `ghcr.io/ersatztv/ersatztv:latest` (v26.3.0, repo archived Feb 2026)
+
+## Architecture
+
+ErsatzTV uses **MediatR + Blazor** (not REST for mutations). The REST API is limited:
+- **GET endpoints**: channels, collections, schedules, playouts, shows, movies, artists, ffmpeg profiles, health, search, watermarks
+- **POST endpoints**: library scan, playout reset, show scan
+- **No REST CRUD for channels/collections/schedules** — must use SQLite DB directly
+
+## REST API
+
+```bash
+# Via docker exec
+docker exec ersatztv curl -s http://localhost:8409/api/ENDPOINT
+```
+
+### Read Endpoints (GET)
+```
+/api/channels              # List channels
+/api/collections            # List collections
+/api/schedules              # List schedules
+/api/playouts               # List playouts
+/api/shows                  # List shows
+/api/movies                 # List movies
+/api/artists                # List artists
+/api/search                 # Search items
+/api/ffmpeg/profiles        # FFmpeg profiles
+/api/watermarks             # Watermarks
+/iptv/channels.m3u          # M3U playlist (for Jellyfin)
+/iptv/xmltv.xml             # XMLTV guide data
+```
+
+### Mutation Endpoints (POST)
+```bash
+# Library scan
+POST /api/libraries/{id}/scan
+
+# Scan single show
+POST /api/libraries/{id}/scan-show \
+  -H "Content-Type: application/json" -d '{"ShowTitle":"Name","DeepScan":false}'
+
+# Reset channel playout (rebuilds schedule)
+POST /api/channels/{channelNumber}/playout/reset
+```
+
+## SQLite DB Operations
+
+```bash
+# Read queries (safe while running, WAL mode)
+sudo sqlite3 ~/downloadswarm/ersatztv/ersatztv.sqlite3 "QUERY"
+
+# Write queries — stop container first
+docker stop ersatztv
+sudo sqlite3 ~/downloadswarm/ersatztv/ersatztv.sqlite3 "QUERY"
+docker start ersatztv
+```
+
+### Key Queries
+```sql
+-- List channels
+SELECT Id, Number, Name FROM Channel ORDER BY CAST(Number AS INTEGER);
+
+-- List collections with item counts
+SELECT c.Id, c.Name, COUNT(ci.Id) as items FROM Collection c LEFT JOIN CollectionItem ci ON ci.CollectionId = c.Id GROUP BY c.Id;
+
+-- List schedules
+SELECT Id, Name FROM ProgramSchedule;
+
+-- Playout (channel-schedule links)
+SELECT p.Id, c.Number, c.Name, ps.Name as Schedule FROM Playout p JOIN Channel c ON p.ChannelId = c.Id LEFT JOIN ProgramSchedule ps ON p.ProgramScheduleId = ps.Id;
+
+-- Media counts
+SELECT 'Shows' as type, COUNT(*) FROM Show UNION ALL SELECT 'Movies', COUNT(*) FROM Movie UNION ALL SELECT 'Episodes', COUNT(*) FROM Episode UNION ALL SELECT 'MusicVideos', COUNT(*) FROM MusicVideo;
+
+-- Jellyfin source
+SELECT jms.Id, jc.Address, jms.ServerName FROM JellyfinMediaSource jms JOIN JellyfinConnection jc ON jc.JellyfinMediaSourceId = jms.Id;
+
+-- Library sync status
+SELECT l.Id, l.Name, l.MediaKind, jl.ShouldSyncItems FROM Library l JOIN JellyfinLibrary jl ON jl.Id = l.Id;
+```
+
+### Channel Setup Workflow (DB)
+
+**Show-specific channel** (single TV show, shuffled):
+```sql
+-- 1. Schedule
+INSERT INTO ProgramSchedule (Id, FixedStartTimeBehavior, KeepMultiPartEpisodesTogether, Name, RandomStartPoint, ShuffleScheduleItems, TreatCollectionsAsShows)
+VALUES (<id>, 0, 0, '<name>', 1, 0, 1);
+-- 2. Schedule item (CollectionType=1 for Show, PlaybackOrder=3 for Shuffle)
+INSERT INTO ProgramScheduleItem (Id, CollectionType, FillWithGroupMode, GuideMode, "Index", MarathonGroupBy, MarathonShuffleGroups, MarathonShuffleItems, MediaItemId, PlaybackOrder, ProgramScheduleId)
+VALUES (<id>, 1, 0, 0, 0, 0, 0, 0, <show_id>, 3, <schedule_id>);
+INSERT INTO ProgramScheduleOneItem (Id) VALUES (<item_id>);
+-- 3. Channel
+INSERT INTO Channel (Id, Categories, FFmpegProfileId, FallbackFillerId, "Group", IdleBehavior, IsEnabled, MirrorSourceChannelId, MusicVideoCreditsMode, MusicVideoCreditsTemplate, Name, Number, PlayoutMode, PlayoutOffset, PlayoutSource, PreferredAudioLanguageCode, PreferredAudioTitle, PreferredSubtitleLanguageCode, ShowInEpg, SongVideoMode, SortNumber, StreamSelector, StreamSelectorMode, StreamingMode, SubtitleMode, TranscodeMode, UniqueId, WatermarkId)
+VALUES (<id>, '', 1, NULL, '<category>', 0, 1, NULL, 0, NULL, '<name>', '<number>', 0, NULL, 0, NULL, NULL, 'eng', 1, 0, <number>.0, NULL, 0, 4, 2, 0, lower(hex(randomblob(4)))||'-'||lower(hex(randomblob(2)))||'-4'||substr(lower(hex(randomblob(2))),2)||'-'||lower(hex(randomblob(2)))||'-'||lower(hex(randomblob(6))), 1);
+-- 4. Playout
+INSERT INTO Playout (Id, ChannelId, ProgramScheduleId, ScheduleKind, Seed)
+VALUES (<id>, <channel_id>, <schedule_id>, 0, abs(random()) % 1000000);
+```
+
+**Collection-based channel** (multiple shows, shuffled):
+```sql
+-- 1. Collection + items (MediaItemId = Show.Id)
+INSERT INTO Collection (Id, Name, UseCustomPlaybackOrder) VALUES (<id>, '<name>', 0);
+INSERT INTO CollectionItem (CollectionId, MediaItemId) VALUES (<coll_id>, <show_id>);
+-- 2. Schedule (same as above but CollectionType=0, CollectionId set instead of MediaItemId)
+INSERT INTO ProgramScheduleItem (Id, CollectionId, CollectionType, ..., PlaybackOrder, ProgramScheduleId)
+VALUES (<id>, <coll_id>, 0, ..., 3, <schedule_id>);
+-- 3-4. Channel + Playout same as show-specific
+```
+
+After creating: `POST /api/channels/{number}/playout/reset`
+
+## Volume Mounts (matches Jellyfin)
+
+| Host Path | Container Path |
+|-----------|---------------|
+| `~/downloadswarm/ersatztv` | `/config` |
+| `/mnt/teramind/episodes` | `/data/tvshows` (ro) |
+| `/mnt/episodes` | `/data/episodes` (ro) |
+| `/mnt/media/movies` | `/data/movies` (ro) |
+| `/mnt/media/standup` | `/data/standup` (ro) |
+| `/mnt/media/music_videos` | `/data/music` (ro) |
+
+## FFmpeg & Hardware
+
+- QSV (Intel Quick Sync) hardware acceleration
+- Resolution: 1920x1080, H264, AAC stereo
+- Device: `/dev/dri` passed through
+- HardwareAccelerationKind: 0=None, 1=Qsv, 2=Nvenc, 3=Vaapi, 4=VideoToolbox, 5=Amf
+
+## Jellyfin Integration
+
+- Secrets: `/config/jellyfin-secrets.json` (`{"Address":"http://jellyfin:8096","ApiKey":"978033be716d46678a5d3c54ae0e0ff9"}`)
+- Libraries: Movies(10), TV Shows(11), Music Videos(8), Standup(9)
+- `JellyfinLibrary.ShouldSyncItems` must be `1` for scans to work
+
+## Gotchas
+
+- DB owned by root — always use `sudo sqlite3`
+- WAL mode: reads OK while running, stop container for writes
+- No REST API for channel/collection/schedule CRUD — DB scripting only
+- Secrets file uses PascalCase JSON (`Address`, `ApiKey`)
+- Scanner is separate binary (`ErsatzTV.Scanner`) — check with `docker top ersatztv | grep Scanner`
+- EF TPT inheritance: `ProgramScheduleItem` has subtype tables (`ProgramScheduleOneItem`, etc.) — MUST insert into subtype table
+- External URL logos work for M3U but NOT for watermark burn-in (code checks `File.Exists()`)
+- `/api/health` returns Blazor HTML, not JSON — use `/api/channels` to verify API
+- PlaybackOrder enum: 3=Shuffle, 6=SeasonEpisode (use 3 for all channels)
+- CollectionType enum: 0=Collection, 1=Show (direct show reference via MediaItemId)
+- SubtitleMode: 0=None, 2=Burn-in. Set to 2 with PreferredSubtitleLanguageCode='eng' for non-music channels
+- MediaItem.State: 0=Normal, 1=FileNotFound — clean up state=1 items by deleting cascading deps
+- ProgramSchedule required NOT NULL columns: FixedStartTimeBehavior, KeepMultiPartEpisodesTogether, RandomStartPoint, ShuffleScheduleItems, TreatCollectionsAsShows
+- Channel required NOT NULL columns: SongVideoMode (set 0), plus all standard columns (see Channel table schema)
+- After schedule changes, rebuild playout: `POST /api/channels/{number}/playout/reset`
+- Playout `ScheduleKind` must be `1` (not `0`/None) — `0` causes "Cannot build playout type None" error
+- M3U `tvg-logo` URLs hardcode `http://localhost:8409` — Jellyfin can't fetch these from inside its container. Fix by downloading logos from ETV and base64-uploading to Jellyfin (see `docs/Docker/ErsatzTV.md` for script). Tracked in issue #171
+- Repo archived Feb 2026, v26.3.0 is final stable version. Maintainer welcomes forks
--- a/.claude/skills/jellyfin/SKILL.md
+++ b/.claude/skills/jellyfin/SKILL.md
@@ -0,0 +1,105 @@
+---
+name: jellyfin
+description: Jellyfin media server management — API for libraries, items, streaming, users. Use when managing media library or checking Jellyfin status.
+---
+
+# Jellyfin Management
+
+Container: `jellyfin` | Port: `8096` | IP: `172.16.238.20` (may change on restart)
+API Token: `978033be716d46678a5d3c54ae0e0ff9`
+Web UI: `https://jellyfin.tblindustries.be` (NO Authelia — native login, password: `coup1802`)
+Config: `/home/timothy/downloadswarm/jellyfin/` on jazz
+
+## Access Pattern
+
+```bash
+docker exec jellyfin curl -s 'http://localhost:8096/ENDPOINT' \
+  -H 'X-Emby-Token: 978033be716d46678a5d3c54ae0e0ff9'
+```
+
+## Volume Mounts
+
+| Host Path | Container Path | Content |
+|-----------|---------------|---------|
+| `/mnt/teramind/episodes` | `/data/tvshows` | TV shows |
+| `/mnt/episodes` | `/data/episodes` | More episodes |
+| `/mnt/media/movies` | `/data/movies` | Movies |
+| `/mnt/media/standup` | `/data/standup` | Standup |
+| `/mnt/media/music_videos` | `/data/music` | Music videos |
+| `/mnt/media/audio/music` | `/data/audio` | Music audio (ro) |
+
+## API Endpoints
+
+### System
+```
+GET  /System/Info                   # Server info, version
+GET  /System/Info/Public            # Public info (no auth needed)
+POST /System/Restart                # Restart server
+```
+
+### Items (Search & Browse)
+```bash
+# Search items
+GET /Items?includeItemTypes=Movie,Episode,Series&recursive=true&searchTerm=QUERY&fields=Path&limit=20
+
+# Get item details
+GET /Items?ids=ITEM_ID&fields=Path,MediaStreams,Overview
+
+# Get all movies
+GET /Items?includeItemTypes=Movie&recursive=true&fields=Path&limit=1000
+
+# Get series
+GET /Items?includeItemTypes=Series&recursive=true&fields=Path
+
+# Get episodes for a series
+GET /Shows/{seriesId}/Episodes?fields=Path,MediaStreams
+
+# Filter by library (parentId)
+GET /Items?parentId=LIBRARY_ID&recursive=true&fields=Path
+```
+
+### Libraries
+```
+GET  /Library/VirtualFolders        # List all libraries
+POST /Library/Refresh               # Trigger full library scan
+POST /Items/{id}/Refresh            # Refresh single item metadata
+```
+
+### Streaming
+```bash
+# Test stream URL
+GET /Videos/{itemId}/stream?static=true
+
+# Get playback info
+GET /Items/{itemId}/PlaybackInfo
+```
+
+### Users
+```
+GET  /Users                         # List users
+GET  /Users/{userId}                # User details
+```
+
+## Library IDs
+
+Check with: `curl -s -H "X-Emby-Token: TOKEN" http://localhost:8096/Library/VirtualFolders`
+
+## Live TV
+
+- **ErsatzTV** (channels <1000): M3U `http://ersatztv:8409/iptv/channels.m3u`, XMLTV `http://ersatztv:8409/iptv/xmltv.xml`
+- **Dispatcharr** (channels 1000+): IPTV stream manager on port 9191, separate tuner
+- Configured in Jellyfin Admin > Live TV
+- Guide refresh task ID: `bea9b218c97bbf98c5dc1303bdb9a0ca` — trigger via `POST /ScheduledTasks/Running/{id}`
+- **Logo fix after guide refresh**: ErsatzTV logos break (aspect ratio=0) because M3U uses `localhost:8409`. Fix script in `docs/Docker/ErsatzTV.md` downloads from ETV and base64-uploads to `POST /Items/{id}/Images/Primary` (body = base64, Content-Type = image/png)
+- **Image upload format**: Jellyfin expects base64-encoded body (NOT raw binary) for `POST /Items/{id}/Images/Primary`
+
+## Gotchas
+
+- **Passwords**: `coup1802` (NOT `ded89Lm4`) — Jellyfin has native auth, no Authelia
+- Auth header is `X-Emby-Token` (Jellyfin is an Emby fork)
+- Music videos are typed as "Movie" in Jellyfin
+- Music library at `/data/music` maps to `/mnt/media/music_videos` on host (not actual music)
+- Items return 404 on stream if source volume is unmounted
+- Jellyfin preserves item IDs across restarts unless files are renamed
+- Full library scan can take a long time — prefer targeted `/Items/{id}/Refresh`
+- `ffprobe` available in container for checking media streams: `docker exec jellyfin ffprobe -v quiet -print_format json -show_streams FILE`
--- a/.gitignore
+++ b/.gitignore
@@ -3,6 +3,9 @@
 project.lock.json
 .DS_Store
 *.pyc
+
+# Claude Code
+.mcp/
 nupkg/

 # Visual Studio Code
--- a/.mcp.json
+++ b/.mcp.json
@@ -0,0 +1,54 @@
+{
+  "mcpServers": {
+    "docker-mcp": {
+      "command": "uvx",
+      "args": [
+        "mcp-server-docker"
+      ],
+      "env": {
+        "DOCKER_HOST": "ssh://timothy@192.168.1.99"
+      }
+    },
+    "ssh-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "ssh-mcp",
+        "--",
+        "--host=192.168.1.99",
+        "--user=timothy"
+      ],
+      "env": {}
+    },
+    "gitea": {
+      "command": "gitea-mcp-server",
+      "args": [
+        "-t", "stdio",
+        "-host", "http://192.168.1.95:3000",
+        "-token", "8341af0733ab9ce084ea7adf38b76aa9ebc3bd67"
+      ],
+      "env": {}
+    },
+    "csharp-lsp": {
+      "command": "/usr/local/share/dotnet/dotnet",
+      "args": [
+        "run",
+        "--project", "/Users/timothy/ersatztv/.mcp/csharp-lsp-mcp/csharp-lsp-mcp/src/CSharpLspMcp",
+        "-c", "Release"
+      ],
+      "env": {
+        "PATH": "/usr/local/share/dotnet:/Users/timothy/.dotnet/tools:/usr/bin:/bin:/usr/sbin:/sbin"
+      }
+    },
+    "nuget": {
+      "command": "/usr/local/share/dotnet/dotnet",
+      "args": [
+        "dnx",
+        "NuGet.Mcp.Server",
+        "--source", "https://api.nuget.org/v3/index.json",
+        "--yes"
+      ],
+      "env": {}
+    }
+  }
+}
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,60 @@
+# ErsatzTV Fork
+
+Custom IPTV channel server for Jellyfin. Forked from [ErsatzTV/ErsatzTV](https://github.com/ErsatzTV/ErsatzTV) after upstream archival (Feb 2026, v26.3.0). Our fork lives on [Gitea](http://192.168.1.95:3000/timothy/ersatztv).
+
+## Architecture
+
+- **Language**: C# / .NET 10, Blazor Server UI (MudBlazor)
+- **Pattern**: CQRS via MediatR — queries/commands in `ErsatzTV.Application/`
+- **Database**: EF Core (SQLite default, MySQL optional) — context in `ErsatzTV.Infrastructure/Data/TvContext.cs`
+- **Media**: FFmpeg via CliWrap, SkiaSharp for logo generation
+- **Functional C#**: Language Ext (Option, Either monads throughout)
+
+### Project Layout
+
+| Project | Role |
+|---------|------|
+| `ErsatzTV/` | ASP.NET Core host, Blazor pages, API controllers, DI setup |
+| `ErsatzTV.Application/` | MediatR handlers (business logic) |
+| `ErsatzTV.Core/` | Domain entities, interfaces, no infrastructure deps |
+| `ErsatzTV.Infrastructure/` | EF Core repos, data access |
+| `ErsatzTV.Infrastructure.Sqlite/` | SQLite-specific implementations |
+| `ErsatzTV.FFmpeg/` | FFmpeg process wrapper |
+| `ErsatzTV.Scanner/` | Media library scanning |
+
+### Key Files
+
+- **M3U generation**: `ErsatzTV.Core/Iptv/ChannelPlaylist.cs` → `ToM3U()`
+- **XMLTV generation**: `ErsatzTV.Application/Channels/Queries/GetChannelGuideHandler.cs`
+- **IPTV controller**: `ErsatzTV/Controllers/IptvController.cs` — `/iptv/*` routes
+- **Logo generation**: `ErsatzTV.Core/Images/ChannelLogoGenerator.cs`
+- **Channel entities**: `ErsatzTV.Core/Domain/Channel.cs`
+- **DB context**: `ErsatzTV.Infrastructure/Data/TvContext.cs`
+
+## Deployment
+
+- **Docker host**: jazz (192.168.1.99), container `ersatztv`, port 8409
+- **Config volume**: `~/downloadswarm/ersatztv/` on jazz → `/config` in container
+- **SQLite DB**: `/config/ersatztv.sqlite3` (WAL mode, root-owned)
+- **Image**: `ghcr.io/ersatztv/ersatztv:latest` (to be replaced with our fork's image)
+
+## Development
+
+```bash
+# Build
+dotnet build ErsatzTV.sln
+
+# Run locally (needs FFmpeg in PATH)
+dotnet run --project ErsatzTV
+
+# Docker build
+docker build -f docker/Dockerfile -t ersatztv:dev .
+```
+
+## Conventions
+
+- Follow existing MediatR CQRS pattern for new features
+- Domain logic in `ErsatzTV.Core`, infrastructure in `ErsatzTV.Infrastructure`
+- Keep Blazor pages thin — delegate to MediatR handlers
+- Test with xUnit (existing test projects)
+- Backlog tracked via [Gitea Issues](http://192.168.1.95:3000/timothy/ersatztv/issues)