Twitch-Recorder

Twitch application for automatically downloading streams as they go live.
Particularly useful for archiving streams that have disabled VODs.

Installation

twitch-recorder can be installed from PyPI and Nix/NixOS as a package or configured as a service with the module from stackpkgs.
After installing you should be able to run twitch-recorder from the terminal.

PyPI

pip install twitch-recorder

Nix/NixOS

# Install just the package
environment.systemPackages = [
    pkgs.stackpkgs.twitch-recorder
];

# Or configure the service
services.twitch-recorder = {
    enable = true;

    # You can use an environment file to safely store client details
    environmentFile = "/var/lib/secrets/twitch-recorder.env";
    settings = {
        twitch = {
            client_id = "$CLIENT_ID";
            client_secret = "$CLIENT_SECRET";
            token = "$TOKEN";
        };
    };
};

Configuration

twitch-recorder is configured using TOML, an example configuration file with defaults can be found here.

On Linux and macOS, the configuration file can be placed at the following paths, in order of priority:

1. $XDG_CONFIG_HOME/twitch-recorder.toml
2. $HOME/.config/twitch-recorder.toml
3. /etc/twitch-recorder.toml

On Windows, the file should be placed at %APPDATA%/twitch-recorder/twitch-recorder.toml

You can also specify the path to the configuration file by setting environment variable TWITCH_RECORDER_CONFIG or with command line flags -c and --config.

In the config you need to set client ID, client secret and token to the values provided by Twitch, as well as a list of users to watch.

Registering an application and obtaining the user token

To register an application for use with twitch-recorder, go to this page of the Twitch developer console.

On the page, fill in the details and click the create button. Make sure the redirect URL is set to something local (e.g. https://localhost) and client type is set to "Confidential". Next, click on the application you just created and press "New secret key". Now copy the client ID and client secret from respective fields and put them to your config.

To obtain the user token you need to authorize the application using your Twitch account by going to this URL:

https://id.twitch.tv/oauth2/authorize?client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI&response_type=token&scopes=

Replace CLIENT_ID, CLIENT_SECRET and REDIRECT_URI with values for your application.

After authorization Twitch will redirect you to a URL similar to:

https://localhost/#access_token=TOKEN$&scope=&token_type=bearer

Where TOKEN is the token you should put in your config.

Limitations

• You cannot watch more than 10 unauthorized users per client ID and token pair. This is a limitation imposed by Twitch for their EventSub API. Note, users that have authorized your application do not count towards this limit.
• Ad stubs may appear in the resulting videos. There isn't much twitch-recorder can do about this, as the issue is on yt-dlp side.

Development

twitch-recorder requires the following tools for development:

• uv - building and managing the Python project;
• ruff - linter and code formatter;
• mypy - type checking;

Install them on your system or use virtualenv. You can also use the provided development shell for Nix.

Used libraries

• TwitchIO - interacting with the Twitch API
• yt-dlp - downloading the actual video streams
• pyserde - serde style deserialization for configuration