feat(llc)!: split the StreamVideo start-up and clean up its options

[renefloor]

Fixes FLU-854

Part of FLU-859 · 26/26, stacked on #1440

What changed

• One builder. StreamVideo(...) builds through StreamVideo.create and then installs the singleton, so the forwarding is written once. StreamVideo.forTesting (C2) keeps its seams.

• Start-up is one awaitable ready future. The constructor used to start four things with no handle on them. ready now covers:

  • the audio configuration;
  • the token pre-warm;
  • the environment collection;
  • the auto-connect.

  It completes once they have run, and never with an error; failures are logged as before.

• Logging only from the singleton path. _setupLogger used to run in every constructor and changed the process-wide StreamLog() for every instance, test ones included. Now StreamVideo(...) applies logPriority and logHandlerFunction. A client from create doesn't; StreamVideo.configureLogging is the explicit call for it.

• failIfSingletonExists: false disposes the client it replaces (InstanceHolder), instead of only disconnecting it.

• A client for background push handling sets up no media.

  • StreamVideo.runWithoutMedia(body) runs body in a zone. A client built inside it, setsUpMedia == false:
    • applies no audio configuration;
    • creates no RtcMediaDeviceNotifier;
    • builds calls that never create it either: the call's notifier is lazy, and a call skips its native WebRTC and web audio observers.
  • StreamVideoPushHandler.handleBackgroundMessage builds its client through it. The zone carries through the app's async createStreamVideo, so the app changes nothing.
  • CallHost gains setsUpMedia.

• Builders moved out of the constructor: NetworkMonitorSettings.build() makes the InternetConnection, and ClientEventReporter.create the reporter or the no-op one.

• Options:

  • The deprecated androidAudioConfiguration is removed.
  • The no-op precacheGenericSdps parameter is removed.
  • MutableClientState no longer holds a second reference to the options; it takes the two values it reads, allowMultipleActiveCalls and multiCallAudioPolicy.

Decisions to check

• The handler path, not an option, for background push handling. The ticket left the choice open. An option the app sets in createStreamVideo relies on every app remembering it, and the media setup happens anyway when one forgets. The zone needs no app change, because the handler already owns the call to createStreamVideo. runWithoutMedia is public, so an app with its own background handler can use it too.
• tokenLoader, onTokenUpdated and pushNotificationManagerProvider stay constructor parameters. They belong to the user and the app wiring, not to tunable behaviour, and moving them into StreamVideoOptions would make the options per-user.
• ready waits for the auto-connect. An app that awaits it before showing the call list gets a connected client, or a logged failure. Without autoConnect, it waits only for the audio configuration and the environment.
• A client built without media cannot join. The doc says so, but nothing enforces it; a join would create the notifier lazily as usual. The background handler never joins: it observes only the incoming and declined events.

Tests

• stream_video_without_media_test (3), on Android with a mock RtcMediaDeviceNotifier.instance:
  • declining a ring from a client built without media touches the notifier zero times;
  • accepting one touches it zero times;
  • a client built outside it does apply the audio configuration, which shows the check can see a touch.
• Mutation checks for those tests: dropping the client's media guard or the call's observer guard fails both no-media tests.
• stream_video_constructor_test (4):
  • ready completes after the auto-connect, also when it fails;
  • replacing the singleton disposes the old client (fails when it only disconnects);
  • only the singleton sets up logging from its options.
• background_push_handler_test: the factory runs without media, also after an await, and the zone ends with it.
• Fixture: MockCallHost answers setsUpMedia with true.
• Results:
  • stream_video: 1316 passed;
  • stream_video_push_notification: 68;
  • stream_video_flutter without goldens: 729.
• Every package's lib and dogfooding analyze without errors.

🤖 Generated with Claude Code

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

❌ Patch coverage is 86.25000% with 11 lines in your changes missing coverage. Please review.
✅ Project coverage is 44.69%. Comparing base (c40daa4) to head (3710761).

Files with missing lines	Patch %	Lines
packages/stream_video/lib/src/stream_video.dart	85.36%	6 Missing ⚠️
...stream_video/lib/src/network_monitor_settings.dart	70.00%	3 Missing ⚠️
...deo/lib/src/call/media/local_media_controller.dart	50.00%	1 Missing ⚠️
...ckages/stream_video/lib/src/core/client_state.dart	93.75%	1 Missing ⚠️

Additional details and impacted files

@@                    Coverage Diff                     @@
##           feat/flu-852-call-host    #1441      +/-   ##
==========================================================
+ Coverage                   44.58%   44.69%   +0.10%     
==========================================================
  Files                         423      423              
  Lines                       31495    31505      +10     
==========================================================
+ Hits                        14041    14080      +39     
+ Misses                      17454    17425      -29     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.