fix: pin video quality to stop OBS source resizing; add audio-only mode

Live testing (2026-09-07) showed two real problems in one root cause:
LiveKit's default subscriber behavior lets the SFU switch simulcast
layers on its own bandwidth/adaptive logic, and this plugin never told
it not to. For a real camera, that showed up as the OBS source's
received frame size visibly hopping between 320x180/640x360/1280x720
mid-show -- OBS's async video source resizes to match, breaking any
manual crop/position a director had set up. For the soundboard (a
Camera-source track that exists only to satisfy RTMP's video
requirement -- Soundboard.tsx -- with no real visual content), the
same instability, plus the video showing at all, was pure noise: there
was no way to pull just its audio.

Both come from RemoteTrackPublication (livekit/remote_track_publication.h
in the pinned SDK), on the exact publication object TrackSubscribedEvent
and attachExistingTracks already hand this code:

  - setVideoQuality(VideoQuality::HIGH) on every wanted video track,
    unconditionally, so the SFU always sends the top simulcast layer
    instead of switching layers underneath a source with no
    rendered-size hint to give it (this is a native subscriber, not a
    sized <video> element).
  - A new SessionConfig::subscribe_video (mirrors subscribe_audio):
    when false, the wanted video track is never attached, and its
    publication is explicitly setEnabled(false) -- the SFU stops
    sending it, not just "decoded and discarded here". Wired to a new
    "Audio only (no video)" checkbox in the source's properties.

Both call sites (a fresh TrackSubscribedEvent, and attachExistingTracks
sweeping tracks already up when the session starts watching) go
through one new handleWantedVideoTrack() so they can't drift apart.

Not unit-testable without a real LiveKit connection (RemoteTrackPublication
isn't fakeable, matching why test_integration_livekit.cpp already needs a
real server) -- verified instead by a full local build against real
libobs-dev + the pinned SDK (clean compile, all 6 existing tests still
pass) and CI. The actual behavioral fix -- stable resolution, no video
for an audio-only source -- needs the same real-OBS verification every
other claim in this repo's "What is verified, and how" section does.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RL8abRmgFXkVASHkkqiJbE

core/include/stplugin/session.h

@@ -43,6 +43,13 @@ struct SessionConfig {
 
     bool subscribe_audio = true;
 
+    /// False for an audio-only source (the soundboard, say): the wanted
+    /// video track is never attached (no AttachVideo command posted), and
+    /// its publication is explicitly disabled server-side (RemoteTrack-
+    /// Publication::setEnabled(false)) so the SFU stops sending it at all --
+    /// not just "decoded and discarded here", genuinely not delivered.
+    bool subscribe_video = true;
+
     /// How long connect() waits for the room to come up before giving up.
     int connect_timeout_ms = 15000;
 };

core/src/session.cpp

@@ -218,6 +218,52 @@ struct LiveKitSession::Impl : public livekit::RoomDelegate {
         queue_cv.notify_one();
     }
 
+    // Handles the wanted video track once matched, shared by onTrackSubscribed
+    // (a fresh subscription) and attachExistingTracks (one already up when
+    // this session started watching). Two responsibilities that only make
+    // sense together, both keyed off the SAME publication:
+    //
+    //   - subscribe_video: an audio-only source (the soundboard) never wants
+    //     this video at all. Rather than attach it and let the OBS adapter
+    //     discard every decoded frame, disable the publication itself
+    //     (RemoteTrackPublication::setEnabled(false)) so the SFU stops
+    //     sending it -- real bandwidth saved, not just wasted decode.
+    //   - Fixed video quality: LiveKit's default subscriber behaviour lets
+    //     the SFU switch simulcast layers per its own adaptive/bandwidth
+    //     logic, which for a source with no rendered-size hint (this is a
+    //     native C++ subscriber, not a sized <video> element) means the
+    //     received resolution can hop between layers -- observed live as OBS
+    //     source geometry visibly changing size mid-show. Pinning to HIGH
+    //     asks the SFU to always send the top layer, which is what a fixed
+    //     OBS source needs regardless of bandwidth (the plugin has no
+    //     picture-in-picture tier to fall back to the way a browser grid
+    //     view would).
+    void handleWantedVideoTrack(const std::shared_ptr<livekit::Track> &track,
+                                 const std::shared_ptr<livekit::RemoteTrackPublication> &publication)
+    {
+        if (!config.subscribe_video) {
+            if (publication) {
+                try {
+                    publication->setEnabled(false);
+                } catch (const std::exception &) {
+                    // Best-effort: worst case this track keeps being
+                    // delivered and decoded, wasting bandwidth -- it is
+                    // still never attached to OBS below.
+                }
+            }
+            return;
+        }
+        if (publication) {
+            try {
+                publication->setVideoQuality(livekit::VideoQuality::HIGH);
+            } catch (const std::exception &) {
+                // Best-effort: worst case this track keeps whatever quality
+                // it already had, which is the pre-existing behaviour.
+            }
+        }
+        post(CommandType::AttachVideo, track);
+    }
+
     // --- RoomDelegate ------------------------------------------------------
 
     void onTrackSubscribed(livekit::Room &, const livekit::TrackSubscribedEvent &event) override
@@ -230,7 +276,7 @@ struct LiveKitSession::Impl : public livekit::RoomDelegate {
             event.publication ? toMediaSource(event.publication->source()) : MediaSource::Unknown;
 
         if (isWantedVideoTrack(config.participant_identity, identity, kind, source))
-            post(CommandType::AttachVideo, event.track);
+            handleWantedVideoTrack(event.track, event.publication);
         else if (config.subscribe_audio && isWantedAudioTrack(config.participant_identity, identity, kind, source))
             post(CommandType::AttachAudio, event.track);
     }
@@ -551,7 +597,7 @@ struct LiveKitSession::Impl : public livekit::RoomDelegate {
             const MediaKind kind = toMediaKind(track->kind());
             const MediaSource source = toMediaSource(publication->source());
             if (isWantedVideoTrack(config.participant_identity, identity, kind, source))
-                post(CommandType::AttachVideo, track);
+                handleWantedVideoTrack(track, publication);
             else if (config.subscribe_audio && isWantedAudioTrack(config.participant_identity, identity, kind, source))
                 post(CommandType::AttachAudio, track);
         }