Merge branch 'master' into ios-render-improv

# Conflicts:
#	ios/RCTWebRTC/WebRTCModule.m
#	package.json

Author: santhoshvai

.claude/skills/upstream-sync.md

@@ -0,0 +1,145 @@
+# Upstream Sync Skill
+
+Sync fork with one or more upstream remotes via cherry-pick + merge-base advance.
+
+## When to use
+
+User says: "sync with upstream", "cherry-pick from X", "merge upstream", or similar.
+
+## Workflow
+
+### Phase 1: Explore divergence
+
+```bash
+git fetch <remote>
+git log --oneline --right-only <branch>...<remote>/master --no-merges
+```
+
+For each upstream-only commit, get files changed:
+
+```bash
+git log --right-only <branch>...<remote>/master --no-merges --format="%h %s" | while read hash msg; do
+  echo "=== $hash $msg ==="; git diff-tree --no-commit-id --name-only -r $hash; echo
+done
+```
+
+### Phase 2: Triage commits
+
+| Category | Action |
+|----------|--------|
+| Already in fork | SKIP |
+| Release/version bumps | SKIP |
+| Lock file only | SKIP |
+| Native WebRTC lib version changes | SKIP (fork uses StreamWebRTC) |
+| Merge commits | SKIP |
+| Cosmetic formatting | SKIP (run formatters separately) |
+| Bug fixes | CHERRY-PICK |
+| New features | CHERRY-PICK (ask user) |
+| Refactoring | CHERRY-PICK (evaluate risk) |
+| Docs/CI/tools | Ask user |
+
+Check for equivalents: `git log --oneline --left-only <branch>...<remote>/master | grep -i "<keyword>"`
+
+### Phase 3: Ask user
+
+Present triage. Ask about large/risky features, optional items, anything ambiguous.
+
+### Phase 4: Cherry-pick in order
+
+```bash
+git checkout -b sync/upstream-cherry-picks <base-branch>
+```
+
+Order: TS fixes → Android fixes → iOS fixes → small features → large features → docs.
+
+If conflict: resolve, `git add`, `git cherry-pick --continue --no-edit`.
+If empty after resolution: `git cherry-pick --skip`.
+
+### Phase 5: Merge to advance merge-base
+
+Without this, future merges replay ALL upstream commits including skipped ones.
+
+```bash
+git merge <remote>/master --no-commit
+
+# Conflicted files — keep ours
+git diff --name-only --diff-filter=U | xargs git checkout --ours
+# Files deleted in our branch — remove
+git rm <deleted-files>
+# Auto-merged files — reset to our version
+git diff --cached --name-only --diff-filter=M | xargs git checkout HEAD --
+# Unwanted new files from upstream — remove
+git diff --cached --name-only --diff-filter=A  # review, then:
+git rm -f <unwanted-files>
+
+git add -A
+git diff --cached --stat HEAD  # should be empty or near-empty
+git commit -m "merge: sync merge-base with <remote>/master"
+```
+
+Verify: `git log --oneline --right-only <branch>...<remote>/master | wc -l` should be `0`.
+
+### Phase 6: Verify
+
+Run ALL of these. Do not skip any.
+
+```bash
+npm run lint
+cd examples/GumTestApp/android && ./gradlew assembleDebug
+cd examples/GumTestApp/ios && pod install && \
+  xcodebuild -workspace GumTestApp.xcworkspace -scheme GumTestApp \
+  -sdk iphonesimulator -configuration Debug build
+```
+
+### Phase 7: Format native files
+
+```bash
+git ls-files | grep -e "\(\.java\|\.h\|\.m\)$" | grep -v examples | xargs npx clang-format -i
+```
+
+Rebuild Android + iOS to confirm, then commit.
+
+### Phase 8: Update package-lock.json
+
+If `package.json` dependencies changed, lock file will be stale.
+
+```bash
+npm install
+git add package-lock.json && git commit -m "chore: update package-lock.json"
+```
+
+## Preservation rules
+
+These MUST NOT change during sync:
+
+| File | Guard |
+|------|-------|
+| `android/build.gradle` | Must keep `io.getstream:stream-video-webrtc-android:*` |
+| `stream-react-native-webrtc.podspec` | Must keep `StreamWebRTC` dependency |
+| `ios/RCTWebRTC/Utils/AudioDeviceModule/` | Fork's custom audio engine — untouched |
+| `SpeechActivityDetector.java` | Fork's custom VAD — untouched |
+| `AudioDeviceModule.ts`, `AudioDeviceModuleEvents.ts` | Fork's custom TS APIs — untouched |
+
+Post-sync: `grep -r "org.webrtc:google-webrtc\|webrtc-ios" --include="*.gradle" --include="*.podspec" .` must return nothing.
+
+## Pitfalls
+
+1. **Always run native builds, not just tsc.** Cherry-picks can pass tsc but fail gradlew/xcodebuild.
+
+2. **Native API names differ across WebRTC versions.** Enum values, type names, and method signatures may not exist in our WebRTC SDK. After cherry-picking from a fork on a different WebRTC version, verify types exist before building.
+
+3. **`git add -A` re-adds files you removed.** Use `git rm -f` (not `--cached`) to remove from both index and disk.
+
+4. **Auto-merged files need `git checkout HEAD --`, not `--ours`.** `--ours` only works on conflicted files. For auto-merged files with unwanted changes, use `git checkout HEAD -- <file>`.
+
+5. **Watch for duplicates after conflict resolution.** Duplicate variable declarations, closing braces, or imports when keeping both sides of a conflict.
+
+6. **Advance merge-base for EVERY upstream remote.** If syncing with multiple upstreams, merge each one separately. Otherwise the un-advanced remote replays all its history on the next merge.
+
+7. **Upstream podspec/build files leak into cherry-picks.** Other forks have their own podspec (e.g., `livekit-react-native-webrtc.podspec`). Always `git rm` them when they appear.
+
+8. **Cross-check cherry-picks against all upstreams for reverts.** Before cherry-picking a commit from one upstream, search the other upstreams for the same change — it may have been tried and reverted. Run: `git log --all --oneline -S "<key code snippet>"` to find if the same change exists elsewhere in history with a subsequent revert.
+
+9. **Verify cherry-picked changes still exist on upstream HEAD.** A commit could have been added and later reverted/modified by a subsequent commit on the same upstream. After cherry-picking, verify the actual code still matches upstream's current state: `git show <remote>/master:<file> | grep "<key code>"`. Don't just trust that a commit was made — it may have been undone.
+
+10. **Squash-merging the sync PR destroys the merge-base advancement.** The merge commits from Phase 5 (`git merge <remote>/master`) are the only thing that tells git "we've seen up to this point." Squash-merge flattens them into a single commit, losing that information. When merging the sync PR, use **"Create a merge commit"** (regular merge), not squash. If already squashed, create a follow-up PR with ghost merges: `git merge -s ours <remote>/master` for each upstream, then merge that PR with a regular merge commit.

.eslintignore

@@ -1,5 +1,6 @@
 examples
 lib
+src/vendor
 tools
 
 metro.*.js

.gitignore

@@ -12,6 +12,8 @@ WebRTC.xcframework
 WebRTC.dSYMs
 examples/GumTestApp/package-lock.json
 examples/GumTestApp_macOS/package-lock.json
+**/.xcode.env.local
+**/PLAN.md
 *.jar
 *.tgz
 *.zip

.nvmrc

@@ -1 +1 @@
-v22
+v24

Documentation/AndroidInstallation.md

@@ -72,6 +72,55 @@ In `android/app/proguard-rules.pro` add the following on a new line.
 -keep class org.webrtc.** { *; }
 ```
 
+## Set audio category (output) to media
+
+The audio is considered calls by default. If you don't want your audio to be treated as a call stream you need to change the category. To set the category:
+
+if your Android files are written in Java, modify `MainApplication.java`:
+```java
+// add imports
+import com.oney.WebRTCModule.WebRTCModuleOptions;
+import android.media.AudioAttributes;
+import org.webrtc.audio.JavaAudioDeviceModule;
+
+public class MainApplication extends Application implements ReactApplication {
+	@Override
+	public void onCreate() {
+		// append this before WebRTCModule initializes
+		WebRTCModuleOptions options = WebRTCModuleOptions.getInstance();
+		AudioAttributes audioAttributes = AudioAttributes.Builder()
+		    .setUsage(AudioAttributes.USAGE_MEDIA)
+		    .setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+		    .build();
+		options.audioDeviceModule = JavaAudioDeviceModule.builder(this)
+		.setAudioAttributes(audioAttributes)
+		.createAudioDeviceModule();
+	}
+}
+```
+
+if your Android files are written in Kotlin, modify `MainApplication.kt`:
+```kt
+// add imports
+import com.oney.WebRTCModule.WebRTCModuleOptions;
+import android.media.AudioAttributes
+import org.webrtc.audio.JavaAudioDeviceModule;
+
+class MainApplication : Application(), ReactApplication {
+	override fun onCreate() {
+		// append this before WebRTCModule initializes
+		val options = WebRTCModuleOptions.getInstance()
+		val audioAttributes = AudioAttributes.Builder()
+			.setUsage(AudioAttributes.USAGE_MEDIA)
+			.setContentType(AudioAttributes.CONTENT_TYPE_SPEECH)
+			.build()
+		options.audioDeviceModule = JavaAudioDeviceModule.builder(this)
+			.setAudioAttributes(audioAttributes)
+			.createAudioDeviceModule()
+	}
+}
+```
+
 ## Fatal Exception: java.lang.UnsatisfiedLinkError
 
 ```

Documentation/BasicUsage.md

@@ -112,6 +112,22 @@ try {
 };
 ```
 
+### Using Media Constraints on getDisplayMedia (Android Only)
+
+It is possible to use mediaConstraints on getDisplayMedia to restricts the user to capturing the default display using the custom boolean parameter `createConfigForDefaultDisplay`.
+A resolution scale can also be applied using `resolutionScale` parameter. Value is a number between 0 and 1.
+
+This configuration in only available for android, so will you have to add the 'android' key in constraints.
+
+```javascript
+	const displayMediaStreamConstraints = {
+		android: {
+			createConfigForDefaultDisplay: true,
+			resolutionScale: 0.5,
+		},
+	};
+```
+
 ## Destroying the Media Stream
 
 Cycling all of the tracks and stopping them is more than enough to clean up after a call has finished.  
@@ -232,11 +248,9 @@ That will allow you to enable and disable video streams on demand while a call i
 
 ```javascript
 let sessionConstraints = {
-	mandatory: {
-		OfferToReceiveAudio: true,
-		OfferToReceiveVideo: true,
-		VoiceActivityDetection: true
-	}
+	offerToReceiveAudio: true,
+	offerToReceiveVideo: true,
+	voiceActivityDetection: true
 };
 ```
 

Documentation/CallGuide.md

@@ -143,11 +143,9 @@ So you can now start creating an offer which then needs sending send off to the
 
 ```javascript
 let sessionConstraints = {
-	mandatory: {
-		OfferToReceiveAudio: true,
-		OfferToReceiveVideo: true,
-		VoiceActivityDetection: true
-	}
+	offerToReceiveAudio: true,
+	offerToReceiveVideo: true,
+	voiceActivityDetection: true
 };
 
 try {

README.md

@@ -75,6 +75,10 @@ Don't worry, there are plans to include a much more broader example with backend
 Come join our [Discourse Community](https://react-native-webrtc.discourse.group/) if you want to discuss any React Native and WebRTC related topics.  
 Everyone is welcome and every little helps.  
 
+## Picture-in-Picture (PIP)
+
+This package does not include a built-in PIP implementation. PIP support is available via [`@stream-io/video-react-native-sdk`](https://github.com/GetStream/stream-video-js).
+
 ## Related Projects
 
 Looking for extra functionality coverage?  

android/src/main/java/com/oney/WebRTCModule/AbstractVideoCaptureController.java

@@ -97,7 +97,8 @@ public boolean stopCapture() {
 
     public void applyConstraints(ReadableMap constraints, @Nullable Consumer<Exception> onFinishedCallback) {
         if (onFinishedCallback != null) {
-            onFinishedCallback.accept(new UnsupportedOperationException("This video track does not support applyConstraints."));
+            onFinishedCallback.accept(
+                    new UnsupportedOperationException("This video track does not support applyConstraints."));
         }
     }
 

android/src/main/java/com/oney/WebRTCModule/AudioTrackAdapter.java

@@ -0,0 +1,92 @@
+package com.oney.WebRTCModule;
+
+import android.util.Log;
+
+import com.facebook.react.bridge.Arguments;
+import com.facebook.react.bridge.WritableMap;
+
+import org.webrtc.AudioTrack;
+import org.webrtc.AudioTrackSink;
+
+import java.nio.ByteBuffer;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.atomic.AtomicBoolean;
+
+/**
+ * Fires the W3C 'unmute' event on a remote audio track when the first
+ * decoded PCM buffer arrives via {@link AudioTrackSink}.
+ *
+ * IMPORTANT — only the initial muted → unmuted transition is detectable.
+ * Subsequent mute events (e.g. network stall mid-call) cannot be detected
+ * from the sink: Android's audio render path and WebRTC's NetEq synthesize
+ * silence / PLC frames whenever RTP stops, so {@code onData} keeps firing
+ * at a steady rate regardless of network state. For "remote participant
+ * muted their mic" UI, use the out-of-band participant state from your
+ * signaling layer — that is the correct source of truth, not this adapter.
+ *
+ * Only attach to remote audio tracks. {@code AudioTrackSink} callbacks
+ * are not delivered for local tracks.
+ */
+public class AudioTrackAdapter {
+    static final String TAG = AudioTrackAdapter.class.getCanonicalName();
+
+    private final Map<String, FirstDataUnmuteSink> sinks = new HashMap<>();
+    private final int peerConnectionId;
+    private final WebRTCModule webRTCModule;
+
+    public AudioTrackAdapter(WebRTCModule webRTCModule, int peerConnectionId) {
+        this.peerConnectionId = peerConnectionId;
+        this.webRTCModule = webRTCModule;
+    }
+
+    public void addAdapter(AudioTrack audioTrack) {
+        String trackId = audioTrack.id();
+        if (sinks.containsKey(trackId)) {
+            Log.w(TAG, "Attempted to add adapter twice for track ID: " + trackId);
+            return;
+        }
+        FirstDataUnmuteSink sink = new FirstDataUnmuteSink(trackId);
+        sinks.put(trackId, sink);
+        audioTrack.addSink(sink);
+        Log.d(TAG, "Created adapter for " + trackId);
+    }
+
+    public void removeAdapter(AudioTrack audioTrack) {
+        String trackId = audioTrack.id();
+        FirstDataUnmuteSink sink = sinks.remove(trackId);
+        if (sink == null) {
+            Log.w(TAG, "removeAdapter - no adapter for " + trackId);
+            return;
+        }
+        audioTrack.removeSink(sink);
+        Log.d(TAG, "Deleted adapter for " + trackId);
+    }
+
+    private class FirstDataUnmuteSink implements AudioTrackSink {
+        private final AtomicBoolean fired = new AtomicBoolean(false);
+        private final String trackId;
+
+        FirstDataUnmuteSink(String trackId) {
+            this.trackId = trackId;
+        }
+
+        @Override
+        public void onData(ByteBuffer audioData,
+                           int bitsPerSample,
+                           int sampleRate,
+                           int numberOfChannels,
+                           int numberOfFrames,
+                           long absoluteCaptureTimestampMs) {
+            if (!fired.compareAndSet(false, true)) {
+                return;
+            }
+            WritableMap params = Arguments.createMap();
+            params.putInt("pcId", peerConnectionId);
+            params.putString("trackId", trackId);
+            params.putBoolean("muted", false);
+            Log.d(TAG, "Unmute event pcId: " + peerConnectionId + " trackId: " + trackId);
+            webRTCModule.sendEvent("mediaStreamTrackMuteChanged", params);
+        }
+    }
+}