twitch-live-downloader

4 min read Original article ↗

TLD is a small, self-hosted Twitch live stream downloader.

You add one or more Twitch channels. TLD monitors them. When a channel goes live, it automatically starts recording the stream to disk using Streamlink.

There is no video player, no accounts, and no cloud. Files are saved locally and can be played with any media player.

Twitch Live Downloader app screenshot

What this does

  • Monitors Twitch channels for live streams

  • Automatically records streams when they go live

  • Saves recordings directly to your filesystem

  • Shows current recording status

  • Converts the completed streams recordings to mp4 to remove any errors and make the recordings playable everywhere

  • Cleanup original stream files (after conversion) to reclaim disk space

What this does NOT do (yet)

  • No authentication or multi-user support

  • No live preview or video player

  • No stream scheduling

  • No editing, trimming, or post-processing

  • This is a minimal, single-user tool by design.

Usage

This project is designed to be run using Docker. No local installation of Streamlink, Node, Bun or any other dependency is required on the host system. The Docker image is published on Docker Hub. You do not need to build the image locally unless you are modifying the source code.

Prerequisites

  • Docker
  • Docker Compose (optional)
  • Sufficient disk space for recordings

Use the following docker compose to start this service:

services:
  tld:
    image: naughtyfinch/tld:latest
    container_name: tld
    restart: no
    ports:
      - 3000:3000
    volumes:
      - ./data:/data # folder where the sqlite database (and recordings, by default) will be saved
      - ./recordings:/recordings # optional: specify a separate folder for recordings
    environment:
      RECORDINGS_DIR: /recordings # optional: set this when you mount a separate folder for recordings
      CLEANUP_OLDER_THAN: 30 # optional: number of days after which the original recordings are cleaned up

Alternatively, you can use the following command to start the container:

docker run -d \
  --name tld \
  -p 3000:3000 \
  -v "$(pwd)/data:/data" \
  -v "$(pwd)/recordings:/recordings" \
  -e RECORDINGS_DIR=/recordings \
  naughtyfinch/tld:latest

This will:

  • start the app server
  • start the background worker that monitors channels
  • automatically begin recording when monitored channels go live

Accessing the UI

Once running, open your browser and navigate to http://localhost:3000

From the UI, you can:

  • add/remove Twitch channels to monitor
  • view the current status of monitored channels
  • for channels being recorded, see how long the recording has been going on for and what is the filename of the recording

Environment Variables

You can use the following environment variables to tweak the application:

Variable Required? Default Value What it does
DATA_DIR No /data Changes the default data directory that the application saves the database and recordings to
RECORDINGS_DIR No /data/recordings Changes the default directory that the application saves the recordings to
DISABLE_RECORDING No false Disable recording app wide
CLEANUP_OLDER_THAN No. 30 Deletes recordings older than these many days (only the original .ts files are removed, not the converted .mp4 files)

Adding channels

Channels are identified by their Twitch channel name (the URL path). Example:

https://twitch.tv/somechannel
→ channel name: somechannel

You can add channels by their channel name or their Twitch url

Recording behavior

  • Channels are checked automatically at a fixed polling interval (15 secs)
  • When a channel goes live, recording starts automatically
  • Only one recording per channel is active at any time
  • Recording continues until:
    • the stream ends, or
    • the application is stopped
  • Long-running or continuous streams may result in very large files.

Limitations

  • This app uses Streamlink for downloading live streams. Twitch or Streamlink changes may temporarily break downloads

  • The application records streams in MPEG-TS (.ts) format by default. These files will be converted to MP4 without re-encoding automatically by the app. The original .ts files will be moved into an originals folder. These will be cleaned up automatically after 30 days (configurable, set CLEANUP_OLDER_THAN environment variable) or manually, to reclaim disk space.

Disclaimer

This project is provided for educational and personal use only.

This software is a general-purpose technical tool that interacts with publicly accessible live streams. It does not include, encourage, or endorse any mechanism to bypass paywalls, DRM, advertisements, authentication systems, or platform safeguards.

Users are solely responsible for ensuring that their use of this software complies with:

  • Twitch’s Terms of Service
  • Twitch’s Community Guidelines
  • Applicable local, national, and international laws

The author(s) of this project:

  • make no guarantees regarding compliance with any third-party terms
  • assume no liability for misuse of the software
  • are not responsible for how this tool is used after distribution

By using this software, you acknowledge that:

  • you understand the legal and contractual obligations associated with accessing and recording online content
  • any consequences arising from misuse are entirely your responsibility

If you are unsure whether your intended use is permitted, do not use this software.

This project is not affiliated with, endorsed by, or supported by Twitch.