AniStream Docs: CLAUDE.md — overview & index · CODING_RULES.md — tech constraints · DESIGN.md — UI/UX rules · ARCHITECTURE.md — structure & platform · API.md — data & caching · README.md — project intro · CONTRIBUTING.md — PR process Covers: project introduction, feature overview, developer setup/build instructions, and licensing. See also: CLAUDE.md for the doc suite's own index and AI/human working norms, ARCHITECTURE.md for the
lib/folder structure and the optional Go server, CONTRIBUTING.md for the PR process. Disclaimer: Until we release v1.0.0, the current releases (up to v0.3.0) are built via Wails (a Svelte frontend with a Go backend, opened via your default webview). That version was built with entirely different tools and is also far more behind in development — in design, compatibility, features, optimizations, and general polish. The description below covers the complete new version of the app, which has not been released yet.
| Doc | Purpose | Start here if you want to… |
|---|---|---|
| CLAUDE.md | Project overview, AI/human working norms, and the index tying the whole doc suite together | …get oriented, or find which doc covers what |
| CODING_RULES.md | Strict, enforced coding rules — performance, state management, caching, linter compliance | …know what a PR or an AI-generated change needs to satisfy |
| DESIGN.md | Visual language, design tokens, TV/D-pad rules | …build or review UI |
| ARCHITECTURE.md | lib/ folder structure, native platform layer, the optional Go server |
…know where a file belongs, or how a platform-specific piece works |
| API.md | AniList & Nyaa.si integrations, scraping, caching | …touch networking, scraping, or tracking |
| CONTRIBUTING.md | PR process, checklist, Code of Conduct | …submit a change |
AniStream started off from two separate ideas from the two of us.
- Ease of use for torrenting animes.
- Automatic tracking for animes you watch.
This is what the app has now become: AniStream is an application that lets you stream anime torrents instantly without waiting for them to finish downloading completely. By combining a sequential torrent engine with mpv, you get the high quality of raw torrents with the seamless convenience of modern streaming platforms.
The app is built entirely in Flutter and Dart (well, technically, optionally Go also). It is compatible with Windows, Linux, MacOS, Android (Android based TVs included) and iOS. Take in mind that neither of us can really test MacOS and iOS, since we do not have any device for that.
- P2P Playback: Click on an episode, and streaming begins within seconds. The app utilizes a high-performance C++ torrent engine (
libtorrent) with time-critical piece deadlines to stream data sequentially. - Progress Tracker: You can log in via OAuth2 into your AniList account. Watching an episode past the 90% mark triggers an automated progress update to your AniList account/library.
- AniList Library: The app automatically pulls your current Watching and Plan to Watch and Watched lists into a personalized library view.
- Calendar: You can view weekly upcoming animes.
- Hardware Acceleration: Powered by the
media_kitpackage, the video player taps directly into your OS graphics pipeline for decoding with near-zero CPU usage.
- The Scraper: When you select an episode, a background Dart isolate queries Nyaa.si RSS feeds, cross-references it with the AniList GraphQL metadata, and assigns a weighted quality score to find the absolute best torrent. (Full scoring rubric and query details: API.md.)
- The Streaming Pipeline: The chosen magnet link is fed into
libtorrent_flutter. Instead of downloading randomly, the engine creates a highly optimized local HTTP streaming server and requests sequential piece deadlines from peers. (Or, optionally, offloaded to the companion Go server — see ARCHITECTURE.md § 6.) - The Native Player: The local stream URL is passed directly to
media_kit. Because Flutter renders UI using its own 2D graphics engine (Impeller), the video frames and the UI overlays are composited onto the exact same native OS window simultaneously, entirely eliminating Z-index bugs and OS rendering conflicts.
If you want to compile AniStream from source, modify components, or run a local development build, follow the setup instructions for your operating system below. For the project's folder structure and where new code belongs, see ARCHITECTURE.md.
Flutter requires standard C++ build tools and GTK3 headers to compile the Linux desktop window.
For Arch Linux:
sudo pacman -S base-devel cmake ninja pkgconf mpv gitFor Ubuntu / Debian:
sudo apt update
sudo apt install build-essential cmake ninja-build pkg-config libgtk-3-dev mpv gitThe cleanest way to install Flutter on Linux is directly from GitHub.
git clone https://github.com/flutter/flutter.git ~/.flutter-sdkAdd Flutter to your shell path (example for Fish Shell):
fish_add_path -g -p ~/.flutter-sdk/bin(For bash/zsh, add export PATH="$PATH:$HOME/.flutter-sdk/bin" to your .bashrc or .zshrc)
Run the diagnostic tool to automatically download the Dart SDK:
flutter doctorInstall Git via winget:
winget install Git.GitDownload and install the Flutter SDK from the official Flutter website. Extract it somewhere like C:\flutter and add C:\flutter\bin to your PATH environment variable.
Then run the diagnostic tool to verify your setup and download the Dart SDK:
flutter doctorFlutter Windows desktop apps require the MSVC C++ compiler and the Windows SDK.
- Download Visual Studio 2022 Build Tools (or the full Visual Studio 2022 IDE).
- In the installer, select the Desktop development with C++ workload.
- Complete the installation and restart your PC.
After restarting, run flutter doctor again to confirm all Windows requirements are satisfied.
Once your Flutter environment is ready, navigate to the project directory to launch the application.
Fetch the necessary dependencies (like media_kit, libtorrent_flutter, etc):
flutter pub getFlutter handles live hot-reloading automatically. When you save a .dart file, the UI will update instantly without losing its state.
For Linux:
flutter run -d linuxFor Windows:
flutter run -d windowsFor macOS:
flutter run -d macosTo compile a highly optimized, production-ready, standalone binary utilizing the AOT (Ahead-of-Time) compiler, execute:
For Linux:
flutter build linux --release*Outputs to: build/linux/x64/release/bundle/*
For Windows:
flutter build windows --release*Outputs to: build/windows/x64/runner/Release/*
These commands strip debug symbols, aggressively tree-shake unused code, and output a native executable that requires no external VMs or browsers to run.
For Android (Phone or AndroidTV):
flutter build apk --release*Outputs to: build/app/outputs/flutter-apk/*
These commands strip debug symbols, aggressively tree-shake unused code, and output a native executable that requires no external VMs or browsers to run.
Note: AndroidTV currently doesn't use your TV's built in DPU, so if your TV model has a weak GPU it most likely won't run 1080p footage well.
AniStream ships an optional companion Go server (anistream_server/) designed for thin clients — Android TV boxes, phones, or weak laptops — that lack the hardware muscle to run a full BitTorrent engine locally. Instead of seeding and downloading on-device, the Flutter app sends a magnet link to the server over the LAN. The server (running on a PC, NAS, or Raspberry Pi) handles all torrent activity and exposes the resulting video as an HTTP range-request stream that MPV opens directly, giving you remote-playback quality without any of the client-side overhead.
For full setup instructions, CLI flags, the REST API reference, and systemd service configuration, see the AniStream Server README. For how this fits into the rest of the app's architecture, see ARCHITECTURE.md § 6.
Contributions are welcome — bug reports, features, design work, and documentation fixes alike. Please read CONTRIBUTING.md before opening a PR; it covers the coding standards (CODING_RULES.md), the design system (DESIGN.md), and the PR checklist (CONTRIBUTING.md § 6).
AniStream is intended to be licensed under the GNU General Public License v3.0 (GPLv3); a LICENSE file is expected at the repository root, though its presence there is currently pending verification. By contributing, you agree your contributions are made available under the same license — see CONTRIBUTING.md § 8.
AniStream is an open-source architectural proof-of-concept designed as a personal utility. Users assume complete liability for the metadata aggregation parameters, torrent tracking hashes, and compliance with local legal frameworks governing peer-to-peer data transfers. No copyright-infringing media files are hosted, stored, or distributed on this codebase. However, while you are streaming, you will become a seeder for that duration.
Last reviewed against the codebase: 2026-07-28. Changed a setup step, added a feature, or introduced a new top-level doc? Update this file's Documentation Index (§ 1) and relevant section too — see CLAUDE.md's Living Documentation Rule (§ 2).