StreamCap: A Multi-Platform Live Stream Recorder Built on FFmpeg

What StreamCap Records, and What It Refuses To Do

StreamCap solves a narrow problem: a live room goes online at an unpredictable time, and you want the stream on disk without watching for it. The README describes it as a multi-platform live stream recording client built on FFmpeg and StreamGet, covering 40 or more platforms, with batch recording, loop monitoring, timed monitoring and automatic transcoding. The audience is anyone maintaining an archive of broadcasts: a researcher tracking a set of channels, a moderator keeping evidence of a stream, or a viewer who cannot watch live.

It is not a screen recorder. It does not capture your desktop, a browser tab or a game. It takes a room URL, resolves the stream through the streamget library, and hands the resulting media URL to FFmpeg. That distinction explains most of its behavior, including why an unlisted platform simply fails rather than falling back to generic capture.

How the Recorder Resolves a Room and Streams It to Disk

The dependency list in pyproject.toml shows the shape of the system. streamget>=4.0.10 is the platform layer that turns a room URL into a playable stream address. FFmpeg does the actual writing. flet and flet-video provide the desktop UI, and the same codebase can run as a web app. The repository also ships an app/api/video_stream_service module, exposed as a second service in docker-compose.yml on port 6007, which serves recorded video.

Monitoring is the part that matters. The README says loop monitoring checks a room's status in real time and records as soon as it goes live, while timed tasks check status only within a configured time range. Output formats listed are ts, flv, mkv, mov, mp4, mp3 and m4a, with optional automatic transcoding to mp4 after recording. There is also a push notification feature for stream status, so the client can tell you a room went live rather than only recording it.

The architecture is therefore a polling loop plus an external process. StreamCap does not hold the media itself; FFmpeg writes the file, and StreamCap manages when to start and stop it. That is why the README tells you to install FFmpeg separately and configure its environment variable if the program reports it missing.

Installing StreamCap from a Release or from Source

The quickest path is a prebuilt package. According to the README, Windows users download StreamCap.zip from the releases page and run StreamCap.exe after extracting, while macOS users download StreamCap.dmg and install it. No Python is involved in that route.

Running from source requires Python 3.10 or higher. The README gives these steps, starting with the clone and the core dependency.

git clone https://github.com/ihmily/StreamCap.git
cd StreamCap
pip install -i https://pypi.org/simple streamget

Then install the dependency set for the mode you want. The desktop client uses requirements.txt; the web build uses requirements-web.txt.

pip install -r requirements.txt

pip install -r requirements-web.txt

First Run: Desktop, Web and Docker

The README says to copy the example environment file and rename it to .env before the first launch.

cp .env.example .env

On Windows and macOS the default mode is the desktop program, started with main.py.

python main.py

The README states that Linux should run in web mode. Either set PLATFORM to web in the .env file, or pass the --web flag directly. Once started, the README says the interface is reachable at http://127.0.0.1:6006.

python main.py --web

For a machine without Python, the README gives a compose path. Docker and Docker Compose must already be installed, and a .env file must exist in the project root. The compose file maps port 6006 by default, sets TZ with a default of Asia/Shanghai, and mounts ./logs, ./config, ./downloads and ./.env.

docker compose up

Where StreamCap Breaks, and When Not to Use It

The README itself flags the sharpest limitation. Several example URLs carry the note that they are one-time addresses and do not support loop monitoring: the Xiaohongshu short link, Huajiao, and Taobao. That is not a bug in the client, it is the platform handing out a session-bound URL that stops resolving. If your workflow depends on loop monitoring, check that your platform's example is not marked this way.

YouTube is the other documented exception: the README says it requires a cookie to be configured. Any platform that gates streams behind login will behave the same way, and the README does not describe a cookie refresh mechanism for it. There is also no documented rollback, no documented retention policy, and no documented behavior for what happens when a recording is interrupted mid-file. The README does not document rollback, so plan for partial files as a possibility rather than assuming clean recovery.

Finally, the project is not archived and its last push was on 2026-09-01, so it is being worked on, but platform extractors break whenever a site changes its player. The version history shows v1.0.3 on 2026-05-13, v1.0.2 on 2025-08-16 and v1.0.1 on 2025-05-23, which is a release cadence measured in months, not weeks. Between releases, a broken platform stays broken unless streamget ships a fix.

StreamCap Versus yt-dlp for Live Recording

The closest general alternative is yt-dlp, which also wraps FFmpeg and also resolves platform URLs, but the approach differs in two concrete ways. yt-dlp is a command line tool you invoke per URL, often through a scheduler you write yourself; StreamCap is a persistent client with its own polling loop, a desktop UI and a web mode, so the monitoring lives inside the application rather than in cron. Second, StreamCap's platform coverage is curated and region-specific: the README lists 30 or more Chinese platforms including Douyin, Kuaishou, Huya, Douyu and Bilibili alongside overseas ones such as TikTok, Twitch, CHZZK and PandTV. yt-dlp's extractor set is broader and maintained by a much larger contributor base, but it does not ship a GUI or a built-in live-status monitor. If you want a library to embed, yt-dlp is the more natural dependency. If you want a running application that watches rooms for you, that is the gap StreamCap fills.

Licence, Upgrade Cost and the Docker Path

StreamCap is released under Apache-2.0, per the README and the license field in pyproject.toml. That permits commercial use and modification, and it includes an explicit patent grant. It also means if you modify and distribute the software you must preserve the licence and state changes. This is a description of the licence text, not legal advice; check the LICENSE file for the terms that apply to you.

Upgrade cost is dominated by two moving parts. FFmpeg is installed by the Dockerfile from the Debian package set, so container builds pick up whatever the base image offers. streamget is pinned as streamget>=4.0.10, a floor rather than a ceiling, so a fresh install can pull a newer extractor set than the one the release was tested against. The Docker path is the most reproducible: docker-compose.yml mounts ./logs, ./config, ./downloads and ./.env, sets TZ with a default of Asia/Shanghai, and defines a healthcheck that curls http://localhost:${PORT:-6006}/about. The video_api service runs python -m app.api.video_stream_service on port 6007 and reads CUSTOM_VIDEO_ROOT_DIR, which defaults to ./downloads. Note the README's warning that the image in the Docker registry may not match the latest main branch; build locally with docker build -t streamcap . if you need the current code.

Editorial conclusion

StreamCap fits people who need unattended, scheduled archiving of specific live rooms on the platforms it lists, and who are willing to keep FFmpeg and the platform extractors current. It is the wrong tool for one-off local screen capture, for platforms outside its supported list, and for anyone who needs a documented recording API or a stable plugin contract. Verify first that your target platform URL appears in the README's example list and that FFmpeg is on PATH; if the URL is not listed, assume it is unsupported until you test it.

Frequently asked questions

Official sources

1. ihmily/StreamCap on GitHub
2. Issues
3. License: Apache-2.0
4. README
5. Releases