feat: add muteChange event with subscription-based muted state tracking (#85)

* feat: add muteChange event with subscription-based muted state tracking

* docs: document muteChange event usage and tracking behavior in README files

* chore: update changeset

* refactor: avoid pre-ready muteChange emission before player initialization

* fix: align onReady muted payload with normalized readyMuted value

Author: saseungmin

.changeset/flat-bats-greet.md

@@ -0,0 +1,32 @@
+---
+"react-native-youtube-bridge": minor
+"@react-native-youtube-bridge/core": minor
+"@react-native-youtube-bridge/web": minor
+---
+
+feat: add muteChange event with subscription-based muted state tracking
+
+- Add `muteChange` event for real-time muted state updates.
+- Forward `muteChange` through core/web/webview/react-native bridge layers.
+- Enable muted-state tracking only while `muteChange` is subscribed (performance optimization).
+- Keep replay mute-preservation behavior intact.
+- Update the example app to use `useYouTubeEvent(player, 'muteChange', false)` for muted state.
+- Update README docs (EN/KO, root + package) to document `muteChange` usage and tracking behavior.
+
+```tsx
+import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-youtube-bridge';
+
+function App() {
+  const player = useYouTubePlayer(videoIdOrUrl);
+
+  // 1. State-based event listening
+  const isMuted = useYouTubeEvent(player, 'muteChange', false);
+
+  // 2. Callback-based event listening
+  useYouTubeEvent(player, 'muteChange', (muted) => {
+    console.log('Player is muted:', muted);
+  });
+
+  return <YoutubeView player={player} />;
+}
+```

README-ko_kr.md

@@ -73,9 +73,12 @@ import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-you
 function App() {
   const player = useYouTubePlayer(videoIdOrUrl);
 
+  // State-based event listening
   const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const isMuted = useYouTubeEvent(player, 'muteChange', false);
   const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
+  // Callback-based event listening
   useYouTubeEvent(player, 'ready', (playerInfo) => {
     console.log('Player is ready!');
     Alert.alert('Alert', 'YouTube player is ready!');
@@ -94,6 +97,9 @@ function App() {
 }
 ```
 
+`muteChange` 이벤트를 구독하면 YouTube 플레이어 기본 UI의 스피커 버튼 또는 `player.mute()` / `player.unMute()` 호출로 변경된 음소거 상태를 실시간으로 받을 수 있습니다.  
+성능 최적화를 위해 `muteChange`를 구독할 때만 muted tracking이 활성화됩니다.
+
 `useYouTubeEvent` hook은 callback으로 값을 전달받는 방식과 state로 값을 바로 사용할 수 있는 두 가지 방법을 제공합니다.
 
 1. Callback 방식: 의존성에 따라 리렌더링이 필요한 경우 4번째 인자에 dependency array를 주입해주면 됩니다.

README.md

@@ -73,9 +73,12 @@ import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-you
 function App() {
   const player = useYouTubePlayer(videoIdOrUrl);
 
+  // State-based event listening
   const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const isMuted = useYouTubeEvent(player, 'muteChange', false);
   const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
+  // Callback-based event listening
   useYouTubeEvent(player, 'ready', (playerInfo) => {
     console.log('Player is ready!');
     Alert.alert('Alert', 'YouTube player is ready!');
@@ -94,6 +97,9 @@ function App() {
 }
 ```
 
+`muteChange` emits real-time muted state updates from both the YouTube player's built-in mute control and `player.mute()` / `player.unMute()`.  
+For performance, muted tracking is enabled only while `muteChange` is subscribed.
+
 The `useYouTubeEvent` hook provides two ways to receive values: callback-based and state-based.
 
 1. **Callback method**: If re-rendering is needed based on dependencies, inject a dependency array as the 4th argument.

example/src/App.tsx

@@ -27,7 +27,6 @@ function App() {
   const [isPlaying, setIsPlaying] = useState(false);
   const [availableRates, setAvailableRates] = useState<number[]>([1]);
   const [volume, setVolume] = useState(100);
-  const [isMuted, setIsMuted] = useState(false);
   const [videoId, setVideoId] = useState('AbZH7XWDW_k');
   const [progressInterval, setProgressInterval] = useState(1000);
   const { oEmbed, isLoading, error } = useYoutubeOEmbed(
@@ -42,6 +41,11 @@ function App() {
     muted: true,
   });
 
+  const isMuted = useYouTubeEvent(player, 'muteChange');
+  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const playbackQuality = useYouTubeEvent(player, 'playbackQualityChange');
+  const progress = useYouTubeEvent(player, 'progress', progressInterval);
+
   const changePlaybackRate = (rate: number) => {
     player.setPlaybackRate(rate);
   };
@@ -54,12 +58,10 @@ function App() {
   const toggleMute = useCallback(() => {
     if (isMuted) {
       player.unMute();
-      setIsMuted(false);
       return;
     }
 
     player.mute();
-    setIsMuted(true);
   }, [player, isMuted]);
 
   const onPlay = useCallback(() => {
@@ -100,10 +102,6 @@ function App() {
     );
   };
 
-  const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
-  const playbackQuality = useYouTubeEvent(player, 'playbackQualityChange');
-  const progress = useYouTubeEvent(player, 'progress', progressInterval);
-
   const currentTime = progress?.currentTime ?? 0;
   const duration = progress?.duration ?? 0;
   const loadedFraction = progress?.loadedFraction ?? 0;
@@ -123,10 +121,6 @@ function App() {
     if (playerInfo?.volume !== undefined) {
       setVolume(playerInfo.volume);
     }
-
-    if (playerInfo?.muted !== undefined) {
-      setIsMuted(playerInfo.muted);
-    }
   });
 
   useYouTubeEvent(player, 'stateChange', (state) => {

packages/core/src/WebYoutubePlayerController.ts

@@ -7,12 +7,18 @@ type PlayerConfig = Omit<YoutubePlayerConfig, 'source'> & {
   videoId: string;
 };
 
+const MUTED_TRACKING_INTERVAL_MS = 250;
+
 class WebYoutubePlayerController {
   private player: YouTubePlayer | null = null;
   private progressInterval: NodeJS.Timeout | null = null;
   private callbacks: PlayerEvents = {};
   private progressIntervalMs = 1000;
   private seekTimeout: NodeJS.Timeout | null = null;
+  private mutedTrackingInterval: NodeJS.Timeout | null = null;
+  private isMutedSyncing = false;
+  private lastKnownMuted: boolean | null = null;
+  private mutedTrackingEnabled = false;
   private desiredMuted = false;
 
   static createInstance(): WebYoutubePlayerController {
@@ -83,6 +89,8 @@ class WebYoutubePlayerController {
     }
 
     this.desiredMuted = Boolean(config.playerVars?.muted);
+    this.lastKnownMuted = null;
+    this.stopMutedTracking();
 
     if (this.player) {
       try {
@@ -111,29 +119,38 @@ class WebYoutubePlayerController {
       events: {
         onReady: (event) => {
           const { playerInfo } = event.target;
+          const readyMuted =
+            typeof playerInfo.muted === 'boolean' ? playerInfo.muted : this.desiredMuted;
 
           this.callbacks.onReady?.({
             availablePlaybackRates: playerInfo.availablePlaybackRates,
             availableQualityLevels: playerInfo.availableQualityLevels,
             currentTime: playerInfo.currentTime,
             duration: playerInfo.duration,
-            muted: playerInfo.muted,
+            muted: readyMuted,
             playbackQuality: playerInfo.playbackQuality,
             playbackRate: playerInfo.playbackRate,
             playerState: playerInfo.playerState,
             size: playerInfo.size,
             volume: playerInfo.volume,
           });
 
+          this.updateMutedState(readyMuted, true);
           this.applyDesiredMutedState();
           this.startProgressTracking();
+          this.startMutedTracking();
         },
         onStateChange: (event) => {
           const state = event.data;
           const mutedState = event.target?.playerInfo?.muted;
+
+          if (typeof mutedState === 'boolean') {
+            this.updateMutedState(mutedState, true);
+          }
+
           this.callbacks.onStateChange?.(state);
 
-          this.handleStateChange(state, mutedState);
+          this.handleStateChange(state);
         },
         onError: (event) => {
           console.error('YouTube player error:', event.data);
@@ -163,11 +180,7 @@ class WebYoutubePlayerController {
     });
   }
 
-  private handleStateChange(state: number, mutedState?: boolean): void {
-    if (state !== PlayerState.PLAYING && typeof mutedState === 'boolean') {
-      this.desiredMuted = mutedState;
-    }
-
+  private handleStateChange(state: number): void {
     if (state === PlayerState.ENDED) {
       this.stopProgressTracking();
       this.sendProgress();
@@ -283,12 +296,22 @@ class WebYoutubePlayerController {
 
   mute(): void {
     this.desiredMuted = true;
-    this.player?.mute();
+    if (!this.player) {
+      return;
+    }
+
+    this.player.mute();
+    this.updateMutedState(true, true);
   }
 
   unMute(): void {
     this.desiredMuted = false;
-    this.player?.unMute();
+    if (!this.player) {
+      return;
+    }
+
+    this.player.unMute();
+    this.updateMutedState(false, true);
   }
 
   async isMuted(): Promise<boolean> {
@@ -370,20 +393,85 @@ class WebYoutubePlayerController {
     this.callbacks = { ...this.callbacks, ...newCallbacks };
   }
 
+  setMutedTrackingEnabled(enabled: boolean): void {
+    this.mutedTrackingEnabled = enabled;
+
+    if (enabled) {
+      this.lastKnownMuted = null;
+      this.startMutedTracking();
+      void this.syncMutedStateFromPlayer();
+      return;
+    }
+
+    this.stopMutedTracking();
+  }
+
+  private startMutedTracking(): void {
+    if (!this.mutedTrackingEnabled || !this.player) {
+      return;
+    }
+
+    this.stopMutedTracking();
+    this.mutedTrackingInterval = setInterval(() => {
+      void this.syncMutedStateFromPlayer();
+    }, MUTED_TRACKING_INTERVAL_MS);
+  }
+
+  private stopMutedTracking(): void {
+    if (this.mutedTrackingInterval) {
+      clearInterval(this.mutedTrackingInterval);
+      this.mutedTrackingInterval = null;
+    }
+    this.isMutedSyncing = false;
+  }
+
+  private async syncMutedStateFromPlayer(): Promise<void> {
+    if (this.isMutedSyncing || !this.player || !this.player.isMuted) {
+      return;
+    }
+
+    this.isMutedSyncing = true;
+
+    try {
+      const muted = await this.player.isMuted();
+      this.updateMutedState(Boolean(muted), true);
+    } catch {
+      // ignore polling errors while player is transitioning
+    } finally {
+      this.isMutedSyncing = false;
+    }
+  }
+
+  private updateMutedState(muted: boolean, emitEvent = true): void {
+    this.desiredMuted = muted;
+
+    if (this.lastKnownMuted === muted) {
+      return;
+    }
+
+    this.lastKnownMuted = muted;
+
+    if (emitEvent) {
+      this.callbacks.onMuteChange?.(muted);
+    }
+  }
+
   private applyDesiredMutedState(): void {
     if (!this.desiredMuted) {
       return;
     }
 
     try {
       this.player?.mute();
+      this.updateMutedState(true, true);
     } catch (error) {
       console.warn('Failed to apply muted state:', error);
     }
   }
 
   destroy(): void {
     this.stopProgressTracking();
+    this.stopMutedTracking();
 
     if (this.seekTimeout) {
       clearTimeout(this.seekTimeout);
@@ -398,6 +486,8 @@ class WebYoutubePlayerController {
       }
       this.player = null;
     }
+
+    this.lastKnownMuted = null;
   }
 }
 

packages/core/src/types/index.ts

@@ -114,6 +114,11 @@ export type PlayerEvents = {
    * This event fires any time the browser blocks autoplay or scripted video playback features, collectively referred to as "autoplay".
    */
   onAutoplayBlocked?: () => void;
+  /**
+   * This event fires whenever the player's muted state changes.
+   * @param {boolean} muted - The current muted state.
+   */
+  onMuteChange?: (muted: boolean) => void;
 };
 
 /**
@@ -234,6 +239,7 @@ export type YoutubePlayerEvents = {
   playbackRateChange: number;
   playbackQualityChange: PlaybackQuality;
   autoplayBlocked: undefined;
+  muteChange: boolean;
 };
 
 export type EventCallback<Data = any> = (data: Data) => any;

packages/core/src/types/webview.ts

@@ -34,6 +34,11 @@ interface AutoplayBlockedMessageData {
   type: 'autoplayBlocked';
 }
 
+interface MuteChangeMessageData {
+  type: 'muteChange';
+  muted: boolean;
+}
+
 interface CommandResultMessageData {
   type: 'commandResult';
   id: string;
@@ -48,4 +53,5 @@ export type MessageData =
   | PlaybackRateChangeMessageData
   | PlaybackQualityChangeMessageData
   | AutoplayBlockedMessageData
+  | MuteChangeMessageData
   | CommandResultMessageData;

packages/react-native-youtube-bridge/README-ko_kr.md

@@ -73,9 +73,12 @@ import { YoutubeView, useYouTubeEvent, useYouTubePlayer } from 'react-native-you
 function App() {
   const player = useYouTubePlayer(videoIdOrUrl);
 
+  // State-based event listening
   const playbackRate = useYouTubeEvent(player, 'playbackRateChange', 1);
+  const isMuted = useYouTubeEvent(player, 'muteChange', false);
   const progress = useYouTubeEvent(player, 'progress', progressInterval);
 
+  // Callback-based event listening
   useYouTubeEvent(player, 'ready', (playerInfo) => {
     console.log('Player is ready!');
     Alert.alert('Alert', 'YouTube player is ready!');
@@ -94,6 +97,9 @@ function App() {
 }
 ```
 
+`muteChange` 이벤트를 구독하면 YouTube 플레이어 기본 UI의 스피커 버튼 또는 `player.mute()` / `player.unMute()` 호출로 변경된 음소거 상태를 실시간으로 받을 수 있습니다.  
+성능 최적화를 위해 `muteChange`를 구독할 때만 muted tracking이 활성화됩니다.
+
 `useYouTubeEvent` hook은 callback으로 값을 전달받는 방식과 state로 값을 바로 사용할 수 있는 두 가지 방법을 제공합니다.
 
 1. Callback 방식: 의존성에 따라 리렌더링이 필요한 경우 4번째 인자에 dependency array를 주입해주면 됩니다.