copilot/frosty
1
0
Fork 0
Code Issues Pull requests Projects Releases 11 Packages Wiki Activity Actions
frosty/DESIGN.md
copilot 9d392d8d6a
All checks were successful
Actions probe / probe (push) Successful in 0s
Details
Release APK / Build & publish release (push) Successful in 7m41s
Details
Add stream language filter and fix directory infinite scroll. 
Settings multi-select filters Top/category/tag lists via Helix (with over-fetch for multiple languages). Larger Helix pages, safer cursors, and scroll near-end loading restore pagination; GQL page-2 integrity failures end the list cleanly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-01 10:51:10 +02:00

3.2 KiB
Raw Permalink Blame History

Frosty fork — Twitch ad blocking (DESIGN)

Personal Forgejo fork of tommyxchow/frosty that adds TwitchAdSolutions (vaft)-style live ad blocking.

Canonical living plan: session active-plan.md for conversation 37b527bf-e540-4753-be1f-39906fe2ba28. ADR: ADR-026.

Problem

Upstream Frosty plays Twitch HLS (native) or player.twitch.tv (WebView). Twitch may stitch ad pods into the media playlist (stitched / EXT-X-DATERANGE). Upstream only detects native ad breaks (to avoid bogus latency recovery); it does not block ads. Turbo/sub hide_ads via linked web session is separate and not a client blocker.

Approach (vaft-equivalent)

Browser vaft hooks Worker/fetch and rewrites m3u8. Frosty’s native player cannot do that from Dart (loadUrl + headers only).

Layer Behavior
Primary token GQL PlaybackAccessToken with playerType=popout (vaft ForceAccessTokenPlayerType) when Settings blockTwitchAds is on
Ad break Native adBreakStream → probe backup types embed → popout → autoplay; accept first Usher multivariant whose sampled media playlist lacks stitched; loadUrl that URL
Ad end Restore primary popout Usher URL
WebView Best-effort inject of vendored assets/js/vaft.user.js (not true document-start on Android)
UI Settings toggle (default on; enabling forces native player); overlay “Blocking ads”

Key code

  • lib/apis/twitch_ad_solutions.dart — constants + TwitchAdFreePlayback
  • lib/apis/twitch_gql_api.dart — playerType / platform, fetchPlaylistText
  • lib/screens/channel/video/native_video_store.dart — load + swap
  • lib/screens/channel/video/video_store.dart — WebView inject
  • lib/screens/settings/stores/settings_store.dart — blockTwitchAds
  • assets/js/vaft.user.js — upstream TwitchAdSolutions script

Non-goals (v1)

  • Upstream PR
  • Full Worker prototype cleaning
  • Third-party proxies
  • HLS segment stripping inside better_native_video_player (unless smoke tests demand it)

Tags + viewer sort (v5.2.2+)

Helix cannot filter by freeform tags or sort ascending. GQL covers both:

  • Search: SearchFreeformTags → tap → TagStreams (streams + freeformTags)
  • Sort: Top (asc), category (game.streams), tag — VIEWER_COUNT / VIEWER_COUNT_ASC via StreamSortButton

Key code: lib/apis/twitch_gql_api.dart, lib/screens/home/search/, lib/widgets/stream_sort_button.dart, ListStore / ListType.tag.

Stream languages (v5.2.4+)

Settings → General → Stream languages (multi-select chips). Default de. Applied to Top, category, and tag lists.

  • One language: Helix language= (paginates cleanly, first=100)
  • Several languages: Helix over-fetch + client filter (still paginated)
  • Tags / ascending sort: GQL with languages: [Language!]; page-2 often hits Twitch integrity — treated as end-of-list after the first page of 30

Also fixed infinite scroll: larger Helix pages, defensive cursors, scroll near-end load-more, and stop disposing shared Home scroll controllers.

Build

Flutter 3.47.0 (pinned in pubspec.yaml). Local SDK: /home/yuna/.local/flutter-3.47.0.