feat(react): display loading indicator while participant audio is connecting

[jdimovska]

💡 Overview

This PR adds a visual indicator that audio is still connecting for remote participants when an audio track exists but no data is flowing yet. It introduces a useIsTrackUnmuted hook that listens to mute/unmute events to detect when audio starts or stops, and integrates this into ParticipantDetails to show a loading indicator while the audio is still connecting.

🎫 Ticket: https://linear.app/stream/issue/REACT-906/loading-indicator-while-participant-audio-is-connecting

📑 Docs: https://github.com/GetStream/docs-content/pull/1091

Summary by CodeRabbit

• New Features

  • Added a loading indicator next to participant names when an audio track is present but still connecting, improving audio feedback during setup.
  • Adjusted participant name layout to accommodate the new indicator without disrupting alignment.

• Style

  • Updated participant-detail styles to size and position the connecting indicator for consistent visuals.

• Documentation

  • Added English text for the "Audio is connecting..." status.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 51b3260

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.

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: fd79b93d-2074-4429-9e71-990d58f42a40

📥 Commits

Reviewing files that changed from the base of the PR and between c6d7592 and 51b3260.

📒 Files selected for processing (2)

• packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx
• packages/react-sdk/src/translations/en.json

✅ Files skipped from review due to trivial changes (1)

• packages/react-sdk/src/translations/en.json

🚧 Files skipped from review as they are similar to previous changes (1)

• packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx

---

📝 Walkthrough

Walkthrough

Detects "audio connecting" by tracking a participant's audio track mute/unmute state via a new hook and conditionally renders a LoadingIndicator in the participant view; adds SCSS to size the indicator and a new English translation string.

Changes

Cohort / File(s)	Summary
Audio Connection & UI packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx	Imported useEffect, useState, LoadingIndicator, and StreamVideoParticipant. Added file-local useIsTrackUnmuted(participant) hook to read the first audio track and subscribe to mute/unmute events. Switched participant name wrapper from <span> to <div> and conditionally renders a loading indicator when hasAudioTrack && !isAudioTrackUnmuted and indicatorsVisible.
Audio Indicator Styling packages/styling/src/ParticipantView/ParticipantView-layout.scss	Added .str-video__participant-details__name--audio-connecting variant that targets .str-video__loading-indicator__icon, setting width/height: 1rem and border-width: 2px.
Localization packages/react-sdk/src/translations/en.json	Added the "Audio is connecting..." translation key/value.

Sequence Diagram(s)

sequenceDiagram
    participant UI as ParticipantView UI
    participant Hook as useIsTrackUnmuted Hook
    participant Track as Audio Track
    participant Indicator as LoadingIndicator

    UI->>Hook: mount with participant
    Hook->>Track: read first audio track (if present)
    Hook->>Track: subscribe to mute/unmute events
    Track-->>Hook: emit "mute"/"unmute"
    Hook-->>UI: update unmuted state
    alt hasAudio && not unmuted && indicatorsVisible
        UI->>Indicator: render "Audio is connecting..." indicator
    else
        UI->>Indicator: do not render / remove
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I sniff the wires, tiny and quick,
I watch the tracks for every tick,
When sound is shy and not yet free,
A little spinner hops with me. 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly summarizes the main change—adding a loading indicator for audio connection state.
Description check	✅ Passed	The description follows the template structure with an Overview section and ticket/docs references; all required sections are present and substantive.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch unmute-track-indicator

📝 Coding Plan

• Generate coding plan for human review comments

---

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.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx`:
- Around line 148-152: The participant name container uses a span (class
"str-video__participant-details__name") but conditionally renders
LoadingIndicator (a div) inside it, creating invalid DOM nesting; update the
markup in DefaultParticipantViewUI so the name container is a div instead of a
span (or alternatively render the LoadingIndicator outside the span or convert
it to an inline element) to ensure the LoadingIndicator (component name
LoadingIndicator) is not a block-level div nested inside a span; keep the same
className and styling when switching to a div to preserve layout.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cbcb42a9-8768-458e-81df-b9a7c6175711

📥 Commits

Reviewing files that changed from the base of the PR and between 4a95b9c and e556c74.

📒 Files selected for processing (2)

• packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx
• packages/styling/src/ParticipantView/ParticipantView-layout.scss

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In
`@packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx`:
- Around line 150-152: The loading indicator is currently shown for both local
and remote users; restrict it to remote participants only by adding a check for
the participant's locality when rendering in DefaultParticipantViewUI: only
render LoadingIndicator when indicatorsVisible && isAudioConnecting &&
!participant.isLocal (or the equivalent isLocal flag used in this
component/state), so the indicator appears only for remote participants with an
audio track but no audio data yet.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: ad54767c-a066-4132-891d-ae676f1b3f54

📥 Commits

Reviewing files that changed from the base of the PR and between e556c74 and c6d7592.

📒 Files selected for processing (1)

• packages/react-sdk/src/core/components/ParticipantView/DefaultParticipantViewUI.tsx