svtplay-dl: a command-line downloader for public streaming video

The gap it fills: no download button on a public stream

Most public streaming sites give you a player and no way to keep a copy. svtplay-dl is a small command-line program for exactly that situation. Its own description is modest: a command-line program to download videos from some streaming sites, and the setup file describes it as a program to download videos from various video on demand sites.

The supported list is long and Nordic leaning, with a few international names in it. Swedish and Norwegian broadcasters dominate the list, along with the Baltic tv3play sites for Estonia, Latvia and Lithuania, Danish and Icelandic broadcasters, and a handful of others. American services are present too, including hbo.com and twitch.tv, alongside Pluto.tv, which the documentation notes is the former viafree.se, viafree.dk and viafree.no.

The intended user is someone watching on a site that offers no saving function and wanting a local file. It is a script, not a library, and it is not a general purpose downloader for arbitrary URLs. That framing matters, because the tool is written against the endpoints that these particular sites happen to use, and a site that changes how it serves video is a site the tool may stop handling.

Two optional dependencies shape what you can do with the output. ffmpeg is needed for postprocessing and for DASH streams, and the cryptography library is what allows encrypted HLS streams to be downloaded.

The Python package layout and the console entry point

The packaging is the tidiest part of this project, and it tells you more about the code than the prose documentation does. The source lives in a lib/ directory, and setup.py sets package_dir to point the install at that directory, with find_packages called on lib and the test packages excluded. The entry point is declared in the usual way:

        "console_scripts": [
            "svtplay-dl = svtplay_dl:main",
        ],

So the program is a module named svtplay_dl with a main function, and pip creates the svtplay-dl command from it. The project also uses versioneer, which is why setup.py appends its own directory to sys.path and imports versioneer directly, and why the setup file is careful to keep versioneer importable when the build runs under PEP 517.

The dependency list is declared twice, and both lists agree. requirements.txt holds four entries:

requests
PySocks
cryptography
pyyaml

setup.py declares the same four, with requests pinned as requests>=2.0.0 and the other three unpinned. Each one has a job. Requests does the HTTP work, PySocks enables proxy support, cryptography handles encrypted HLS streams, and pyyaml is for the configuration file.

Around that, the repository carries the usual supporting cast: a Makefile, setup.cfg, pyproject.toml, tox.ini, a .pre-commit-config.yaml, a .coveragerc, a dockerfile directory, a docs directory, scripts, and a svtplay-dl.pod file for the man page.

Installing on Debian and Ubuntu from the project apt repository

The distribution packages are the recommended route, because the versions in the Debian and Ubuntu archives are often old and the project asks you to use its own repository instead.

The first step is to add the release signing key:

    curl -s https://svtplay-dl.se/release-key.txt | sudo apt-key add -

Then you add the release channel to your APT sources:

    echo "deb https://apt.svtplay-dl.se/ svtplay-dl release" | sudo tee /etc/apt/sources.list.d/svtplay-dl.list

With the key and the source in place, update and install:

    sudo apt-get update

    sudo apt-get install svtplay-dl

Two things to notice. The repository is served over HTTPS, so the transport is encrypted, but the key handling uses apt-key, which is the older mechanism and writes a key file in a way that some distributions now discourage. And the package is a normal apt package, so it lands in the system package database and can be upgraded with the rest of your packages.

Solus has its own package manager, and the documentation gives the equivalent one-liner:

sudo eopkg it svtplay-dl

If you would rather not add a third party repository to a production machine, the pip route in the next section avoids that entirely.

Installing on macOS, Windows and from source

On macOS, Homebrew is the path of least resistance:

    brew install svtplay-dl

The documentation asks you to run brew install ffmpeg afterwards if you do not already have ffmpeg, and the same requirement applies on every other platform.

For any other Unix-like system, the documentation offers a single file download and a permission change:

sudo curl -L https://svtplay-dl.se/download/latest/svtplay-dl -o /usr/local/bin/svtplay-dl

sudo chmod a+rx /usr/local/bin/svtplay-dl

Windows users can take the prebuilt binaries from the project site, and the documentation also explains how to build your own with cx_Freeze, including a step that rewrites the version string with setversion.py and a final command that produces svtplay-dl.exe together with the pythonXX.dll it needs.

For any platform with Python, the simplest option is pip:

    pip3 install svtplay-dl

And where no packaging exists, the sources can be cloned and installed:

    git clone https://github.com/spaam/svtplay-dl

    sudo python3 setup.py install

Note that this last command uses setup.py install, which modern pip discourages in favour of a wheel build. The project also has a Makefile that builds a standalone script, generates the man page with pod2man, and provides test, cover, pylint and doctest targets, so there is more than one way in.

The Python version is documented twice, and the two answers differ

This is the sharpest inconsistency in the project, and it will bite anyone on an older interpreter.

The project documentation lists the requirements and says Python 3.6 or higher, and the formatting configuration in pyproject.toml still targets py36. The packaging tells a different story. setup.py checks the running interpreter before it does anything else:

vi = sys.version_info
if vi < (3, 9):
    raise RuntimeError("svtplay-dl requires Python 3.9 or greater")

The same file then declares python_requires=">=3.9" in the setup call. So the install refuses Python 3.8 and below with a clear error, while the prose documentation still advertises 3.6. The packaging is the authority, since it is what actually runs, and that documentation is simply out of date.

The check is deliberate rather than incidental. It is placed before the dependency list is assembled and before the version file is read, so an unsupported interpreter fails immediately with a message rather than a stack trace from somewhere inside the import machinery.

For an administrator this matters twice. On a machine that still runs Python 3.8, the pip install fails outright rather than installing something broken. And on a machine with several interpreters, the failure tells you which interpreter the project expects, which is more information than the README gives you.

Running the program and what ffmpeg actually unlocks

The usage is one line, options followed by a URL:

    svtplay-dl [options] URL

Everything the program does hangs off that URL, which is why the supported site list is the real specification of what it can do. The documentation names about thirty services, so the surface area is wide, and the tool has to parse the page, find the stream metadata, and hand the media to a downloader.

ffmpeg is the hard dependency in practice. The documentation lists it as needed for postprocessing and for DASH streams, and recommends installing it separately on every platform, including on Windows where a separate build is linked. Without it, the plain HLS path still works, and the more complicated paths do not. A second optional piece is PySocks, which is what enables proxy support for users behind a network that requires one.

The cryptography library sits in the same category, and its stated purpose is downloading encrypted HLS streams. Without it those streams cannot be handled at all, which means the required dependency set is not optional in the way a package list sometimes suggests.

Configuration comes through a file read with pyyaml. The documentation does not describe the file's location, its keys or its format, so a user who needs a configuration option has to read the source in lib/ to find it.

Licence, release hygiene and the limits of the packaging

The project is licensed under the MIT licence, and the setup file declares the same licence string. That permits reuse and redistribution with the notice kept, and it places no obligation on a downstream project to publish changes.

Version handling is handled by versioneer, which derives the version from git rather than a hardcoded string, and the Makefile carries a current VERSION of 1.9.11 with a release target that tags the commit. The repository itself has no GitHub releases, so there is no tag list to browse on the project page, and the version a package manager installs is the version in the repository's own metadata rather than something you can see at a glance.

The project publishes to several package managers and hosts its own apt repository, its own download endpoint and a Windows binary, which is more distribution work than most scripts of this size take on. There is a dockerfile directory in the tree and a tox.ini for test environments, and a .pre-commit-config.yaml for hook-based checks.

What is missing is equally clear. The documentation does not describe how a user should upgrade, and there is no documented mechanism for a site that changes its delivery to be patched from a user side. The dependency on the endpoints of third party services is the project's core fragility, and nothing in the packaging addresses it.

Editorial conclusion

Adopt svtplay-dl if you regularly need an offline copy of a stream from one of the listed public sites and you are comfortable with a script that depends on ffmpeg and on the site continuing to serve the same endpoints. Do not adopt it as a long lived part of a product pipeline, since the list of supported services and the internals of each site change without notice, and no GitHub releases are published for the project. Before you install, check that your Python is 3.9 or newer, because setup.py refuses anything older even though the documentation says 3.6, and install ffmpeg at the same time, since without it the DASH and postprocessing paths will not work.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. spaam/svtplay-dl on GitHub