chore: identify if a call was put on hold by the remote user

[pierre-lehnen-rc]

Proposed changes (including videos or screenshots)

Issue(s)

VGA-41
VGA-43

Steps to test or reproduce

Further comments

Summary by CodeRabbit

• New Features
  • Added remote hold state detection and tracking to calls. The application now detects and reports when the remote party places the call on hold, with real-time state synchronization. This ensures accurate visibility into call status throughout the application and enables appropriate responses to remote hold conditions.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 6430a41

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[dionisio-bot]

Looks like this PR is ready to merge! 🎉
If you have any trouble, please check the PR guidelines

[coderabbitai]

Walkthrough

This PR adds remote hold detection to the media-signaling library. It tracks whether the remote party has placed the call on hold by analyzing audio transceiver directions during WebRTC negotiation, exposing this state through the public call API via a remoteHeld property.

Changes

Cohort / File(s)	Summary
Interface Definitions packages/media-signaling/src/definition/call/IClientMediaCall.ts, packages/media-signaling/src/definition/services/webrtc/IWebRTCProcessor.ts	Added remoteHeld: boolean field to IClientMediaCall interface and isRemoteHeld(): boolean method to IWebRTCProcessor interface to expose remote hold state.
Call State Management packages/media-signaling/src/lib/Call.ts	Added private _remoteHeld field with public getter, initialization in constructor, and updateRemoteHeld() method invoked from onWebRTCInternalStateChange to synchronize remote hold state and emit trackStateChange events.
WebRTC Processor Implementation packages/media-signaling/src/lib/services/webrtc/Processor.ts	Implemented isRemoteHeld(): boolean method that determines remote hold status by examining audio transceiver directions, with helper method getAudioTransceivers(): RTCRtpTransceiver[]. Returns false when stopped or connection is in [closed, failed, new] states.

Sequence Diagram

sequenceDiagram
    participant WRTCState as WebRTC<br/>Internal State
    participant Call as Call<br/>Component
    participant Processor as WebRTC<br/>Processor
    participant UI as UI Layer

    WRTCState->>Call: onWebRTCInternalStateChange()
    Call->>Call: updateRemoteHeld()
    Call->>Processor: isRemoteHeld()
    Processor->>Processor: getAudioTransceivers()
    Processor->>Processor: Check transceiver<br/>currentDirection
    Processor-->>Call: boolean (remote hold state)
    
    alt State Changed
        Call->>Call: Update _remoteHeld
        Call->>UI: emit trackStateChange
    end
    
    UI->>Call: remoteHeld (getter)
    Call-->>UI: boolean value

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

• Focus areas:
  • WebRTC transceiver direction logic in Processor.ts — verify correct interpretation of transceiver states for hold detection
  • State synchronization timing — ensure updateRemoteHeld() is called at appropriate points in the call lifecycle
  • Event emission — confirm trackStateChange events are only emitted when state actually changes

Suggested labels

stat: ready to merge, stat: QA assured

Suggested reviewers

• gabriellsh

Poem

🐰 A call placed on hold, now we know,

Through audio transceivers' subtle flow,

Remote hold state exposed with care,

The UI awaits, crystal-clear and fair! ✨

Pre-merge checks and finishing touches

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: adding functionality to detect when a remote user puts a call on hold by examining WebRTC audio direction.
Linked Issues check	✅ Passed	The PR successfully implements the core objective of VGA-41 by detecting remote hold status via WebRTC audio transceiver directions and exposes it through the IClientMediaCall interface for UI access (VGA-43).
Out of Scope Changes check	✅ Passed	All changes are directly scoped to implementing remote hold detection: interface definitions, WebRTC processor logic, and call state management. No unrelated modifications detected.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch chore/identify-remote-held

---

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 and usage tips.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.05%. Comparing base (465e541) to head (6430a41).
⚠️ Report is 1 commits behind head on feat/voip-sync-audio-direction.

Additional details and impacted files

@@                        Coverage Diff                         @@
##           feat/voip-sync-audio-direction   #37382      +/-   ##
==================================================================
+ Coverage                           68.03%   68.05%   +0.01%     
==================================================================
  Files                                3361     3364       +3     
  Lines                              115490   115626     +136     
  Branches                            20771    20798      +27     
==================================================================
+ Hits                                78573    78688     +115     
- Misses                              34240    34254      +14     
- Partials                             2677     2684       +7     

Flag	Coverage Δ
e2e	57.47% <ø> (+0.03%)	⬆️
unit	72.11% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

packages/media-signaling/src/lib/services/webrtc/Processor.ts (1)

331-335: Consider using the helper in existing code to reduce duplication.

The new getAudioTransceivers() helper extracts common logic, but the same filtering pattern exists inline at lines 109-111 (createOffer) and lines 185-187 (createAnswer). Consider refactoring those locations to use this helper.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Jira integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 688786a and 07ebb90.

📒 Files selected for processing (4)

• packages/media-signaling/src/definition/call/IClientMediaCall.ts (1 hunks)
• packages/media-signaling/src/definition/services/webrtc/IWebRTCProcessor.ts (1 hunks)
• packages/media-signaling/src/lib/Call.ts (4 hunks)
• packages/media-signaling/src/lib/services/webrtc/Processor.ts (2 hunks)

🧰 Additional context used

🧠 Learnings (1)

📓 Common learnings

Learnt from: pierre-lehnen-rc
Repo: RocketChat/Rocket.Chat PR: 36718
File: packages/media-signaling/src/lib/Call.ts:633-642
Timestamp: 2025-09-23T00:27:05.438Z
Learning: In PR #36718, pierre-lehnen-rc prefers to maintain consistency with the old architecture patterns for DTMF handling rather than implementing immediate validation improvements, deferring enhancements to future work.

🧬 Code graph analysis (1)

packages/media-signaling/src/lib/Call.ts (1)

packages/media-signaling/src/lib/services/webrtc/Processor.ts (1)

• isRemoteHeld (245-270)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (4)

• GitHub Check: 🔨 Test Unit / Unit Tests
• GitHub Check: 🔎 Code Check / Code Lint
• GitHub Check: 🔎 Code Check / TypeScript
• GitHub Check: 📦 Meteor Build - coverage

🔇 Additional comments (7)

packages/media-signaling/src/definition/services/webrtc/IWebRTCProcessor.ts (1)

38-38: LGTM! Clean interface extension.

The addition of isRemoteHeld() to the interface is straightforward and properly exposes the remote hold detection capability.

packages/media-signaling/src/definition/call/IClientMediaCall.ts (1)

81-82: LGTM! Well-documented interface extension.

The remoteHeld field is properly documented and follows the existing pattern for tracking call state flags.

packages/media-signaling/src/lib/Call.ts (4)

127-131: LGTM! Consistent state management pattern.

The private field and public getter follow the established pattern used for muted and held properties.

---

226-226: LGTM! Proper initialization.

Initializing _remoteHeld to false is correct—the call starts with the remote side not on hold.

---

1087-1099: LGTM! Well-structured update method.

The updateRemoteHeld() method correctly:

• Guards against missing processor
• Queries the current remote hold state
• Only updates and emits when state changes
• Emits trackStateChange to notify observers

---

1121-1121: LGTM! Proper integration point.

Calling updateRemoteHeld() from onWebRTCInternalStateChange ensures the remote hold state is synchronized whenever WebRTC internal state changes, which is appropriate since transceiver directions can change during negotiation.

packages/media-signaling/src/lib/services/webrtc/Processor.ts (1)

331-335: Verify merge conflict resolution with PR #37381.

The PR description notes a merge conflict with PR #37381, where both PRs define getAudioTransceivers(). Please ensure this doesn't cause issues when both PRs are merged.