Skip to content
DesertIce Wiki

TwitchArchivist

TwitchArchivist is a Windows-oriented ASP.NET Core application that watches Twitch channels through EventSub, queues an archive job when a stream ends, and downloads the VOD with TwitchDownloaderCLI. Channel-to-directory mappings and jobs are tracked in SQLite, and a built-in localhost web UI handles mappings, diagnostics, logs, and job history. It runs as a Windows Service in production.

Platforms: Windows service, Web UI (localhost)
Product page: desertice.tech/products/twitch-archivist

Who it’s for: Windows users who want Twitch VODs archived automatically per channel

Features

Section titled “Features”
  • Listens for Twitch stream.online and stream.offline EventSub events
  • Queues archive jobs when a stream ends and waits for the VOD to become discoverable
  • Downloads VODs by invoking an existing TwitchDownloaderCLI installation, with one-click managed setup from the diagnostics page
  • Channel-to-directory mappings in SQLite with optional filename aliases and Helix-backed login autocomplete
  • Optional auto-prune of older successful VODs per channel, with an additional gzip retention tier
  • Localhost web UI: dashboard, channels, jobs, diagnostics, and logs pages
  • Health and runtime JSON endpoints (/healthz, /api/runtime-status)
  • EventSub transport via direct WebSocket or conduit-backed WebSocket

Requirements

Section titled “Requirements”
  • Windows
  • .NET 10 SDK for development; service installs publish a self-contained win-x64 build
  • A Twitch developer application with a client ID and client secret
  • A local TwitchDownloaderCLI installation (or use the managed one-click install)

Install

Section titled “Install”
  1. Copy src/TwitchArchivist/appsettings.example.json (or the Development example) into a local appsettings.json
  2. Populate Twitch:ClientId and Twitch:ClientSecret from a Twitch application registered at dev.twitch.tv/console
  3. Restore packages with dotnet restore TwitchArchivist.slnx
  4. Build with dotnet build TwitchArchivist.slnx
  5. Run with dotnet run –project src/TwitchArchivist, or install as a Windows Service using the repository scripts

Setup

Section titled “Setup”
  1. Register an OAuth redirect URI matching the running host exactly: http://localhost:5000/auth/twitch/callback for the installed service, or http://localhost:5222/auth/twitch/callback (dev HTTP) / https://localhost:7153/auth/twitch/callback (dev HTTPS)
  2. Start user authorization from /auth/twitch/start; the callback is served by the same host and the token is stored in SQLite-backed application state
  3. Use the diagnostics page for the one-click managed TwitchDownloaderCLI setup, which validates the executable by running –version, or set Downloader:ExecutablePath manually
  4. Create channel-to-directory mappings on the /channels page, optionally with a filename alias and auto-prune settings
  5. Configure EventSub transport with Twitch:EventSubTransportMode (websocket or conduit-websocket); the example files opt into conduit-websocket

Using it

Section titled “Using it”
  • Dashboard (/): service overview, recent jobs, downloader/EventSub/OAuth summary
  • Channels (/channels): create, edit, enable, disable, and delete channel mappings
  • Jobs (/jobs): recent archive job history
  • Diagnostics (/diagnostics): downloader validation, EventSub status, OAuth status
  • Logs (/logs): recent in-memory and rolling-file log output
  • Check /healthz for database readiness, downloader validation, EventSub state, and Twitch authorization state

Troubleshooting

Section titled “Troubleshooting”

Twitch authorization fails

Section titled “Twitch authorization fails”

The redirect URI must match the running host, scheme, and port exactly. Also note that generating a new Twitch client secret invalidates the old one.

Downloads stall or fail

Section titled “Downloads stall or fail”

Each downloader process is terminated and the job marked failed if it goes without stdout, stderr, or output-file progress for DownloadInactivityTimeoutSeconds (default 600). Check the downloader path on the diagnostics page.

FAQ

Section titled “FAQ”

Where should TwitchDownloaderCLI live?

Section titled “Where should TwitchDownloaderCLI live?”

The diagnostics page can install it into \tools\TwitchDownloaderCLI\current and save the resolved path. You can also set Downloader:ExecutablePath manually; when blank, the app falls back to %APPDATA%\TwitchDownloaderCLI\TwitchDownloaderCLI.exe.

What port does the service use?

Section titled “What port does the service use?”

An installed Windows Service listens on http://localhost:5000 by default; local dotnet run uses 5222 (HTTP) and 7153 (HTTPS) from launchSettings.json.

Section titled “Links”