Skip to content

Building from Source

Jump to bottom
OnlyXianzo edited this page Jun 10, 2026 · 1 revision

Building from Source

This guide walks you through building TrueStream from source for Android, Windows, and Linux. You'll find the prerequisites, setup steps, build commands, and testing instructions you need to compile the app yourself.

Prerequisites

Before you start, make sure you have the following installed on your machine.

Dependency Version Notes
Flutter SDK Stable (3.x) Install via flutter upgrade or your package manager
Dart Bundled with Flutter Ships with the Flutter SDK
Python 3.11+ Required for the engine and Chaquopy on Android
Android SDK 34+ Required for Android builds
Java 17 Required for Android builds
CMake 3.31+ Required for Android Chaquopy builds

Runtime dependencies

FFmpeg and aria2c are not bundled in the source build. They're downloaded automatically on the app's first launch, with SHA-256 verification before extraction. You can also point to custom binary paths in Settings.

Clone and setup

Start by cloning the repository and installing dependencies.

git clone https://github.com/OnlyXianzo/TrueStream.git
cd TrueStream

Flutter dependencies

flutter pub get

Python engine setup

If you're doing local development or running Python tests, set up a virtual environment and install the engine in editable mode.

python3 -m venv .venv
source .venv/bin/activate
pip install -r engine/requirements.txt
pip install -e engine/

On Windows, use .venv\Scripts\activate and pip as appropriate.

Build commands

Android

Chaquopy bundles Python 3.11 and the engine directly into the APK. yt-dlp and curl_cffi are installed via pip during the Gradle build.

# Release APK
flutter build apk --release

# Debug APK
flutter build apk --debug

The output lives at build/app/outputs/flutter-apk/app-release.apk.

  • minSdk is set to 24, required by Chaquopy.
  • ABI filters target arm64-v8a and x86_64.
  • For signing, place a key.properties file in android/ with your storeFile, storePassword, keyPassword, and keyAlias.

Windows

The Python engine is not embedded in the desktop binary. You need to copy it alongside the release bundle, or rely on the built-in bootstrapper that downloads it on first launch.

flutter build windows --release

# Copy the Python engine into the bundle
xcopy /E /I engine\truestream_engine build\windows\x64\runner\Release\truestream_engine

The output goes to build/windows/x64/runner/Release/.

Linux

The Linux build follows the same approach as Windows.

# Install Linux build dependencies
sudo apt-get install -y ninja-build libgtk-3-dev liblzma-dev

flutter build linux --release

# Copy the Python engine into the bundle
cp -r engine/truestream_engine build/linux/x64/release/bundle/

The output goes to build/linux/x64/release/bundle/.

Running tests

Flutter tests

flutter test

This runs widget and unit tests located under test/.

Python engine tests

pytest engine/tests/ -v

This runs 91+ unit tests covering config, errors, format selection, options building, paths, playlists, and other engine modules.

Static analysis

dart analyze

This must pass with zero errors before you commit.

GitHub Actions

Two workflows are available in .github/workflows/.

Verification

The verification workflow triggers on every push and pull request to main. It runs:

  • flutter analyze
  • flutter test
  • pytest engine/tests/ -v

Build and release

The build workflow is a manual trigger (workflow_dispatch). It builds all three platforms:

  • Android — APK uploaded as an artifact.
  • Windows — release bundle with the engine copied alongside.
  • Linux — release bundle with the engine copied alongside.

To trigger it, go to GitHub, then Actions > Build and Release > Run workflow.

Platform-specific notes

  • Android minSdk: 24, required by Chaquopy. Devices must run Android 7.0 or later.
  • Python bundling on Android: The Chaquopy Gradle plugin compiles engine/ into the APK. yt-dlp and curl_cffi are installed via the pip block in build.gradle.kts.
  • Python bundling on desktop: The engine is not bundled. You must copy the truestream_engine directory alongside the binary, or the bootstrapper downloads it on first launch.
  • Binary bootstrapper: FFmpeg and aria2c are downloaded at runtime, SHA-256 verified, and extracted. You can also configure custom paths in Settings.
  • FFmpeg: Required for media processing like merging and remuxing. Roughly 25-35 MB.
  • aria2c: Download accelerator for faster concurrent chunked downloads. Roughly 3-5 MB.
  • iOS and Web: Not currently supported as target platforms.

Clone this wiki locally