Repository navigation
Troubleshooting
TrueStream is in active development. You might run into issues from time to time, and most of them have a straightforward fix. This page covers common problems and their solutions.
If the engine fails to download or extract on first launch, check your internet connection first. The bootstrapper downloads FFmpeg and aria2c from a CDN, so a firewall or proxy could be blocking the request.
If your network restricts outgoing connections, you can download the binaries manually and point to them in Settings > Custom binary paths. The app shows the expected SHA-256 hash for each binary on the bootstrap screen, so you can verify the download yourself.
Desktop builds don't bundle the Python engine. If you see an error about the engine being missing, you probably haven't set up the virtual environment yet.
Run the following from the project root:
python3 -m venv .venv
source .venv/bin/activate
pip install -r engine/requirements.txtMake sure you're using Python 3.11 or later. You can verify your Python version with python3 --version.
This usually means yt-dlp's extractors are out of date or the site has changed its layout. Try switching your engine update channel. Go to Engine settings and change the update channel from Stable to Nightly or Master, then restart the app.
If the issue persists, the site might be blocking automated access. Try the Cookie WebView workaround described below.
Some sites restrict available formats when you're not signed in. TrueStream includes a Cookie WebView that lets you log into your account and export session cookies to the engine.
Open the Cookie WebView from the settings menu, log into the site, and the cookies will be passed to yt-dlp automatically. After that, try fetching formats again.
If you see an FFmpeg-related error during download, the binary may have been corrupted during the initial download. The easiest fix is to close and re-launch the app. The bootstrapper verifies the binary's SHA-256 hash on every startup and will re-download it if the check fails.
If re-launching doesn't help, you can manually download FFmpeg and set the path in Settings > Custom binary paths.
Rate limiting means the site has detected too many requests from your IP address in a short time. You have two options:
- Enable a proxy in Network settings. TrueStream supports HTTP, HTTPS, and SOCKS5 proxies.
- Wait a few minutes before retrying the download.
Repeated rate limiting over a long period may indicate you need to authenticate through the Cookie WebView.
If sharing a link from another app doesn't open TrueStream, the app might not be set as the default handler for link sharing.
Go to your device's Settings > Apps > Default apps > Opening links, find TrueStream, and make sure it's allowed to open supported links. You may also need to check Share intent under the app's own settings screen.
A corrupt cache or configuration can cause the app to crash immediately. Try clearing the app's data:
- Go to your device's Settings > Apps > TrueStream > Storage.
- Tap Clear data or Clear storage.
- Re-launch the app.
If the crash persists after clearing data, uninstall the app and reinstall it from a fresh build.
TrueStream is in active development. If you encounter an issue not listed here, please open a bug report on GitHub.