Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
161 lines (121 loc) · 6.28 KB

CONTRIBUTING.md

File metadata and controls

161 lines (121 loc) · 6.28 KB
Raw

Contributing to Strozz

Thanks for your interest in Strozz. This document covers everything you need to build, run, and develop the app. For what Strozz is and does, see the README.

Strozz is a solo, non-commercial hobby project. Bug reports, feature ideas, and pull requests are welcome, but please keep in mind that reviews and merges may take a while.

Reporting bugs & requesting features

Please open a GitHub issue. For bugs, include your Apple TV model and tvOS version, the channel or stream where it happened, and steps to reproduce. For feature ideas, a short description of what you want and why is plenty.

Requirements

  • macOS with Xcode installed (targets tvOS 18+ and iOS/iPadOS 18+).

  • Homebrew tools:

    brew install xcodegen xcbeautify xcode-build-server

Building and running

Strozz.xcodeproj is generated from project.yml (the source of truth), so generate it first:

./tools/generate-project.sh

Build for the tvOS simulator:

./tools/xcbuild.sh \
	-project Strozz.xcodeproj \
	-scheme Strozz \
	-configuration Debug \
	-destination 'generic/platform=tvOS Simulator' \
	build | xcbeautify

For real Apple TV deployment, use a valid signing team and a device destination. Several features (live playback, Top Shelf) only work on real hardware.

For the initial iPhone/iPad app, use scheme StrozzMobile and destination generic/platform=iOS Simulator. Its source selection shares services with the TV target but excludes the TV interface and Top Shelf extension. See the mobile setup and scope for supported features and simulator test commands. Use the build wrappers for both platforms.

Twitch auth setup (no committed secrets)

Twitch device auth needs a Twitch app client_id, but you don't commit it to this repo.

  1. Copy Config/TwitchSecrets.xcconfig.local.example to Config/TwitchSecrets.xcconfig.local.

  2. Set your value:

    TWITCH_CLIENT_ID = your_real_client_id

Important:

  • Do not use Twitch's public web client ID (for example kimne78kx3ncx6brgo4mv6wki5h1ko). If you do, the consent page will show "Twilight" and followed-channel APIs may fail.
  • Create your own Twitch app in the Twitch Developer Console and use that Client ID.

Config/TwitchSecrets.xcconfig.local is gitignored (*.xcconfig.local), so your ID stays local.

On Apple TV, sign-in uses the Twitch Device Code flow: start sign-in on the TV, then complete approval on your phone or browser using the shown code/link. On iPhone/iPad, open the approval link from Account on that device and return to Strozz after approving.

Working in git worktrees

Because the secrets file is gitignored, it does not exist in freshly created worktrees. After making a new worktree, run the bootstrap helper from inside it:

./tools/bootstrap-worktree.sh

This copies Config/TwitchSecrets.xcconfig.local from your primary checkout and regenerates the Xcode project. Without it, builds fail with "Missing Twitch client ID".

Versioning & releases

Strozz follows the standard Apple two-number scheme, and both numbers update automatically — you should not normally edit version numbers by hand:

  • Marketing version — CFBundleShortVersionString, a semver like 0.2.0, defined by MARKETING_VERSION in project.yml. It bumps one minor per feature merged into main. The version-bump GitHub Actions workflow runs on every push to main, runs tools/bump-version.sh (minor +1, patch → 0), and commits the change back to main with a [skip ci] marker. Bot pushes don't retrigger Actions, so the bump can't loop.
  • Build number — CFBundleVersion, a monotonic integer derived from git rev-list --count HEAD by the postBuildScripts in project.yml (the app and the Top Shelf extension are kept in lockstep). It is set at build time and never hand-edited.

Manual bump (e.g. a major release): run tools/bump-version.sh or edit MARKETING_VERSION in project.yml, then tools/generate-project.sh.

The current tvOS release lanes ship to TestFlight with fastlane using an App Store Connect API key:

cp .env.fastlane.example .env.fastlane   # fill in ASC_KEY_ID / ASC_ISSUER_ID / ASC_KEY_PATH
fastlane beta --env fastlane             # archive a Release build + upload to TestFlight

.env.fastlane and the .p8 key are gitignored — never commit them. Other lanes: fastlane build (archive only, no upload), fastlane release, fastlane metadata.

How playback works

Apple TV has no official Twitch playback SDK. Strozz resolves playback via the Twitch GraphQL PlaybackAccessToken and Usher HLS playlists, similar in spirit to open-source clients like Streamlink and Frosty. Playback is AVPlayer-backed with custom overlay controls and an in-process low-latency HLS proxy — see docs/low-latency.md for the details of that work.

This project is non-commercial and ad-respecting.

Tech stack

  • Swift / SwiftUI targeting tvOS.
  • AVPlayer-backed playback with custom overlay controls and an in-process low-latency HLS proxy.
  • Twitch EventSub / Hermes for real-time raids, polls, predictions, and live events.
  • A Top Shelf app extension for the tvOS home screen.
  • XcodeGen project generation (project.yml is the source of truth).

Things Strozz intentionally does not do

  • Automatically spend points or farm unseen channels. The optional rewards connection can collect Twitch-provided watch bonuses only during real, advancing playback; the viewer can disable this in Accounts. Spending points always requires confirmation and a fresh price/availability check. Poll votes are free only; Bits and prediction wagers are not supported. Rewards use a separate Twitch TV connection because Twitch rejects the app's ordinary OAuth login on its private rewards API. Authentication happens on Twitch's own device-activation page, not through an in-app password form.
  • Follow / unfollow. Strozz can show who you follow, but Twitch now blocks follow/unfollow mutations from this app context with integrity checks. Use the official Twitch app or website to change follows.